chore: sync standards components

docs/standards/README.md

@@ -0,0 +1,18 @@
+---
+standards-contract: 1.0.2
+---
+
+# Standards index
+
+Team-layer engineering standards synced from melodic-software/standards
+(`conventions/engineering/`). Change them there, not here.
+
+| Surface | Applies when | File |
+|---|---|---|
+| bulk-mutation | a command or sweep that creates, deletes, or changes many objects; background or unattended runs; work spanning several targets | bulk-mutation.md |
+| concise-prose | writing or reviewing any prose: docs, comments, commit messages, PR bodies, replies | concise-prose.md |
+| deterministic-work-execution | counts, diffs, sorting, arithmetic, inventories; composing shell commands an agent runs | deterministic-work-execution.md |
+| documentation-and-citations | citing upstream docs; recording an external default or version; labeling the basis of a recommendation | documentation-and-citations.md |
+| reference-dont-duplicate | a fact, value, or rule appearing in more than one place; origin or history notes in code or docs | reference-dont-duplicate.md |
+| simpler-code | writing or reviewing code; proposing a new check, process, document, or dependency; serializing work; keeping an existing mechanism | simpler-code.md |
+| source-authority-tiers | grounding a recommendation, option, or decision; judging how much a source is worth | source-authority-tiers.md |

docs/standards/bulk-mutation.md

@@ -0,0 +1,36 @@
+# Bulk mutation
+
+A command that creates, deletes, or changes many objects at once is only as
+safe as the scope it runs over. This convention covers bounding that scope
+before the command runs. It is a reasoning-only judgment: a tool can report a
+count, but only the author can tell whether the scope matches what was meant.
+
+## The scope sets the blast radius
+
+A policy flag such as "delete everything not yet handled" or "install all
+missing" does not decide how much it touches; the scope argument beside it
+does. The same wording is safe over a curated set and destructive over every
+set the machine knows about. Before a sweep runs unattended, resolve how many
+objects it will create, delete, or modify, and state that number.
+
+## Count first, then act
+
+Count before acting whenever a run does any of the following:
+
+- runs in the background or unattended;
+- spans more than one target; or
+- inherits an automatic policy that someone configured with a narrower case
+  in mind.
+
+## Running unattended does not grant consent
+
+A background task needs the confirmation it would get if run interactively.
+Running it unattended removes the person from the loop, not the need for their
+approval. An automatic policy that an unattended run inherits drops to its
+confirm-first variant rather than standing in for consent.
+
+## Boundaries
+
+- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-work-execution.md)**:
+  that file covers producing the count honestly by running a tool. This file
+  says when the count is required and what to do with it.

docs/standards/concise-prose.md

@@ -0,0 +1,84 @@
+# Concise prose without semantic loss
+
+Write prose as briefly as clarity and completeness allow. Remove words only
+when the result preserves the same meaning and remains as easy to apply. This
+is a reasoning-only judgment: word or sentence counts can flag a passage for
+review, but they cannot prove that a shorter version is equivalent.
+
+This rule owns wording, not whether content belongs or where it lives.
+[`documentation-existence.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-existence.md) owns whether a
+page may exist at all;
+[`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md) owns reductions to executable code;
+[`progressive-disclosure.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/progressive-disclosure.md) owns information
+layering; and [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md) and
+[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md) jointly own
+whether a fact stays inline or is cited. [`naming.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/naming.md) owns
+identifiers, and [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/legacy-and-migration-debt.md)
+owns whether historical narration belongs at all. Apply this convention to the
+prose that remains after those decisions.
+
+## Remove non-semantic overhead
+
+Cut filler openings, empty intensifiers, reflexive hedges, unnecessary
+modifiers, repeated restatements, and multi-word phrases that a precise word
+can replace. Keep a hedge or qualifier when it communicates real uncertainty,
+confidence, or scope. The test is whether each word adds meaning or helps the
+reader act;
+[Digital.gov](https://digital.gov/guides/plain-language/principles/short-simple)
+and the
+[Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences)
+recommend removing words that add no substance.
+
+Do not vary terminology merely to avoid repetition. Use one term for one
+concept. Repeat a word deliberately when the repetition prevents ambiguity or
+keeps parallel conditions explicit, as Google's
+[global-audience guidance](https://developers.google.com/style/translation#use-helper-words-and-optional-words)
+recommends.
+
+State the point literally. Where a plain phrase says it, use that phrase
+instead of a metaphor or flourish: figurative wording makes the reader
+translate it back into the claim, and the translation can go wrong.
+
+## Preserve the whole contract
+
+A shorter version is wrong when it changes what the reader must know or do.
+Keep all of the following when they carry meaning:
+
+- normative force, scope, actors, and required actions;
+- conditions, exceptions, alternatives, and ordering;
+- thresholds, defaults, units, and other exact values;
+- definitions and context needed to remove ambiguity;
+- rationale needed to evaluate or maintain a decision; and
+- examples needed to understand a concept or apply a rule.
+
+Do not turn explicit content into an inference the reader must supply. W3C's
+[supplemental cognitive-accessibility guidance](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p12-implicit-explained/)
+recommends explaining implied or ambiguous information; it informs this clarity
+judgment but is not conformance-required WCAG guidance.
+
+## Shorten structure, not meaning
+
+Prefer one point per sentence and one topic per paragraph. Split compound
+thoughts, lead with the point or condition that governs what follows, and use a
+list when several parallel items must remain distinct. Digital.gov's
+[clear-and-short guidance](https://digital.gov/guides/plain-language/writing/clear-short)
+and W3C's
+[succinct-text pattern](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p05-succinct-text/)
+use this structure to make information easier to process.
+
+Length is a review trigger, not a target. A long sentence or paragraph deserves
+a clarity check; keep it when splitting it would obscure a relationship, add
+redundancy, or make the prose less natural. A short passage still fails when it
+is incomplete, ambiguous, or abrupt.
+
+## Sources
+
+- [Digital.gov, "Short and simple"](https://digital.gov/guides/plain-language/principles/short-simple)
+- [Digital.gov, "Clear and short"](https://digital.gov/guides/plain-language/writing/clear-short)
+- [Microsoft Writing Style Guide, "Use simple words, concise sentences"](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences)
+- [Microsoft Learn style and voice quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start)
+- [Google developer documentation style guide, "Write for a global audience"](https://developers.google.com/style/translation)
+- [W3C cognitive accessibility pattern, "Keep Text Succinct"](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p05-succinct-text/)
+- [W3C cognitive accessibility pattern, "Explain Implied Content"](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p12-implicit-explained/)
+- [GOV.UK, "Publishing accessible documents"](https://www.gov.uk/guidance/publishing-accessible-documents)
+- [ISO 24495-1:2023, *Plain language — Part 1: Governing principles and guidelines*](https://www.iso.org/standard/78907.html) <!-- ai-slop-ignore: em dash is part of the literal ISO standard title -->

docs/standards/deterministic-work-execution.md

@@ -0,0 +1,108 @@
+# Execute deterministic work with tools
+
+When a task contains a substep that a mechanical procedure can decide, run the
+narrowest existing tool, query, calculator, interpreter, or disposable script
+that fits, then reason over its actual output. Do not hand-count, mentally sort,
+or imitate execution in prose when the operation can run. Writing code-shaped
+text without executing it produces no result.
+
+The policy is grounded in a bounded body of evidence. PAL and Program of
+Thoughts improved performance on the numerical, symbolic, and algorithmic
+tasks they studied by delegating execution to an interpreter
+([Gao et al.](https://proceedings.mlr.press/v202/gao23f),
+[Chen et al.](https://openreview.net/forum?id=YfZ4ZPt8zd)). Toolformer found a
+similar benefit from calling specialized tools, including a calculator, instead
+of asking one language model to supply every result
+([Schick et al.](https://proceedings.neurips.cc/paper_files/paper/2023/hash/d842425e4bf79ba039352da0f658a906-Abstract-Conference.html)).
+Those studies do not prove that every generated program is correct. The policy
+inference is narrower: once a substep has a complete mechanical specification,
+its result should come from executing that specification rather than predicting
+the result in text.
+
+## Classify each substep before executing it
+
+[`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md) owns the tier definitions.
+Apply them to the current substep, not to the task as a whole:
+
+- For **deterministic** work, execute the operation and consume the returned
+  result. Examples include an exact count or diff, arithmetic, sorting by a
+  declared key, matching a declared pattern, a syntax-aware transformation, or
+  a repository-wide inventory over an explicit path set.
+- For **detect-then-judge** work, execute only the detection half. The result is
+  a candidate set; a human or agent still rules on every candidate. A similarity
+  score, heuristic match, or advisory scan cannot promote its own flag to a
+  verdict.
+- For **reasoning-only** work, do not encode the verdict in a script. A tool may
+  gather deterministic evidence for the judgment, but meaning, intent, fit, and
+  semantic equivalence remain with the human or agent.
+
+Classification is itself reasoning-only. A task that mixes exact inventory with
+architectural judgment therefore gets an executed inventory followed by a
+reasoned decision, not one mechanism pretending to own both.
+
+## Make the execution honest
+
+A script is not deterministic merely because it is code. Before relying on its
+output:
+
+- state the operation, input scope, comparison rule, and ordering explicitly;
+- prefer a mature existing tool over generating new logic when both implement
+  the same operation;
+- run the command or script and inspect its exit status and material output;
+- check nontrivial generated logic against a known case, invariant, or second
+  representation in proportion to the consequence of a wrong answer; and
+- record the invocation, input scope, and material result when they support a
+  change or verification claim, so another reader can repeat the computation.
+
+Successful execution proves only that the encoded operation ran. It does not
+prove that the inputs were complete, that the operation answered the intended
+question, or that a later judgment is sound. The National Academies report
+defines computational reproducibility around the same inputs, computational
+steps, methods, code, and conditions of analysis
+([*Reproducibility and Replicability in Science*](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science)).
+The UK Government Analysis Function likewise recommends minimizing manual steps
+while retaining quality assurance and an audit trail
+([RAP strategy](https://analysisfunction.civilservice.gov.uk/policy-store/reproducible-analytical-pipelines-strategy/)).
+
+## Keep session-time work in its lane
+
+This convention governs one-off execution during the current task. It does not
+require committing a throwaway script, adding a dependency, or building a
+general utility. If the same deterministic finding recurs, route it through
+[`enforceability-tiers.md#routing-a-recurring-finding`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md#routing-a-recurring-finding)
+instead of accumulating session scripts.
+
+When executable logic becomes committed behavior, the simplicity, ownership,
+and test obligations in [`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md),
+[`code-organization.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/code-organization.md), and
+[`../review/testing.md`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md) apply. When the concern is a
+reusable artifact's fixed shape rather than an in-task computation,
+[`deterministic-artifact-scaffolding.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-artifact-scaffolding.md)
+owns it. Treat the output as proof only of the exact structural or computational
+claim it checked; the verification-honesty criteria in
+[`../review/testing.md#verification-honesty`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md#verification-honesty)
+own broader proof claims.
+
+## Keep agent-run commands plain
+
+When an agent runs commands through a harness that checks each command before
+it runs, the command's shape decides how cheaply it is checked. Keep each one
+plain:
+
+- absolute paths, rather than a `cd` followed by relative paths;
+- no inline environment assignments (`VAR=value command`), `export`, or output
+  redirection;
+- the harness's own file-read and search tools in place of shell reads such as
+  `cat`, `sed -n`, or `grep`, where it has them;
+- a POSIX shell rather than PowerShell unless the command needs PowerShell,
+  because PowerShell starts noticeably slower on Windows; and
+- a background job or the harness's wait mechanism for a long operation, never
+  a foreground `sleep` or polling loop.
+
+## Sources
+
+- Gao et al., ["PAL: Program-aided Language Models"](https://proceedings.mlr.press/v202/gao23f) (ICML 2023).
+- Chen et al., ["Program of Thoughts Prompting: Disentangling Computation from Reasoning for Numerical Reasoning Tasks"](https://openreview.net/forum?id=YfZ4ZPt8zd) (TMLR 2023).
+- Schick et al., ["Toolformer: Language Models Can Teach Themselves to Use Tools"](https://proceedings.neurips.cc/paper_files/paper/2023/hash/d842425e4bf79ba039352da0f658a906-Abstract-Conference.html) (NeurIPS 2023).
+- UK Government Analysis Function, ["Reproducible Analytical Pipelines (RAP) strategy"](https://analysisfunction.civilservice.gov.uk/policy-store/reproducible-analytical-pipelines-strategy/).
+- National Academies of Sciences, Engineering, and Medicine, [*Reproducibility and Replicability in Science*](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science) (2019).

docs/standards/documentation-and-citations.md

@@ -0,0 +1,32 @@
+# Documentation and external citations
+
+A source of truth that lives outside the repo is owned by that upstream, not by you: a vendor's product docs, a framework reference, a cloud dashboard, an API reference, a registry page. Copying its content into tracked files creates a snapshot that decays the moment the upstream changes. Cite it; fetch it at read time. This complements the in-repo discipline (see `reference-dont-duplicate.md`): one governs facts you own, this governs facts someone else owns. These are reasoning-only judgments. A link checker can verify that a cited URL still resolves, but whether to cite rather than copy, and where the citation lives, is yours to decide.
+
+## Upstream bodies are read-on-demand
+
+Catalogs, defaults, schemas, flag inventories, pricing, lifecycle mechanics, and install matrices are upstream-owned. Do not recap them in tracked markdown. Link to the authority and let the reader (human or agent) fetch the current version. What the repo records instead is **policy and wiring**: the paths it commits, the decisions it made, the empirical findings it observed, and operator recipes that have no stable upstream source.
+
+For one fact, cite either your own policy hub or the upstream URL, not both with recap prose between them. The hub owns repo policy; the upstream owns product behavior. The narrow exception is a minimal install or verify command for which no stable upstream source exists for your exact wiring; keep that inline and point at the upstream for everything around it.
+
+## Place the citation where it is read
+
+Documentation is rarely read top to bottom. Place an upstream link at the sentence that actually defers to it, so it survives a partial read or a search hit, not only in a footer. Pages that are read whole (reference hubs, overviews) additionally aggregate their external links in a footer section so a whole-file reader sees every authority at once. Both placements together beat footer-only, because readers attend to the start and end of a document more than its middle ([Liu et al., "Lost in the Middle", TACL 2024](https://aclanthology.org/2024.tacl-1.9/)).
+
+## Two distinct footer kinds
+
+Keep research provenance separate from product documentation:
+
+- A **sources** footer holds research provenance, the durable reasoning behind a convention: books, talks, studies, papers.
+- An **external-authority** footer holds vendor, framework, and cloud *product* documentation URLs: the living references a reader fetches for current behavior.
+
+## Time-bound external claims need a recheck trigger
+
+A recorded upstream default, version gate, or price belongs in durable content only with an explicit recheck trigger: a date, an automation, or a tracked task. Prefer linking and fetching at read time over storing a snapshot at all. A snapshot with no recheck trigger is drift waiting to happen.
+
+## Label the basis of a recommendation
+
+Every recommendation, option, or decision an author or agent presents, and every recommended number, default, limit, or "best practice" in it, carries a `Basis:` label that names where it came from: a `file:line`, a tool's output, or a URL retrieved for it in the current session, or `judgment` when no source stands behind it. The label lets a reader check the claim without re-deriving it and shows which claims rest on the author alone.
+
+The rule covers what is presented from now on: a reply, a pull request or issue body, a design or decision record. It does not require relabeling tracked prose written before it, and a convention document is not such a presentation: its rules rest on its sources footer.
+
+`judgment` is not enough for a decision that spans repositories, changes shared infrastructure, cannot be undone, or bears on security. When research cannot settle such a decision, present it as an open question that names the evidence that would settle it, not as a recommendation.