msd-core/docs/contributor-standards.md

Contributor Standards

Standards for working with CONTEXT.md, docs/adr/, and AI-agent-assisted contributions.

These apply to every PR — fix, enhancement, or feature. They are part of the merge contract, not optional background reading.

Standards hierarchy (canonical, in order):

1. CONTEXT.md — domain language and module naming
2. docs/adr/ — accepted architectural decisions
3. Approved issue scope

---

CONTEXT.md

What it is

CONTEXT.md is the single source of truth for domain vocabulary. It defines:

• Domain modules and seams — canonical Module names, seam vocabulary, and Interface names (e.g. Dispatch Policy Module, Command Contract Validation Module, Planning Workspace Module)
• Recurring PR mistakes — CodeRabbit findings that recur; covers tests, shell guards, changesets, docs
• Workflow learnings — patterns distilled from triage + PR cycles

Format

CONTEXT.md is written as flat named sections under ## Glossary — Domain modules and seams (for Modules/seams) and ## sections for recurring rules. Machine-oriented predicates use KEY.SUBKEY=value flat format, grouped into the ## section that owns the topic — ## Test rules and lint, ## CodeRabbit + repo-process guards (machine-oriented predicates), or ## Workspace seams (machine-oriented predicates).

Adding a new Module or seam:

• Add a ### <Module Name> entry under ## Glossary — Domain modules and seams.
• Write one paragraph. State what the Module owns. Be concrete — list the Interface names and policy boundaries it covers.
• Do not add synonyms; pick one name and use it everywhere.

Extending an existing predicate:

• Add a KEY.SUBKEY=value line inside the relevant predicate section — for a test or lint rule that is ## Test rules and lint.
• Do not create a new top-level section for a variation on an existing concept.

When to add a new predicate vs extend an existing one:

• New predicate: the concept has a distinct identity, distinct owner, and is not covered by any existing section.
• Extend existing: the new fact qualifies, constrains, or amends an already-named Module. Add it as a sub-entry or amendment paragraph.

Contributor requirements

• Read CONTEXT.md in full before naming anything (modules, interfaces, seams, tests, PRs).
• Use CONTEXT.md vocabulary consistently in code comments, tests, issue/PR text, and docs.
• Do not invent synonyms. If you need a concept that is not in the glossary, note it explicitly in the issue or PR rather than using ad-hoc language.
• Do not rewrite CONTEXT.md as part of drive-by cleanup; propose focused updates tied to the approved issue scope.
• CONTEXT.md is maintainer-owned. Contributors can propose additions via issue discussion, but final wording is the maintainer's call.

Example (correct)

A PR that adds a new query adapter should use the term Native Dispatch Adapter Module (from CONTEXT.md), not "native adapter," "query native handler," or any other variant.

---

ADRs

What they are

docs/adr/ contains Architecture Decision Records. Each ADR is a concise record of one accepted decision: the problem, the decision, and the consequences. Accepted ADRs are the current standard.

Currently accepted ADRs:

File	Decision
0001-dispatch-policy-module.md	Dispatch Policy Module as the single seam for query execution outcomes
0002-command-contract-validation-module.md	Command Contract Validation Module / command contract centralization
0003-model-catalog-module.md	Model Catalog Module as the single source of truth for agent profiles and runtime tier defaults
0004-worktree-workstream-seam-module.md	Planning Workspace Module as single seam for worktree and workstream state
0005-sdk-architecture-seam-map.md	SDK Architecture seam map for query/runtime surfaces
0006-planning-path-projection-module.md	Planning Path Projection Module for SDK query handlers
0007-sdk-package-seam-module.md	SDK Package Seam Module owns SDK-to-msd-core compatibility

When an ADR is required

An ADR is required when a decision:

• Introduces or removes a Module seam that other code will depend on.
• Changes the policy contract of an existing accepted ADR.
• Establishes a new architectural invariant (naming convention, test contract, CI enforcement).

An ADR is optional (a comment in the relevant issue or PR is sufficient) when:

• The change is a bugfix that lands squarely within an existing accepted decision.
• The change is a docs or test improvement with no architectural surface.

Naming conventions

New ADRs and PRDs use issue#-prefix slug naming. This is a contributor requirement, not a suggestion.

docs/adr/<issue#>-<kebab-slug>.md    (new ADRs)
docs/prd/<issue#>-<kebab-slug>.md    (new PRDs)

Example: docs/adr/2264-golden-parity-redesign.md.

Why: GitHub issue numbers are server-assigned and atomic — the reservation mechanism already exists because the issue-first rule requires it. Promoting the issue# to the artifact ID eliminates the entire collision class that the NNNN-* local-compute scheme created (see the 0010-* × 2 and 0011-* × 3 duplicates on disk).

Migration policy: Legacy ADRs keep their numbers as immutable historical record — see the authoritative legacy-range statement in docs/adr/README.md for exactly which zero-padded files that covers (and which zero-padded files are actually modern, mis-padded). Do not renumber legacy files. The new convention applies to all ADRs and PRDs created on or after the merge of the implementing PR (#3485 — a pre-rename number from get-shit-done-redux; it does not resolve in golem15com/msd-core, whose issue numbering restarted at the rename).

For the end-to-end workflow — opening the issue, waiting for approval, creating the file, and submitting the PR — see CONTRIBUTING.md — "Proposing an ADR or PRD".

The legacy four-digit scheme (0003-model-catalog-module.md) applies only to pre-existing files.

Required sections

Every ADR must open with:

# <Title>

- **Status:** Accepted | Proposed | Deprecated
- **Date:** YYYY-MM-DD

Body: one-paragraph decision summary, then ## Decision (specifics), then ## Consequences (behavioral changes downstream callers can rely on).

Amending an accepted ADR

An accepted ADR is never rewritten — it is amended. Before concluding that a change needs a brand-new ADR, check whether a broader existing ADR already owns the area: 857-capability-system.md's Consequences and Ratification sections, for example, explicitly name the Loop Extension Points and their render-hook call sites — a change to that contract amends 857, it does not leave the area without a governing ADR. Two patterns are established, chosen by size:

1. In-place dated section (the default; use this first). For an addition that stays within the ADR's existing decision, append a ## Amendment (YYYY-MM-DD): <topic> section to the end of the same file — the original ## Decision / ## Consequences body is never rewritten, and the dated marker can be the heading itself or the section's opening line. This is the common case: see 1239-msd-embeddable-orchestration-engine.md (PR #4146) and 1411-resolution-provenance.md (PR #2678).

2. A separate ADR that Amends the original. When the addition is substantial enough to warrant its own issue and its own ## Decision / ## Consequences — not just a section — write it as its own file (docs/adr/<issue#>-<slug>.md, per "Naming conventions" above) and declare the relation in its header:

- **Amends:** [ADR-<n>](<n>-slug.md) — <one-line reason>

The amended ADR must record the reciprocal pointer in its own header, in the same PR:

- **Amended by:** [ADR-<new>](<new>-slug.md) — <one-line summary of what changed>

This mirrors the Supersedes/Superseded by and Subsumes/Subsumed by reciprocity rule in docs/adr/README.md — a one-way Amends pointer is the same failure mode: a reader who lands on the original ADR has no way to know it was extended. See 2782-reviewer-lane-capability-surface.md, whose single Amends field lists four targets (857-capability-system.md, 894-capability-declaration-format.md, 1016-runtime-capability-descriptor.md, 1244-capability-ecosystem.md) — all four carry the reciprocal **Amended by:** [ADR-2782] back-link, added in the same PR.

Note: unlike Supersedes/Subsumes, Amends/Amended by reciprocity is convention, not yet machine-checked by scripts/gen-adr-index.cjs — get the back-link right by hand and by review.

Status block format

- **Status:** Accepted
- **Date:** 2026-05-09

Status values: Proposed (under discussion), Accepted (current standard), Deprecated (superseded — include a forward reference to the replacement).

Cross-reference style

Reference sibling ADRs by filename, not by title prose: see \0001-dispatch-policy-module.md``. This survives title edits.

ADR README index

docs/adr/README.md maintains the canonical index table and the naming convention documentation. The table in this document (above) covers accepted ADRs for contributor reference. If an ADR is added, update both tables in the same PR.

Governance

• ADR creation and final wording is maintainer-owned. Contributors must not open ADR files as part of a contribution PR.
• Contributors can — and should — give input on proposed ADR direction in the linked issue discussion.
• Once an ADR is Accepted, reopening the decision must be explicit (a dedicated issue with rationale), not implied by a drive-by PR change.
• If your PR intentionally revisits an accepted ADR decision, call it out explicitly in the issue and the PR body: "This revisits ADR-0002 because…"

---

AI-agent-assisted work

When AI assistance is appropriate

AI assistance is appropriate for every contribution type. The bar for correctness and review quality does not change because the code was AI-assisted.

Pre-work requirements

Before any AI agent writes a single line of code or docs, it must read:

1. CONTEXT.md in full.
2. The ADRs relevant to the area being changed (check docs/adr/).
3. The approved issue scope.

If you are dispatching an AI agent, include these reads in the agent's prompt explicitly. An agent that invents synonyms for CONTEXT.md vocabulary or contradicts an accepted ADR without flagging it has failed the pre-work requirement.

Citing a machine-oriented predicate in a brief. CONTEXT.md's KEY.SUBKEY=value predicates (see below) must be cited by ID verbatim, never paraphrased (META.RULE.brief-must-cite-doc, META.RULE.brief-no-paraphrase). Rather than grepping the file by eye for the predicate set a brief needs, pull it with the selector, which parses the live file on every call:

node msd-tools.cjs query context-predicates --class <CLASS> | --prefix <dotted.prefix> | --contains <text>

See query context-predicates for the full flag and output reference.

In the PR body, state which ADR or standards section was followed. If using an AI assistant, this statement is your responsibility as the author — not the agent's.

Worktree isolation

Agent-written code must use an isolated worktree to prevent branch pollution. The standard pattern:

git worktree add ../my-feature-worktree fix/NNNN-short-description

Never commit agent output directly to main or to an already-open feature branch without review.

Model selection

Sonnet for most tasks — implementation, test writing, docs, triage. Use the current Sonnet model unless the task requires deep reasoning over a large context.

Opus for architecture-level tasks — ADR authorship (maintainer only), cross-cutting refactors, adversarial review of complex PRs. Using a more capable model when a capable model suffices wastes context and delays the cycle.

General-purpose vs specialist agents: prefer the specialist agent for the domain (e.g. a TypeScript-aware agent for SDK surface changes, a docs-aware agent for contributor docs) over a general-purpose agent. Specialist agents load less irrelevant context.

TDD discipline

For any Behavior-Adding Task (see CONTEXT.md):

1. RED — commit a failing test that names the expected behavior before writing the implementation.
2. GREEN — write the minimum implementation that makes the test pass.
3. REFACTOR — polish without changing behavior; tests must still pass.

Commit each phase separately. A PR that has no failing-test commit for a new behavior will be asked to add one before merge.

Adversarial review requirement

Before opening a PR:

• Read each changed section as if you are a hostile reviewer. Does it stand alone? Does it cite existing artefacts accurately? Is anything aspirational that is not actually current practice?
• Mark aspirational items as [proposed] in the text if they describe future intent rather than current behavior.
• Check that every cross-reference (file path, ADR number, CONTEXT.md term) resolves to something that actually exists on disk.

CR-loop discipline

After a reviewer thread is addressed:

• Fix the code or docs in a new commit (never amend a pushed commit).
• Resolve the thread via GraphQL mutation — do not rely on auto-resolve and do not post a reply comment:

gh api graphql -f query='mutation { resolveReviewThread(input:{threadId:"PRRT_..."}) { thread { isResolved } } }'

Address every reviewer finding claim-by-claim. Do not dismiss a thread because one sub-claim is a false positive — read all sub-claims before deciding.

Standards followed — block (proposed)

The maintainer is evaluating whether to require a ## Standards followed block in every issue and PR body. Current proposal:

• Enhancements and features: required. List the ADR(s) and CONTEXT.md section(s) consulted.
• Bug fixes: lighter-weight. A one-line note suffices: "Follows ADR-0002 command contract."

This is marked [proposed] — it is not yet a merge gate. Feedback on workflow impact is welcome in issue #3232.