Skip to content

Process Specifications

How we run this project. Covers CI configuration, GitHub workflow, agent conventions, documentation standards, and spec authoring rules.

Behavioral Specifications

The following specifications define Event-Condition-Action (ECA) behavioral requirements with typed preconditions, ordered steps, and postconditions.

Architecture

Defines the architectural constraints for the Vultron codebase. The system follows hexagonal architecture (Ports and Adapters): the core domain is isolated from all external systems, which interact through defined ports via thin adapters. Covers layer separation rules, the core object hierarchy, domain model richness, and the fail-fast validation boundary.

File ID: ARCH

Architecture Ratchet Discipline

ID Priority Requirement Related
ARCH-18-001 MUST Architecture boundary tests that enforce a KNOWN_VIOLATIONS allowlist MUST use a bidirectional equality assertion: assert actual_violations == KNOWN_VIOLATIONS. One-directional subset assertions (assert actual ⊆ KNOWN) are prohibited because they allow the violation count to grow silently.

A subset assertion says "we have at most these violations". A violation that is fixed can then stay on the known list, and a later change can bring it back while the test still passes. Bidirectional equality says "we have exactly these violations": any addition fails immediately, and a fixed violation fails until its entry is removed (ARCH-18-002).
ARCH-18-002 MUST The commit that resolves a known architectural violation, by removing or refactoring the file or import, MUST remove its entry from the KNOWN_VIOLATIONS allowlist.

The exact-set check (ARCH-18-001) fails as soon as a listed violation is gone. A removal in the same commit keeps the allowlist equal to the real violations at every commit.
Derives from: ARCH-18-001
ARCH-18-006 MUST NOT A KNOWN_VIOLATIONS allowlist MUST NOT keep an entry that no longer matches a real violation.

Stale entries hide the true state of the architecture boundary. A fixed violation that stays listed makes the ratchet look tighter than it is. It also hides a regression when a new violation with the same name appears later.
Extends: ARCH-18-002
ARCH-18-003 MUST Each non-empty ratchet baseline under test/ MUST carry an # owner: #N comment that names the GitHub issue that owns driving it to its terminal value. A baseline is an allowlist, exclusion set or numeric ceiling not at its terminal value.

A ratchet records what is exempt but not who retires it. When the issue that created a baseline closes with entries left, the debt becomes invisible and the test stays green. MS-10-006 already imposes this rule on the spec-corpus ceilings; this extends it to every baseline.
ARCH-18-007 MUST A permanent-by-design baseline MUST carry a # permanent: <reference> comment, not an owner comment, citing the issue, ADR or spec requirement behind it.

The permanent marker keeps a pinned exemption set from needing an invented owner. It also keeps the decision behind the set citable.
Extends: ARCH-18-003
ARCH-18-004 SHOULD A CI job outside the merge path SHOULD query GitHub for the state of every issue that an # owner: #N comment cites.

Only GitHub knows whether an owner is still open, so this check cannot run in the unit suite.
Extends: ARCH-18-003
ARCH-18-008 SHOULD When an owner issue that a baseline cites is closed, the ARCH-18-004 job SHOULD file or update one tracking issue that lists the affected baselines.

One tracking issue gathers every baseline that lost its owner, so a person can find and re-own them in one place.
Extends: ARCH-18-004
ARCH-18-009 MUST NOT The ARCH-18-004 job MUST NOT fail the build on a closed owner.

Failing the build on it would turn main red when an unrelated issue closes, which no pull request caused. This is the same race a two-directional count pin produces when two pull requests land together.
Extends: ARCH-18-004
ARCH-18-005 MUST A ratchet is a baseline under test/ that an # owner: #N issue drives to an empty set or a zero ceiling. A pinned exemption set is an exact set with no terminal value, kept equal to reality in both directions (ARCH-18-001, ARCH-18-002). Its entries are exempt by a recorded decision, not waiting for a fix. Only a ratchet counts as open debt. A pinned exemption set MUST carry the # permanent: marker of ARCH-18-007.

Only a ratchet is open debt. A reader who counts open debt must thus know which exact sets are ratchets and which are permanent. Both kinds use the same equality check in both directions. The difference is whether an end state exists, so the marker must state it.
Refines: ARCH-18-007
Uses definition from: ARCH-18-001
Uses definition from: ARCH-18-002
ARCH-18-010 MUST The comment and module docstring of a pinned exemption set MUST call that constant a pinned exemption set, not a ratchet or a backlog.

A reader who counts open debt reads the comment and the docstring. If they call a pinned set a ratchet or a backlog, the reader counts permanent exemptions as debt.
Extends: ARCH-18-005
ARCH-18-011 MUST A pinned exemption set entry that waits for a fix MUST move to its own ratchet constant with an # owner: #N marker.

If a pinned set holds an entry that waits for a fix, that debt is hidden in a set that nobody plans to empty.
Extends: ARCH-18-005
ARCH-18-012 MUST A pull-request check MUST fail when the pull request's body closes an issue that an # owner: #N marker on a ratchet baseline under test/ still cites after the pull request's changes.

A merge that closes the owner while its entries remain leaves the debt with no owner, and the closed-owner report (ARCH-18-004) only notices afterwards, without failing the build (ARCH-18-009). Refusing the merge keeps an owner open until its ratchet is empty. A manual close is still caught by the report.
Extends: ARCH-18-003

Behavior Tree Integration

Requirements for integrating py_trees behavior trees into Vultron handler functions. Covers the BT execution model, state management via the DataLayer, handler integration patterns, actor isolation, concurrency constraints, and failure diagnosis. Complex protocol workflows such as report validation, case creation, and embargo management must be implemented as BT nodes or subtrees.

File ID: BT

Fuzzer Node Replacement Lifecycle

ID Priority Requirement Related
BT-21-001 MUST Each fuzzer BT node targeted for production replacement MUST have a tracking issue that records the node name, the replacement design and the blocking dependencies. The replacement design is a BT-20 entry or equivalent.

Without a tracking issue per fuzzer node, the replacement backlog is invisible in the project board. The BT-20 entries document the design; this entry mandates the process artefact (issue) that makes the work schedulable.
BT-21-003 MUST The relevant BT-20 entry's tracking_issue field MUST link the tracking issue of each fuzzer node that the entry replaces.

The BT-20 entry documents the design, and the issue makes the work schedulable. A link from the entry lets a reader go from the design to the work.
Extends: BT-21-001
BT-21-004 MUST The pull request that replaces a fuzzer node with its production equivalent MUST close the BT-21-001 tracking issue of that node.

An open tracking issue for a node already replaced shows work that is done as still to do. Closing it in the same pull request keeps the spec and the project board consistent.
Extends: BT-21-001

Behavior Tree Composability

Requirements for implementing Vultron's behavioral logic as composable, reusable BT structures using the simulator as the canonical blueprint. Covers the workflow of BT composition: how to use the simulator reference, where structures must live, when to use BT composite idioms instead of procedural code, and the fractal composability principle that applies at every depth.

File ID: BTC

Simulator Reference Workflow

ID Priority Requirement Related
BTC-01-003 MUST If a corresponding simulator class does NOT exist for the behavior being implemented, the developer MUST document the divergence with a brief rationale comment before proceeding.

A node with no simulator counterpart departs from the canonical design. Without a written reason, a later reader cannot tell a deliberate extension from a mistake. The reader also cannot check the node against the protocol.
Extends: BTC-01-002

Build Workflow Learnings Policy

Defines the content policy for the per-entry incoming learnings queue used by the build and bugfix skills to pass implementation observations upstream to the learn skill. Covers what belongs in the queue, what must not go there, file naming and format, how the learn skill processes and archives entries, and the learning history entry type. The queue is narrow by design: findings with a definite owner are routed to a GitHub issue or an in-session fix at the moment of discovery, and only unverified general claims and spec divergences are queued for batch processing (BW-07).

File ID: BW

Incoming Learnings Queue Content Policy

ID Priority Requirement Related
BW-01-001 MUST plan/incoming/learnings/ MUST contain only implementation observations, open questions, constraints and insights. Each one comes from a build or bugfix run and bears on future implementation work.

The queue is a focused upstream communication channel from executing skills to the learn skill. Mixing status updates with actionable insights dilutes the signal and creates noise for learn to filter. Thus completion summaries, "what was done" narratives and status updates do not go in the queue (BW-01-002).
BW-01-002 MUST NOT The build and bugfix skills MUST NOT write completion summaries or task-status narratives to plan/incoming/learnings/.

A completion summary in the queue gives learn nothing to promote. It also hides the observations that learn must act on. Completion summaries have their own record (HM-05-001).
Derives from: BW-01-001
BW-01-003 MUST Each incoming learning file MUST be named YYYYMMDD-SLUG.md. YYYYMMDD is the creation date. SLUG is a short, lowercase, hyphenated phrase that describes the observation.

One file for each learning lets each branch record an observation without merge conflicts on a shared file. The date prefix sorts the directory by date. By convention, the slug is the originating issue number and then a descriptive phrase, for example 20260918-3399-bt18-has-no-contract-for-a-refusal-carrying-a-payload.md.
BW-01-008 MUST NOT A tool or skill MUST NOT require a learning file's SLUG to equal or derive from its source frontmatter field.

The source field carries the link to the originating work item (BW-02-002), so the filename does not have to carry it. One work item can produce many learnings. A name from source gives all of them the same filename.
Uses definition from: BW-01-003
BW-01-009 MAY One work item MAY produce several incoming learning files.

One session can find several unrelated observations. Each one needs its own file, so that learn can promote, archive or reject each one separately.
BW-01-010 MUST Each incoming learning file's SLUG MUST differ from the SLUG of every other file in the queue with the same date prefix.

Two files with the same date and slug have the same filename. Then the second file overwrites the first, and the first observation is lost. This can occur when one work item produces several learnings on one day (BW-01-009).
Extends: BW-01-003
BW-01-006 MUST Incoming learning files MUST be committed as part of the originating PR so the learning is permanently linked to the work that produced it.

A learning that is committed with its PR stays linked to the change that produced it. It goes into main when the change does. A learning that is committed separately can be lost when a branch is abandoned. It can also arrive before or after the work that it describes.
BW-01-004 MUST NOT Skills other than build and bugfix MUST NOT create files in plan/incoming/learnings/.

plan/incoming/learnings/ is specifically a channel for code-execution insights flowing from build/bugfix to learn. Gap-analysis observations from update-plan are a different signal and belong in notes directly.
BW-01-007 MUST The update-plan skill MUST write observations and open questions directly to the notes/*.md file whose topic matches the content.

Gap-analysis observations already have a topic file in notes/. If they go into the learnings queue first, a later step must move them to notes/. A direct write also keeps the queue for build and bugfix output only (BW-01-004), so update-plan does not stage its observations there.

Incoming Learnings File Format

ID Priority Requirement Related
BW-02-001 MUST Every file in plan/incoming/learnings/ MUST use the same YAML frontmatter format as history entry files: required fields title, type (value learning), timestamp (tz-aware ISO 8601 UTC), and source (the originating work-item identifier, per BW-02-002). The incoming file is named YYYYMMDD-SLUG.md, which is a different naming scheme from the archived entry — the archived filename is derived from source, not carried over from the incoming name.

Using identical format means archiving is a git mv equivalent via uv run append-history --from-file — no content transformation needed.
Uses definition from: HM-02-001
Uses definition from: BW-02-002
BW-02-002 MUST The source field of an incoming learning file MUST be the originating work-item identifier, not the file's YYYYMMDD-SLUG stem. Examples are ISSUE-<n>, CONCERN-<n>, IDEA-<n> and BUG-<n>.

source identifies the work item that produced the observation. HM-02-001 defines it as an originating identifier. append-history uses it to name the archived file. Thus it must be the work-item ID, so that a reader of that item can find the archived entry. The incoming filename is the date and slug (BW-01-003), which is a different value. Many incoming files can have the same source when one work item produced several observations.
Uses definition from: HM-02-001
BW-02-003 MUST The timestamp field in an incoming learning file MUST reflect the actual creation time of the observation (not the current date if the entry was written for a historical run).

learn sorts entries by timestamp and uses it to find old entries. For example, it archives an uncorroborated theme candidate after 30 days (BW-07-007). If the timestamp is the date of writing, not the date of the observation, a backfilled entry goes into the wrong position.
Extends: BW-02-001
BW-02-004 MUST NOT The timestamp field MUST NOT be written as a bare YYYY-MM-DD date. _coerce_to_utc() in vultron/metadata/history/models.py rejects any value that is not timezone-aware, and YAML parses a bare date into a naive datetime, so a bare-date entry fails validation the moment append-history --from-file reads it. Write "YYYY-MM-DDTHH:MM:SSZ" (quoted, so YAML yields a string for Pydantic to parse) and use T00:00:00Z when only the date is known.

This is stated separately because bare dates are the dominant form currently present in plan/incoming/learnings/ and are silently accepted by every check except the archiving step — the one that matters. An entry written this way looks fine in review and then cannot be archived, so the defect surfaces only when learn tries to process it.
Derives from: BW-02-001
BW-02-005 MUST Conformance to BW-02-001 through BW-02-004 MUST be checked at commit time by validating every file in plan/incoming/learnings/ through HistoryEntryFrontmatter — the same model append-history --from-file uses — so the check and the archiver cannot drift. A validator that reimplements the rules independently does not satisfy this.

Without a commit-time check, learn finds frontmatter that the archiver rejects. This is frequently weeks after the author wrote the file, and then the entry cannot be archived. A commit-time check with the archiver's own model finds the error while the author has the file. Because the check and the archiver use one model, they cannot disagree.
Verifies: BW-02-001
Verifies: BW-02-004

learn Skill Processing

ID Priority Requirement Related
BW-03-001 MUST When the learn skill processes plan/incoming/learnings/, each file MUST be promoted to the durable destination matching the content type — requirements to specs/*.yaml, design insights to notes/*.md, agent guidance to AGENTS.md — before being archived via uv run append-history --from-file <path>.

The queue is a temporary location, not a durable one. If a learning is archived before its content goes into a spec, a note or AGENTS.md, the queue loses it and the project does not keep the lesson.
BW-03-002 MUST An agent MUST archive each processed incoming learning file with uv run append-history --from-file <path>, not by moving it by hand.

Using the CLI tool preserves the audit trail, regenerates the monthly history README, and enforces write-once semantics. The command moves the file from plan/incoming/learnings/ to plan/history/YYMM/learning/ and deletes the source (BW-05-004), so no archived file stays in the queue. It keeps the file's frontmatter as written, where another method can type it again incorrectly.
BW-03-003 SHOULD After a complete learn cycle, plan/incoming/learnings/ SHOULD contain only a .gitkeep file.

Each learn cycle must process all queued entries. An empty queue after the cycle shows that the cycle did not skip an entry. An entry that stays in the queue shows that processing is not complete.

Skill Documentation Updates

ID Priority Requirement Related
BW-06-001 MUST The build skill documentation MUST distinguish between learnings (observations and constraints recorded as individual files in plan/incoming/learnings/) and completion summaries (archived via uv run append-history implementation). Both outputs are required; neither may be omitted or combined.

The two outputs have different readers. Learnings go to learn, and completion summaries go to the record of the work item. If the documentation does not keep them separate, agents omit one, or they put a summary in the queue.
BW-06-002 MUST The learn skill documentation MUST name plan/incoming/learnings/ as its primary input source.

learn agents follow the skill text. If the skill does not name the queue, agents do not read the entries.
BW-06-004 MUST The learn skill documentation MUST describe the append-history --from-file archiving lifecycle.

learn agents follow the skill text. If the skill does not describe the archive step, agents leave the entries in the queue after processing.
Extends: BW-06-002
BW-06-003 MUST NOT The update-plan skill MUST NOT instruct agents to write to plan/incoming/learnings/.

Agents follow the skill text. If update-plan tells agents to write to the queue, it contradicts BW-01-007, which sends gap-analysis observations directly to notes/*.md. It also puts those observations in a channel that is for build and bugfix output.

Upward-Reflection Finding Routing

ID Priority Requirement Related
BW-07-001 MUST Before an agent completes a build or bugfix session, it MUST run an upward-reflection checklist. The checklist asks explicitly whether the session found each of six things. The first two are behaviour with no spec entry, and a requirement that was unclear or conflicted with another. The next two are something that exists but is wrong, and something that should exist but does not. The last two are a broken tool, skill or tracking artefact, and a narrow but true fact about the code.

Without a mandatory checklist, agents usually record only small tactical tips. They do not record the more important problems: spec gaps, conflicts and broken tools. The checklist asks each question explicitly. Each triggered item goes to one destination (BW-07-004), so somebody acts on it, and it is not only recorded. A session that records nothing is valid only if the agent completed the checklist and every answer was "no".
BW-07-002 SHOULD Incoming learning files SHOULD include a signal: frontmatter field set to one of theme-candidate, spec-gap, spec-ambiguity, or spec-contradiction. The values design-question, concern, tooling-issue, and process-issue are retired: findings of those kinds are routed to a GitHub issue or an in-session fix per BW-07-004 and do not produce a learning file.

The retired values all named findings with a definite owner and a definite action, which made the queue a waiting room for work that could already have started. The surviving values name the two things that genuinely require a batch — an unverified general claim, and a divergence between spec and reality.
Derives from: BW-07-004 — The taxonomy is a consequence of the routing table rather than an independent list.
BW-07-003 MUST The learn skill MUST process learning files tagged signal: spec-gap, signal: spec-contradiction, or signal: spec-ambiguity before processing signal: theme-candidate or untagged entries.

These signal types represent cases where the specification has diverged from reality or contains internal conflicts. Deferring them risks future build sessions making the same gap-driven interpretations independently.
BW-07-004 MUST Each triggered checklist item MUST be routed at discovery to exactly one destination. Something that exists but is wrong → a GitHub type:Bug, type:Task, or type:Concern issue, chosen by the shape of the work. Something that should exist but does not → a GitHub type:Idea issue. A broken tool, skill, or tracking artefact → a fix applied in the same session. A narrow, symptom-retrievable fact about the code → an assertion at the site (regression test, type annotation, or comment) in the same session. A general claim that cannot be verified from a single instance → a signal: theme-candidate learning file. Behaviour with no spec entry, or an unclear or conflicting requirement → a signal: spec-* learning file. Only the last two destinations produce a learning file.

A finding with a known owner and a known action does not need to wait for the next learn batch. If it waits, each agent before that batch can find the same problem again. Only an unverified general claim, or a difference between spec and code, needs a batch. Thus only those two produce a learning file.
BW-07-005 MUST NOT The learn skill MUST NOT promote a claim to notes/ or AGENTS.md on the strength of a single learning file. Promotion requires at least two independent witnesses — two entries from different source work items making the same claim — or independent confirmation against the code.

A single build session cannot distinguish a general pattern from a local accident, and its author is the party least able to judge which it is. Corroboration is the cheapest available test. The queue exists to accumulate it.
BW-07-006 MUST When a session produces a finding that corroborates an existing queued signal: theme-candidate entry, the agent MUST file or update a GitHub issue (type:Bug, type:Task, or type:Concern, chosen by the shape of the work) for the now-corroborated theme in that session rather than adding a second learning file and waiting for learn.

A second finding that agrees with a theme candidate makes the claim trustworthy, so that is the time to act. Without this rule, a corroborated theme stays in the queue until the next learn run. The corroboration threshold would then cause the delay that it must prevent.
Supersedes: BW-07-004
BW-07-007 SHOULD A signal: theme-candidate entry that has received no corroborating witness within 30 days of its timestamp SHOULD be archived by learn as unreproduced, via append-history learning, without promotion to notes/ or AGENTS.md.

An uncorroborated claim that has not recurred in a month is more likely to have been a local accident than a pattern. Archiving preserves the record without letting the queue grow without bound.
Uses definition from: BW-07-005
BW-07-008 MUST NOT A decision that was made, applied, and shipped within the session — leaving no open question and asking nothing of any future reader — MUST NOT be recorded as a learning file. The commit message, the diff, and the PR body are its record.

Such entries cannot satisfy the completeness rule that a learning must produce a durable output, because there is no output left to produce. They are guaranteed to be archived unpromoted, and the reader who processes them recovers nothing.
Refines: BW-01-001 — A closed decision is a completion summary in the shape of an insight.
BW-07-009 MUST This rule covers each code-review finding in a file that the current change did not touch. An agent MUST file each such finding as a GitHub type:Bug, type:Task or type:Concern issue, in the session that surfaced it.

Such findings are pre-existing findings and findings deferred as out of scope. A PR comment records a finding but does not schedule it, so a PR-comment advisory alone does not meet this rule. A merged PR records what shipped, not what was deferred. Only an issue keeps the finding open until somebody resolves it.
Refines: BW-07-004
BW-07-010 MUST NOT An agent MUST NOT record a code-review finding in a file that the current change did not touch as a learning file.

Nobody can assign, schedule or close a learning file. Thus a finding in a learning file is not tracked, but it can seem tracked. The finding goes to an issue instead (BW-07-009).
Extends: BW-07-009

Case Ledger Processing

Requirements for participant assertions, CASE_MANAGER canonicalization, local case audit ledgering, recorded-history projection, and replication-facing CaseLedgerEntry objects. Covers the commit authorization model, per-case genesis hash derivation, the canonical entry criteria that separate the case ledger from the process log, the CASE_MANAGER inbox routing path that enables ledger entry authorship, and the causal-ordering model that makes log_index order the authoritative causal sequence.

File ID: CLP

CASE_MANAGER Inbox Routing for Canonical Ledger Entry Authorship

Requirements for the end-to-end routing path that delivers protocol-significant activities to the CASE_MANAGER's inbox so the CASE_MANAGER can author canonical ledger entries. Covers outbound addressing rules, the rule that the CASE_MANAGER commits its own emissions in the emitting tree rather than addressing a copy to itself (ADR-0109), and the rule that a received-side use case runs its tree only as the receiving actor.

ID Priority Requirement Related
CLP-10-020 MUST test/architecture/test_no_dl_mutations_in_execute.py MUST flag a DataLayer write that a received-side execute() body reaches through a helper. A helper is any function or method defined under vultron/core/use_cases/, resolved transitively. A received-side execute() is that of a use case under vultron/core/use_cases/received/.

A write that a helper does for execute() is still a write by execute(). A test that sees only the writes in the execute() body misses them, so it would pass code that the rule forbids. A write inside a BT node is allowed, so the resolution stops at the use-case package boundary. Trigger-side execute() and _prepare() bodies follow BT-15-001, not this rule.
Verifies: CLP-10-030
CLP-10-040 MUST test/architecture/test_no_dl_mutations_in_execute.py MUST list the remaining violations (CLP-10-020) as an exact KNOWN_VIOLATIONS set.

An exact set is a ratchet. A new violation fails the build, and a fixed one must leave the set, so the list never hides a regression (ARCH-18-001).
Extends: CLP-10-020
Refines: ARCH-18-001

CI Security

Requirements for securing CI/CD workflows and GitHub Actions usage in the Vultron project.

File ID: CISEC

Action Version Pinning

ID Priority Requirement Related
CISEC-01-001 MUST All uses: references to third-party or external actions in .github/workflows/*.yml MUST be pinned to a specific commit SHA rather than a version tag or branch name. Local path references to actions within this repository (e.g. ./.github/actions/<name>) are exempt — they are already pinned to the commit being checked out and have no separate tag/release lifecycle to pin against

The owner of an upstream action can move a tag or a branch to new code. Then changed code runs in CI with no change in this repository, and it can read secrets or change what CI builds. A commit SHA cannot move, so CI runs the same code until a change in this repository updates the pin. A local action is already fixed to the commit that CI checks out.
CISEC-01-002 MUST Each SHA-pinned uses: reference MUST carry an inline comment identifying the corresponding human-readable version tag (e.g., # v4.1.0) to aid maintainability

A reviewer cannot tell from a SHA alone which release it pins. The version comment shows the release. Then a reviewer can see when a pin is old, or when a security advisory applies to the pinned action.
CISEC-01-003 SHOULD A CI verification test SHOULD confirm that all uses: lines in .github/workflows/*.yml reference a SHA hash rather than a mutable version tag or branch name, and that each SHA line carries the human-readable version comment required by CISEC-01-002

A person can add an unpinned uses: line or drop a version comment by mistake, and review does not always see it. A test that reads every workflow file finds the mistake in CI. Then the pinning rules (CISEC-01-001, CISEC-01-002) do not depend on the memory of each author and reviewer.
Verifies: CISEC-01-001
Verifies: CISEC-01-002

Secrets Management

ID Priority Requirement Related
CISEC-02-001 MUST NOT A secret or token that a workflow uses MUST NOT appear in a repository file.

Every person who can read the repository can read a secret in a repository file. The secret also stays in the version history after someone deletes the file.
CISEC-02-003 MUST The maintainers MUST store each secret and token that a workflow uses in GitHub Secrets.

A workflow needs its secrets at run time, so they must be stored somewhere outside the repository files (CISEC-02-001). GitHub Secrets gives the value to the workflow and hides it in the job logs.
Implements: CISEC-02-001
CISEC-02-002 MUST The minimal set of permissions required MUST be declared explicitly via permissions: at the job or workflow level

If a workflow does not limit its token, the token gets the default permissions, which can be broad. A compromised step or action can then do everything the token allows. An explicit, minimal permissions: block limits that damage, and it shows a reviewer what each workflow can change.

Artifact Integrity

ID Priority Requirement Related
CISEC-03-001 MUST CI workflows that download third-party artifacts or tools MUST verify signatures or checksums before using them

Prevents supply-chain attacks via compromised artifacts

Maintenance

ID Priority Requirement Related
CISEC-04-001 SHOULD SHA pins SHOULD be reviewed and updated on a documented periodic cadence, at minimum when a security advisory is issued for the pinned action or when a new minor version is released

A pin that nobody updates keeps the known vulnerabilities of the pinned release, and the distance to the current release grows. A review on a fixed cadence, a review when an advisory is published, and a review for each new minor version keep the pins current. Each update is still a change that a person reviews.
CISEC-04-002 MUST When adding a new workflow step or action, the SHA pin and version annotation MUST be included before the step is merged to main

A step that merges without its pin runs unpinned code on main from the first run after the merge. A later fix does not undo what that run did. Thus the pin and its version comment must be in the change that adds the step.

CI Failure Notification

ID Priority Requirement Related
CISEC-05-001 MUST Every workflow that a push to main or a schedule event triggers MUST include a failure-conditioned step that files or updates a GitHub Issue.

Without a failure alert, nobody sees a broken main or a failed scheduled job until a developer looks at the Actions tab. An issue puts the failure in the issue tracker, where the team already triages work. A cancelled run is not a failure, so it must not cause an alert (CISEC-05-006).
CISEC-05-008 MUST The failure-conditioned notify step (CISEC-05-001) MUST use the shared .github/actions/notify-failure composite action.

One shared action makes the alert the same in every workflow. A fix to the alert logic then applies to every workflow at once.
Implements: CISEC-05-001
CISEC-05-002 MUST Every qualifying workflow (CISEC-05-001) MUST include a separate step, conditioned on success, that closes any open failure issue for that workflow.

A failure issue that stays open after the workflow recovers is misleading. The close step shows the recovery. Two dedicated steps (one on failure, one on success) keep each step single-purpose and avoid embedding workflow-status logic inside the composite action itself.
Uses definition from: CISEC-05-001
CISEC-05-009 MUST NOT The close step (CISEC-05-002) MUST NOT run on a cancelled run, such as a run that its concurrency group superseded.

A superseded run must not declare recovery. An aggregate with no failure but a cancelled result proves nothing about the commit, because the cancelled job might have failed had it run to completion. A step keyed on the success() status function already meets this rule. This is the mirror image of CISEC-05-015, where the notify step drops the same exclusion because a genuine failure beside a cancelled sibling is still genuine.
Extends: CISEC-05-002
CISEC-05-010 MUST A close step keyed on the needs.*.result aggregate MUST require the absence of cancelled, with !contains(needs.*.result, 'cancelled').

The aggregate does not exclude a cancelled run by itself, unlike the success() status function. Without the explicit check, a superseded run with no failure result closes the failure issue (CISEC-05-009).
Implements: CISEC-05-009
CISEC-05-003 MUST Each failure notification issue MUST carry the ci:main-failure label and a workflow-specific label, such as ci:workflow-python-app.

The composite action finds the open failure issue of a workflow by its labels. Without both labels, the action cannot find the issue to update or close it.
CISEC-05-011 MUST The two labels of CISEC-05-003 together MUST identify exactly one open failure issue for each workflow.

The composite action uses the label pair to find and update the open issue, not to file a duplicate. If two workflows share a pair, one workflow updates or closes the issue of the other.
Extends: CISEC-05-003
CISEC-05-012 MUST Within a workflow, exactly one job MUST run the notify step and the close step for its workflow-specific label.

The close step closes every open issue that has both labels. If several jobs each run a notify step and a close step under the same label, a job that passes closes the issue that another job filed. Then the job that finishes last decides if a failed main stays reported.
Uses definition from: CISEC-05-003
CISEC-05-013 MUST If several jobs can run in one workflow run, the reporting job MUST be a final job that needs: all others and keys on needs.*.result.

One final job that reads the result of every other job makes one decision for each run. Its notify and close steps then key on the aggregate as CISEC-05-010 and CISEC-05-015 require.
Implements: CISEC-05-012
CISEC-05-004 SHOULD A CI verification test SHOULD confirm that every qualifying workflow (push to main or schedule trigger) includes the .github/actions/notify-failure composite action step.

The author of each new workflow on main or on a schedule must remember to add the notify step. If the author forgets, the failures of that workflow cause no alert, and nobody sees that the alert is missing. A test that finds every qualifying workflow finds the missing step in CI.
CISEC-05-005 SHOULD A workflow triggered on the issues: labeled event SHOULD remove the ci:main-failure label at once when github.actor is not github-actions[bot].

This keeps the label bot-managed, and it prevents label spoofing that could suppress failure notification or create false alerts. The ci:main-failure label is the deduplication key used by the composite action to find and update an existing failure issue rather than creating a new one. If a human or external actor applies the label manually, the signal is corrupted — the action may comment on an unrelated issue or fail to file a new one. Bot-only enforcement keeps the alerting signal reliable.
CISEC-05-006 MUST NOT The failure-conditioned notify step (CISEC-05-001) MUST NOT file a failure issue on cancellation alone.

When a newer merge makes the concurrency group cancel a push run on main, the cancelled run is not a CI failure. The newer run gives the current result, and it files or closes the issue. A step keyed on the GitHub Actions failure() status function already meets this rule, because failure() is false on cancellation. The close step keeps its cancellation exclusion, because a cancelled run must not report recovery either (CISEC-05-009).
Refines: CISEC-05-001
CISEC-05-014 MUST The notify step MUST file when any job in the run genuinely failed, even if a sibling job in the same run was cancelled.

A newer push can cancel a job after another job really failed, for example lint jobs cancelled beside failing tests. The failure is still real, so the alert must not be lost. The failure() status function already meets this rule.
Refines: CISEC-05-001
CISEC-05-015 MUST A notify step keyed on the needs.*.result aggregate MUST key on contains(needs.*.result, 'failure') alone.

A guard can file on cancellation directly, for example with &#124;&#124; contains(needs.*.result, 'cancelled'). A guard can also require the absence of cancelled, for example with && !contains(needs.*.result, 'cancelled'). Such a guard cannot tell a real failure from a false one, so it hides the alert for a real failure beside a cancelled job. A guard on failure alone avoids both errors.
Implements: CISEC-05-006
Implements: CISEC-05-014
CISEC-05-016 MUST A qualifying workflow (CISEC-05-001) MUST skip every job that consumes another job's artifact when the producer job was cancelled.

A cancelled job can make a job that needs its artifact fail. That failure then shows in the needs.*.result aggregate, and the notify step files an alert for a failure that did not occur. The failure() status function is not affected by this. When the consumer is skipped, a failure in the aggregate is always genuine (CISEC-05-015). DEMOCI-04-007 applies this rule to the invariant harness.
Uses definition from: CISEC-05-001
Derives from: CISEC-05-006
CISEC-05-007 MUST A failure notification issue that the composite action files MUST carry the Bug issue type.

Without a type, no issue-type query finds the failure issue, and it is not triaged with the other bugs.
Extends: CISEC-05-001
CISEC-05-017 MUST The composite action MUST resolve the repository's Bug issue type by name and apply it with the updateIssue mutation, immediately after it creates the issue.

gh issue create cannot set an issue type, so a separate mutation is necessary. A lookup by name still works when someone creates the type again.
Implements: CISEC-05-007
CISEC-05-020 MUST NOT The composite action MUST NOT rely on a bug label for the label-to-issue-type workflow to convert into the Bug type.

An event that a workflow causes with its own GITHUB_TOKEN does not start other workflows, so the label-to-issue-type workflow never sees that label. An issue that relies on it stays untyped.
Constrains: CISEC-05-007
CISEC-05-018 MUST When a later notify run finds the open failure issue still untyped, the composite action MUST apply the Bug type then.

One mutation can fail for a transient reason. A later run then sets the type, so the issue does not stay untyped.
Implements: CISEC-05-007
CISEC-05-019 MUST The composite action MUST fail visibly when the repository has no Bug issue type.

If no Bug type exists, the action fails with an error, so the problem shows in the run. A silent pass would leave every failure issue untyped.
Extends: CISEC-05-017

CSAF Documents in Reports

Requirements for a Common Security Advisory Framework (CSAF) 2.1 document that travels as an attachment of a VulnerabilityReport: how it is carried and recognized, the one occasion on which a receiver may read it as the sender's statement (the initial Offer of a report), how its fields map onto the inputs of the case created from that report, and how this codebase checks documents against a CSAF 2.1 draft that is still changing. Producing a CSAF document from a case (a projection) is out of scope (#5134).

File ID: CSAF

Following the CSAF 2.1 Draft

ID Priority Requirement Related
CSAF-05-005 MUST A scheduled job MUST open an issue when an upstream change to the CSAF 2.1 draft would change the generated models, the profile text or the list of mandatory tests.

CSAF 2.1 is a draft that its Technical Committee can still change. Most upstream commits change neither the schema nor the profiles, so a filter on what the models and profiles depend on keeps the job from reporting them.
CSAF-05-006 MUST NOT The job of CSAF-05-005 MUST NOT open a second issue or comment on its open issue while that issue stays open.

One open issue says that the pin is behind. Repeating it adds noise and no information.
Extends: CSAF-05-005
CSAF-05-007 MUST The issue of CSAF-05-005 MUST say which of the CSAF fields that this codebase reads the upstream change affects.

A change to a field that sets a case input needs a review of its mapping, and a change elsewhere needs only a regeneration.
Extends: CSAF-05-005

Demo CI — GitHub Actions Demo Integration Workflow

Requirements for a GitHub Actions workflow that builds and runs Vultron demo containers on pull requests, and for hardening the demo runner to exit non-zero when the demo fails — closing the gap where tests pass while the demo produces silent failures. Includes requirements for the invariant harness to run as an independent CI gate so failures are visible even when the demo itself also fails.

File ID: DEMOCI

GitHub Actions Demo Workflow

ID Priority Requirement Related
DEMOCI-02-017 MUST The step of the demo job that runs the demo MUST have its own timeout-minutes, at least 5 minutes shorter than the job timeout (DEMOCI-02-009).

A job can reach its 15-minute cap after the demo passed, when the runner hangs in a post step that runs no project code. With a shorter bound on the demo step, a hung demo fails in that step, and a job that reaches the cap with the demo step green has hung after the demo. The difference also leaves time to collect the logs of a hung demo.
Uses definition from: DEMOCI-02-009
DEMOCI-02-018 MUST The demo image build MUST pull its Docker Hub images through a public registry mirror that needs no credential.

Anonymous Docker Hub pulls share a quota per runner. When the quota is spent, the build fails with 429 Too Many Requests before any project code runs, and a pull request goes red for a reason outside its diff. A login would need a secret, which a fork pull request does not get.
Extends: DEMOCI-02-005

Invariant Harness as an Independent CI Gate

ID Priority Requirement Related
DEMOCI-04-008 MUST Each attempt of the demo job MUST upload its case-log artifact under a name that carries the run attempt number.

A re-run of a failed job uploads a second artifact in the same workflow run. With one name for both, the harness of the re-run can download the first attempt's log and fail a demo that passed.
Implements: DEMOCI-04-003
DEMOCI-04-009 MUST The invariant-harness job MUST read the case-log artifact of the highest run attempt that is not later than its own.

The highest attempt not later than the harness's own is the demo run the harness follows. When only the harness is re-run, the demo keeps the artifact of its earlier attempt, so the harness cannot require its own attempt number.
Depends on: DEMOCI-04-008

Diátaxis documentation requirements

Brief requirements for organizing project documentation according to the Diátaxis framework.

File ID: DF

General architecture

ID Priority Requirement Related
DF-01-001 SHOULD Each reader-facing page SHOULD be one of the four Diátaxis content types — tutorial, how-to guide, explanation or reference — and declare it as its page_type (DF-11-018); the content types label pages and need not organize the site's navigation.

A reader arriving from search learns what kind of page they landed on from the page itself, while the navigation is free to group pages by subject and reader (ADR-0136). Keeping Diátaxis as a per-page property preserves its authoring discipline (DF-01-002 through DF-01-004) without making it the site's top level.
Uses definition from: DF-11-018
DF-01-002 MUST Ensure each documentation page maps to exactly one of the four user needs (Learning, Goals, Information, or Understanding).

A reader comes to a page with one need: to learn, to do a task, to look up a fact, or to understand. A page that serves one need can give that reader what they came for. A page that tries to serve two needs gives each reader text they did not ask for, and the author cannot tell which rules for voice and content apply.
DF-01-003 SHOULD NOT A documentation page SHOULD NOT combine more than one Diataxis content type in one page or section.

Each content type has its own rules for voice and content (DF-03 to DF-06). When one page mixes two types, the reader cannot tell which part to follow and which part to study, and a reviewer cannot apply one set of rules to the page.
DF-01-006 MUST Where a combined view of Diataxis content types is temporarily unavoidable, the page's author MUST separate the parts clearly.

A reader of a combined page must see where one content type stops and the next starts. Clear separation lets the reader find the part that serves their need, and lets a reviewer apply the rules of one type to each part.
Extends: DF-01-003
DF-01-007 MUST Where a combined view of Diataxis content types is temporarily unavoidable, the author MUST link each part to the canonical full page of its type.

A part of a combined page is a short view of one content type, not the full content. A link to the full page lets the reader go to the complete material, and keeps the full page as the one source for that content.
Extends: DF-01-003
DF-01-004 SHOULD Use hyperlinks to connect related but distinct content types instead of embedding cross-type content.

A link keeps each page to its own content type and lets the reader choose to go deeper. Text copied from a page of a different type mixes the types (DF-01-003) and makes a second copy that can become different from its source.
DF-01-005 SHOULD Write documentation in Markdown and prepare it for the MkDocs site defined by mkdocs.yml.

One source format and one site build let every page go through the same lint checks and the same strict build. A page in a different format gets neither check. A page outside the site that mkdocs.yml defines gets no strict build and does not appear in the published site.

Documentation maintenance

ID Priority Requirement Related
DF-02-001 SHOULD Build the documentation architecture iteratively from the inside-out by improving pages until their Diátaxis category is clear.

A complete structure that is planned before the pages exist is usually wrong, because the content shows where it belongs only when it is written well. When authors improve one page at a time until its type is clear, the structure follows the content, and each change is small enough to review.
DF-02-002 SHOULD Maintain navigation structure to avoid link breakage when moving or renaming files.

Readers and other pages link to a page by its path. When a file moves or changes its name and nothing points the old path to the new one, those links break, and a reader who follows them finds nothing.

Tutorials

ID Priority Requirement Related
DF-03-001 MUST Author tutorials as practical lessons that help learners acquire new skills through guided, hands-on experience.

A tutorial is for a reader who does not yet have the skill. That reader learns from doing the work with guidance, not from a description of the work. A tutorial that only describes gives the learner nothing to practice.
DF-03-002 MUST Require that each tutorial is an activity where the learner learns by doing.

A learner gets a skill from doing the steps, not from reading about them. When each part of the tutorial is an action, the learner practices the skill as they read.
DF-03-003 MUST Ensure tutorials produce visible results early and often to maintain learner confidence.

A learner does not yet know if they are on the correct track. A visible result after each short part tells them that they are, and keeps them working. A long run of steps with no result lets one early error stop the learner with no way to find it.
DF-03-004 MUST Use first-person plural ("we") in the tutorial narrative to establish tutor/learner rapport.

"We" tells the learner that the tutor goes through the steps with them. This makes the tutorial a shared activity, not a list of commands, and keeps the learner confident through the steps (DF-03-011 gives the scope of each pronoun).
DF-03-005 MUST NOT Forbid alternative learning paths within a single tutorial's primary flow; present a single prescribed learning path.

A learner cannot yet judge which of two paths is better for them. Each choice adds a decision they cannot make well and a path the author must test. One prescribed path lets the learner finish, and lets the author make sure that every step works.
DF-03-006 MUST NOT Exclude in-depth explanations and theoretical discussions from the body of tutorials; link to explanatory pages for background.

Explanation in a tutorial stops the activity and gives the learner theory before they have the experience to use it. A link to the explanation page keeps the steps short and lets the learner read the background when they are ready.
DF-03-007 MUST Require every tutorial step to produce a comprehensible result that gives immediate feedback.

Each step must show the learner that it worked. Without a result they can see and understand, the learner cannot tell an error from success, and an error stays hidden until a later step fails.
DF-03-008 MUST State at the start of each tutorial exactly what the learner will have accomplished.

A learner who knows the goal at the start can decide if the tutorial is the correct one for them. They can also see their progress toward the goal while they do the steps.
DF-03-009 MUST Point out specific signs or changes the learner should notice during the tutorial.

A new learner does not know which outputs are important. When the tutorial names the signs to look for, the learner can confirm each step and starts to learn what correct operation looks like.
DF-03-010 SHOULD provide explicit links to the related Reference and Explanation pages (prerequisites, background, deeper rationale). Keep these resources out of the tutorial body.

A learner who finishes a tutorial often wants the facts or the reasons behind it. Explicit links let them find those pages, and keeping the pages out of the tutorial body keeps the steps short (DF-03-006).
DF-03-011 MUST Tutorials MUST reserve first-person plural ("we") for the shared journey and use second person ("you") for the learner's own actions, possessions, and state.

DF-03-004 establishes "we" as the tutorial voice but does not say what it covers. The division of labor is what makes the voice work: "we" affirms the tutor/learner relationship, while "you" identifies who is acting and what they now have. Writing "we need Docker installed" misattributes the learner's prerequisite to the tutor, and pervasive "you should understand that" signals a tutorial drifting into Explanation.

How-to guides

ID Priority Requirement Related
DF-04-001 MUST Present how-to guides as goal-oriented directions that resolve a specific real-world task or problem.

A reader of a how-to guide has a task to do now. A guide that starts from that task, and stops when the task is done, gives that reader the steps and nothing more. A guide organized around a feature makes the reader find their task in it.
DF-04-002 MUST Assume the reader is a competent user with required basic skills; surface prerequisites explicitly rather than embedding lessons.

A how-to reader already has the basic skills and wants to finish a task. A lesson in the guide slows that reader down. A stated list of prerequisites lets a reader without the skills see the gap and go to the tutorial first.
DF-04-003 MUST Require how-to titles to state exactly what the guide shows the user how to do (e.g., start with "How to ...").

A reader looks for a how-to guide by the task they must do. A title that names the task lets the reader find the correct guide in a list or a search result before they open it.
DF-04-004 MUST Use conditional imperatives (e.g., "If you want X, do Y") when the step applies only under a specific condition.

Real tasks have conditions. A conditional imperative puts the condition before the command, so a reader to whom the condition does not apply can skip the step without doing it first.
DF-04-005 MUST NOT Exclude pedagogical teaching, background history, and extended lessons from how-to bodies.

A how-to reader wants to finish a task, not to learn the subject. Teaching and history in the guide hide the steps the reader needs. Those parts belong in a tutorial or an explanation page that the guide can link to.
DF-04-006 SHOULD Prefer concise branching ("if this, then that") to prepare users for real-world complexity.

Real tasks start from different states and can go differently. Short branches show the reader what to do in each case without a separate guide for each case.
DF-04-007 MUST Omit unnecessary steps that do not contribute directly to the specified goal.

Each extra step costs the reader time and is one more place where the task can fail. A step that does not move the reader toward the goal gives no value for that cost.
DF-04-008 SHOULD provide a short "Prerequisites" or "Starting points" section (or link to one) that handles different starting states and messy real-world setups instead of embedding multiple alternative flows.

Readers start a task from different setups. One section that handles those setups lets the main steps stay one path. Alternative flows inside the steps make each reader find the part of the guide that applies to them.
DF-04-009 SHOULD A how-to guide that covers the same demonstration as a tutorial SHOULD lead with the task and place the demonstration's invocation last, as confirmation. The task is what the reader's actor sends, in order, with its branches, and how to verify the result.

Each page answers its own reader's question: "I need my actor to propose an embargo" is work, answered by the activities to send; "I want to see an embargo negotiation happen" is study, answered by the demo. Leading a how-to with the command the tutorial opens with writes it to the tutorial's question. DF-01-003 forbids mixing quadrants within a page and says nothing about two pages; this item covers the pair.
Refines: DF-04-001
DF-04-011 MAY A how-to guide MAY cover the same demonstration as a tutorial.

Overlap across quadrants is not duplication when each page answers its own reader's question. A reader who must do a task and a reader who wants to study it can both need the same demonstration, so neither page has to give it up.
DF-04-012 SHOULD A how-to guide that covers a tutorial's demonstration, with nothing to place before that demonstration's invocation, SHOULD be a tutorial instead.

A how-to guide that only runs the demonstration has no task steps for the reader to follow. It answers the tutorial's question, so it belongs in the tutorial's content type.
Supersedes: DF-04-009
DF-04-010 SHOULD When a how-to guide and a tutorial show the same demonstration, the section both pages show SHOULD be one {% include-markdown %} fragment that both include.

Two copies of a demo invocation and its expected result drift apart; one fragment cannot (DF-10-002), and placement stays with each host page, so DF-04-009's ordering survives. A fragment with two hosts satisfies both hosts' quadrant rules (DF-09-012).
Refines: DF-10-002
DF-04-013 SHOULD When a how-to guide and a tutorial show the same demonstration, the how-to guide's level SHOULD be higher than the tutorial's.

A how-to assumes a competent reader (DF-04-002), and the tutorial is where that competence comes from, so the how-to sits above it and may link down to it (DF-11-002).
Derives from: DF-11-002

Reference

ID Priority Requirement Related
DF-05-001 MUST Produce reference material that is neutral, objective, and technical in tone.

A reader uses reference material to get facts that they can trust. A neutral, technical tone shows that the text describes the system as it is, not as the author would like it to be.
DF-05-002 MUST Structure reference content to mirror the physical or logical architecture of the system or code being described.

A reader who knows the system looks up a fact by where it is in the system. When the reference uses the same structure as the system, the reader can find the fact without a search. It is also easy to see when a part of the system has no reference entry.
DF-05-003 MUST Keep reference content dry and free from instruction, discussion, or opinion.

A reader goes to reference material to look up a fact, often more than one time. Instructions, discussion or opinion make each fact harder to find, and they belong in a how-to guide or an explanation page.
DF-05-004 MUST State facts about behaviors, commands, parameters, versions, and limitations.

Reference material is where a reader goes to confirm what the system does. If it does not state the behaviors, parameters, versions and limits, the reader must read the code or guess.
DF-05-005 MUST Use consistent, standard patterns and formatting in reference documents to make information easy to find.

When every reference entry has the same structure, a reader learns the structure one time and then finds each fact in the same location on every entry. Different formats make the reader read each entry from the start.
DF-05-006 MAY Allow brief code examples in reference material only to illustrate usage, not to provide step-by-step instruction.

A short example often shows the use of a command or field more clearly than a description. A step-by-step procedure makes the page a how-to guide, which mixes content types (DF-01-003).
DF-05-007 MUST Reference material MUST make the system, not the reader, the grammatical subject of its descriptive sentences.

DF-05-001 and DF-05-003 require neutral, instruction-free description without saying how to achieve it. Naming the grammatical subject is the operational test: "A value of 0 disables the timeout" describes the machinery, while "Set timeout to 0 to disable it" has crossed into instruction and belongs in a How-to guide. The subject test catches the drift that "be neutral" alone does not.

Explanation

ID Priority Requirement Related
DF-06-001 MUST Provide explanatory material that focuses on understanding and context for a topic.

Explanation is the content type for a reader who wants to understand a subject, not do a task. The other types do not give context or reasons. Without explanation pages, a reader can follow the steps but cannot apply them to a new case.
DF-06-002 MUST Address "Why?" questions by discussing history, design decisions, or technical constraints.

The reason for a design is what lets a reader apply it to a case that the documentation does not cover. Design decisions, constraints and their history are the content that the other types leave out.
DF-06-003 MAY Permit opinion, perspective, and weighing of approaches in explanatory documents.

To understand a design, a reader must see the alternatives and why one was chosen. Opinion and the comparison of approaches are how an explanation page shows that choice.
DF-06-004 MUST NOT Exclude practical instructions and dry technical descriptions that belong in Tutorials, How-to, or Reference.

Instructions and dry technical descriptions have their own content types. In an explanation page, they make the text longer and mix content types (DF-01-003), and they become a second copy of a how-to guide or a reference page that can become different from it.
DF-06-005 SHOULD Prefer titles that can be read as "About X" for explanatory topics.

A title that reads as "About X" tells the reader that the page explains a subject, not a task or a list of facts. The reader can then choose the page by what they want to understand.
DF-06-006 MUST Weave connections to related topics to build a web of understanding.

Understanding comes from how concepts relate to each other. Links from an explanation page to related subjects let the reader see those relations and move to the next subject that they need.
DF-06-007 MAY Explanation MAY use first-person plural ("we") for the author's reasoning and second person ("you") to invite the reader to consider a point.

Explanation is discussion, and DF-06-003 lets it give opinion. "We" lets the author show their reasons, as in "we chose a state-machine model because…". "You" lets the author ask the reader to think about a point, as in "you might expect this to behave like a queue". Impersonal text cannot do these two jobs as well.

File metadata

ID Priority Requirement Related
DF-08-001 SHOULD Name Diátaxis specification files using snake_case and concise topic descriptors.

A consistent file-name style lets a contributor predict the path of a page and its URL. Short topic names keep the URLs short.
DF-08-002 SHOULD Place cross-reference sources only in the header metadata and use inline links for cross-spec references.

When the list of sources is only in the header metadata, a reader finds every source of a page in one location. An inline link puts each cross-reference at the point where the reader needs it.

Prose style

Requirements governing the prose itself, as distinct from the architecture of the documentation set. The detailed rules, their SG-nn identifiers, and their worked examples live in .claude/skills/shared/docs-style-guide.md; these entries make that file normative and give reviewers citable IDs.

ID Priority Requirement Related
DF-09-001 MUST Hand-written prose under docs/ MUST follow the documentation style guide at .claude/skills/shared/docs-style-guide.md.

Style rules are numerous, example-heavy, and change more often than requirements do, so they are maintained as a guide rather than as several dozen spec entries. This entry is the anchor that gives the guide normative force and lets lint-docs findings cite a spec ID. Generated trees (docs/reference/code/, docs/reference/case_states/) and docs/adr/ are outside the guide's scope; fix the generator or the template instead.
DF-09-002 MUST Domain terminology in docs/ MUST match the canonical term in docs/reference/glossary.md, with docs/reference/vultron-taxonomy.md canonical for Vultron concept names.

"Avoid jargon" and "use domain language" are the same rule with the glossary as arbiter: a term in the glossary is domain language and should be used, and a term in neither the glossary nor the taxonomy is jargon that must be expanded, replaced, or registered. Naming one arbiter also prevents the three overlapping term sources from drifting further apart.
DF-09-003 MUST Acronyms MUST be expanded on first use on each rendered docs/ page, where "page" means the page as published rather than the source file it was authored in. Site navigation rendered by the theme (the sidebar and tabs) is not page content and is exempt. In a generated listing of child pages, each entry is one unit: an acronym in an entry's link label is expanded on first use when that entry's own description expands it.

First use resets per page because readers arrive from search results and deep links rather than by reading in nav order. Site-wide abbr tooltips do not survive print output and are invisible in raw Markdown. "Page" names the rendered artifact because an assembled page has one first use, not one per fragment (DF-09-011). A generated listing reuses navigation labels as link text, so each entry's description carries the expansion.
DF-09-004 MUST Every acronym used in docs/ MUST be registered in docs/_acronyms/index.md.

pymdownx.snippets auto-appends that file to every page, so a registered acronym gets a hover definition everywhere it appears. An unregistered one silently gets nothing.
DF-09-005 SHOULD A docs/ page SHOULD introduce, define, or link out for each concept before the sections that depend on it.

Prose is a directed acyclic graph of topics. A forward reference forces the reader to hold an undefined term until the page explains it, or to leave the page to find out. Across pages the dependency edge is a hyperlink from first use to the concept's canonical introduction, so the glossary and the taxonomy serve as the concept registry and no separate dependency file is required.
DF-09-006 SHOULD Every diagram in docs/ SHOULD be accompanied by prose stating what the diagram shows.

The page must stay comprehensible when the Mermaid render fails, in print-site output, and to a screen reader. The accompanying sentence also disciplines the author: a diagram whose point cannot be stated in a sentence usually has not earned its place.
DF-09-007 MUST A reviewer or style check MUST evaluate a sentence-scoped or block-scoped rule against the source file that holds it, including an {% include-markdown %} fragment.

A fragment is prose, so it must be checked. If the check skips fragments, a large part of a page that is assembled from fragments, such as the Protocol Specification, gets no check.
DF-09-011 MUST A reviewer or style check MUST evaluate a rule whose scope is a page against the rendered page.

A fragment is not a page. A rule about a page, such as the first use of an acronym (DF-09-003) or the order of concepts (DF-09-005), gives false findings when it is applied to one part of a page. For the same reason, .markdownlint-cli2.yaml turns off MD041, which wants a top-level heading as the first line.
Extends: DF-09-007
DF-09-008 MUST A reviewer or style check MUST take the Diátaxis quadrant of an {% include-markdown %} fragment from the pages that include it.

Quadrant selects the voice rules (DF-03-004, DF-04-004, DF-05-001, DF-06-007), and a fragment's own path does not determine it. docs/tutorials/worked_example.md and docs/topics/measuring_cvd/possible_histories.md are both included into the reference Protocol Specification's annexes. Inferring quadrant from the fragment's directory would apply tutorial voice rules to reference content and vice versa.
DF-09-012 MUST The author of an {% include-markdown %} fragment with more than one host MUST make it satisfy the quadrant rules of each host.

A fragment renders in every page that includes it, and each reader sees it under that page's quadrant. includes/_rm-states-table.md has four host pages. A fragment that fits only one host breaks the voice rules on the others.
Extends: DF-09-008
DF-09-009 MUST A documentation check that acts as a blocking gate MUST report an empty target set as a distinct failure, not as success.

A gate that checks nothing and reports success is worse than no gate. It gives a false clean signal, and reviewers then skip the review that the gate replaced. A target set that is empty because of a wrong path or a wrong pattern looks the same as a clean result unless the gate reports it as a failure.
DF-09-010 MUST A reader-facing docs/ page MUST name a protocol activity by its formal protocol message name and code, paired with its AS2 wire form. An example is "Report Valid (RV) is implemented in ActivityStreams as Accept(Offer(VulnerabilityReport))". Where a shorthand has no formal name, or expands across several activities, the page uses the plain-English name from the matching docs/reference/messages/ heading.

Three names identify each activity: the formal protocol message, the prototype class and the AS2 wire form. Only the first and the last are for readers. The wire form alone does not give the protocol meaning: Accept(Offer(...)), TentativeReject(Offer(...)) and Reject(Offer(...)) mean valid, invalid and closed, and nothing in the wire form tells which. A page that uses only the wire form loses the protocol layer.
DF-09-013 MUST NOT A reader-facing docs/ page MUST NOT name a protocol activity by its prototype class name.

An implementer who builds a peer in a different language has no RmValidateReport class (ADR-0083). A prototype class name tells that reader nothing about the protocol, and it ties the page to one implementation.
Extends: DF-09-010
DF-09-014 MAY A reader-facing docs/ page MAY keep a prototype class name only as a non-rendered identifier, such as a mermaid node id.

A non-rendered identifier is not shown to the reader, so it does not break DF-09-013. The checks in test/architecture/test_docs_activity_verbs.py read the mermaid node id to identify the activity, so the class name is useful there.

Sweep verification

Requirements that apply whenever a documentation sweep (naming sweep, Diátaxis extraction, page split, or any mechanical pass that moves or republishes existing prose) touches content in docs/. Faithful copying is insufficient — re-reading content in a new context is a different act from reading it in place, and a sweep carries source errors forward with full authority unless each moved claim is actively verified.

ID Priority Requirement Related
DF-10-001 MUST When a claim is moved, extracted, or republished in a new docs/ location, it MUST be verified against its authority (source code, specs/*.yaml entry, or docs/reference/ page) before the change is committed. Faithful copying is not verification.

A sweep usually counts as done when all content is accounted for. A faithful copy meets that test, even when it moves a false statement to a new location where it has more authority than before. The error is often not visible in the source context and shows only when the claim is read as a statement on its own in the new location. Only a check against the authority finds it.
DF-10-002 SHOULD When the same content is needed in more than one docs/ location, use an {% include-markdown %} fragment instead of copying prose — one authoritative source, multiple render points.

Copied prose drifts silently: one copy is updated, the other is not, and both pass lint because neither is wrong by itself. DRY is already a project standard (CS-22-001) and the tree already assembles pages from fragments, so this names the existing mechanism as the required one. An extracted fragment stays in lint-docs' target set for sentence- and block-scoped rules (DF-09-007), but the claims it carries are still verified at the moment of the move (DF-10-001). Placement and include-path mechanics: notes/documentation-sweeps.md.

Site information architecture — stakeholder types, levels, and routing

ID Priority Requirement Related
DF-11-001 MUST Every reader-facing docs/ page MUST declare an audience stakeholder_type and a prerequisite level in its YAML frontmatter. The stakeholder_type value is a list whose members are drawn from cvd-practitioner, platform-developer, process-researcher, and project-contributor, or the bare scalar ALL. The level value is one of 100, 200, 300, 400, or 500. A reader-facing page is a published page under docs/ that is neither a project working-record page (DF-11-003) nor an {% include-markdown %} fragment (DF-11-010).

Both axes must be machine readable so ordering can be checked and landing pages generated rather than hand-maintained. The key is list-valued because a page may serve exactly two audiences. No member is a CVDRole value, making the reader-type versus case-role conflation structurally impossible. This item is the normative enumeration; its derivation chain is in notes/site-information-architecture.md.
Uses definition from: DF-11-003
See also: DF-11-010 — a pointer to the fragment rule for what a fragment is; a change to it changes nothing here
DF-11-027 MUST A reader-facing page that serves every stakeholder type MUST declare the bare scalar stakeholder_type: ALL, not a list naming every type and not [ALL].

Requiring ALL over a full enumeration stops one fact having two forms. A tool or reviewer that looks for the pages that serve every reader then needs to match only one value.
Refines: DF-11-001
DF-11-002 MUST NOT A docs/ page MUST NOT depend on a page whose declared level is higher than its own, where depending means using a concept the higher-level page introduces without introducing, defining, or linking out for it.

This is the rule that levels exist to support. It makes each ordering decision one that a reviewer can show to be wrong, so a page that goes out of order can be found. A violation means that the page is in the wrong location, that its prerequisites are not stated, or that it does two jobs. It extends DF-09-005 from the inside of a page to the relation between pages. A link to the page that introduces the concept satisfies the rule, because SG-11 makes a link the connection between concepts on different pages.
DF-11-003 MUST Project working-record pages — decision records, generated code documentation, exhaustively enumerated state pages, retained design-history pages, individual requirements-traceability records (the docs/reference/user_stories/ story pages and the traceability matrix that routes them, but not the stories' reader-facing index), and agent- and contributor-facing material such as docs/agents/, docs/developer/ and docs/reference/codebase/ — MUST be excluded from the reader-facing navigation while remaining published and reachable.

The working record is a different kind of content, not a deeper level of the same content. It is also a large part of the site, so if it stays in the reader-facing navigation, readers must go through it to find the pages for them. Research pages are not working record. They are reader-facing material for process-researcher and declare a level (ADR-0102), so this requirement does not apply to them. User stories are working record because each story records a requirement that the implementation was traced against. A contributor reads a story when a question about that requirement comes up, not in sequence. The reader-facing index that introduces the stories keeps its level. The pages stay published and reachable, because contributors still need them and other pages link to them.
DF-11-012 MUST A project working-record page (DF-11-003) MUST declare stakeholder_type: [project-contributor].

The working record is for a specific audience, contributors, so it declares a type. This rule is separate from DF-11-003 because it is checked against page frontmatter, and DF-11-003 is checked against mkdocs.yml. One combined rule could pass on the navigation while every declaration is missing.
Uses definition from: DF-11-003
DF-11-033 MUST NOT A project working-record page (DF-11-003) MUST NOT be assigned a level.

A level on the working record has no meaning, because the working record is not part of the reader path that levels order. Because the page still declares its audience (DF-11-012), the absent level is a property of the material for one audience, not an exemption.
Extends: DF-11-012
Uses definition from: DF-11-003
DF-11-004 MUST NOT A page's own level MUST NOT appear in its rendered content or in the site navigation. Documenting the level ladder itself — in the glossary, in an ADR, or in a shared fragment they include — is not a page declaring its own level and is unaffected.

Levels describe prerequisite depth, which is a property of the content, while readers sort themselves by goal: someone wiring a scanner into report validation thinks "how do I plug this in", not "I need a 300-level page". Exposing levels would ask a newcomer to rank their own knowledge before their first click, which is the same self-classification problem the Study/Work split already has. The reader sees a linear flow; the hierarchy that produced it belongs to the author.
DF-11-005 MUST This codebase MUST generate each section landing page that enumerates its contents from page frontmatter, gated by a check mode, not by hand.

A hand-written landing page is a second copy of the navigation, and it becomes different from the navigation when a page is added, moved or removed. A fix to each missing entry does not stop the next one, because the copy is the cause. A generated page that a check mode gates cannot drift without a failure, as vultron/metadata/adr/index_gen.py (from ADR frontmatter) and demo-scenarios-sync (from the scenario registry, ADR-0098) already show.
DF-11-028 MUST Every section index MUST declare its shape in its frontmatter as generated, routing or rendered. A section index is an index.md that opens a navigation group, or the only navigation entry for a directory holding reader pages the navigation omits. The generated shape is the enumeration DF-11-005 requires. The routing shape is an index whose links to its members are part of its framing, or of a themed grouping that is editorial content. The rendered shape is an enumeration produced at build time from a registry (DEMOCI-11-009). A routing or rendered index is exempt from DF-11-005.

The shape is a required declaration, so that no section can be left without a decision. The two exempt shapes exist because generation can only list pages, and it cannot give an argument or a theme. A rendered index is exempt because nothing is committed to drift. Each index records its decision in its contents: frontmatter, and test/metadata/docs/test_site_sync.py pins that set.
Supersedes: DF-11-005
See also: DEMOCI-11-009 — an example of a rendered index
DF-11-029 MUST uv run docs-site --check MUST fail when a routing section index (DF-11-028) does not link every member of its section.

A routing page is exempt from generation, but it must still link every member of its section. That completeness can be derived, so a check enforces it. DEMOCI-11-007 makes the same split between what is generated and what is checked.
Uses definition from: DF-11-028
DF-11-006 SHOULD A set of sibling leaf pages that is too large to browse SHOULD be reached through a routing page that links each member, with the navigation carrying the group rather than enumerating the members.

A navigation that lists a large set of sibling pages one by one is too long to scan, and the pages around the set become hard to find. A routing page keeps the navigation short and still links each member, so no page becomes unreachable. The docs/reference/user_stories/ set uses this shape: the navigation carries one entry, and traceability.md reaches each story.
DF-11-007 MUST A rendered docs/ page MUST remain self-sufficient for a reader arriving directly at it.

Readers arrive from search results and deep links rather than in navigation order (DF-09-003, SG-12). A page that needs its predecessor fails every reader who arrives at it by a deep link. Nav order carries dependency and prominence, not narrative.
DF-11-030 MUST NOT An author MUST NOT remove a repeated opening, restated prerequisite, or re-expanded acronym from a rendered page to make adjacent pages read continuously. Sourcing a repeated block from one {% include-markdown %} fragment that each page includes satisfies this requirement.

A block repeated between neighbors is usually DF-11-007 working, and removing it degrades every deep-link arrival. The requirement is on what the reader sees, not on the source: a block one authority owns, such as a banner, a pointer, or a shared prerequisite list, is sourced once (DF-10-002) and still renders on every page.
Refines: DF-11-007
DF-11-008 MUST This codebase MUST generate a stakeholder_type × level coverage matrix from page frontmatter into an unpublished location outside docs/.

The matrix turns "we do not serve audience X" from an impression into a recorded fact planning can act on. It sits outside docs/ because it is a planning artifact, and a per-page level table shown to readers would defeat DF-11-004 page by page.
DF-11-046 MUST A check mode MUST fail when the committed coverage matrix (DF-11-008) disagrees with the page frontmatter.

Gating currency keeps the matrix a checked object rather than an advisory one. A matrix that drifts from the tree records a site that does not exist.
Verifies: DF-11-008
DF-11-031 MUST NOT The coverage matrix check (DF-11-046) MUST NOT fail because a cell is empty.

The check gates currency, not fullness. Requiring fullness would harden into "every type at every level", which the divergence-above-100 shape contradicts. An empty cell is a recorded fact about the site, not a fault.
Extends: DF-11-046
DF-11-009 MUST NOT A page's own stakeholder_type MUST NOT appear in its rendered content or in the site navigation. This rule does not cover the vocabulary itself, documented in the glossary, in an ADR, or in a shared fragment they include.

Extends DF-11-004's reasoning one step. A reader should not have to classify themselves before their first click. Documenting the vocabulary itself is not a page declaring its own audience. The rule also keeps the enumeration free to change: cvd-practitioner may be split later on evidence, and a reader never taught the term loses nothing when it happens, whereas a published label would make the split a change to something readers had been taught.
Constrains: DF-11-015
Constrains: DF-11-032
DF-11-032 MUST A routing page generated for a stakeholder type MUST be titled by the reader's situation, not by the stakeholder type.

A situation is recognizable without asking anyone to identify with a label. A title that named the type would show the reader the label that DF-11-009 keeps off the page.
DF-11-010 MUST NOT An {% include-markdown %} fragment MUST NOT declare stakeholder_type or level of its own; both are taken from the pages that include it, and a fragment with more than one host is governed by each host's declarations.

A fragment is not a page, so a page-scoped declaration applied to one yields artifacts of the authoring split rather than facts about a reader — the same reason DF-09-008 takes a fragment's quadrant from its hosts. Without this the validator's target set is ambiguous for the published-but-unnavved fragments under docs/includes/, and stakeholder_types.md would have to declare an audience for a table with no reader.
DF-11-011 MUST This codebase MUST generate the shared fragment defining the stakeholder_type members from the frontmatter schema, gated by a check mode, not by hand.

The fragment has a different source from a landing page. A landing page comes from the frontmatter of many pages, but this fragment comes from the schema that defines the vocabulary. Thus, it needs its own requirement and its own check. A generated fragment keeps the list that readers see the same as the normative list in DF-11-001. A fragment that is maintained by hand can become different from the schema with no failure.
DF-11-013 MUST A reading-path thread MUST be declared once, as data in the frontmatter of the start page that opens it, one thread per start page, as an ordered list of stages, where each stage has a title naming the reader's goal, may be marked as a stopping point, and is either an unordered set of reader-facing pages or an ordered chain of them, each member carrying its page path and a blurb written for this thread.

A reader's route through the site is a partial order: at some points order matters, and at others any of several pages will do. Ordered stages of sets or chains express that directly without forcing a sequence, and cannot contain a cycle. Declaring the thread once is what lets the start-page listing and every member page's directions be renders of one source (DF-10-002) instead of copies that drift.
DF-11-014 MUST This codebase MUST generate a start page's thread listing from the thread's data, gated by a check mode, not by hand. Framing prose outside the generated block stays hand-written.

The listing is an enumeration of the thread, the defect class DF-11-005 exists to remove when it is hand-maintained. Generating it into the committed source keeps the diff showing what readers will see, the way generated landing pages do.
DF-11-015 MUST Every page that is a member of a thread, and every start page, MUST show one box per thread it is on. A member page's box is titled by the reader's situation rather than by stakeholder_type (DF-11-009). It names the stage the page belongs to. It holds a link back to the start page, then two tiles: the pages before this one and the pages after it. A start page's box is its Begin tile (DF-11-053).

A reader who followed a thread into a page needs directions onward. A page on several threads shows each, so it never needs to know which thread a reader is on, and it still stands alone (DF-11-007). A reader who lands on a start page needs one place to begin.
DF-11-034 MUST A thread box (DF-11-015) MUST hold a "Path overview" link to the thread's start page, then a previous tile and a next tile. Each tile is a list of links. Previous holds the set of thread pages immediately before the page. Next holds the set immediately after it. A tile whose set holds more than one page says so in its label. An empty set gives an empty tile. The set before a member page is the preceding member of its chain, or else the previous stage's exit pages. The set after it is the next member of its chain, or else the next stage's entry pages. A set stage's entry and exit pages are all its members. A chain's entry page is its first member, and its exit page is its last.

A reader who followed a thread into a page needs directions onward without being forced down one next page, so predecessors and successors are sets. The start link gives a deep-linked reader the way back. The box does not repeat the page's own title: the reader is on that page, and the stage line already says where it sits. Tiles shaped like buttons read as directions onward, where a table read as data.
Refines: DF-11-015
DF-11-053 MUST A start page's box (DF-11-015) MUST be a single tile labelled "Begin". The tile links the first stage's entry pages: a chain's first member, or every member of a set. It has no title and no stage line. A start page carries no hand-written buttons beside it (SG-50).

A reader new to the situation needs one obvious place to begin, and it must be where the thread begins. Hand-picked buttons drifted: three of four pointed somewhere other than their thread's first page. A tile generated from the thread data stays in step. A reader who knows the basics skips ahead by the goal-named stage headings, and a returning reader has the lookup link (DF-11-021).
Refines: DF-11-015
DF-11-035 MUST The build MUST render a page that shows thread boxes (DF-11-015) the same for every reader.

A page that rendered differently by reader would need to know which thread the reader is on. With no query parameter, script or referrer involved, the page renders the same on a deep link.
Extends: DF-11-015
DF-11-016 MUST A thread check MUST fail when a thread lists a page that does not exist or is not reader-facing (DF-11-001), when a page appears more than once in one thread, or when it resolves no threads at all (DF-09-009).

A thread that routes a reader to a missing or working-record page is a broken route, and a page listed twice in one thread has two places in a partial order. The build's broken-link check catches only the first, and only on the start page.
Refines: DF-09-009
Uses definition from: DF-11-001
DF-11-018 MUST Every reader-facing docs/ page (DF-11-001) MUST declare exactly one page_type in its YAML frontmatter: tutorial, how-to, explanation, reference or routing. The routing type is for a page that mainly gives directions, such as the home page, the start pages, and indexes that only route. A page's page_type is independent of its contents: shape (DF-11-028), so an index whose prose mostly explains is explanation.

Once the navigation stops grouping pages by Diátaxis type, the type survives only as a declaration on the page. A required key makes a missing one a fault rather than a silent gap, for the same reason contents: is required on landing pages.
Uses definition from: DF-11-001
See also: DF-11-028 — scope boundary: "independent of its contents: shape"
DF-11-036 MUST NOT A project working-record page (DF-11-003) and an {% include-markdown %} fragment (DF-11-010) MUST NOT declare a page_type (DF-11-018).

The working record's door already says what kind of page it is, and a fragment takes its declarations from its hosts, so a page_type on either would be a declaration nothing reads.
Extends: DF-11-018
Uses definition from: DF-11-003
See also: DF-11-010 — a pointer to the fragment rule for what a fragment is; a change to it changes nothing here
DF-11-025 MUST Every reader-facing docs/ page (DF-11-001) MUST declare exactly one subject in its YAML frontmatter: protocol for a page about the Vultron protocol — its specification, requirements, messages, models and design, including a tutorial that teaches protocol behavior on the reference implementation; implementation for a page about CERT/CC's reference implementation — its code, demos, architecture and project record, however protocol-shaped the subject; or neutral for a page about neither, which may sit in any section.

Whether a page is about the protocol or about the reference implementation is a fact about the page, so it lives on the page; the nav-section check (DF-11-020) reads it rather than restating a list that drifts. A required key makes an unclassified page a fault rather than a silent pass.
Uses definition from: DF-11-001
DF-11-026 MUST NOT A project working-record page (DF-11-003) and an {% include-markdown %} fragment (DF-11-010) MUST NOT declare a subject (DF-11-025).

The working record is out of the nav the nav-section check (DF-11-020) walks, and a fragment takes its declarations from its hosts, so a subject on either would be a declaration nothing reads.
Extends: DF-11-025
Uses definition from: DF-11-003
See also: DF-11-010 — a pointer to the fragment rule for what a fragment is; a change to it changes nothing here
DF-11-019 MUST On every reader-facing page whose page_type (DF-11-018) is not routing, the built site MUST show a badge naming that type. The badge is rendered from the page's own frontmatter.

A badge tells a reader arriving from search what kind of page they landed on. A badge read from the page's own declaration cannot drift from it.
Uses definition from: DF-11-018
DF-11-037 MUST NOT The built site MUST NOT show a page-type badge on a routing page.

A routing page only gives directions, so a badge there would be noise.
Extends: DF-11-019
DF-11-038 MUST NOT An author MUST NOT hand-write a page-type badge beside a link unless a check fails when the badge differs from the linked page's page_type.

A hand-written badge beside a link restates the target's declaration and drifts silently when the target changes type. A check that compares the two is the only thing that keeps such a badge true.
Uses definition from: DF-11-019
DF-11-020 MUST NOT A navigation section MUST NOT hold both a page about the Vultron protocol and a page about the reference implementation.

A reader who wants the protocol must be able to trust that every page in a protocol section binds them or explains what binds them; a reference-implementation page beside them reads as part of the protocol. The nav is the only place the two are grouped together, and pages move between its sections often enough that a review rule alone would let one slip.
DF-11-021 MUST The site MUST have one lookup page, linked from the home page and from every start page, that lists the reader-facing reference pages (DF-11-018). The lookup page groups them by top-level navigation section, in navigation order, each with its description:.

Reference is not a top-level tab (ADR-0136), so a returning reader has no view of the site by content type. One page gives that view without a top level organized by type.
Uses definition from: DF-11-018
DF-11-039 MUST NOT The lookup page (DF-11-021) MUST NOT be a start page (DF-11-013).

A start page opens one reading-path thread for one reader situation. The lookup page serves a returning reader of any kind who wants a view by content type, so it does not fit one thread.
Extends: DF-11-021
Uses definition from: DF-11-013
DF-11-040 MUST The lookup page MUST list a reference page in a navigation group below the top level once, through the index.md opening the outermost such group. A reference page with no such group, or whose groups below the top level have no opening index.md, is listed on its own.

A subgroup listed through its index keeps the page short enough to scan (DF-11-006).
Refines: DF-11-021
DF-11-041 MUST The lookup page MUST place a reference page the navigation omits by the navigation-reachable index.md of its directory, then list it by DF-11-040.

A page the navigation omits has no navigation group of its own. The index of its directory is the nearest place in the navigation, so the page is listed where a reader would look for it.
Refines: DF-11-021
Extends: DF-11-040
DF-11-042 MUST This codebase MUST generate the lookup page's listing and gate it with a check mode.

The check mode fails when the listing differs from the navigation and the frontmatter, so the page stays current (DF-11-005).
Extends: DF-11-021
DF-11-047 MUST The lookup page's check mode (DF-11-042) MUST fail when a reference page has no entry on the lookup page.

A reference page with no entry is one a reader cannot find from the lookup page, which defeats the page's purpose (DF-11-021).
Extends: DF-11-042
DF-11-048 MUST The lookup page's check mode (DF-11-042) MUST fail when the home page or a start page does not link the lookup page.

A lookup page that the home page and start pages do not link is reachable only by search, so a reader who needs it does not find it (DF-11-021).
Extends: DF-11-042
DF-11-022 MUST The box (DF-11-015) of a thread member whose path names a section (page.md#anchor) MUST say the section, not the page, is on the thread.

A reader who followed the thread to one section of a page must know that the thread goes through that section, not the whole page. Otherwise the reader reads parts of the page the thread does not need.
Refines: DF-11-015
DF-11-043 MUST The author of a page with a section member (DF-11-022) MUST place that member's box at the end of the section (DF-11-050).

A box at the end of a long page is out of reach for a reader who followed the thread to one section of it. The end of the section is where that reader looks for directions onward. No build pass can find it reliably (DF-11-044), but the page's author knows where the section ends, and the built site, where the anchor is an id, can check it.
Extends: DF-11-022
DF-11-023 MUST This codebase MUST commit each box (DF-11-015) as a fragment under docs/start/_paths/<thread>/, generated from the thread's data and gated by a check mode. There is one fragment per thread and member, and a section member's anchor is part of its fragment's name.

A committed fragment shows the box in a diff. The generator's check mode fails when the fragment differs from the thread, so a box that the author places by hand keeps the content of the thread. The message-vocabulary fragments use the same pattern (ADR-0128).
Uses definition from: DF-11-015
DF-11-052 MUST The documentation build MUST exclude each box fragment (DF-11-023) as a page.

A box fragment is part of the pages that include it. Built as a page of its own, it would publish a page with no frontmatter, no navigation entry and no reader.
Extends: DF-11-023
DF-11-044 MUST A box (DF-11-023) MUST reach a page only through an include-markdown directive that the page's author places, never through one the build adds.

The author knows where on a page the directions to the next page belong. An automatic insert can only guess, and the only safe guess is the end of the page, which is wrong for a long page.
Extends: DF-11-023
DF-11-045 MUST A built-site check MUST fail when a member page or start page does not render its box for each of its threads.

A check over the built site finds a missing box however the page is assembled, and the placement does not need to be mechanical.
Verifies: DF-11-015
DF-11-049 MUST The built-site box check (DF-11-045) MUST fail when a page renders a box made for another page.

A box made for another page shows the reader the wrong previous and next pages, so the thread sends them somewhere it should not.
Extends: DF-11-045
DF-11-050 MUST The box check (DF-11-045) MUST fail when a section member's box (DF-11-022) sits outside the section its anchor opens.

A section runs from the anchor's element to the next heading of the same or a higher level, and a section member's box belongs at its end (DF-11-043). A box outside it tells the reader that a different part of the page is on the thread.
Verifies: DF-11-043
Extends: DF-11-045
Uses definition from: DF-11-022
DF-11-051 MUST Each failure of the built-site box check (DF-11-045) MUST name the page and the include-markdown directive to add.

A failure that names the page and the line to add can be fixed at once. A bare failure makes the author search the site for the missing box.
Extends: DF-11-045
DF-11-024 MUST NOT A page on a reading-path thread (DF-11-013) MUST NOT depend on a member that comes after it on that thread, where depending is as DF-11-002 defines it and a member comes after another when it is in a later stage, or later in the same chain; members of one set stage are unordered among themselves.

A thread's order is a claim that a reader can follow it, and this makes the claim falsifiable in the same way DF-11-002 makes navigation order falsifiable: a reader who meets a concept before the page that introduces it either needs a link out or a different order. The level rule cannot see this, since a thread need not climb in level.
Uses definition from: DF-11-013
Uses definition from: DF-11-002

Protocol Specification normative text rendered from the requirement tiers

The Protocol Specification presents the protocol and foundation requirement tiers of specs/*.yaml as rendered content, never as restated prose, so the specification cannot state a requirement differently from the YAML and presents every one of them; the normative banner marks exactly the normative set (ADR-0136, ADR-0147).

ID Priority Requirement Related
DF-12-001 MUST The Protocol Specification MUST contain a Requirements Catalog body section that renders every requirement of kind protocol or foundation exactly once. The section is placed after the Conformance section and before the back matter.

The specification is the complete normative text only if every rule a conformant implementation must obey renders in it, and normative content belongs in the body rather than in an annex, which the specification declares informative.
DF-12-008 MUST A Requirements Catalog subsection (DF-12-001) MUST be one requirement file.

A subsection that matches one requirement file gives each rule one predictable place in the catalog. A reader who knows the file a rule comes from can find the rule, and an author who adds a file knows where it renders.
Extends: DF-12-001
DF-12-009 MUST The Requirements Catalog MUST render foundation requirements on a catalog page of their own.

Keeping the inherited foundation rules apart keeps visible what Vultron adds and what it takes unchanged from the standards beneath it.
Extends: DF-12-001
DF-12-002 MUST The build MUST define a protocol or foundation requirement's anchor only in its Requirements Catalog row and that row's copy in the single-page edition (full.md). The single-page edition of the specification includes the catalog in document order.

A requirement with two published anchors gives two answers to where it lives, and links written against either can disagree. One home also lets the retired per-kind pages for the two tiers redirect to a single place.
DF-12-010 MUST Every page that shows or links a protocol or foundation requirement without defining its anchor (DF-12-002) MUST link to its Requirements Catalog row. This includes the inline callouts of DF-12-003 and the requirement pages for the other kinds.

A link to the one anchor that DF-12-002 defines keeps every reference to a requirement pointing at the same place, so no page can send a reader to a stale or second copy.
Derives from: DF-12-002
Uses definition from: DF-12-003
DF-12-011 MUST On the single-page edition of the specification, a requirement link (DF-12-010) MUST target the in-page copy of the catalog row.

The single-page edition holds its own copy of the catalog. A link that left the page would take a reader of the one-page view away from the text they are reading.
Refines: DF-12-010
DF-12-003 MUST Outside the Requirements Catalog, the Protocol Specification MUST present a normative requirement only as a callout rendered by ID from its YAML entry. The callout uses the catalog's row format.

A callout shows the YAML's own words, so the narrative cannot paraphrase a rule into something different.
DF-12-012 MUST The callout renderer (DF-12-003) MUST fail the documentation build when a callout ID names no requirement of kind protocol or foundation.

Failing on a non-normative ID stops the specification from presenting a Project or Architecture rule as protocol.
Extends: DF-12-003
DF-12-004 MUST NOT A fragment of the Protocol Specification MUST NOT contain an RFC 2119 keyword outside a rendered requirement block. The exception is the §1.4 Document Conventions paragraph that states the keyword convention.

Every hand-written normative sentence is a restatement that can drift from the YAML, and an unlabeled one may have no YAML counterpart at all. Banning the keywords in prose makes the YAML the only place a normative sentence can be written.
DF-12-013 MUST A check MUST enforce DF-12-004 over the fragments of the Protocol Specification.

A rule against keywords in prose that only reviewers apply lets a keyword slip through. A check finds each one on every change.
Verifies: DF-12-004
DF-12-014 MUST The DF-12-013 check MUST report an empty target set as a failure.

A keyword check that resolves no fragments and reports success gives a false clean signal, the fault DF-09-009 exists to stop.
Refines: DF-09-009
Extends: DF-12-013
DF-12-005 MUST This codebase MUST declare the placement of requirement files on Requirements Catalog pages once, on the documentation side, without a field in the requirement files.

Declaring the placement where it is rendered keeps the requirement file format unchanged, and one declaration lets callouts and the other kinds' pages find the catalog page that holds a requirement.
DF-12-015 MUST A check MUST fail when a requirement file holding protocol or foundation requirements is on no catalog page (DF-12-005), or on two for one tier.

A new requirement file would otherwise be silently missing from the catalog, and a file placed twice would render its requirements twice.
Extends: DF-12-005
DF-12-006 MUST Every page of the normative set MUST include the shared normative banner (docs/includes/normative.md) in the page itself, not through a shared fragment. The normative set is the Protocol Specification's body section pages and the protocol and foundation requirement-tier pages. It excludes the specification's landing page, its single-page full view, its annexes and its open-questions page.

A reader trusts the normative banner only if it is true. A check against one declared list of normative pages finds each missing banner.
DF-12-016 MUST NOT A page outside the normative set (DF-12-006) MUST NOT include the shared normative banner, except the page that documents the banners.

Banners that authors place by hand can stay on pages after those pages leave the normative set, so a page outside the set can call itself normative. A check against one declared list of normative pages finds each wrong banner.
Extends: DF-12-006
DF-12-017 MUST This codebase MUST declare the normative-set pages (DF-12-006) once, in the check that enforces DF-12-006 and DF-12-016.

One declared list is what lets the check find both a wrong banner and a missing one. A second list could drift from the first and let a page pass one check while it fails the other.
Extends: DF-12-006
See also: DF-12-016 — names which check holds the declaration; adds no duty from DF-12-016
DF-12-018 MUST The normative banner check MUST fail when a declared normative-set page (DF-12-017) does not exist.

A failure on a declared page that does not exist keeps the list current when pages move, as they did when the Requirements Catalog replaced the per-tier pages.
Extends: DF-12-017
DF-12-007 SHOULD An informative page that explains the protocol's design SHOULD carry the shared "specification governs" banner, which states that the page is informative and that where it differs from the Protocol Specification the specification governs, instead of the not-normative banner, which says a page is not part of the protocol.

Pages such as Formal Protocol and the RM, EM and CS process models still explain how the protocol is defined, but they predate the specification and may lag it. Neither the normative banner nor the not-normative banner is true of them; a precedence statement keeps their standing and names the tiebreaker.
DF-12-019 MUST The Protocol Specification MUST include a known-gaps page, outside the normative set (DF-12-006), that is generated from the coverage states of SR-05-017. The page lists every xfail-only protocol and foundation requirement in one section, every partly-met one in a second, each with the issues its holds cite (SR-05-018), and every untested one in a third section that says no test shows main meets it. A section with no requirement says so. It lists no verified requirement, and it presents each listed requirement as a callout (DF-12-003).

A reader of a draft needs to know which published requirements main is not shown to meet. A page generated from the test suite shrinks as tests are written and cannot fall behind them, which hand-written prose or placeholder tests would. A requirement with one passing test and one held test is only partly met, and leaving it off would hide the held part (#6075). An untested requirement is labelled by what the tests show, because no test does not mean the behavior is unbuilt.
Uses definition from: SR-05-017
Uses definition from: SR-05-018
Uses definition from: DF-12-006
Uses definition from: DF-12-003
DF-12-020 MUST A check MUST fail a pull request whose committed known-gaps fragment (DF-12-019) differs from a fresh generation, whether the change is to the requirements, to the tests, or to the fragment itself.

A requirement's state changes when a test gains a marker or loses an xfail, which a pull request that touches no docs/ file can do. The page is trustworthy only if every such change regenerates it.
Extends: DF-12-019
DF-12-021 MUST The Requirements Catalog row and every callout (DF-12-003) of an xfail-only protocol or foundation requirement (SR-05-017) MUST carry the marker "Not yet in the reference implementation", linking each issue its holds cite (SR-05-018). The build generates the marker from the coverage states, so a verified, partly-met or untested requirement's row carries none, and the marker leaves a row once a test marked for the requirement runs. The statement keeps its RFC 2119 keyword.

A reader of a draft would take an unlabeled row written ahead of its code for built behavior. The rule stays normative, so only the implementation status is labeled and the keyword stays. A marker read from the tests cannot fall behind them. A partly-met requirement is listed on the known-gaps page (DF-12-019) instead. A prototype carve-out held by a strict xfail citing its production issue takes the same marker (#6023).
Extends: DF-12-001
Uses definition from: SR-05-017
Uses definition from: SR-05-018
Uses definition from: DF-12-003
DF-12-022 MUST NOT The prose of the Protocol Specification MUST NOT describe an xfail-only protocol or foundation requirement (SR-05-017) as behavior that the reference implementation's main branch has.

A marked callout (DF-12-021) is undone by a sentence beside it saying that main does what the requirement asks, and a reader trusts the sentence.
Extends: DF-12-021
Uses definition from: SR-05-017

History File Management

Defines the structure, location, entry format, and tooling for managing project history entries. For implementation and idea types whose --source is ISSUE-N, append-history posts the entry body as a comment on GitHub issue N rather than writing a file. learning and priority types continue to write per-entry write-once files under plan/history/, managed by the append-history CLI tool.

File ID: HM

History File Location and Structure

ID Priority Requirement Related
HM-01-001 MUST History entries for learning and priority types MUST reside under plan/history/ as per-entry write-once files.

Later sessions and the learn skill read learning and priority records, so these records need a fixed location that tooling can find. Each entry is one file that the tool never rewrites. Thus concurrent branches can each add a record without a merge conflict on a shared file.
HM-01-006 MUST NOT The top-level plan/ directory MUST NOT contain any *HISTORY.md files.

Orientation reads plan/*.md (HM-04-001). A history file at the top level of plan/ would thus put the full project history into the starting context of every agent. History stays only under plan/history/, which orientation does not read.
HM-01-002 MUST The append-history tool MUST store each learning or priority history entry as one write-once file at plan/history/YYMM/<type>/<entry-id>.md. In that path, YYMM is the two-digit year and two-digit month when the entry was created. The <type> part is the entry type (HM-02-002). The <entry-id> part is the originating task or idea identifier, such as TASK-BTND5.

Readers and tools find an entry by its month, its type and its source. One file per entry lets concurrent branches each add an entry without a merge conflict on a shared file.
Uses definition from: HM-02-002
HM-01-009 MUST When the path that HM-01-002 names is already taken, the append-history tool MUST write the entry to <entry-id>-<slug>.md instead. The <slug> part is the YYYYMMDD-SLUG stem of the incoming file (BW-01-003).

<entry-id> comes from source, and source is not unique: one work item can produce several learnings (BW-01-009). BW-01-003 and BW-01-010 give incoming files distinct YYYYMMDD-SLUG names so that they do not collide. Without a fallback name, the tool could not archive the second learning of a work item.
Uses definition from: BW-01-003
Depends on: BW-01-010
Supersedes: HM-01-002
HM-01-010 MUST NOT The append-history tool MUST NOT overwrite an existing entry file, at the HM-01-002 path or at the HM-01-009 fallback path.

An entry is the record of finished work. If the tool overwrote a file, a second archive under the same name would remove the first record without a trace.
Refines: HM-01-002
Uses definition from: HM-01-009
HM-01-011 MUST NOT A contributor MUST NOT commit the plan/history/YYMM/README.md index to the repository. The index is a gitignored local cache.

Each branch that archives an entry changes the index. A committed index would thus cause a conflict on almost every concurrent merge. A local regeneration rebuilds the index at any time, so version control adds no value to it.
HM-01-005 MUST NOT A contributor MUST NOT modify an entry file once it has merged to main. History entries are immutable records.

History entries are evidence of what the project did and decided, so no one may rewrite a published record later. Immutability starts at the merge, because the merge publishes the record.
HM-01-012 MAY A contributor MAY correct an entry while it is still unmerged on the branch that created it.

Until the merge to main, no record has been published. A branch whose plan changes during review can then correct its entry. It does not have to choose between a wrong record and a broken rule.
HM-01-007 MUST History entries for implementation and idea types whose --source is ISSUE-N MUST be posted as a comment on GitHub issue N (see HM-08).

GitHub comment mode keeps implementation and idea records co-located with the issue they describe, avoiding file churn in plan/history/.
HM-01-008 MUST NOT History entries for implementation and idea types whose --source is ISSUE-N MUST NOT be written as files under plan/history/.

Writing these entries as files would duplicate content already posted as GitHub comments and pollute the plan/history/ directory with redundant records.
Extends: HM-01-007

Entry File Format

ID Priority Requirement Related
HM-02-001 MUST Every history entry file MUST begin with a YAML frontmatter block that holds at least the title, type, timestamp and source fields. The title field is a human-readable summary. The type field is one of the valid HistoryEntryType values. The timestamp field is a tz-aware ISO 8601 datetime string in UTC, such as "2026-05-01T15:30:00+00:00". The source field is the originating identifier, such as an IDEA-ID or TASK-ID.

The indexes, show-history and the archiver read these four fields from each entry. An entry without one of the fields thus breaks every reader. A tz-aware timestamp puts entries from contributors in different time zones in one correct order. A date without a time cannot do this.
HM-02-006 MUST NOT The append-history tool MUST NOT write the legacy date field in a new entry.

The timestamp field replaces date, and HistoryEntryFrontmatter rejects an entry that carries date. A new entry with date would thus fail validation when a reader loads it.
Extends: HM-02-001
HM-02-003 MUST The Markdown body following the frontmatter MUST contain the full human-readable text of the history entry (e.g., the archived idea text, the completed task summary, or the priority change record).

The frontmatter only indexes an entry. The body is the record that a later reader needs. If the body only points to a different location, the entry loses its content when that location changes or goes away.
HM-02-004 MUST The append-history tool MUST generate the plan/history/YYMM/README.md index (HM-03-006) only from the frontmatter of the entry files in the same monthly directory.

The index is derived data. The tool builds it only from frontmatter, so the index always agrees with the entries.
Uses definition from: HM-03-006
HM-02-007 MUST NOT A contributor MUST NOT edit the plan/history/YYMM/README.md index by hand.

The next regeneration removes a manual edit. Until then, the edit can show content that no entry file supports.
Derives from: HM-02-004

append-history CLI Tool

ID Priority Requirement Related
HM-03-012 MUST Normal skill and agent guidance MUST use the default current-date flow.

When every agent uses the default flow, the clock sets the month directory. Entries from concurrent sessions then go into the correct month. If each agent chose the month, some entries would go into the wrong directory.
Uses definition from: HM-03-004
HM-03-013 MUST NOT Normal skill and agent guidance MUST NOT require agents to choose a target month manually.

An agent can make a mistake when it chooses a month by hand, and the tool already derives the month from the clock. A rule that requires the choice would bring back the error that the tool prevents.
Derives from: HM-03-004

Agent Context Boundaries

ID Priority Requirement Related
HM-04-001 MUST NOT Agents MUST NOT read plan/history/ in the default plan-context step of the standard orientation that starts every workflow.

plan/history/ grows without limit. If orientation read it, the agent would use its context budget on finished work that the current task seldom needs. Orientation thus reads only current plans.
HM-04-002 SHOULD Agents SHOULD read plan/history/ only when specifically investigating historical changes, auditing completed work, or extracting lessons from prior implementation phases.

History helps with audits and lessons, but it is large, so a default read uses much context. When agents read it only for a historical question, only the sessions that need it pay that cost.
HM-04-003 MUST The orient-agent skill documentation MUST state that its plan-context reading covers plan/*.md and not plan/history/.

Agents do the steps of orient-agent exactly as written, so the skill must state the history boundary. If the skill does not state it, an agent that reads all of plan/ puts the full history into its context.

Skill and AGENTS.md Integration

ID Priority Requirement Related
HM-05-001 MUST The build and bugfix skills MUST write completion summaries only with uv run append-history implementation.

When the tool writes a completion summary, the summary gets validated frontmatter and goes to the configured output mode (a file or an issue comment), where readers of the work item find it. A summary written in a different way skips both and is lost, or it goes into the learnings queue, which is not its location (BW-01-002).
HM-05-002 MUST The plan-issue skill MUST use uv run append-history idea to archive processed ideas.

When the tool archives a processed idea, the idea gets the same validated format and the same known location as all other history records.
HM-05-003 MUST When the learn skill needs historical context, it MUST invoke deepen-context and let that skill choose which plan files to load.

deepen-context selects the plan files that bear on the task. Thus learn gets the history it needs and does not read the full history by default.
HM-05-004 MUST NOT The learn skill MUST NOT read plan/*HISTORY.md files directly.

Legacy history files are large, and most of their content is not related to a given learning batch. A direct read puts all of that content into the context of the session.

Timestamp Field and Future-Date Rejection

ID Priority Requirement Related
HM-06-001 MUST Every new history entry MUST include a timestamp field containing a tz-aware ISO 8601 datetime string in UTC (e.g., "2026-05-01T15:30:00+00:00").

A tz-aware UTC timestamp puts entries from contributors in different time zones in the correct order. A date alone or a local time cannot do this.
HM-06-005 MUST All timestamp values MUST be timezone-aware.

A timestamp without a time zone is ambiguous, so readers cannot reliably put two entries from different zones in order.

Protocol Shorthand to MessageSemantics Mapping

Authoritative normative bridge from protocol message shorthand labels (RS, EP, CV, etc.) used in behavioral conformance specs to their MessageSemantics enum values and corresponding AS2 wire-format specifications. Each entry provides one row in the three-hop chain: shorthand to MessageSemantics enum value to AS2 wire form. The correspondence is many-to-many in both directions: several shorthands may collapse onto one wire activity (CV/CF onto vfState, CP/CX/CA onto pxaState, EV onto EP), and one shorthand may expand across several wire activities (GI, ER). Shorthands with no dedicated dispatch value are the protocol-layer error and acknowledgment signals; these are not unimplemented — the purposes they name are served by mechanisms partitioned on a different axis, specified normatively in MSM-05.

File ID: MSM

Fault and Acknowledgement Mechanism Evolution

Normative record of how the formal protocol's per-model error and acknowledgement shorthands (RE, EE, CE, GE and RK, EK, CK, GK) are realized in the AS2 wire vocabulary. The formal set partitions both concerns by which state machine the message belonged to; the implementation partitions faults by failure mode and acknowledges replicated state cumulatively. These are orthogonal axes, so the shorthands have no one-to-one wire counterparts even though the behaviours they describe are implemented.

ID Priority Requirement Related
MSM-05-004 MUST NOT Documentation MUST NOT describe the wire fault taxonomy as RmError, EmError, CsError, or GmError discriminated by as:inReplyTo; those types exist in no ontology file and no code.

No ontology file and no code defines this taxonomy, so documentation that cites it leads implementers to a wire format that does not exist.

Message Type Reference Rendering

Requirements governing the consolidated per-message-type reference pages under docs/reference/messages/, so that the shorthand-to-wire mapping presented to implementers cannot drift from this specification or from the semantic registry.

ID Priority Requirement Related
MSM-06-001 MUST The mapping tables in docs/reference/messages/ MUST be committed include-markdown fragments generated from SEMANTIC_REGISTRY, committed with the occasion table YAML they are rendered from.

Hand-maintained mapping tables drift silently, as the orphaned examples of issue 2904 showed. The tables are generated and committed rather than rendered at build time because they are mostly links, and MkDocs neither rewrites nor checks a .md link a markdown_exec block prints (ADR-0128).
MSM-06-005 MUST NOT A maintainer MUST NOT hand-write a mapping table in docs/reference/messages/, or render one by a build-time markdown_exec block.

A hand-written table drifts from the registry, and MkDocs neither rewrites nor checks a .md link that a markdown_exec block prints (ADR-0128).
Extends: MSM-06-001
MSM-06-006 MUST A pre-commit --check hook MUST regenerate the occasion table YAML and every mapping fragment, and fail on any difference from the committed files. A committed fragment that nothing generates counts as a difference.

A generated file that nothing compares with a fresh generation is a hand-edited one. The hook makes divergence fail at commit time.
Verifies: MSM-06-001
MSM-06-002 MUST Each SEMANTIC_REGISTRY entry MUST be designated to exactly one primary page under docs/reference/messages/. The exception is an entry explicitly exempted as a dispatcher fallback rather than a protocol message.

Without a completeness check a new registry entry can be added without ever being documented, so every entry needs one page that owns it. A bare "exactly one page" rule would be unsatisfiable, because the mapping is many-to-many — see docs/reference/messages/ for the entries that legitimately need a second home. A primary page keeps the completeness guarantee without contradicting MSM-06-003. The dispatch fallbacks are the intended exemptions.
MSM-06-007 MUST Every SEMANTIC_REGISTRY entry that is not exempted as a dispatcher fallback MUST appear on its primary page.

A designation that the page does not honour leaves the entry undocumented while the check passes.
Extends: MSM-06-002
MSM-06-008 MAY A page other than an entry's primary page MAY cross-reference that SEMANTIC_REGISTRY entry.

The mapping is many-to-many, so a reader on a related page can be pointed at an entry without that page owning it.
MSM-06-009 MUST A page MUST cross-reference a SEMANTIC_REGISTRY entry where a collapse or an evolved mechanism gives the entry a second home on that page.

A collapsed or evolved entry belongs to two message families, and a reader of the second family needs to find it there.
MSM-06-003 MUST Each occasion section on a message page MUST state its entry's mapping status. The status is direct, collapse, expansion, evolved or none. A collapse maps several shorthands onto one wire activity. An expansion spreads one shorthand across several wire activities. An evolved mechanism moved onto a different axis (MSM-05).

Reference material must state what is true, including divergence from the normative message set. Documentation that shows only direct mappings and omits the rest reads as a complete correspondence and misleads implementers about both the collapses and the evolved mechanisms. The status sits in each section, beside the formal definition it qualifies, rather than in a table column a sender does not need, so the occasion table need not carry it.
MSM-06-010 MUST The Message Types page MUST define each mapping status value.

Each occasion section links its status to a definition, so the page has to hold one for every value.
Extends: MSM-06-003
MSM-06-004 MUST The Protocol Quick Reference's "Message Types at a Glance" section MUST include the whole occasion table and a table of the formal message set. Both are committed fragments generated from SEMANTIC_REGISTRY (MSM-06-001).

A hand-written table has nothing comparing it with the registry, so it can give an emit trigger and a response for every shorthand, including the ones that faults and hash-chain acknowledgment replace on the wire. Generating both tables from the registry keeps the quick reference in step with the message pages.
Uses definition from: MSM-06-001
MSM-06-011 MUST NOT The Protocol Quick Reference's "Message Types at a Glance" section MUST NOT carry a hand-written table.

Beside the generated occasion table, a hand-written one would give a second, ungated answer to what is sent when.
Extends: MSM-06-004
MSM-06-012 MUST The formal message-set table MUST list each shorthand with the wire activities whose occasions carry it, or state that it has none.

Some shorthands are replaced on the wire by faults or hash-chain acknowledgment, so the table says which have no wire activity rather than inventing one.
Extends: MSM-06-004

Occasions

Requirements for the occasion, the unit of the message lookup table: a situation in a case that a sender conveys with a wire activity, sometimes narrowed by a distinguishing field value, state context or sender standing (glossary, Messaging and Protocol). One SEMANTIC_REGISTRY entry has one or more occasions. Occasions are declared on the entry, and the lookup table and the per-occasion reference sections are renderings of them. Decision: ADR-0128.

ID Priority Requirement Related
MSM-08-001 MUST Every SEMANTIC_REGISTRY entry outside the dispatcher-fallback exemptions (MSM-06-002) MUST declare at least one occasion.

The lookup table is complete only if every wire activity has a row.
Uses definition from: MSM-06-002
MSM-08-015 MUST Each occasion MUST state when it applies, a stable anchor ID, a description and the example that renders it.

These are the fields the lookup table and the occasion section render, so an occasion without one leaves a gap in the reference.
Extends: MSM-08-001
MSM-08-016 MUST Construction of a non-exempt SEMANTIC_REGISTRY entry with no occasion MUST fail.

A construction-time failure makes a new registry entry without an occasion impossible, not merely detectable, so completeness does not depend on a ratchet someone remembers to extend.
Implements: MSM-08-001
MSM-08-002 MUST An occasion's distinguisher MUST be a field value, a state context or a sender standing.

"Distinguished by" is what tells two occasions of one wire activity apart when they share an addressee (MSM-08-009), such as vendor awareness and fix ready on Add(ParticipantStatus). A free-text distinguisher can name a value no implementation sends. Some occasions differ only in who sends them: the Case Owner's request to invite an actor and a participant's suggestion are one Offer(Actor), and the CASE_MANAGER answers them differently (CM-17-007, CM-16-003).
MSM-08-017 MUST A field-value distinguisher MUST be a member of that field's enum.

Typing the value against the enum makes a renamed or retired value fail at construction, rather than name a value no implementation sends.
Refines: MSM-08-002
MSM-08-018 MUST A state-context distinguisher MUST name a state machine, and states that are members of that machine's state enum.

Typing the states against the machine's enum makes a renamed or retired state fail at construction.
Refines: MSM-08-002
MSM-08-019 MUST A sender-standing distinguisher MUST name a SenderEntitlementKind member and whether the sender holds it.

The sender's standing is typed by the entitlement kinds a receiver already checks (HP-01-009), so it has one vocabulary and its wording comes from the kind (MSM-08-010).
Refines: MSM-08-002
MSM-08-003 MUST Each occasion's example MUST dispatch to the occasion's own SEMANTIC_REGISTRY entry.

An example that dispatches elsewhere would show the reader a different wire activity from the one the occasion describes.
MSM-08-020 MUST An occasion whose distinguisher is a field value MUST have an example that carries that field value.

Dispatch alone does not tell occasions of one entry apart. Vendor awareness, fix readiness and fix deployed all dispatch to Add(ParticipantStatus), so one shared example would dispatch correctly for each yet show two of them a status value that is not theirs. No example can carry a state context, such as the receiver's EM state or the CASE_MANAGER's register status of the named embargo.
Extends: MSM-08-003
MSM-08-004 MUST Occasion anchor IDs MUST be unique across SEMANTIC_REGISTRY.

The table links each row to its details by anchor. A duplicate anchor links two rows to one section.
MSM-08-021 MUST Each occasion anchor MUST resolve to exactly one section on the entry's message page.

A table row links to its details by anchor, so the anchor has to land on one section.
Extends: MSM-08-004
MSM-08-022 MUST A row of the lookup table MUST reference every occasion section.

An unreferenced section is reference content no reader can reach from the table.
Extends: MSM-08-004
MSM-08-005 MUST The lookup table's "Sent by" value MUST be derived from the side of the sender entitlement that the occasion's received use case declares (HP-01-007, HP-01-008). That side is the one matching the occasion's addressee (MSM-08-009), and the value is worded from its entitlement kinds (MSM-08-010).

The entitlement is the rule a receiver applies, so it is what another implementation must satisfy, and deriving it means it cannot drift from the code. It is often broader than the CVD convention: any active participant may announce that a fix is ready, though in practice a vendor does. Positions such as the invitee are entitlement kinds (HP-01-009), so they appear in the derived value.
Uses definition from: HP-01-007
Uses definition from: HP-01-008
Uses definition from: MSM-08-009
Uses definition from: MSM-08-010
MSM-08-023 MUST The lookup table's "Sent by" value MUST state an exempt use case as not yet checked.

An exempt use case declares no rule to derive the value from, so the table says so rather than imply one.
Extends: MSM-08-005
MSM-08-024 MUST The lookup table's "Sent by" value MUST state an entry with no received use case as internal to the CASE_MANAGER (SE-05-002).

An entry with no received use case is an act the CASE_MANAGER role performs on its own case, whichever actor holds that role. No receiver handles it, though it may still be committed to the case ledger, so "not handled" would misread it as an unsupported message.
Extends: MSM-08-005
Uses definition from: SE-05-002
MSM-08-025 MAY An occasion MAY add the CVD roles that usually send it.

The usual-role note gives the CVD convention without replacing the entitlement rule.
MSM-08-026 MUST Each usual-sender CVD role that an occasion adds MUST be a value of CVDRole.

Typing the role against the enum keeps the note to roles the protocol defines.
Extends: MSM-08-025
MSM-08-006 MUST The mapping status that MSM-06-003 requires MUST be derived from the occasions and their shorthands.

A declared status is a second copy of what the shorthands already say, and the two disagreed: EP was tagged as expanding to Create(Event) and Announce(EmbargoEvent), where MSM-02-001 maps it to Invite(EmbargoEvent) alone.
Implements: MSM-06-003
MSM-08-027 MUST NOT A SEMANTIC_REGISTRY entry MUST NOT declare its mapping status, except as MSM-08-028 allows.

A declared status drifts from the shorthands it should be derived from (MSM-08-006).
Extends: MSM-08-006
MSM-08-028 MAY An occasion MAY declare a mechanism that evolved per MSM-05.

An evolved mechanism has no shorthand to count, so it alone is declared.
Supersedes: MSM-08-027
MSM-08-007 MUST An occasion's "when" text MUST describe the sender's situation. This holds for protocol mechanics and for a Create that precedes an Add, as well as for CVD events.

One grammar lets a reader scan the "When…" column by situation.
MSM-08-029 MUST Every occasion's prose fields MUST follow the documentation style guide (DF-09-001), use the glossary's canonical terms (DF-09-002) and address no reader.

The prose lives in Python, outside the reach of DF-09-001 as written, yet renders on reference pages and in how-to guides; a fragment with more than one host must satisfy the rules of each (DF-09-012), so it can use neither the how-to "you" nor reference-only phrasing.
Extends: DF-09-001
Extends: DF-09-002
MSM-08-008 MUST A lookup-table row's details link MUST name the formal protocol message and its shorthand when the occasion has a shorthand that expands to no other entry, and otherwise the plain-English heading of the occasion's section.

DF-09-010 requires reader-facing docs to name a protocol activity by its formal name and code paired with its wire form. The row supplies the wire form in "Send", so the link text supplies the name, for example "Fix Readiness (CF)". Where one shorthand expands across several entries, as GI does, DF-09-010 lets the plain-English heading stand in, since the formal name would label every row of the expansion alike.
Uses definition from: DF-09-010
MSM-08-009 MUST Each occasion MUST declare its addressee as one of the sides a sender entitlement can have. The sides are the CASE_MANAGER, a participant, or an actor outside any case for an activity sent before a case exists.

An emitter looks up its own situation. One wire activity can carry two occasions with different senders: a participant proposing an embargo sends Invite(EmbargoEvent) to the CASE_MANAGER, and the CASE_MANAGER asking a participant about a proposal sends Invite(EmbargoEvent) to that participant. Both match one registry entry and one use case, so only the addressee tells the two rows which side of the rule gives their sender. See ADR-0129.
Uses definition from: HP-01-024
MSM-08-030 MUST The lookup table MUST render an occasion's addressee as the row's "Send to" value.

The addressee is what tells two rows of one wire activity apart, so the reader has to see it.
Extends: MSM-08-009
MSM-08-031 MUST Construction MUST fail for an occasion of a non-exempt use case whose addressee is not a side of that use case's declared rule.

An addressee the rule lacks would give the row a sender no receiver admits.
Implements: MSM-08-009
MSM-08-010 MUST Each entitlement kind MUST declare the wording a "Sent by" value uses for it and the glossary term that defines it.

A wording table kept apart from the kinds is a second copy that drifts when a kind is added. Declaring the wording on the kind makes a new kind incomplete until it can be rendered and defined. See ADR-0129.
Uses definition from: HP-01-009
MSM-08-032 MUST The glossary term that an entitlement kind declares MUST exist in the glossary.

A term that the glossary lacks defines nothing for the reader.
Extends: MSM-08-010
MSM-08-033 MUST The addressee kind's wording MUST name the request from the object type of the activity being answered.

The addressee kind serves every request type but an Invite, so its wording takes the request from the answered activity's object type to stay identified ("the addressee of the case proposal") without a kind per request.
Refines: MSM-08-010
MSM-08-011 MUST Each occasion that shares a SEMANTIC_REGISTRY entry and an addressee with another occasion MUST declare a distinguisher.

The lookup table is how a receiver finds which occasion an activity is. Two same-addressee occasions with no distinguisher render as two rows only prose separates, so a receiver cannot tell which one an activity is.
Uses definition from: MSM-08-002
Uses definition from: MSM-08-009
MSM-08-034 MUST The distinguishers of occasions that share a SEMANTIC_REGISTRY entry and an addressee MUST differ.

Two equal distinguishers tell the rows apart no better than none.
Extends: MSM-08-011
MSM-08-035 MUST NOT Two such distinguishers of one kind on one field, state machine or entitlement kind MUST NOT overlap. Two field values or state contexts overlap when they share a field value or a state. Two sender standings overlap unless they differ in whether the sender holds the kind.

Distinguishers that overlap, such as EM NONE and PROPOSED against PROPOSED, still let one activity match two rows. Different fields or machines are not compared, since one activity may carry both values by design.
Extends: MSM-08-034
MSM-08-036 MUST Construction of a registry that breaks MSM-08-011, MSM-08-034 or MSM-08-035 MUST fail.

A construction-time failure makes an ambiguous lookup table impossible, not merely detectable.
Implements: MSM-08-011
Implements: MSM-08-034
Implements: MSM-08-035
MSM-08-012 MUST Each occasion whose activity moves a protocol state machine MUST declare each transition it carries, as a trigger of that machine.

An occasion is the bridge from a formal protocol message to its wire form, and without a link its effect is prose that can drift from the transition table actors' moves are held to (#5172). One occasion may carry several: a Case Owner's embargo activation moves the case's EM and the owner's PEC consent row (MSM-07-008). An occasion that moves no machine, such as a note, a ledger replication, an acknowledgment or an error, declares none.
MSM-08-013 MUST Each declared transition MUST state whose state it moves: the sender's, the receiver's or the case's.

No rule on the machine alone gives it. SM-10-001 has a received RM move update the sender's status, but a report submission moves the receiver's RM, and a participant's public-state observation is adopted into the case's state, so a derivation would hide special cases in generator code. Another implementer reads this fact off the table.
Extends: MSM-08-012
MSM-08-014 MUST An occasion section's statement of the state change its activity causes MUST be generated from the occasion's declared transition.

A hand-typed effect in the description is the drift MSM-08-012 removes. The generated line names the machine, whose state moves, and the source and destination states the chart gives for the trigger.
Uses definition from: MSM-08-013

Meta-Specification Style Guide

Normative rules for authoring specification files in this project. Covers file structure, requirement format, IDs, writing rules, cross-references, lifecycle, quality criteria, and the delineation between spec files and ADRs.

File ID: MS

File Structure

ID Priority Requirement Related
MS-01-001 MUST Each spec file MUST focus on a single topic of concern and be largely independent of other spec files.

Focused files are easier to navigate and maintain.
MS-01-002 MUST Each spec file MUST group its requirements by category.

Grouping by category improves navigation and traceability.
MS-01-003 MUST Each requirement group MUST address a single, cohesive area of concern.

A group with one area of concern lets a reader load only the requirements a task needs. A group that mixes areas makes a reader load rules that do not apply, or miss the ones that do.
Extends: MS-01-002

Priority Levels

ID Priority Requirement Related
MS-02-001 SHOULD A requirement's statement: SHOULD hold the RFC 2119 keyword that its priority: field names.

The priority: field is the authoritative record of requirement strength; inline keywords aid readability but are advisory.
MS-02-002 MUST Each spec entry MUST have a priority: field whose value is one of the RFC 2119 keywords, written MUST, MUST_NOT, SHOULD, SHOULD_NOT or MAY.

The priority: field is the machine-readable record of requirement strength. The Pydantic schema enum is the implementation of this normative requirement, not its source.
MS-02-003 MUST Any spec requirement, lint check, ratchet, or tool that selects requirements by priority MUST treat a negative keyword as the same tier as its positive: MUST_NOT with MUST, and SHOULD_NOT with SHOULD.

RFC 2119 makes MUST NOT the same absolute strength as MUST, and SHOULD NOT the same strength as SHOULD; a prohibition is no less binding than an obligation. A gate that names only the positive keyword silently drops every prohibition. See notes/spec-authoring-rules.md for the gaps this left in the corpus.
Uses definition from: MS-02-002
MS-02-004 MUST Code that selects spec requirements by priority MUST obtain the MS-02-003 tiering from a single shared definition on RFC2119Priority, not by comparing against individual enum members.

Selecting with == RFC2119Priority.MUST is easy to write and fails silently, and each hand-written member list (backstop/_model.py has one) re-decides which members count. One shared definition means the tiering is decided once. Display code that maps each member to a label is not a selection and is out of scope.
Implements: MS-02-003

Requirement Format

ID Priority Requirement Related
MS-03-001 MUST Each spec entry MUST contain exactly one normative statement.

Atomic requirements are independently testable and traceable.
MS-03-008 MUST An author MUST split a compound or multi-condition requirement into separate entries.

Two obligations under one ID cannot be verified, cited or retired apart. A compound requirement that stays whole keeps that fault, so the author splits it rather than only rewording it.
Implements: MS-03-001
MS-03-002 MUST Every requirement MUST have a unique ID.

IDs enable stable cross-referencing.
MS-03-003 SHOULD Each sentence of a requirement's statement: SHOULD hold at most 25 words.

A short sentence is read once and understood. A long one hides its actor, its condition or its obligation, and an implementer who misreads a requirement builds the wrong behavior.
MS-03-004 SHOULD A statement: SHOULD use the active voice and name the actor that holds the obligation, such as the CASE_MANAGER, a participant, spec-lint, or this codebase.

A passive requirement does not say who must act, so each reader supplies an actor, and two implementations can each leave the obligation to the other.
MS-03-005 SHOULD A statement: SHOULD state an action with its plain verb, such as "remove", not with a noun phrase such as "the removal of".

A noun phrase buries the action and adds words, which makes the sentence longer and its obligation harder to find.
MS-03-006 SHOULD A plain-language rewrite of a statement: SHOULD keep its domain terms and its RFC 2119 keywords as written.

Domain terms are defined in the glossary and RFC 2119 keywords set the requirement's priority. A simpler word in their place changes what the requirement means, which a rewrite for plain language must not do.
MS-03-007 MUST spec-lint --changed-since <ref> MUST fail each requirement whose statement: the branch adds or changes and that holds more than one RFC 2119 keyword outside backticks. A requirement whose lint_suppress: lists compound_statement with its reason in a YAML comment is exempt.

The corpus holds a backlog of compound requirements, so a corpus-wide error would fail every branch. Checking only the statements a branch writes holds new text to MS-03-001 without forcing a branch that edits another field to split a requirement it did not reword.
Verifies: MS-03-001

Requirement IDs

ID Priority Requirement Related
MS-04-001 MUST Requirement IDs MUST follow the format PREFIX-NN-NNN where PREFIX is the file-level prefix, NN is a two-digit group number, and NNN is a three-digit requirement number.

Consistent format enables automated validation.
MS-04-003 MUST A requirement ID MUST be stable: once it is assigned, nobody renumbers it.

Stable IDs preserve traceability in git history.

Writing Rules

ID Priority Requirement Related
MS-05-001 MUST A requirement's statement: MUST state its obligation without an inline prose explanation.

An explanation inside the statement mixes the reason with the obligation, so a reader cannot tell which words bind. The rationale: field holds the reason.
MS-05-006 MUST A requirement's statement: MUST be concise.

Concise statements reduce ambiguity.
Extends: MS-05-001
MS-05-002 MUST A requirement MUST be specific.

Specificity makes requirements testable.
MS-05-007 MUST NOT A requirement MUST NOT use a vague term, such as 'appropriate' or 'robust', unless it explicitly defines the term.

A vague term lets each reader supply a different meaning, so two implementations can both claim to obey the requirement and still differ. A defined term has one meaning.
Refines: MS-05-002
MS-05-003 MUST Each requirement MUST be testable.

Untestable requirements cannot be verified.
MS-05-008 MUST Where measurable acceptance criteria apply, a requirement MUST provide them.

A measurable criterion tells the tester when the requirement is met. Without one, a reviewer and an implementer can disagree on whether a test proves the requirement.
Extends: MS-05-003
MS-05-004 MUST A requirement MUST be declarative: it states what the system does, not how, unless the how is itself normative.

Declarative requirements avoid constraining implementation unnecessarily.
MS-05-005 MUST A requirement written to guard against an implementation mistake MUST state the domain truth the mistake violates, in the vocabulary of its kind. It states that truth instead of a prohibition of the mistake, or a correction of the mistake in another kind's vocabulary.

A bare prohibition makes the mistake look like a possible design, and it gives an implementer no target. The positive truth is a design that an implementer can follow, and the regression test verifies it. RSH-08-001 is the example: an assertion that a participant makes about itself is about that participant, not about another actor. A recurring mistake violated that truth (ADR-0089). The rationale names the mistake as the problem that the requirement prevents. The requirement has no marker, tag or field that identifies it as a guard. A guard with no domain truth behind it is not protocol (MS-12-003), or it is only a regression test.

Cross-References and Sources

ID Priority Requirement Related
MS-07-001 MUST Cross-references between spec entries MUST use the relationships: list with a rel_type field (one of the defined vocabulary terms) and a spec_id field referencing the target requirement ID.

Structured cross-references in the relationships: field enable automated graph analysis and linting of dangling references.
MS-07-004 MUST Source attribution MUST appear only in the file header, not repeated on individual requirements.

Per-requirement sources create maintenance overhead.

File Naming

ID Priority Requirement Related
MS-08-001 MUST Each spec file other than specs/README.md MUST have a kebab-case.yaml name.

Consistent naming enables glob patterns and automated tooling.
Refines: SR-01-001
MS-08-002 MUST The file specs/README.md MUST stay a Markdown file.

The README is the index of the spec corpus that a person reads first, and Markdown renders on the code host. The spec loaders read only YAML files, so a Markdown README stays outside the corpus they load.

Lifecycle of Requirements

ID Priority Requirement Related
MS-09-001 MUST Superseded requirements MUST be removed from spec files rather than marked deprecated or left in place with an annotation.

A deprecated requirement that stays in place is noise for agents and can cause incorrect behavior. An agent that reads the corpus cannot tell a retired obligation from a live one. A spec states the current understanding. Git and the archive of retired requirements (MS-09-002, MS-09-005) keep the text that it replaced. The spec schema refuses a deprecated or superseded_by key with a pointer to the retirement archive (MS-09-007).
MS-09-002 MUST The removal of a requirement MUST be recorded in its retired-requirement file, plan/retired-specs/<ID>.md, so there is an audit trail. That file is the record of the removal; no plan/history/ entry repeats it.

An audit trail preserves context for future maintainers. The retired-requirement file already holds the date, the retiring issue or PR, the reason, any replacement and the final text, so a history entry would only repeat it.
MS-09-004 MUST A requirement ID MUST NOT be reused. Once an ID is removed (MS-09-001), no later requirement in any spec file carries it. A rule that replaces the removed one gets a new ID.

Citations outlive requirements: code comments, tests, ADRs, PR bodies and history entries cite IDs. A reused ID silently re-points every one of those at a rule they never meant, and the reuse of CM-11-005 with the opposite force (found in the 2026-10-02 audit) did exactly that. A new ID costs nothing; a stale citation that still resolves is undetectable.
Uses definition from: MS-09-001
MS-09-005 MUST The text of every removed requirement MUST be kept in an archive of retired requirements, one file per requirement ID. The archive is the folder plan/retired-specs/, outside specs/ and laid out like plan/history/.

MS-09-001 keeps retired text out of the specs so it cannot be mistaken for current obligation, but git history is a poor place to look up what a cited ID used to say. One file per ID gives a citation something to resolve to.
Extends: MS-09-001
MS-09-009 MUST NOT A loader or agent that reads the spec corpus MUST NOT load the archive of retired requirements in plan/retired-specs/.

Retired text in agent context can be mistaken for a current obligation. The archive sits outside specs/, which is the only directory the spec loaders read, so no loader can see it.
Uses definition from: MS-09-005
MS-09-006 MUST uv run spec-retire <ID> MUST move the item's final text from its spec file to plan/retired-specs/<ID>.md, with the retiring issue or PR, the date and any replacement ID.

Doing a retirement by hand means several separate edits, and the one that gets skipped is the one that leaves the audit trail or a stale citation behind. One command makes the whole retirement.
Implements: MS-09-005
MS-09-011 MUST uv run spec-retire <ID> MUST list every remaining citation of the ID that MS-09-003 requires repointing.

A citation of a removed ID still resolves in a reader's head, so nobody sees it go stale. The list gives the author each citation to repoint in the same change.
Extends: MS-09-006
Uses definition from: MS-09-003
MS-09-012 MUST uv run spec-retire <ID> MUST change nothing when the ID is already archived, is not declared, or the spec files would no longer load without it.

A retirement that stops part way leaves a spec with no archive entry, or a spec corpus that does not load. Refusing the whole retirement keeps the corpus and the archive in step.
Extends: MS-09-006
MS-09-007 MUST spec-lint MUST fail on a deprecated: or superseded_by: key on any requirement in specs/, and on any requirement ID that is both declared in specs/ and present in plan/retired-specs/.

MS-09-001 and MS-09-004 are rules a human forgets; the corpus already held both violations (deprecated-in-place entries, and CM-11-005 reused with the opposite force) before anything checked for them.
Verifies: MS-09-004
Verifies: MS-09-001
MS-09-008 MUST The text that uv run spec-retire <ID> archives (MS-09-006) MUST be the item's last published text: its block at the merge base of HEAD and the base branch, which is origin/$GITHUB_BASE_REF, else origin/main, unless --base names another. When the item is not declared at that merge base, or the merge base cannot be resolved, the tool changes nothing.

A branch can change a requirement and then retire it. The archive must then keep the text that was published, not the change that nobody approved. The merge base holds the last published text. An item that is not at the merge base was never published, so you delete it; you do not retire it. If the tool cannot find the merge base, it cannot find the published text, so it stops and does not guess.
Refines: MS-09-006
MS-09-003 MUST Cross-references to a removed requirement MUST be updated to point to the replacement requirement.

Dangling cross-references break traceability.
MS-09-013 SHOULD Prepared spec text SHOULD be applied item by item to the current corpus, not by replaying its diff from the base it was written on. Prepared text is spec text written earlier on another branch, in a reverted commit or in an issue comment.

Replaying an old diff reverts every requirement that landed on the base branch after the diff was cut. Every gate asks whether the corpus is well formed, not whether it is current: the older text passes spec-lint, and spec-amendments.sh lists a reverted item exactly as it lists an amended one, so the PR body describes the reversion as an amendment. An item whose new text equals its merge-base text (MS-09-008) while the base text differs is a reversion.
Uses definition from: MS-09-008

Quality Criteria

ID Priority Requirement Related
MS-10-001 SHOULD Spec files SHOULD be scannable via priority-grouped layout.

Priority grouping lets readers quickly find the most critical requirements.
MS-10-002 SHOULD Spec files SHOULD be traceable via stable IDs and cross-references that the requirements graph lets a reader follow from either end.

Traceability supports change impact analysis.
MS-10-003 MUST Every priority: MUST or priority: MUST_NOT requirement MUST include a verification: field.

An implementer cannot reliably build to a requirement that no test can check. A MUST requirement with no verification: field gives reviewers and agents no contract. MS-05-003 makes every requirement testable, and this rule uses the same tier. Thus the linter checks the field where that rule is strongest. MS-02-003 puts MUST_NOT in scope, because a prohibition that nothing checks is the same gap. MS-10-005 through MS-10-008 apply the rule to one requirement at a time while the backlog decreases.
Refines: MS-05-003
MS-10-005 MUST spec-lint MUST print, in its default output, one summary line for each kind that has an owner entry (MS-10-021) or a verification_debt: marker. The line gives the number of priority: MUST or priority: MUST_NOT requirements of that kind that carry a marker, tallied by the issue each marker names.

MS-05-008 and MS-10-003 require measurable acceptance criteria for MUST and MUST_NOT requirements. A count for each kind keeps the backlog easy to read and shows the progress of each backfill.
Uses definition from: MS-10-006
Uses definition from: MS-10-021
MS-10-019 MUST spec-lint MUST compute each MS-10-005 summary line from the markers, not read it from a committed count.

A committed count is right only on the pull request that sets it. Each concurrent pull request that adds or removes a marker makes it wrong. A count that spec-lint computes from the markers has no shared number to race on.
Extends: MS-10-005
MS-10-020 MUST spec-lint MUST print the marked requirement IDs only when an opt-in flag asks for them, and never one line per marked requirement by default.

One warning for each unverified requirement gives so many lines that a new instance is not visible. A reader who needs the IDs asks for them.
Extends: MS-10-005
MS-10-006 MUST Until it gains a verification: field, each priority: MUST or priority: MUST_NOT requirement MUST carry a verification_debt: marker. The marker names, in #N form, the open issue that owns verifying the requirement.

The marker gives each unverified requirement a tracked path to verification. A count that must equal the live value is correct on the pull request that sets it, and incorrect on all other open pull requests. A rule for each item has no shared number, so two pull requests conflict only when they edit the same requirement.
Supersedes: MS-10-003
Uses definition from: MS-02-003
MS-10-021 MUST The issue that a verification_debt: marker names MUST be listed as an owner of its requirement's kind in the one owner table under vultron/metadata/specs/.

Each kind has its own backlog, and the owner table says which issues own it. A marker that names any other issue adds debt to a backlog that never took it on. The table holds issue references and no counts, so the verification of a requirement does not change the table.
Extends: MS-10-006
MS-10-022 MUST spec-lint MUST fail each requirement, one at a time, that breaks the marker rules of MS-10-006 and MS-10-021. It fails a MUST-tier requirement with neither field, and a requirement with both, a stale marker. It also fails a marker below the MUST tier, and a marker naming an issue that does not own its kind.

A per-item failure names the requirement to fix, and it has no shared number for concurrent pull requests to race on. A stale marker hides a verified requirement in the backlog, and a marker below the MUST tier counts debt that MS-10-003 does not require.
Verifies: MS-10-006
Verifies: MS-10-021
MS-10-023 MUST A pull-request check MUST fail a pull request that closes an owner issue that a verification_debt: marker or the owner table still names.

Usually, the backfill pull request that says Closes #N closes the owner issue. A failure on that pull request affects no other pull request. It also finds a backfill that claims to be complete but leaves requirements unverified.
Verifies: MS-10-006
MS-10-024 MUST A scheduled check MUST report each marker or owner entry that names a closed issue. It reports through one tracking issue and does not fail the build.

When a person closes an owner issue manually, no pull request causes the change. A build failure would then make every open pull request fail, so the scheduled check reports it instead (ARCH-18-009).
Verifies: MS-10-006
MS-10-029 SHOULD The scheduled check of MS-10-024 SHOULD run at least once a week.

An owner closed by hand leaves its debt with no one to act on it until the report shows it, so the report must not wait long. A week is the longest delay that still finds a closure before the debt is forgotten. The exact time is a setting in the workflow, not part of the requirement.
Refines: MS-10-024
MS-10-007 MUST An owner issue that no verification_debt: marker names MUST leave the owner table (MS-10-021), and a kind's entry leaves with its last owner.

A backlog can stay at zero only if nothing can increase it again. When the entry for a kind is removed, spec-lint accepts no marker of that kind (MS-10-026), so the end state is permanent. The pull request that closes the owner issue fails until the entry is removed, so the removal must occur.
Uses definition from: MS-10-006
Uses definition from: MS-10-021
MS-10-025 MUST spec-lint MUST report an owner issue that no verification_debt: marker names.

The report shows which owner must leave the table (MS-10-007). spec-lint reports it but does not fail. Two pull requests that each verify some of the last requirements of that owner pass alone, but together they would make main fail.
Verifies: MS-10-007
MS-10-026 MUST spec-lint MUST treat as a hard error a verification_debt: marker on any requirement of a kind that has no owner entry.

MS-10-022 already fails an unverified requirement with no marker. With no marker allowed, an unverified MUST or MUST_NOT of that kind can only pass by gaining a verification: field. While an owner remains, the growth guard (MS-10-016) fails a pull request that adds a marker.
Refines: MS-10-022
MS-10-008 MUST A change that moves a priority: MUST or priority: MUST_NOT requirement carrying a verification_debt: marker from one kind to another MUST replace the marker with a verification: field in the same change.

Each kind's backlog has its own owner. Re-pointing a relabelled requirement's marker at the destination kind's owner would add debt to a backlog that never took it on, which is the growth the marker exists to forbid.
Refines: MS-10-003
MS-10-009 MUST A verification: clause MUST name a check that exists and that inspects the property its requirement's statement asserts. Naming a tool or test that merely runs near the property does not satisfy this requirement: a build, lint or type-check that never examines the artifact the statement constrains, or a test that does not exist, is not verification.

A verification clause is a claim about the test suite, and a false claim looks the same as a true one. This failure has several forms. A clause can cite a build for a property that the build does not examine, such as a strict docs build named for links that it does not see. A clause can describe a test that does not exist, or name the wrong component. A requirement can also have no check that enforces it, and then only some of the code obeys it. MS-15-001 makes sure that a path resolves, not that a check examines the property. See notes/spec-authoring-rules.md.
Refines: MS-10-003
MS-10-004 SHOULD A spec entry SHOULD need only id, priority, kind, statement and rationale (MS-10-012) to be complete.

Requiring optional fields on every entry creates boilerplate that discourages keeping specs current.
Uses definition from: MS-10-012
MS-10-018 SHOULD An author SHOULD add an optional field, such as tags or relationships, only when it gives clear value, not by default.

An optional field added by habit is noise that a reader must check and a maintainer must keep current. A wrong relationships: entry also gives the impact walk a wrong answer.
Extends: MS-10-004
MS-10-010 MUST spec-lint MUST report as a hard error each test a verification: clause names that does not exist: a pytest node (<file>.py::<name>) whose names do not resolve, in order, in that file; and a bare test_<name> token that no test file or test directory the clause names defines, or, when the clause names none, that no file under test/ or integration_tests/ defines.

A named test that does not exist looks the same as a test that exists, and MS-15-001 resolves only the file. spec-lint looks for the name only where the clause points, so it also finds a test that moved to a different module.
Verifies: MS-10-009
MS-10-011 MUST When the verification: clause of a kind: protocol or kind: foundation requirement names test files, at least one of them MUST carry @pytest.mark.spec("<ID>") for that requirement.

A clause pointing at a test that does not carry the marker claims a check the coverage report cannot see.
Derives from: SR-05-004
MS-10-027 MUST spec-lint --changed-since <ref> MUST report each requirement that the branch adds or changes and that breaks MS-10-011.

The corpus has a backlog, so a corpus-wide error would fail every branch. Checking what a branch touches holds each new or changed requirement to the rule.
Verifies: MS-10-011
MS-10-028 MUST A pull-request growth guard MUST fail on each requirement that a pull request adds to the set that breaks MS-10-011.

An author can skip spec-lint --changed-since. The guard runs in CI on every pull request, so the set of requirements that break the rule cannot grow.
Verifies: MS-10-011
MS-10-012 MUST Every requirement MUST carry a rationale: that explains why the requirement is necessary given current conditions: the problem it prevents or the property it guarantees.

A requirement with no written reason can only be obeyed or guessed at. When it conflicts with another requirement, nobody can weigh the two, and when its reason lapses, nobody can see that it should be retired. User stories give a reason only where they exist (SR-11), so for most project and process requirements the rationale is the only place the reason can live.
MS-10-013 MUST NOT A rationale: MUST NOT narrate how its requirement came about, such as its prior wording, a reverted change, or the issues and pull requests behind it. That history belongs in the decision record the adr: field cites, the version-control log, or the project history.

A narrated history answers what happened, not why the rule holds, and it reads as a standing endorsement of the earlier state it describes. A reader then has to reconstruct the current reason from the story, and the story goes stale with every later edit, while a stated reason stays true for as long as the requirement does.
Extends: MS-10-012
MS-10-015 SHOULD The project SHOULD provide two advisory reports, each filterable by spec file and neither failing the build: requirements whose ID a live decision record's body names while their adr: field does not cite that record, and rationales that match patterns of history narration.

A requirement a decision record names is often one that record motivates, so a missing adr: link is a likely gap in the trace from rule to reason. History narration is easy to recognize but has false positives, such as an issue cited as evidence, so both lists are worklists for a person to judge rather than gates. A per-file filter lets one task work through its own spec files.
Verifies: MS-10-013
Verifies: SR-02-020
MS-10-016 MUST A PR-only growth guard MUST fail a pull request that gives a requirement a verification_debt: marker its merge-base version lacked. A marker naming a different issue there counts as a new marker. A marker removed, or moved with its requirement to another file, does not. Nor does the same marker on a new ID whose own relationships: name a requirement that carried it at the merge base. A new ID whose own relationships: name such a new ID, with the same marker, is exempt too. No other new ID is exempt, even one split off a requirement with no marker. Such a split gives its new ID a verification: check instead. The guard lists each requirement it fails and compares against no committed count.

spec-lint judges each marker alone, so it passes a new unverified requirement with a marker, and a relabel that re-points its marker at another kind's owner, which MS-10-008 forbids. Either adds debt to a backlog that may only shrink. A split (MS-03-001) moves a marker to a new ID that links back, adding none; an unmarked parent has none to move. Per-item sets compared with the merge base leave no committed number for concurrent pull requests to race on (#3984).
Constrains: MS-10-006
MS-10-017 SHOULD A rationale: SHOULD read as Simplified Technical English in spirit: short sentences, a constrained vocabulary, the active voice and no jargon. Its domain terms are the ones CONTEXT.md and docs/reference/glossary.md define, even where an STE-approved word could replace one.

For most project and process requirements, the rationale is the only written reason. A reader who is new to the project must understand it. Short, plain sentences are easy to read and to translate. One term for each concept lets a reader find the same idea in specs, docs and code. An STE swap gives a second word for the concept and breaks that link, so the glossary term or spec term stays: "create a case", not "make a case".
Extends: MS-10-012

Spec vs. ADR Delineation

ID Priority Requirement Related
MS-11-001 MUST A spec file MUST capture testable requirements: what the system does, stated with RFC 2119 keywords, so that the spec defines the system's intended behaviour.

A requirement that a test can check gives implementers and reviewers one contract. RFC 2119 keywords state how binding each requirement is.
MS-11-009 MUST NOT A spec file MUST NOT record the reason for choosing one approach over another.

Mixing decision rationale into spec files blurs the distinction between requirements and design history, making both harder to maintain and trace. A decision record holds that reason (MS-11-002).
Extends: MS-11-001
MS-11-002 MUST An Architecture Decision Record (ADR) MUST be created whenever a meaningful alternative was evaluated and rejected. The primary signal for an ADR is the presence of options considered and discarded — "we weighed X, Y, and Z and chose X because …"

If no real fork existed, there is no decision to record. An ADR without evaluated alternatives is just prose documentation and belongs in notes/ instead.
MS-11-003 SHOULD When a significant architectural decision generates recurring testable requirements, both an ADR and a spec entry SHOULD be created. The ADR captures the why (context, options, consequences); the spec captures the what (requirements agents and reviewers must satisfy going forward).

The two documents serve different audiences. The ADR is for human reviewers asking "why was this chosen?"; the spec is for implementation agents asking "what must I do?". Collapsing them into one document serves neither well.
MS-11-004 SHOULD A spec entry that an ADR-backed decision motivated SHOULD reference the ADR in its rationale field.

Bidirectional cross-references make it possible to trace a requirement back to its decision rationale and forward from a decision to its testable consequences.
MS-11-010 SHOULD An ADR SHOULD list the spec IDs that it generated in its "More Information" section.

The list lets a reader go from a decision to its testable consequences. With MS-11-004, the trace runs in both directions.
MS-11-005 SHOULD When the correct approach is uncontested and no alternative was seriously considered, a spec entry alone is sufficient. An ADR SHOULD NOT be created merely to document an obvious or unchallenged choice.

Writing ADRs for trivial decisions adds noise to the decision log and devalues the records that capture genuine trade-offs.
MS-11-006 SHOULD When a decision is a one-time structural or process choice with no recurring testable requirements (e.g., "use CalVer for project versioning", "pin CI actions to full commit SHAs"), an ADR alone is sufficient. A spec entry SHOULD NOT be created if there is no per-change requirement for agents to check.

Not every decision produces enforceable requirements. Creating spec entries for binary one-time choices inflates the spec corpus without providing testable value.
MS-11-007 MUST NOT This rule covers spec files, notes/ files, and code comments and docstrings under vultron/ and test/. Such a file MUST NOT resolve its meaning by naming a numbered part inside a decision record's body. A numbered part is a record ID with a detail, rule, step, option, part, invariant or section (§) number. Examples are a record's "Rule N" and "invariant N". A decision record that cites a numbered part of another record is out of scope: that is history citing history. Any "detail" followed by a number counts, even a bare "detail N" a sentence after the record was named. The other part words count only with a record ID nearby, because a numbered step of a procedure is ordinary prose.

A part number is defined nowhere but the record body, so a citation of one makes the body load-bearing and forces every reader to load it, which ADR-0127 removes from routine agent context. A rule stated in a requirement is checked by its verification clause; a rule left in a body ages with nothing to say it has. The shape is not specific to one word: a rule, option or decision-part number points into a body exactly as a detail number does. Agents read code comments as often as spec files, so the citation shape is equally harmful there.
MS-11-011 MUST A file that MS-11-007 covers MUST state a decision-record rule where the reader already is, or cite the requirement that states it. It cites the record only as provenance for why.

A reader can then act on the rule without loading the record body, which ADR-0127 removes from routine agent context. A rule stated in a requirement is checked by its verification clause, and the record still shows why the rule exists.
Extends: MS-11-007
MS-11-008 MUST deepen-context, the routine context-loading skill, MUST route through decision records by the generated title index and by the adr: edges of requirements. It reads those edges in the record-to-requirements direction.

A record body is history. Its description of the code becomes out of date with each refactor, but the decision stays valid. When an agent loads the body as routine context, it uses working memory on claims that are no longer true (ADR-0127).
MS-11-012 MUST deepen-context MUST carry a written list of the skills that read decision-record bodies in full, with the reason each one needs them. The list names at least decision auditing, record authoring, the learning workflow, issue planning and pull-request triage.

A written list of exceptions prevents a reader from taking the routing rule of MS-11-008 to mean "never read a record". The skills it names make a record their object of work, so they need its full text.
Extends: MS-11-008
MS-11-013 MUST NOT A skill kept in this repository and not on the MS-11-012 list MUST NOT tell an agent to read a decision-record body.

A skill off the list that reads record bodies brings back the routine loading that MS-11-008 removes. The list is the only way to add an exception.
Uses definition from: MS-11-012
MS-11-014 MUST Each skill on the MS-11-012 list kept in this repository MUST weigh what it reads by the shared guidance on when a record is challengeable.

A record can be provisional or uncertain. A skill that weighs what it reads treats such a record as provisional or uncertain, and not as settled fact.
Uses definition from: MS-11-012

SpecKind Classification Decision Tree

Rules for assigning a kind value to a new or reclassified spec. Who must obey a rule decides its kind. Split a spec that mixes kinds first, then stop at the first matching question.

ID Priority Requirement Related
MS-12-001 MUST When a spec is about how the project is run — CI configuration, GitHub workflow, agent conventions, documentation standards, or spec authoring rules — the spec MUST be classified as process.

Rules about how the project is run apply only to the maintainers and agents of this repository. The behavior of an implementation does not depend on them. When this question comes first, these rules stay out of project, so project holds only constraints on the codebase. The rules also stay out of the protocol and conformance views that implementers read. Each kind has its own verification owner (MS-10-006), so a process rule in the wrong kind also goes into the wrong backlog.
MS-12-002 MUST A spec's kind MUST be decided by who must obey it. Naming a codebase construct, such as a file path, library, class, or Behavior Tree node, never decides it.

Compare TCP and an operating system's socket API. An RFC fixes what two independent implementations exchange on the wire; how one implementation structures its internals (its endpoints, stores, compare-and-set loops) is not RFC content, however firm the MUST. Naming code is a symptom, not the test: a protocol rule spelled in this codebase's terms is reworded, and one that also says how this codebase meets it is split (MS-12-010). Neither is relabeled.
MS-12-012 MUST When only this codebase must obey a spec, the spec MUST be classified as project. Such a spec is a deployment choice, a performance or operating limit, how a receiver records what it receives, or a core internal. One deployment choice is running the CASE_MANAGER as an actor separate from the Case Owner.

A rule that only this codebase must obey binds no other implementation, so it stays out of the protocol view that implementers read. EP-02-007 (compare-and-set on the policy PUT) is the worked example: only this codebase must obey it, so it is project.
Uses definition from: MS-12-002
MS-12-003 MUST When every Vultron implementation, in any language or framework, must obey the spec to take part in the protocol, the spec MUST be classified as protocol. protocol is the Vultron layer: Vultron's message forms on the wire (including where ActivityStreams allows several forms and Vultron requires one), which messages are sent and when, what a receiver does given its state (including on duplicate delivery), and the state machines underlying those behaviors. Nothing else is protocol.

The test is the TCP analogy: if the sentence could appear in an RFC for the protocol and an implementer in any language would have to honour it to interoperate, it is protocol. Behaviour that only changes how one implementation is built is not. State-machine states such as RM.CLOSED are protocol constructs. The CASE_MANAGER role and case-ledger sync are protocol for now; they are re-judged if the protocol moves to a federated design with no CASE_MANAGER (ADR-0134).
MS-12-004 MUST When none of the above apply — the spec is a structural or behavioral constraint that is implementation-independent but not required for Vultron compliance — the spec MUST be classified as architecture.

The decision tree needs a last answer, so that each spec gets exactly one kind (MS-12-005). After the earlier questions, the remaining specs are recommended structure. Any implementation can adopt such a constraint, but compliance does not require it. The name architecture keeps these specs out of protocol, where implementers would read them as necessary to interoperate. It also keeps them out of project, where they would seem specific to this codebase.
MS-12-005 MUST An author MUST apply the decision tree in order (MS-12-001 → MS-12-012 → MS-12-009 → MS-12-003 → MS-12-004) and assign the kind of the first question that matches.

Each question asks who must obey the rule, in this order: how the project is run, this codebase only, every implementation of a standard Vultron inherits, every Vultron implementation, and recommended structure. foundation precedes protocol so a rule that only restates ActivityStreams, ActivityPub or HTTP is not counted as Vultron's own.
Uses definition from: MS-12-001
Uses definition from: MS-12-012
Uses definition from: MS-12-009
Uses definition from: MS-12-003
Uses definition from: MS-12-004
MS-12-013 MUST Before an author applies the decision tree (MS-12-005), the author MUST split a spec that mixes kinds as MS-12-010 directs.

A mixed spec would otherwise match project and hide its protocol half from implementers. Splitting first gives each half its own kind.
Extends: MS-12-005
Uses definition from: MS-12-010
MS-12-006 MUST spec-lint MUST emit a hard error for any protocol or foundation spec that carries no stories: back-reference and whose statement names an unambiguous codebase construct. Such a construct is a .py suffix, a vultron/, test/, or scripts/ path, or the token pytest, pydantic, or py_trees.

A MUST that nothing enforces gives a false signal. When only some specs obey it, readers think that no rule exists. Also, protocol-kind specs collect suppressions of the missing-story-reference check, and nobody corrects their kind. Two choices keep the check off specs that already comply. The check scans only specs with no stories. Its token list is narrow, so it does not match domain English. notes/spec-authoring-rules.md gives the derivation. The check scans only the statement. A verification field names the test that checks a rule, and a test file name there does not show if the rule is protocol content. The check also scans foundation. A foundation rule whose statement names code in this codebase also tells how this codebase obeys it, so it is a mixed spec to split (MS-12-010, ADR-0134).
Verifies: MS-12-002
MS-12-014 MUST spec-lint MUST let a spec suppress the MS-12-006 check with the protocol_kind_with_code_reference lint_suppress code.

A per-spec suppression is the escape hatch for a statement that names code on purpose. The code has the name protocol_kind_with_code_reference, but it also applies to foundation. Specs use that name, and a new name would break them. MS-12-008 holds the code at no carrier.
Extends: MS-12-006
MS-12-015 MUST The MS-12-006 error message MUST advise rewording the statement so any implementation could obey it, or splitting the spec (MS-12-010), rather than relabeling it.

A code reference never decides a kind (MS-12-002). A message that advised a new kind would route a spec around the decision tree, so the remedy is to reword or split the spec.
Extends: MS-12-006
Uses definition from: MS-12-010
MS-12-007 MUST A PR-only growth guard MUST fail each pull request that adds a lint_suppress: [missing_story_reference] carrier. A carrier is added when a spec carries the code at the PR head but not at the merge base with the base branch. This holds whether or not SR-11-003 would fire on it. The guard names each such spec.

Suppression is the escape hatch SR-11-003 provides, so it cannot be forbidden, but an unguarded escape hatch is how the backlog accumulated. Every carrier counts, dead ones too; spec-lint prints the total. MS-12-008 closes the other code, so the two cannot trade places.
Constrains: SR-11-007 — bounds the lint_suppress opt-out SR-11-007 allows for the hard error
Constrains: SR-11-008 — the same suppression code silences the SR-11-004 advisory through SR-11-008
See also: SR-11-003 — a scope phrase ("whether or not SR-11-003 would fire"); the guard bounds the SR-11-007 opt-out, not the error
MS-12-016 MUST NOT The MS-12-007 guard MUST NOT fail a pull request that removes a missing_story_reference suppression.

Removing a suppression shrinks the backlog, which is the direction the guard exists to protect. A guard that failed on it would block the cleanup it asks for.
Extends: MS-12-007
MS-12-017 MUST NOT The MS-12-007 guard MUST NOT compare against a committed count.

Each carrier is recorded on its own spec, so the guard compares carrier sets and commits no number. A pinned count races concurrent PRs and a one-sided ceiling collects slack (notes/testing-pitfalls.md).
Extends: MS-12-007
MS-12-008 MUST A test MUST assert that no spec in the live corpus carries lint_suppress: [protocol_kind_with_code_reference].

MS-12-014 adds a second escape hatch next to the one MS-12-007 guards. If only one of the two is held, a pass can swap suppressions from the guarded code to the unguarded one: one total falls, the other grows, and every gate stays green. The code has never had a carrier, so it is held at that terminal value outright rather than by a growth guard; admitting a carrier means amending this requirement.
Uses definition from: MS-12-014 — holds the suppression escape hatch MS-12-014 provides at no carrier
MS-12-009 MUST A spec MUST be classified as foundation when every implementation must obey it because Vultron inherits it from a standard beneath it. Those standards are ActivityStreams 2.0, ActivityPub, and HTTP.

Addressing and delivery, HTTP status codes, and rules that only restate ActivityStreams (every id is an IRI) bind every implementation, but Vultron does not own them. Filing them as protocol inflates what Vultron defines; filing them as project hides them from implementers, who read protocol and foundation together. Where Vultron requires one form among several the standard allows, the rule is Vultron's own and is protocol.
MS-12-018 MUST A foundation spec MUST carry the tag that names the standard it inherits from: as2, activitypub, or http.

The tag lets a reader trace each rule to the standard that owns it.
Extends: MS-12-009
MS-12-019 MUST spec-lint MUST emit a hard error for a foundation spec whose effective tags name none of the three standards.

A tag rule that nothing checks is obeyed only by some specs. A hard error keeps every foundation spec traceable to its standard.
Verifies: MS-12-018
MS-12-010 MUST An author MUST split a spec that mixes kinds along what other participants can observe.

A mixed spec gives one kind to two kinds of rule, so one half lands in the wrong view. What other participants can observe is the line between the protocol half and the half that only this codebase must obey. Worked example: default-embargo creation. The protocol half says other participants never observe the intermediate Proposed state; the project half says this codebase applies PROPOSE and ACCEPT atomically in one behavior tree node.
MS-12-020 MUST In that split, the original ID MUST keep the half that states what is emitted or observed, reworded so any implementation could obey it.

Keeping the original ID on the protocol half keeps its user stories, test markers and citations where implementers look, so the PR-only growth guards (SR-05-005, MS-12-007) see no new uncovered protocol spec and no new suppression.
Extends: MS-12-010
MS-12-021 MUST In that split, the half that states how this codebase does it MUST move to a new project ID whose relationships: name the original ID.

The codebase half binds no other implementation, so it leaves the protocol view. The link to the original ID lets a reader find the protocol rule that this codebase meets.
Extends: MS-12-010
MS-12-011 MUST Changing a spec's kind MUST NOT remove the tests or @pytest.mark.spec markers that already verify it, whatever the destination kind. A spec relabeled from protocol to project, for example, keeps its tests and markers even though project does not require them.

A test that verifies a rule is evidence the rule holds, and a kind change does not change whether it holds. Dropping markers on a relabel would turn a re-judgement sweep into a way to shed coverage, and a later relabel back would find the tests gone.
Constrains: MS-12-005 — constrains how the kind the decision tree assigns is applied

Spec Item Format Selection (StatementSpec vs BehavioralSpec)

ID Priority Requirement Related
MS-13-001 MUST A spec item MUST use BehavioralSpec format (with preconditions, steps[], and postconditions fields) when it describes a sequential, stateful process that has a defined start state, ordered actions, and terminal conditions.

StatementSpec statement text is a single normative sentence. Encoding ordered sub-steps as numbered lists inside that sentence violates MS-05-001 (no inline prose explanations) and makes the start state, step ordering, and terminal conditions invisible to conformance tooling.
MS-13-002 MUST A spec item MUST use StatementSpec format when it expresses a capability constraint, behavioral property, or structural rule that does not depend on step ordering — i.e., it specifies a required outcome or invariant, not a prescribed sequence of actions.

BehavioralSpec's steps[] field implies ordering that is not meaningful for property requirements; StatementSpec is simpler and more appropriate.
MS-13-003 MUST A spec group whose items describe a demo scenario workflow MUST include a trigger field with type: scenario_start to indicate to conformance tooling that the group is a process workflow, not a property group.

The trigger field allows tooling to classify groups by activation kind without parsing item content. scenario_start distinguishes demo-script-triggered workflows from message_received and state_entered behavioral groups.
MS-13-004 MUST A spec group with trigger type scenario_start MUST contain at least one BehavioralSpec item with a non-empty steps field describing the ordered protocol exchange.

Mixed groups are permitted. Terminal-state assertions and infrastructure constraints can stay StatementSpec items. But the sequential workflow must be a BehavioralSpec, so that conformance tooling and CI can verify the ECA structure without parsing prose. spec-lint enforces the rule (SR-04-003): a group with only StatementSpec items is a hard error.

ADR Status as Confidence Signal

ID Priority Requirement Related
MS-14-001 MUST Every ADR under docs/adr/ (excluding the template and index) MUST declare a non-empty status field whose value is a member of the AdrStatus StrEnum (proposed, accepted, accepted-provisional, deprecated, rejected, superseded); the inline MADR form "superseded by " is accepted and normalised to superseded.

The status field is the primary confidence signal that reaches coding agents (deepen-context weights ADR trust by it). A blank or non-standard status leaves agents to treat an unvalidated decision as settled fact. ADR-0024 shipped with a blank status; this rule prevents recurrence. AdrStatus is the fixed vocabulary (SR-02-002) the linter typechecks against. Enforced by spec-lint. See ADR-0043 and notes/specs-vs-adrs.md.
MS-14-002 SHOULD An ADR's status value SHOULD agree with its prose.

A status/prose contradiction is a landmine: the agent trusts status: accepted while the body admits the design is unvalidated. ADR-0025 was the motivating case.
MS-14-013 SHOULD Provisional markers include formed in sand, not concrete, provisional, forward-looking, will converge, SHOULD refine this ADR and status will advance. An ADR whose body holds one SHOULD declare accepted-provisional or proposed as its status, not accepted.

spec-lint emits an advisory warning (not a hard error) because the substring scan can false-positive on ADRs that merely discuss provisional-ness; flagged ADRs are decision-audit candidates for human adjudication. An ADR that legitimately discusses provisional-ness (e.g. ADR-0043, which defines the vocabulary) MAY opt out with frontmatter 'lint_suppress: [status_prose_contradiction]', mirroring the spec-level lint_suppress mechanism (SR-02-011).
Refines: MS-14-002
MS-14-003 MUST An ADR's placement in docs/adr/index.md (Accepted / Proposed / Rejected / Superseded-Archived sections) MUST agree with its own status field.

Index-vs-frontmatter drift (ADR-0027 was listed provisional in the index while its file said accepted) misleads both humans and the agents that read the index.
MS-14-014 MUST docs/adr/index.md MUST list a retired ADR (status deprecated or superseded) under the Superseded / Archived section, with a forward link to its replacement, not under Accepted.

A retired ADR listed under Accepted reads as a live decision. The forward link takes a reader from the retired decision to the one that replaced it.
Refines: MS-14-003
MS-14-004 SHOULD A newly-retired ADR (status deprecated or superseded) SHOULD be moved to docs/adr/archived/ so it stays out of the default docs/adr/ context sweep.

Archiving retired ADRs keeps outdated decisions out of the default docs/adr/ sweep so agents must deliberately seek them. See ADR-0043.
MS-14-015 MAY An ADR retired before the archive convention of MS-14-004 MAY stay in docs/adr/ until it is next touched.

The convention applies forward (SHOULD, not a retroactive MUST) to avoid churn on already-superseded ADRs that are still referenced by path.
Uses definition from: MS-14-004
MS-14-007 MUST An ADR's status MUST be at least the lifecycle epoch computed for it (ADR-0120). Epoch 1 (proposed) ends at the first of two events: day 14 after updated, or a test-verified dependent (MS-14-010). A test-verified dependent is a spec requirement that cites the ADR in adr: and whose verification names a test file that exists. The dependent is counted in the tree being checked: the pull request's head for a check on a pull request, main for the scheduled check. Epoch 3 (accepted) starts at day 28 after updated. Between the two, the epoch is 2 (accepted-provisional).

Elapsed time alone does not show that an ADR had its chance to be revised. The first dependent that a test verifies shows it, because the material test asks if something built on the old text would now be wrong. The timers are a backstop, so every ADR gets to accepted. Boundaries are counted in whole days (14 and 28), because updated is a date. The dependency is counted on the head of the pull request, because the pull request that creates the dependency must already show its effect (MS-14-010).
Uses definition from: MS-14-001
MS-14-019 MUST A pull request that materially edits an ADR MUST leave its status on the epoch for the new updated date. Only a status_override: whose value is a human's reason lets the status stay off that epoch. A material edit changes the ADR's updated date, or adds the ADR.

A material edit restarts the ADR's timers, so the status that the edit leaves must match the restarted epoch. An override keeps a status off its epoch only as a visible human act.
Uses definition from: MS-14-007
MS-14-020 MUST A check that compares a pull request against its base MUST fail a pull request that breaks MS-14-019.

A rule on pull requests is only as strong as the gate that refuses a pull request that breaks it. Comparing against the base shows which ADRs the pull request materially edited.
Verifies: MS-14-019
MS-14-021 MUST NOT A merge-blocking check MUST NOT depend on today's date for an ADR that the pull request did not materially edit.

A merge-blocking check that reads the current date would make main fail when no commit causes the failure. The scheduled check reports the drift of the clock instead (MS-14-022, ARCH-18-009).
Constrains: MS-14-020
MS-14-022 MUST A scheduled check MUST report every ADR whose status is behind today's epoch, without failing the build. It reports through one tracking issue that closes itself when none remain.

The clock moves an ADR's epoch with no commit, so a scheduled check, not a merge-blocking one, finds a status left behind. A report that fails no build keeps main green while it shows the drift.
Verifies: MS-14-007
MS-14-031 SHOULD The scheduled check of MS-14-022 SHOULD run at least once a week.

An ADR whose status falls behind its epoch misleads every reader until a human flips it, and the report is what tells the human. A week is the longest delay that keeps a stale status from being read as current. The exact time is a setting in the workflow, not part of the requirement.
Refines: MS-14-022
MS-14-008 MUST ADR frontmatter MUST carry created (set once, never changed), updated (changed only by a material edit), and revision (an integer incremented by each material edit).

The epochs of ADR-0120 are measured from updated, so it must move only when the decision changes; date was rewritten by editorial edits and cannot serve. created is the immutable birth date and revision counts how many times the decision has changed.
Extends: MS-14-005
MS-14-023 MUST Each ADR that predates the MS-14-008 fields MUST be migrated with created and updated set to its date, and revision set to 1.

An ADR with no lifecycle fields has no epoch, so every check that reads one would fail on it. Setting both dates to the ADR's own date starts its epoch where its decision was made.
Refines: MS-14-008
MS-14-009 MUST adr-lifecycle-check MUST fail a diff that changes the Decision Outcome or Considered Options section of an epoch-3 ADR without a dated Amendment block. It runs as a pre-commit check.

ADR-0120 forbids rewriting an accepted ADR under its own number, and the audit that produced it found exactly that done by agents. The rule is only as strong as the gate that refuses the edit, and a reviewer reading a large diff does not reliably see a changed section. A heading that names "Amendment" and a date is the mechanical mark of a dated Amendment block.
Uses definition from: MS-14-007
MS-14-024 MUST adr-lifecycle-check MUST fail a diff that bumps updated on an ADR that was past epoch 1, unless the ADR carries a status_override.

Bumping updated restarts the timers, which would move a settled ADR back to an editable epoch. The override makes that move a visible human act.
Extends: MS-14-009
MS-14-025 MUST adr-lifecycle-check MUST also run, against the merge base, on every pull request that changes an ADR, so a skipped local hook cannot bypass it.

A pre-commit hook runs only where an author installed it, and an author can skip it. The same check in CI holds every pull request to the rule.
Extends: MS-14-009
MS-14-010 MUST This rule covers a pull request after which an ADR that is proposed on its base first has a test-verified dependent (MS-14-007). Such a pull request MUST set that ADR's status to accepted-provisional. The rule holds however the dependent is created. A new requirement that cites the ADR creates one. So does adr: or a verification added to an existing requirement, or the test file that a verification names.

The dependency ends epoch 1 (MS-14-007), but it lands in a spec and a test, usually in a pull request that never touches the ADR. The pull request that changed the facts owns the status, as a material edit already does; leaving the flip to the scheduled drift report would leave the ADR reading proposed, and free to rewrite, while code depends on it.
Uses definition from: MS-14-007
MS-14-026 MUST The check that compares a pull request against its base MUST fail a pull request that breaks MS-14-010.

Without a gate, the flip waits for the scheduled drift report, and the ADR stays free to rewrite while code depends on it. The check sees that the named test file exists, not that it passes.
Verifies: MS-14-010
MS-14-012 MUST An ADR's status MUST only move forward through the epochs. A status ahead of the computed epoch that the ADR already carried on the base stands. It is not a fault for the scheduled check, nor for a pull request that does not materially edit the ADR. A material edit that restarts the timers keeps it under the status_override: that MS-14-019 and MS-14-024 already require of that edit.

ADR-0120 exists so that a citation keeps meaning what it meant. A change to the timers can make an ADR that is already accepted compute as accepted-provisional; demoting it would loosen the edit tiers on a decision agents had already built on. Treating the computed epoch as a floor covers any such change.
Uses definition from: MS-14-007
Uses definition from: MS-14-019
Uses definition from: MS-14-024
MS-14-029 MUST A pull request that moves status ahead of its computed epoch MUST add or change a status_override: whose value is a human's reason. An override already on the base does not satisfy this.

The guard keeps a promotion ahead of the clock a visible human act rather than a silent frontmatter edit. An override left from an earlier, unrelated reason would make every later promotion silent again.
Extends: MS-14-012
MS-14-030 MUST The check that compares a pull request against its base MUST fail a pull request that breaks MS-14-029.

A rule on pull requests is only as strong as the gate that refuses a pull request that breaks it.
Verifies: MS-14-029

Spec Statements and ADR Edits Must Not Reference Phantom Paths or Phantom Symbols

ID Priority Requirement Related
MS-15-001 MUST NOT A spec item's statement, verification, behavioral step, precondition, and postcondition fields MUST NOT reference a file path or directory path that does not exist.

A normative statement naming non-existent infrastructure is a stale-premise landmine: the agent invents something inconsistent with the codebase or silently ignores a MUST. DEMOMA-19-008 named a conftest.py registry that had never existed; an audit found 18 phantom-path clauses. Behavioral step, precondition, and postcondition fields are scanned in addition to statement and verification because they are equally normative. rationale legitimately cites gone paths and is excluded.
MS-15-002 MUST NOT A spec item's statement and verification fields MUST NOT use an absolute path or a .. segment.

Absolute paths and parent-traversal segments are deployment-specific and will not resolve correctly in the repo-relative context used by spec-lint.
Extends: MS-15-001
MS-15-003 MUST A spec-first requirement that deliberately names a file yet to be created MUST either use a placeholder form (e.g. test_XXX_invariants.py) or opt out with lint_suppress: [phantom_path_ref].

The placeholder or lint_suppress mechanism makes the spec-first intent explicit rather than silently passing a phantom-path check by accident.
Supersedes: MS-15-001
MS-15-004 MUST NOT A spec item's statement, verification, behavioral step, precondition, and postcondition fields MUST NOT reference a backticked all-caps code symbol containing at least one underscore that appears nowhere in the vultron/ or test/ Python sources.

MS-15-001 examines only backticked tokens that contain a directory separator. Thus a bare symbol name passes it, and a retired symbol can stay in MUST-level protocol statements across many spec files. A MUST about a symbol that nobody can find is worse than no requirement. The agent either invents a replacement or ignores the obligation. The rule needs at least one underscore, so it excludes token shapes that are not symbols: RFC 2119 keywords, protocol shorthands and one-word state names. The check is textual and covers the whole tree, and it does not look up bindings. It accepts a false negative, so that it does not block a valid reference. The rule excludes rationale, as MS-15-001 does, because the problem that a rationale names (MS-10-012) can be a removed symbol that must not return.
Extends: MS-15-001 — extends the phantom-reference guarantee from paths to code symbols
MS-15-005 MUST A requirement that deliberately names a retired code symbol, or a convention token that was never code, MUST opt out with lint_suppress: [phantom_symbol_ref].

Two valid reasons exist to name a symbol that does not resolve. One reason is to record its removal, so that it does not return. The other reason is to name a proposed spec-authoring tag that is not an identifier (PROTO-04-001's PROD_ONLY). The explicit opt-out shows both as deliberate choices. Without it, they look the same as the stale MUSTs that MS-15-004 finds.
Supersedes: MS-15-004
MS-15-006 MUST NOT A change that edits an ADR MUST NOT add to it a backticked file path, directory path or code symbol that resolves nowhere. Such a reference is a path missing from the repository, or a symbol found nowhere in the vultron/ or test/ Python sources. Recognized symbol shapes are underscored all-caps constants, CamelCase class names and called names such as snake_case(). Members of a CamelCase class, and all-caps members after a dot, are symbol shapes too. The rule covers only references the change adds to a record it edits. A reference present on the merge base, however stale, and a change that edits no ADR are outside it.

ADR-0127 makes an ADR a historical record: a reference that aged after it was written is an accurate account of the code as it then stood, so a refactor owes the record nothing and no check keyed on code changes may fail on it. A reference newly written into a record is different — it should resolve on the day it is written, and that is a question about the change's own diff. The spec-corpus check of MS-15-004 reads only underscored constants, which misses the class and function names that make up the aged references in the corpus, so this check reads more shapes. It resolves textually, preferring a false negative to refusing a legitimate reference, as MS-15-004 does.
Extends: MS-15-001 — extends the phantom-reference guarantee to references an edit adds to an ADR
Extends: MS-15-004
MS-15-008 MUST The pre-commit check adr-added-reference-check MUST enforce MS-15-006 against HEAD.

A hook at commit time finds an unresolvable reference while the author still has the edit open, which is the cheapest place to fix it.
Verifies: MS-15-006
MS-15-009 MUST adr-added-reference-check MUST also run, against the merge base, on every pull request that changes an ADR, so a skipped local hook cannot bypass it.

An author can skip a local hook. Comparing against the merge base is the shape MS-14-025 already uses, and it sees every reference the pull request adds.
Verifies: MS-15-006
MS-15-007 MUST An ADR edit that deliberately adds a reference that does not resolve — a symbol or path the record annotates as removed, or a convention token that was never code — MUST opt the record out in its frontmatter with lint_suppress: [phantom_symbol_ref] for a symbol or lint_suppress: [phantom_path_ref] for a path. The opt-out covers the whole record: every later edit to it adds references of that kind unchecked.

A decision record that notes a removal names the removed symbol or path because it is gone. Thus that reference can never resolve. The opt-out is the same as MS-15-005 for requirements. It shows the choice as deliberate, so that it does not look like a mistyped name.
Supersedes: MS-15-006

Long-Lived Docs Must Not State Unverifiable, Drift-Prone Facts

ID Priority Requirement Related
MS-16-001 MUST A spec statement, notes file, or AGENTS.md entry MUST NOT restate a count that will drift independently of the authoritative source. When cross-referencing another spec item, omit the count and cite the source by ID: write "the universal types (DEMOMA-16-001)" not "the five universal types (DEMOMA-16-001)". Counts in enumerations that are the authoritative source (e.g. DEMOMA-16-001 itself listing its own members) are not subject to this rule.

A count that a cross-reference restates drifts, and nobody sees it. When the authoritative requirement changes, its sibling references and the citations in other files do not change. The linter makes sure that a referenced spec ID resolves, but it does not examine the prose near the ID. A reader who sees the stale count first gets a false picture of the system. The count adds no normative force. "The universal types (DEMOMA-16-001)" is equally specific, because the ID points to the authoritative source. Without this rule, one change to an enumerated set can require an edit in each file that restates its size. The same principle applies to all long-lived documents, not only to spec cross-references. Notes files, AGENTS.md pitfall entries and architecture docs must not state counts such as "there are 4 unimplemented nodes" or "15 xfails". These snapshots will be wrong when a person reads them later. Decision-record bodies are out of scope, because a dated count in a record stays true on its date (ADR-0127).
Refines: MS-16-002
See also: DEMOMA-16-001 — an example of an authoritative enumeration
MS-16-002 MUST A long-lived document MUST NOT state a fact that no automated check could falsify and that drifts independently of its source. A long-lived document is a spec, a notes file, AGENTS.md, or a docs/ table that mirrors a code, spec, or config inventory. The governing test is "could a test fail on this sentence?" A restated count (MS-16-001) is one such fact. A per-item runtime outcome ("✅ passes"), a forecast ("resolved by #789"), or a free-prose claim copied from source are others.

Nobody checks a fact that nothing can check, so it becomes wrong first. It also becomes a confident wrong answer, not a gap, and that costs more than no document. Counts (MS-16-001) are the most usual example. The question "could a test fail on this sentence?" finds the other examples. In a table that mixes the two, the columns derived from source stay correct, and the columns that no test holds become wrong. Decision-record bodies are out of scope, because readers read them as dated history (ADR-0127).
MS-16-003 MUST Each fact that MS-16-002 forbids MUST either be made verifiable or be replaced by a pointer to where the live answer lives. A fact is made verifiable when it is derived from, or ratcheted against, its source.

Deleting the fact alone leaves a reader with no answer, and keeping it unchecked leaves a wrong one. Before you decide that a column is unverifiable, find out if it combines two or more facts. A column that answers two questions cannot be verified as a unit, but each part can possibly come from its source. notes/documentation-sweeps.md gives the procedure for this check.
Extends: MS-16-002

One Wire Form per Protocol Act

How a requirement handles an act that ActivityStreams lets a sender express in more than one wire form, so that the reference implementation's habit never reads as a protocol rule and a receiver never pays for forms no sender needs.

ID Priority Requirement Related
MS-18-001 MUST When ActivityStreams allows more than one wire form for one protocol act, the protocol requirement for that act MUST name exactly one form. A form the protocol does not name is not a protocol message.

A receiver that must accept all allowed forms pays for each form that any sender selects. When several forms are allowed, a reader sees only the choice of the reference implementation, so its habit looks like a protocol rule. When the other forms are deferred, they stay open for later design, and no receiver must accept them now.
MS-18-003 MUST Each other wire form considered for the act MUST be recorded as a deferred alternative in an open question. The question goes on the Open Questions page (docs/topics/future_work/open_questions.md).

A deferred form stays open for later design, and the open question shows a reader that it was weighed. No receiver must accept it now.
Extends: MS-18-001
MS-18-002 MUST NOT A requirement, a semantic registry occasion or a reader-facing page MUST NOT allow several wire forms for one protocol act and then record which of them this codebase sends; the choice is made once, in the protocol requirement (MS-18-001).

A per-message marker of "allowed versus sent" makes each receiver accept forms that no implementation must send. It is also one more manual fact that drifts from the emitters (MS-16-002). When the protocol requirement makes the choice once, a receiver has one form to accept.
Refines: MS-18-001 — rules out the allow-several-then-mark-one alternative

Notes Frontmatter

Requirements for YAML frontmatter in notes files, covering the required schema, a Pydantic-based loader, validation enforcement, migration requirements, what a note is for and how it is written, and the report that flags delivered plan notes.

File ID: NF

Frontmatter Schema

ID Priority Requirement Related
NF-01-001 MUST Every notes/*.md file (except notes/README.md) MUST contain a YAML frontmatter block delimited by --- at the top of the file.

Tooling and agents use the frontmatter to select which notes to read, and they do not open each body. A note without a frontmatter block cannot be selected and cannot be validated.
NF-01-002 MUST The frontmatter MUST include a title field whose value is a non-empty string matching the file's # H1 heading.

Indexes and agents use the title to name a note. If the title is not the same as the H1, the note has two names, and a reader cannot tell that they are one file.
NF-01-003 MUST The frontmatter MUST include a status field whose value is one of: active, draft, superseded, archived.

A reader must know if a note is current before the reader acts on it. A closed vocabulary lets tooling remove superseded and archived notes from a selection. Free text does not let tooling do this.
NF-01-004 MUST When status is superseded, the frontmatter MUST include a superseded_by field.

A superseded note is useful only if it points to the file that replaced it. Without that pointer, a reader who opens the note cannot find the current guidance.
NF-01-012 MUST A superseded_by value MUST be a non-empty string that names the replacement file path, such as notes/new-topic.md.

The pointer is useful only if it names a file. An empty value passes a presence check, but it still gives the reader no way to find the current guidance.
Extends: NF-01-004
NF-01-005 MUST The optional description field, when present, MUST be a non-empty string summarising the file's purpose for tooling and agents.

An empty description looks like a value, but it gives tooling and agents no data for a selection. When the field is present, it must be a non-empty string, so that the field always gives information.
NF-01-006 MUST The optional related_specs field, when present, MUST be a non-empty list of non-empty strings naming related specification files (e.g., ["specs/behavior-tree-integration.md"]).

Tooling and agents use related-spec lists to go from a note to the requirements that it informs. An empty list or an empty entry looks like a link, but it points to nothing.
NF-01-007 MUST The optional related_notes field, when present, MUST be a non-empty list of non-empty strings naming related notes files.

Related-note lists let a reader find related guidance. An empty list or an empty entry looks like a link, but it points to nothing.
NF-01-008 MUST Each relevant_packages entry MUST be either a dot-separated Python package name, such as vultron.core, or a top-level package directory name, such as vultron.

Entries are package names only, so a tool can compare them with import paths mechanically.
Extends: NF-01-013
NF-01-013 MUST The optional relevant_packages field, when present, MUST be a non-empty list of non-empty strings that name packages relevant to the topic of the note.

Package lists connect a note to the code that it governs. Thus an agent that edits a package can find the notes for that package. An empty list or an empty entry connects the note to no code.
NF-01-009 MUST The frontmatter MUST include a kind field whose value is one of guidance, plan, or generated, as defined by NF-08-002.

The kind sets the lifecycle of the note. A plan note retires when its work lands. A guidance note stays. A tool writes a generated note again each time it runs. Without a declared kind, no reader or tool can tell which rules apply to the note.
Uses definition from: NF-08-002
NF-01-010 MUST A note whose kind is plan MUST include a tracks field. Its value is a non-empty list of GitHub issue references in #N form, naming the issues the plan informs and their parent epic.

Tooling uses the tracked issues to find when the work of a plan is done (NF-09-001). The note also tracks the parent epic, not only the leaf issues. Thus the note stays active while related work continues. For example, a Concern closed by a split into Tasks, or a leaf moved to a different epic, does not close all tracked issues.
NF-01-014 MUST NOT A note whose kind is not plan MUST NOT include a tracks field.

Only plans have work to track. A tracks field on a different kind gives tooling a false signal of open work.
Uses definition from: NF-01-010
NF-01-011 MUST A note whose kind is generated MUST begin its body, right after the frontmatter, with an HTML comment. The comment text starts with the word GENERATED and names the command that writes the file.

The tool of a generated note writes over the file, so the next run removes a hand edit. The marker tells an editor not to edit the file by hand, and it names the command to run.

Migration

ID Priority Requirement Related
NF-05-001 MUST All existing notes/*.md files (except notes/README.md) MUST have compliant YAML frontmatter added as part of the initial implementation of this spec.

The corpus test (NF-04-001) fails on each non-compliant note. Thus the schema could be enforced only after each existing note had frontmatter.
NF-05-002 MUST The status field added during migration MUST accurately reflect the current state of each file's content.

Readers use status to decide if a note is current. If the status is a default value and does not come from the content, stale notes show as active and current notes do not.

Maintenance

ID Priority Requirement Related
NF-06-001 SHOULD When modifying any notes/*.md file, the author SHOULD review and update its frontmatter — in particular status, related_specs, and related_notes — to reflect any changes in scope or relationships.

Tools and agents select notes by their frontmatter. If the frontmatter does not agree with the note, it gives incorrect data to all of them. The author of an edit that changes the scope of a note knows the new values at that time.
NF-06-002 MUST AGENTS.md MUST document the frontmatter maintenance rule so that AI coding agents apply it consistently.

During usual edits, agents follow AGENTS.md, not this spec. If the rule is not in AGENTS.md, agents edit notes and do not update the frontmatter.

Note Kinds and Content

ID Priority Requirement Related
NF-08-001 MUST A note MUST exist only to inform work that has not been done yet.

A note that records history does not tell the reader what to do next. A note stays only until its work lands, so notes/ stays small enough to read.
NF-08-005 MUST Once the work that a note informs lands, a contributor MUST archive the note's content (PD-03-004) or, if it stays useful, move it. Reference material moves to docs/, and lasting rules move into a guidance note.

Content whose work has landed no longer informs work to do. Archiving it, or moving it to its lasting place, keeps notes/ to the notes that still inform work.
Refines: PD-03-004
NF-08-006 MUST NOT A contributor MUST NOT use notes/ as a narrative history of the project. Git and plan/history/ hold the history.

A history note becomes longer with each change that it records, and it does not tell the reader what to do next. Git and plan/history/ already keep the history.
NF-08-002 MUST A contributor MUST apply the kind values by these tests. A guidance note holds a rule for changing the project without repeating a known mistake, or a procedure for a recurring task. That rule or procedure would still be true, and still change how someone works, if every open issue were closed. A plan note holds a design or decision for work the code does not do yet. That design is too large or too cross-cutting for one issue body. A generated note is a file that a tool writes.

Each kind has a different lifecycle. Thus a writer must be able to apply a test to find the kind of a note.
NF-08-007 MUST NOT A contributor MUST NOT keep material that fits none of the NF-08-002 kinds in notes/, such as reference material or the rationale for delivered work. That material belongs in docs/ or the archive.

Reference material and the rationale for delivered work have a permanent location in docs/ or the archive. If they stay in notes/, each note takes longer to read.
Uses definition from: NF-08-002
NF-08-003 MUST Each note MUST have exactly one kind.

Each kind has a different lifecycle (NF-08-002). A note with two kinds has parts that expire at different times, and nothing removes the part that expires first.
Uses definition from: NF-08-002
NF-08-008 MUST NOT A contributor MUST NOT add a plan item to a guidance note. The item goes in a plan note, a new one if needed, or in the issue itself.

A plan item in a guidance note gives a permanent note a part that expires. Nothing removes that part when the plan lands.
Uses definition from: NF-08-002
NF-08-009 MUST When a plan is delivered, a contributor MUST promote its lasting lessons before the plan note is archived. The lessons go into the matching guidance note or into docs/.

Archiving a plan note removes it from notes/. If the lasting lessons are promoted first, the project keeps them.
Extends: NF-08-005
NF-08-004 MUST A contributor MUST state each item in a guidance note as the rule and its reason, with at most one citation. A citation is an issue, ADR or spec ID.

A reader of a guidance note needs the rule and the reason. The reader does not need the story of how somebody found the rule, and git already keeps that story.
NF-08-010 MUST NOT An item in a guidance note MUST NOT carry any of the patterns that follow. They are provenance chains, HTML Source: comments, accounts of how a defect hid or was found, change-history lists and migration-complete notices. They are also reconstructions of removed features, copies of live code, file.py:line tables and inventories that a test already enforces. The writing guide at .agents/skills/shared/notes-writing-guide.md holds the full pattern list.

The listed patterns make a note longer, but they do not tell the reader what to do. Copies of code or test-enforced inventories become incorrect when the source changes.
Extends: NF-08-004

Parallel Agentic Development

Requirements for coordinating multiple parallel AI agents and human developers via GitHub Issues. Defines the issue hierarchy, label taxonomy, task claiming protocol, size labeling, orphan recovery, bundle selection and execution, and revised workflows for the build, plan-issue, review-priorities, and update-plan skills, and the two paths through GitHub Project #24: Schedule on Epics, and a Status path for every other Issue and a ship stage for PRs, both mirrored from facts, and where the build-to-merge pipeline places its local test gates.

File ID: PAD

Issue Hierarchy

ID Priority Requirement Related
PAD-01-001 MUST Tasks MUST be represented as GitHub Issues in the CERTCC/Vultron repository. All work is tracked exclusively as GitHub Issues.

Every agent and human contributor reads, claims and links work through GitHub. Thus one tracker is the only place where all of them see a claim, a blocker or a priority. Selection and the stale-claim sweeper cannot see work in a second tracker.
PAD-01-002 MUST Issues MUST be organized in up to three levels: Epic (thematic group), Task (coherent unit of work), and Subtask (atomic PR-sized chunk). Leaf issues (those with no sub-issues) are the claimable work units.

Selection, claiming and sizing all operate on leaf Issues, so the hierarchy must end in pieces that one PR can close. Capping the depth at three keeps the Epic that sets a leaf's priority tier at most two links away.
PAD-01-003 MUST Epic Issues MUST be wired on GitHub Project #24 with a Schedule field value (Focus/Now/Next/Later/Someday) that reflects the current priority tier of the thematic group they represent.

Agents choose work by Epic tier (PAD-03-003, PAD-08-001). An Epic with no Schedule value gives no priority to the leaves under it, and tier-ordered selection does not find those leaves.
PAD-01-005 MUST Task Issues MUST be sub-issues of their parent Epic.

A Task takes its priority tier from its Epic (PAD-02-001), and GitHub shows and queries that link only as a sub-issue relationship.
Part of: PAD-01-002
Refines: PAD-01-007
PAD-01-006 MUST Subtask Issues MUST be sub-issues of their parent Task.

Leaf selection and the Ready check (PAD-16-004) follow sub-issue links. They cannot see a Subtask that has a different link, and its Task then looks like a leaf.
Part of: PAD-01-002
PAD-01-004 SHOULD The minimum depth that produces right-sized leaf issues SHOULD be used. Not every Epic requires Task or Subtask children.

Each extra level is one more Issue to create, wire and close. An intermediate Issue with a single child adds that cost without dividing the work.
PAD-01-007 MUST Every open non-Epic Issue (Task, Feature, Bug, Idea, Concern) MUST have an Epic ancestor. A non-Epic Issue with no Epic ancestor is untriaged, and triage consists of routing it to an Epic.

A non-Epic Issue carries no Schedule value of its own (PAD-02-001), so its only priority signal is its Epic's tier. Without an Epic ancestor it is invisible to every tier-ordered selector. Small work that belongs to no thematic group goes under a long-lived catch-all Epic, whose tier is set like any other Epic's.
PAD-01-008 MUST When the last open sub-issue of an Epic is closed, the Epic MUST be closed. This rule does not apply to an Epic that has never had a sub-issue.

An Epic reaches "all children closed" only once its tasks are done and no further planning is open. Work that arrives later belongs to a new Epic, so closing needs no human confirmation and the Schedule field needs no end-of-life value.

Label Taxonomy

ID Priority Requirement Related
PAD-02-001 MUST NOT A non-Epic Issue on GitHub Project #24 MUST NOT carry a Schedule value. Its priority tier is the Schedule value of its nearest Epic ancestor.

A child's own Schedule value could only restate its Epic's or silently differ from it, and skills could not tell deliberate from drifted. Holding back one member of an active Epic is done by moving it to a separate Epic, or with the needs-info hold (PAD-16-004), not with a per-issue tier. Priority grouping is by Epic sub-issue relationships, not by group: labels.
Derives from: PAD-03-001
PAD-02-004 MUST A stale-claim label MUST be applied by the sweeper job (PAD-10) when a claimed Issue has no open PR and the claim branch has not received a commit within 3 days.

A claim branch is a lock that does not expire (PAD-04-001). If a session stops or its owner abandons it, the session holds its Issue until something marks the claim. The label makes the stale claim visible, and agents skip the Issue (PAD-02-011) until a human decides.
PAD-02-011 MUST Agents MUST skip Issues that carry the stale-claim label.

A stale claim can still have work behind it that nobody pushed. An agent that takes the Issue can conflict with that work. Thus only a human, who can ask the claimant, releases the Issue.
Refines: PAD-04-003
PAD-02-005 MUST A needs-rebase label MUST be applied when an open PR has merge conflicts that cannot be automatically resolved (PAD-11). Human intervention is required before the label is removed.

An unresolvable conflict means that an agent stopped (PAD-11-005). Without a marker, other agents and the merge step continue to select the PR. The label shows that the PR waits for a person. Only the person who resolved the conflict knows when it is safe to remove the label.
PAD-02-006 MUST Docs-only PRs (containing only specs/ and notes/ changes) MUST carry the specs-notes label to identify them as docs-only for reviewers.

The label tells a reviewer that the PR changes no code and needs no test review. It also lets skills and humans find planning PRs with a query.
PAD-02-008 MUST Every thematic group that has two or more open leaf Issues MUST have exactly one open Epic Issue on GitHub Project #24. A leaf Issue is any Issue with no open sub-issues.

A group with several open leaves needs one place that holds their shared priority tier and shows their progress. With two Epics for one group, the same work can have two tiers. With no Epic, the leaves have no tier (PAD-02-001).
PAD-02-009 MUST An agent or person who creates an Epic Issue MUST give it the GitHub Epic issue type. They set it through the GraphQL createIssue mutation with the type's issueTypeId, which the issueTypes query returns.

Skills identify an Epic by its issue type, not by a label. Only GraphQL can set the issue type, and it needs the ID of the type, which a query must find first.
PAD-02-013 MUST The create-epic skill MUST be used to create Epic Issues to ensure consistent sub-issue wiring, correct issue type assignment, and addition to Project #24.

To create an Epic takes several API calls, and a missed call gives no error. A missing type, a missing board item or an unwired child each hides work from selection. One skill that makes every call gives the same result each time.
Implements: PAD-02-009
PAD-02-014 MUST Every open leaf Issue MUST carry exactly one theme: label, chosen from the active themes in the theme catalog in notes/epic-themes.md.

A theme names the outcome an Issue delivers. With no theme, nobody can check that the Issue belongs in its Epic. With two, the Issue serves two outcomes, and it cannot be ranked with either one.
PAD-02-015 MUST An Epic Issue MUST carry one theme: label, chosen from the active themes in the theme catalog, and a second one only when its body names the split between the two themes.

An Epic is one design idea, and one design idea serves one outcome. An unexplained second theme shows that the Epic holds two ideas. A named split shows that a person decided that the two themes share one idea.
PAD-02-016 MUST An Issue's theme: label MUST name the outcome that the Issue's own content delivers. The label is not copied from the parent Epic or from the work that found the Issue.

A copied theme hides the case that this rule exists to find: an Issue in the wrong Epic. A bug that a test Epic finds is still a protocol bug, and an Issue that has its parent's label looks as if it fits.
PAD-02-017 MUST Every sub-issue of an Epic MUST carry a theme: label that the Epic also carries.

Epics are cut by design idea, and each design idea sits inside one theme. When the children of an Epic serve different outcomes, the Epic has no single priority. The child must move, its label must change, or the Epic must split.
PAD-02-018 MUST An Issue body with a theme: label MUST include a line of the form Theme: <label> — <outcome>. The <outcome> is what this Issue delivers toward that theme.

A label alone gives a reviewer nothing to check. The reason line states why the theme fits, so that a reviewer can compare it with the body and a wrong classification is visible.
PAD-02-019 MUST The theme: labels on GitHub MUST be created and updated from the theme catalog block in notes/epic-themes.md with the theme-labels command, not edited by hand.

A label made by hand has no in-bounds or out-of-bounds text, so the next person who classifies an Issue has only the label name. One source also stops the GitHub description and the note from becoming different.
PAD-02-020 MUST NOT The theme-labels command MUST NOT delete a label.

When a label is deleted, GitHub removes it from every Issue that has it, and the Issues do not keep a record of it. Only a person can decide that a theme is no longer used.
Constrains: PAD-02-021
PAD-02-021 MUST The theme-labels command MUST report each theme: label on GitHub that the theme catalog does not list.

The command does not delete labels (PAD-02-020), so an unlisted label stays on GitHub. Without a report, it stays there unseen, and agents can still apply a theme that the catalog does not define.
PAD-02-022 MUST Agents MUST create every Issue except an Epic only through the create-issue skill, which picks the Issue's one theme by its own outcome, writes its Theme: line, and makes it a sub-issue of an open Epic with the same theme. Epics are created through create-epic (PAD-02-013). This rule covers agents only; an Issue that a GitHub Actions workflow files follows PAD-02-026 to PAD-02-029.

When each skill files Issues its own way, each one drops a different rule. Bugs then land under the Epic of the work that found them, and Issues get no theme. One path applies every rule the same way.
Implements: PAD-02-017
See also: PAD-02-013 — scope boundary: Epics are created another way
See also: PAD-02-026 — scope boundary: workflow-filed Issues follow other rules
See also: PAD-02-029 — scope boundary: workflow-filed Issues follow other rules
PAD-02-023 MUST manage_github_issue.sh MUST refuse to create an Issue that does not carry exactly one active catalog theme: label, has no Theme: line naming it, or has a parent that is closed or does not carry that theme. The refusal names every rule broken and creates nothing.

A skill is text that an agent can misread. A check in the script that creates the Issue stops an Issue that breaks a theme rule before it exists, so the theme-fit report does not have to find it later.
Implements: PAD-02-014
Implements: PAD-02-018
PAD-02-024 MUST When no open Epic with the new Issue's theme fits it and no user is present, the create-issue skill MUST create a Someday Epic in that theme, marked as auto-calved, and make the Issue its sub-issue.

An Issue without a parent has no tier and is invisible to planning (PAD-01-007). An unattended run cannot ask, so an Epic that a person reviews later is better than an orphan; the auto-calved marker lets theme-fit show it until someone does.
Implements: PAD-01-007
PAD-02-025 MUST create_epic.sh MUST refuse to create an Epic that does not carry one active catalog theme, or two with a body line naming both, and a Theme: line naming it.

An Epic is the parent every new Issue's theme is checked against (PAD-02-023). An Epic created without a theme would refuse every child, and one with an unnamed second theme holds two design ideas.
Implements: PAD-02-015
PAD-02-026 MUST An Issue that a GitHub Actions workflow files MUST carry exactly one theme: label and a Theme: line naming it, set by the workflow.

The theme and the Theme: line show which Epics are candidates for an Issue that has no parent (PAD-02-027), so routing it later is quick. A workflow sets them because no agent or skill is in the loop to do it.
Refines: PAD-02-014
Refines: PAD-02-018
PAD-02-027 MUST NOT A GitHub Actions workflow that files an Issue MUST NOT make it a sub-issue. The Issue starts untriaged (PAD-01-007) until someone routes it to an Epic.

A workflow cannot ask anyone and cannot calve an Epic, so it can only use an Epic that someone names in advance. A fixed Epic number needs upkeep each time that Epic closes, is rethemed or split, or fills up, and the workflow fails until someone edits it.
Uses definition from: PAD-01-007
PAD-02-028 MUST theme-fit MUST list each open non-Epic Issue that has no parent as untriaged, apart from its findings, without counting it against a clean report.

Workflows file Issues with no parent on purpose (PAD-02-027), so a report that counted them as findings would never come back clean. Listing them still shows triage what to route (PAD-01-007).
Verifies: PAD-01-007
PAD-02-029 MUST NOT A GitHub Actions workflow MUST NOT change the theme: label or the body of an Issue whose theme: label a person set.

A person who chose another theme read the Issue; the workflow did not. Leaving their choice keeps a later run from undoing triage.
Constrains: PAD-02-026
PAD-02-030 MUST An Epic's title MUST be a done-state claim: a present-tense sentence in domain terms, false when the Epic opens and true when it closes.

The board shows Epics by title alone. A feature name, an activity or a mechanism says what area is being worked, not what changes, so sibling Epics cannot be told apart and nobody can tell from the board whether one is done. A claim says what the Epic changes and doubles as its close test. It fits a guarantee ("X never happens") as well as a feature ("X can do Y").
PAD-02-031 SHOULD An Epic's title SHOULD name, as its subject, the audience its claim serves when one is natural. For protocol work the audience is a reporter, vendor, coordinator, participant or the CASE_MANAGER; for project work it is a maintainer, agent or docs reader.

A named audience tells a board reader whom the Epic serves. It is a SHOULD because a guarantee often has no natural subject, and a forced one ("case managers can count on…") reads worse than the claim alone.
Extends: PAD-02-030
PAD-02-032 MUST NOT An Epic's title MUST NOT contain an ADR number or a spec ID.

A bare ID means nothing to a board reader and turns the title toward mechanism. IDs belong in the Design idea: line (PAD-02-038).
Extends: PAD-02-030
PAD-02-033 MUST An Epic's Theme: line MUST give, as the outcome PAD-02-018 asks for, the consequence of the title's claim that a reader of the theme notices.

The title already states the claim, so the Theme: line adds what the title cannot show: how the claim serves the theme the Epic is ranked in. Read as "why the claim matters", the line was written as a second copy of the claim in most Epics; naming the consequence a reader notices gives it its own content.
Refines: PAD-02-018
PAD-02-034 MUST NOT An Epic body MUST NOT restate its title, its Theme: line or its Design idea: line in another line or section.

Each repeat is one more copy to keep in step when the Epic changes, and copies drift. Every section of the body has to add something the others do not say.
PAD-02-035 SHOULD An Epic SHOULD hold no more than 12 open Task, Feature and Bug leaves, about what one work-epic-tasks run drains.

An Epic that one run can drain has one clear point at which its claim comes true. A larger one stays open across many sessions and its claim stays false long after most of its work is done. work-epic-tasks drains Tasks and Bugs and never Ideas or Concerns, which plan-issue works one at a time, so only the kinds a run drains count; an Epic of 12 Ideas is a planning queue, not an oversized Epic. The number 12 gives a point to act: "about 10" left Epics at 11 and 12 with no clear call.
Uses definition from: PAD-01-002
PAD-02-036 SHOULD Two Epics SHOULD be fused only when they share an outcome and the fused Epic fits PAD-02-035.

A shared outcome is not a reason to merge when the result is too big to work. Epics that share an outcome but would be too large together stay separate, split by size (PAD-02-037). It is a SHOULD because the size bound it tests against is approximate.
Uses definition from: PAD-02-035
PAD-02-037 MUST Epics that share an outcome but stay separate for size MUST each claim their own slice of that outcome in their titles.

A size split is a valid cut, but two titles that make the same claim cannot be told apart on the board. Each sibling names the slice it makes true: a layer, a set of spec groups, or a phase.
Uses definition from: PAD-02-030
PAD-02-038 MUST An Epic body MUST include a Design idea: line that states the approach tying the Epic's children together, including any mechanism, ADR numbers and spec IDs.

The title carries no mechanism and no IDs (PAD-02-032), so the approach needs one home in the body. The design idea as an approach is also the grain calve-epics cuts Epics along.
PAD-02-039 MUST A proposal to fuse Epics at different Schedule tiers MUST state the tier the fused Epic takes.

Leaves take their Epic's tier (PAD-02-001), so fusing a Someday Epic into a Next one moves every child it brings to Next. Stated, the change is the user's to accept; unstated, the children are promoted or buried without anyone deciding it.
Extends: PAD-02-036
PAD-02-040 MUST An Epic split off another MUST take its parent's Schedule tier, unless the split proposal states a different one.

A size split changes how work is grouped, not when it is done. A slice that keeps its parent's tier keeps every child's rank, so no in-flight work moves; a different tier is a ranking decision the user makes on its own.
PAD-02-041 MUST NOT An Issue opened during other work (any opened-as reason) that does not block the Issue being worked, and that the PR working that Issue does not also close, MUST NOT be routed to a Focus or Now Epic unless that Epic's title claim stays false while the Issue is open. It is routed among the same-theme Epics in Next, Later and Someday instead.

A finding about code an agent is touching always matches best the Epic that is working on that code, and it inherits that Epic's tier. Routed by grain alone, discovered work piles into Focus Epics, which then never finish and crowd out the work the quarter planned. The title test keeps a discovery that is part of the Epic's claim, such as a mismatch an audit Epic exists to find, and sends the rest to be ranked on its own. An Issue the same PR closes is part of delivering the worked Issue, not backlog to rank, so it may go under the worked Issue's Epic whatever its tier.
Extends: PAD-02-022

Priority Ordering Authority

ID Priority Requirement Related
PAD-03-001 MUST The Schedule field (Focus/Now/Next/Later/Someday) on Epic Issues on GitHub Project #24 MUST be the authoritative source for work priority ordering.

The Project #24 board is the single source of truth for scheduling, and scheduling is decided per body of work, not per issue.
PAD-03-004 MUST A person or skill that changes work priority MUST update the Schedule field on the relevant Epic, not an external file.

Selection reads only the Schedule field (PAD-03-003). A priority change kept in a file does not reach selection, and the file and the board then disagree.
Derives from: PAD-03-001
PAD-03-002 MUST NOT Agents MUST NOT create or write to any external priority-ordering file. Only the review-priorities skill (and humans directly) may change Schedule field values on GitHub Project #24.

With a second ordering source, two places can disagree, and no rule says which one is correct. When only one skill and humans write Schedule, each priority change is a deliberate decision, not a side effect of other work.
PAD-03-003 MUST When the build skill selects a task, it MUST query GitHub Project #24 for Epics with Schedule=Focus or Schedule=Now (Focus first), then select an open unblocked leaf Issue that is a sub-issue of one of those Epics and passes the PAD-08-001 filters (no stale-claim, needs-info, or ready-for-human label, and not already assigned).

Selecting from the top tiers keeps parallel agents on the work humans ranked highest, and the filters keep them off work that is claimed, held or waiting on a person.
Uses definition from: PAD-08-001

Task Claiming Protocol

ID Priority Requirement Related
PAD-04-001 MUST An agent MUST claim an Issue before beginning work on it by having GitHub create a branch named <prefix>/<issue-number>-<slug> linked to the Issue, then checking that branch out. The branch's existence on GitHub is the authoritative distributed lock: if it already exists, the Issue is already claimed. A bundle member other than the first is claimed by the first member's branch instead (PAD-15-009), so "the Issue's claim branch" means its own branch or, for such a member, its bundle's branch.

A branch that exists only in a local clone locks nothing across machines or cloud agents. The stale-claim sweeper also cannot see it until the agent pushes a PR. A linked branch that GitHub creates also shows in the Development sidebar of the Issue. When the name exists, createLinkedBranch returns a null linkedBranch, not an error, and that null is the "already claimed" signal. gh issue develop exits 0 in the same case, so it is not a lock.
Uses definition from: PAD-15-009
PAD-04-002 MUST After creating the claim branch, the agent MUST assign the Issue to the triggering user.

The branch is the lock, but humans read the assignee. A claim that does not set it holds the Issue but shows it as free.
PAD-04-005 MUST After creating the claim branch, the agent MUST set the Issue's Project #24 Status to In Progress (PAD-16-008).

The board reads Status. A claim that does not set it holds the Issue but shows it on the board as free.
Extends: PAD-04-002
Implements: PAD-16-008
PAD-04-006 MUST After creating the claim branch, the agent MUST post a comment on the Issue that identifies the agent session and the branch name.

The comment connects the Issue to its session and branch, so a person can trace a stale claim.
Extends: PAD-04-002
PAD-04-007 MUST NOT An agent that claims an Epic this way, to plan it, MUST NOT assign the Epic or set its Status.

An Epic carries no Status (PAD-16-012). Its assignee is the epic-run claim (PAD-19-001), so it shows that an epic run holds the Epic. A planning claim must not set that signal.
Supersedes: PAD-04-002
Supersedes: PAD-04-005
PAD-04-008 MUST NOT A split's non-final PR, which says Part of #N, MUST NOT be opened from the claim branch of #N. It opens from an unlinked sibling branch, and the claim branch carries the final Closes #N PR.

GitHub gives a PR from a linked branch a closing reference to its Issue, whatever the body says, so a part opened from the claim branch closes the Issue when it merges (#4805, PR #6267). The claim branch stays the lock (PAD-04-001), so the part leaves it rather than unlinking it.
Refines: PAD-04-001
PAD-04-003 MUST NOT Agents MUST NOT begin implementation work on an Issue whose claim branch already exists, whose stale-claim label is set, or that is already assigned to another user.

Each of these facts means that another session can own the work. If an agent starts anyway, one Issue gets two branches that diverge, and the work on one of them is wasted.
PAD-04-004 SHOULD An agent working on a claimed Issue SHOULD push the claim branch at each checkpoint of its workflow, so that the branch's last commit on GitHub reflects current activity.

The stale-claim sweeper (PAD-10-001) judges activity by the claim branch's last commit on GitHub, so work kept only in a local clone reads as abandoned.

Size Labeling

ID Priority Requirement Related
PAD-05-001 MUST At Issue creation, an Issue with 1 acceptance-criteria (AC) checkbox MUST receive the size:S label.

Provides an objective, count-based size estimate at the point the Issue is created, before any implementation diff is available.
PAD-05-002 MUST At PR open time, the actual diff (total lines added plus removed across all changed files) MUST be measured and the corresponding size: label applied to the pull request. This applies to PRs whose head branch is in this repository; a PR from a fork is exempt, because the workflow that applies the label holds a read-only token there.

The diff is the objective measure of the work delivered, and it exists only when the PR exists. The label goes on the PR because the measurement describes the PR. On the Issue, the label would replace the estimate (PAD-05-010) on an Issue that is about to close.
PAD-05-003 MUST The measured size: label on the pull request (PAD-05-002) is the authoritative size of the delivered change; the AC-count label on the Issue is an estimate only.

The estimate and the measurement answer different questions, so each keeps its own label. Naming the PR label as authoritative tells a reader which one describes the change that shipped.
Uses definition from: PAD-05-002
PAD-05-010 MUST NOT The PR-open measurement MUST NOT overwrite the AC-count estimate label on the Issue.

Keeping both makes estimate-versus-actual a queryable calibration signal. Overwriting the estimate destroys the only record of what the work was predicted to cost, and does so at the moment the Issue closes, where no consumer reads the result.
PAD-05-011 MUST Every size: label — estimate or measurement — MUST be derived from the shared band table in vultron/metadata/planning/size_bands.py, via the pr-size console script.

A threshold that prose restates can contain a typing error, and each copy changes independently. With one table and one tool that applies it, every label uses the same bands. This rationale is also the one place that states the survey figures behind the bands; every other site points here, and a recalibration replaces them here (re-run with pr-size --calibrate). Survey of 2026-11-03, PRs merged 2026-09-22..2026-11-03: under the previous bands and AC rule, 22% of estimates matched the measured band and 76% were too small. The current AC rule scored 42% exact, 95% within one band and 23% too small on held-out Issues, against 14% / 62% / 83% for the previous rule. The current diff ceilings sit near the p23 / p61 / p87 quantiles the previous bands were cut at, recomputed on those PRs. Later bug fixes per 1,000 diff lines are flat from 200 to 3,500 lines (0.4–0.7, overlapping intervals), so no size marks a quality break; above about 2,500 lines the CI-fix rate doubles (about 40% against 20%), which is where size:XL starts. Drift baseline, pr-size --calibrate on 2026-11-05 over 60 days (1081 merged PRs): band shares S / M / L / XL 27.5% / 34.5% / 23.3% / 14.7% against targets 23 / 38 / 26 / 13; p23 / p61 / p87 at 156 / 970 / 2665 diff lines; the existing Issue estimates, made under the previous AC rule, 32% exact and 80% within one band of 898; median 262 diff lines per AC. Earlier, while the rule lived only in skill prose, a survey of 692 PRs merged 2026-07-22..2026-09-22 found 40% with no size: label and size:S applied correctly 24% of the time, which is why pr-size-label applies the measured label (PAD-05-002).
PAD-05-004 MUST At Issue creation, an Issue with 2–3 acceptance-criteria (AC) checkboxes MUST receive the size:M label.

Provides an objective, count-based size estimate at the point the Issue is created, before any implementation diff is available.
PAD-05-005 MUST At Issue creation, an Issue with 4–8 acceptance-criteria (AC) checkboxes MUST receive the size:L label.

Provides an objective, count-based size estimate at the point the Issue is created, before any implementation diff is available.
PAD-05-006 MUST At PR open time, a diff of ≤200 lines MUST receive the size:S label.

The size label shows the implementation effort measured at PR open time (PAD-05-002). The size:S ceiling sits near the quantile of merged-PR diff size it was cut at (the survey in the PAD-05-011 rationale). Thus size:S holds the small changes, and it is not a band that almost no PR falls in.
PAD-05-007 MUST At PR open time, a diff of 201–1000 lines MUST receive the size:M label.

The size label shows the implementation effort measured at PR open time (PAD-05-002). Merged-PR diff size has no natural clusters (the survey in the PAD-05-011 rationale). This band holds the median merged PR, so size:M covers the normal unit of work.
PAD-05-008 MUST At PR open time, a diff of 1001–2500 lines MUST receive the size:L label.

The size label shows the implementation effort measured at PR open time (PAD-05-002). The upper bound separates a large change from one whose CI-fix rate doubles (PAD-05-009). Without an upper bound, the band would put both changes under one label.
PAD-05-009 MUST At PR open time, a diff of 2501+ lines MUST receive the size:XL label.

size:XL marks the size where a PR's CI-fix rate doubles, not a quality break. Later bug fixes per diff line stay flat from small PRs through the largest band, so a large PR is not shipping more defects per line. Above the XL floor, though, a PR needs CI repair about twice as often as below it, which is a cost worth splitting the work to avoid. The survey figures are in the PAD-05-011 rationale.
PAD-05-012 MUST NOT An Issue MUST NOT receive the size:XL label from an AC-count estimate; size:XL is reachable only by measuring a diff.

An Issue predicted to need more work than size:L should be decomposed, not labelled (PAD-05-013). XL is a retrospective finding — the PR grew past the size where CI-fix rates double — and "estimated L, landed XL" is the signal worth keeping.
PAD-05-013 MUST At Issue creation, an Issue with 9+ acceptance-criteria (AC) checkboxes MUST be decomposed into smaller Issues rather than given a size: label; pr-size --acs reports decompose for it.

An AC costs a roughly steady number of diff lines once its tests, specs and docs are counted (.agents/skills/shared/sizing.md), so nine or more ACs predict a PR past the size:L ceiling. Labelling such an Issue would record an estimate in a band the AC rule does not cover; splitting it gives each part an estimate that can land in its measured band.
Refines: PAD-05-012

Pre-PR Review Protocol

Who reviews a branch before its first push, and how the post-push triage reuses that review. The author runs a four-item self-check; a fresh agent then runs the pr-triage phases that need no Pull Request, and the post-push triage runs only the phases that do, plus the delta.

ID Priority Requirement Related
PAD-07-001 MUST Before invoking create-pr, the build skill MUST have the PR-independent phases of pr-triage (its pre-push mode) run on the branch by a subagent that did not write the change. Those phases include the code-review subagent.

An author reviewing its own change misses what it overlooked while writing it; the post-push fresh-agent triage still found a median of six problems per PR, each fixed after the push at the cost of a fix commit and a CI run.
PAD-07-005 MUST The build skill MUST run the pre-push review against the branch diff relative to origin/main, with every change committed.

The reviewer reads only committed work, so it does not see uncommitted work. The comparison with origin/main keeps the review on the change that the branch makes.
Refines: PAD-07-001
PAD-07-011 MUST The build skill MUST give the pre-push review the draft PR body.

The draft body lets the reviewer check the author's Self-check: record (PAD-07-009), which exists only in that body before the push.
Extends: PAD-07-005
PAD-07-002 MUST Every pre-push review finding MUST carry a pr-triage severity (FAIL, IMPROVE, or NEW-ISSUE) and a pr-triage decision outcome (fix-now, fix-now-file, defer-ask, or inversion-halt).

One taxonomy across the pre-push and post-push reviews lets the post-push triage carry a pre-push finding forward unchanged.
PAD-07-003 MUST The build skill MUST resolve every pre-push review finding by its decision outcome before invoking create-pr.

An unresolved finding is a known defect that reaches the PR anyway, at the cost of a fix commit and a CI run.
Extends: PAD-07-001
PAD-07-010 MUST The build skill MUST record each pre-push review finding's resolution in the pre-push artifact.

The recorded resolution lets the post-push triage confirm each fix on the PR head (PAD-07-013).
Extends: PAD-07-003
PAD-07-006 MUST NOT The build skill MUST NOT re-run the pre-push review after resolving its findings. The post-push triage reviews those fixes as part of its delta (PAD-07-012).

A second full review before the push would repeat every phase on a diff that changed only where the fixes landed; the delta review covers exactly those lines, once.
Extends: PAD-07-003
See also: PAD-07-012 — explanation: the post-push delta reviews the fixes
PAD-07-004 SHOULD After a PR is opened, the pre-push review's findings and their resolutions SHOULD be posted as a comment on the PR for human review.

The pre-push review runs before the PR exists, so its findings are otherwise only in a gitignored local artifact. A comment lets a human see what the review caught and how each finding was handled.
PAD-07-007 MUST This rule applies when a PR's branch has a pre-push artifact and PAD-07-008 does not call for a full triage. Then pr-triage MUST run the phases that need the PR. These are issue linkage as posted, PR body format, the Docs: line comparison, CI status, and merge state.

The pre-push review ran before the PR existed, so it could not run these phases. Running them here means that every phase still runs, once per change.
PAD-07-012 MUST In the triage that PAD-07-007 describes, pr-triage MUST re-run the PR-independent phases on the delta alone. The delta is the change to the branch's own added and removed lines between the reviewed head and the PR head.

The pre-push review already ran these phases on the rest of the change. Defining the delta on the branch's own lines keeps create-pr's cherry-pick onto a newer base out of it.
Extends: PAD-07-007
PAD-07-013 MUST In the triage that PAD-07-007 describes, pr-triage MUST confirm each pre-push finding's recorded resolution on the PR head, re-emitting each finding whose fix is absent.

A recorded resolution is a claim by the author. A fix that did not reach the PR head leaves the defect in the change that merges.
Extends: PAD-07-007
PAD-07-008 MUST pr-triage MUST run the full triage when the PR carries the needs-rebase label, when the PR's branch has no usable pre-push artifact (none exists, it is not a JSON object, it lacks a reviewed SHA, it names another branch, or a reviewed commit is not in the object store), when the reviewed diff is empty, or when the delta's changed lines exceed half of the reviewed diff's changed lines.

A PR not opened by build, a conflict resolved by hand, or a delta most of the size of the change gives the pre-push review too little claim on the tree that will merge.
Supersedes: PAD-07-007
PAD-07-009 MUST The build and bugfix skills MUST run the four-item pre-review self-check on the finished diff and record its results. They record the four results under Self-check: in the ## Verification section of the PR body. The four items are the affected-text sweep, the failure-path pass, branch coverage, and the reuse check.

About 45% of post-push triage findings fall into these four oversights. A written result per item shows the reviewer the check ran.
PAD-07-014 MUST pr-triage MUST give its code-review subagent the four items of the PAD-07-009 self-check as review prompts.

A reviewer that checks the same four items against the diff catches what the author missed.
Uses definition from: PAD-07-009
PAD-07-015 MUST After deepen-context, before the branch's first commit, the build and bugfix skills MUST write the build context file with build-context write. The file records the branch, the head and base commits, the Spec manifest's loaded IDs, the domain hints, and the notes and glossary sections loaded, and no other field.

Each later pipeline phase is a fresh agent that would load the same context again. A list of facts found, with no reasoning, lets the phase skip that work and still review with a fresh eye (PAD-07-001).
PAD-07-016 MUST A pull-request pipeline phase (pr-triage in every mode, pr-execute) MUST reuse the build context file only when build-context check reports it usable. Usable means that the file exists, holds a valid record, names the PR's branch, and was recorded at a commit that is an ancestor of the PR head.

pr-ship often runs from another agent system or machine, or on a branch whose file was written for older work. Only a file that provably describes this branch may stand in for loading context.
Uses definition from: PAD-07-015
PAD-07-017 MUST When build-context check reports the build context file unusable, the phase MUST load its context with orient-agent and deepen-context, as it does when no file exists.

The file is an optimization. A phase that cannot use it must reach the same context, and so the same verdict, as before the file existed.
Refines: PAD-07-016
PAD-07-018 MUST NOT A pull-request pipeline phase MUST NOT fail, skip a check, or narrow a check because the build context file is missing or unusable.

A PR shipped from a checkout that never ran build is the ordinary case, not an error. Making the file a precondition would block those PRs or review them less.
Extends: PAD-07-016
PAD-07-019 MUST pr-triage MUST name in its comment header whether it reused the build context file, and the build-context check reason when it did not.

A reviewer reading the triage needs to know which context the findings rest on. When the file was unusable, the reason shows why.
Extends: PAD-07-016

Build Skill — Issue-Based Task Selection

ID Priority Requirement Related
PAD-08-001 MUST The build skill MUST select work by querying GitHub Project #24 for Epics with Schedule=Focus or Schedule=Now (Focus first), then querying for open unblocked leaf Issues that are sub-issues of those Epics, filtered to exclude Issues that carry stale-claim, needs-info, or ready-for-human, that are already assigned, or that are held by an epic run (PAD-19-002).

The filters skip Issues that another session owns, that wait on a person, or that an epic run holds, so parallel agents do not pick the same work or work a human reserved. Ordering by Epic tier puts effort where humans ranked it.
Uses definition from: PAD-19-002
PAD-08-002 MUST The build skill MUST open a GitHub Pull Request with "Closes #N" in the body after completing implementation and passing all validations.

Closes #N closes the Issue when the PR merges. This moves the Issue to Done and keeps the board correct with no manual step. When the PR opens only after validation, known-broken work stays out of review and CI.
PAD-08-004 MUST NOT The build skill MUST NOT commit directly to main.

A direct commit to main skips review and CI. When several agents work in parallel, it can break every branch that starts from main.
PAD-08-003 MUST After implementation, the build skill MUST compute the diff size and update the size label on both the Issue and the PR per PAD-05-002 before opening the PR.

A size taken from the measured diff tells a reviewer how much review the PR needs before review starts (PAD-05-002).
Uses definition from: PAD-05-002
Conflicts with: PAD-05-010

Ingest-Idea — Docs-Only PR and Issue Creation

ID Priority Requirement Related
PAD-09-001 MUST After writing specs/<topic>.yaml and notes/<topic>.md, the plan-issue skill MUST open a docs-only PR carrying the specs-notes label before creating the implementation GitHub Issue. This ensures spec and notes files are on main and referenceable from Issues before any implementation work begins.

An implementation Issue that links a spec not yet on main points at text that can still change or never merge. Thus an agent could implement a requirement that does not exist. When the docs merge first, the Issue has a stable target.
PAD-09-002 MUST After the docs-only PR is opened, plan-issue MUST create a GitHub Issue for the spec. The Issue has a title and description derived from the spec, and a link to the spec file in its body. It carries the size: label derived from the AC count per PAD-05-001.

The Issue is the unit agents select and claim, so it must carry what selection reads: a size estimate and a link to the governing spec.
Uses definition from: PAD-05-001
PAD-09-004 MUST plan-issue MUST add the Issue to GitHub Project #24 as a sub-issue of an Epic (PAD-01-007), with no Schedule value (PAD-02-001).

The Epic ancestor gives the Issue its tier, so selection can reach it. A Schedule value of its own would only restate or contradict its Epic's (PAD-02-001).
Extends: PAD-09-002
Refines: PAD-01-007
Refines: PAD-02-001
PAD-09-003 MUST NOT plan-issue MUST NOT begin implementation work.

Planning and building are separate steps, so a human can review the plan and its docs PR before code depends on them. Implementation work begins only when the Issue is Ready (PAD-16-004) and is selected under its Epic's Schedule tier on GitHub Project #24 (PAD-15-003). If planning starts the build at once, it skips the Epic tier that decides when the work is worth doing.
PAD-09-005 MUST plan-issue MUST stop after creating the Issue.

A clear end point keeps the planning run from doing any step that belongs to a later run, such as claiming or building the Issue.
Refines: PAD-09-003

Orphan Recovery — Stale Claim Sweeper

ID Priority Requirement Related
PAD-10-001 MUST A scheduled GitHub Actions workflow (weekly cadence, also triggerable on workflow_dispatch) MUST scan for Issues that are assigned, have a claim branch on GitHub under any claim prefix (PAD-04-001), have no open PR, and have had neither a branch commit nor their claim within 3 days.

GitHub creates a claim branch at the main tip, whose last commit can already be older than 3 days when the claim is taken. The claim time (the Issue's latest assignment) is therefore activity too. An open PR whose body says Part of #N outside code counts as the claim's open PR: a split's non-final part opens from an unlinked sibling branch, so the claim branch itself sits idle (PAD-04-008).
Uses definition from: PAD-04-001
PAD-10-002 MUST When the sweeper identifies an orphaned claim, it MUST apply the stale-claim label to the Issue.

The sweeper cannot tell abandoned work from slow work, so it marks the claim instead of releasing it.
PAD-10-003 MUST When the sweeper identifies an orphaned claim, it MUST post a comment on the Issue that names the orphaned branch and asks for human review.

Only a person can decide whether the claimed work is abandoned. The comment names the branch so that the person can check what is on it.
Extends: PAD-10-002

Merge Conflict Recovery

ID Priority Requirement Related
PAD-11-001 MUST When an open PR conflicts with its base branch, the syncing agent MUST merge the base into the task branch and resolve the conflicts.

A merge commit keeps the commits that reviewers commented on and the commit_ref values that the triage and execute artifacts recorded.
PAD-11-006 MUST NOT The agent syncing an open PR MUST NOT rebase its branch.

Rebasing a pushed branch rewrites the commits reviewers commented on and the commit_ref values the triage and execute artifacts recorded.
Extends: PAD-11-001
PAD-11-002 MUST After resolving the merge, the agent MUST push the merge commit with a normal push, not a force-push.

A merge only adds commits, so a normal push succeeds unless the remote branch moved. A push that git rejects as non-fast-forward means another push landed or someone rewrote the remote branch; either is a reason to fetch and inspect, never to force. CI re-runs automatically on the updated head.
PAD-11-003 MUST If the agent cannot resolve the merge safely, it MUST abort the merge and post a comment on the PR explaining the conflict.

Ensures human reviewers have visibility into the nature of the conflict before intervening.
PAD-11-004 MUST If the agent cannot resolve the merge safely, it MUST apply the needs-rebase label to the PR.

The label tells the sweeper and other agents that the PR needs a human before it can continue. The name says "rebase", but recovery uses a merge (PAD-11-001). The name stays so that existing queries and skills still find the label.
PAD-11-005 MUST NOT If the agent cannot resolve the merge safely, it MUST NOT attempt further changes; human intervention is required to resolve the conflict and remove the needs-rebase label.

Prevents the agent from making the conflict worse or creating additional commits on a branch that requires human resolution.

Review-Priorities — Issue Triage

ID Priority Requirement Related
PAD-12-001 MUST The review-priorities skill MUST surface as a triage list for the current review session every open Epic with Schedule=Someday or no Schedule value, and every open non-Epic Issue with no Epic ancestor (PAD-01-007).

An Epic at Someday or with no tier, and an Issue with no Epic, are where work gets lost, because selection never reaches them. The skill shows them at each review, so a human can schedule, route or close each one.
Uses definition from: PAD-01-007
PAD-12-002 MUST For each Epic surfaced in triage, the review-priorities skill MUST use ask_user to choose its Schedule tier, or to close or defer it.

Scheduling is a human decision (PAD-03-002), so the skill asks rather than guesses a tier.
PAD-12-004 MUST For each unparented non-Epic Issue, the review-priorities skill MUST ask which Epic the Issue belongs under.

An Issue with no Epic has no tier at all, so the question for it is where it belongs. The skill asks rather than guesses a parent, because placement is a human decision (PAD-03-002).
Extends: PAD-12-002
PAD-12-003 MUST After the user confirms a placement, the review-priorities skill MUST apply it via the GitHub API: the Epic's Schedule field on GitHub Project #24, or the Issue's sub-issue relationship to the chosen Epic.

A placement that only the session holds is lost when the session ends, and selection reads only the board and the sub-issue links. When the skill applies the placement immediately after confirmation, the board stays the single source of priority (PAD-03-001).

Update-Plan — Issue Creation

ID Priority Requirement Related
PAD-13-001 MUST When the update-plan skill identifies a new implementation gap (a spec requirement with no corresponding code or test), it MUST create a GitHub Issue for the gap.

A gap noted only in a report is not selectable work, so it goes unbuilt. An Issue puts it where agents select work.
PAD-13-002 MUST Issues created by update-plan MUST be added to GitHub Project #24 as sub-issues of an Epic (PAD-01-007), with no Schedule value (PAD-02-001) and the initial size: label derived from the AC count per PAD-05-001.

An Issue outside an Epic has no tier, so no selector reaches it (PAD-01-007). The size estimate lets bundle selection weigh it before any diff exists (PAD-15-005).
Refines: PAD-01-007
Refines: PAD-02-001
Uses definition from: PAD-05-001

GitHub Actions Requirements

ID Priority Requirement Related
PAD-14-003 MUST A GitHub Actions workflow MUST implement the stale-claim sweeper (PAD-10). It runs on schedule (weekly) and workflow_dispatch. It scans for orphaned claims per PAD-10-001, applies the stale-claim label per PAD-10-002, and posts a comment per PAD-10-003.

Abandoned claims come from sessions that ended, so the sweeper must run when no agent session is active. A scheduled workflow runs without one, and workflow_dispatch lets a human run it on demand.
Implements: PAD-10-001
Implements: PAD-10-002
Implements: PAD-10-003
PAD-14-004 MUST A GitHub Actions workflow MUST run theme-fit daily and on workflow_dispatch, and write its report into one standing "Theme fit report" Issue.

calve-epics needs a current work list when no agent session is running, and one Issue rewritten in place stays the single place to look.
PAD-14-005 MUST The PAD-14-004 workflow MUST find the report Issue by its theme-fit-report label through the list-issues endpoint. It rewrites the oldest open one, else reopens the oldest closed one, and creates one only when none exists.

The search index lags, and that lag once let a workflow file a second tracker (#5105). Reopening a closed report keeps one Issue, where a new one would leave two.
Extends: PAD-14-004
PAD-14-006 MUST The PAD-14-004 workflow MUST publish the report and end green only when theme-fit exits 0 or 1 with a report on stdout (text that starts with # Theme fit report), and fail the run on any other outcome: exit 2, or exit 0 or 1 without a report.

A finding (exit 1) is what the report exists to show, so failing on one would file a CI failure every day the board is imperfect. Python also exits 1 on an uncaught crash, so the exit code alone cannot tell findings from a crash, and a crash published as a report would blank the Issue. A failed run must reach notify-failure (CISEC-05).
Extends: PAD-14-004
PAD-14-007 MUST NOT The PAD-14-004 workflow MUST NOT label, move or otherwise change any Issue but the report Issue.

The report is read-only by design: a person or calve-epics decides each finding (notes/epic-themes.md § "Acting on a Theme-Fit Finding").
Extends: PAD-14-004

Bundle Selection and Execution

ID Priority Requirement Related
PAD-15-001 MUST Bundle selection MUST pick a work bundle in two stages: eligibility, then fit. An eligible Issue is open, unassigned and a leaf, and every blockedBy Issue is CLOSED. It carries no stale-claim, needs-info, or ready-for-human label, and no epic run holds it (PAD-19-002).

Eligibility rules out the Issues that are not free to take before any fit rule weighs them. Each refusal then belongs to one stage (PAD-15-006).
Uses definition from: PAD-19-002
PAD-15-012 MUST NOT Bundle selection MUST NOT make an Issue a bundle member only because it clears eligibility.

Clearing eligibility shows only that an Issue is free to take. Without a fit stage, selection takes candidates in sub-issue order and can propose an Idea, a Someday Concern and two size:L Tasks as equal members of one bundle.
Derives from: PAD-15-001
PAD-15-002 MUST A bundle MUST be homogeneous by executing skill, determined from each candidate's issueType: Task and Feature are executed by build, Bug by bugfix, and Idea, Concern and Epic by plan-issue.

An Idea or Concern leaf clears every eligibility gate but cannot be implemented; it needs planning first. Routing by type is the rule work-issue already applies to a single issue.
PAD-15-003 MUST Bundle selection MUST order candidates by their governing Project #24 Schedule tier per PAD-03-001. That tier is the tier of the candidate's nearest Epic ancestor (PAD-02-001).

The Schedule field is the authoritative priority signal (PAD-03-001), and only Epics carry it, so a candidate's priority is its Epic's tier.
Refines: PAD-03-001
Uses definition from: PAD-02-001
PAD-15-013 MUST NOT Bundle selection MUST NOT read a leaf's own Schedule value.

Only Epics carry Schedule (PAD-02-001), so a value on a leaf is always drift.
Extends: PAD-15-003
PAD-15-014 MUST Bundle selection MUST use sub-issue list order only to break ties.

The order of the sub-issue list is a manual order and has no priority meaning. If selection used it as the priority signal, it would override the authoritative field.
Extends: PAD-15-003
PAD-15-004 MUST NOT An Issue whose governing Schedule tier is Someday MUST NOT be proposed as a bundle member.

Someday is explicit human deprioritisation; bundling such an Issue reverses a scheduling decision the board already recorded.
PAD-15-005 MUST Bundle selection MUST bound a bundle by a total size budget computed from the PAD-05 size: label weights. It weights an unlabelled Issue as the largest bundlable size.

A bundle is implemented as one PR, so the budget is a review budget. An unlabelled Issue is unmeasured rather than small, so counting it as the largest bundlable size fails safe. The weights themselves are not restated here: they are derived from the band table (PAD-05-011), so a recalibration cannot leave this requirement behind.
PAD-15-015 MUST Bundle selection MUST bound the number of members in a bundle.

The size budget alone admits many small members. Each member adds acceptance criteria and a Closes #N line that one review must cover.
Extends: PAD-15-005
PAD-15-011 MUST NOT An Issue labelled size:XL MUST NOT be proposed as a bundle member.

size:XL means a change already past the size where its CI-fix rate doubles (PAD-05-009), and a bundle is one PR, so adding members only makes it bigger. It is refused outright rather than given a weight. A weight would say "fits alongside something smaller", which is precisely what this band rules out, and a raised --budget could then reopen it.
PAD-15-006 MUST A bundle proposal MUST report every candidate it excluded with a per-candidate reason, distinguishing exclusion at the eligibility stage from exclusion at the fit stage.

A candidate held back for size or tier needs a different action from one that is blocked or already claimed. Without the stage in the reason, a reader cannot tell which of the two happened.
PAD-15-007 MUST The agent proposing a bundle MUST decide its thematic coherence by stating, in one sentence, the single design idea its members share.

Cutting by a superficial shared keyword rather than design grain produces plausible-looking but wrong work units — the same failure calve-epics guards against when shaping the Epic forest.
PAD-15-016 MAY The agent proposing a bundle MAY surface mechanical overlap signals as evidence of coherence.

A shared spec ID, label or file path can point a person to a design idea that members share, even though it cannot prove one.
PAD-15-017 MUST NOT The agent proposing a bundle MUST NOT treat mechanical overlap signals as the coherence verdict.

A shared keyword is a superficial match, not design grain. A verdict taken from it gives the same wrong work units that PAD-15-007 exists to stop.
Constrains: PAD-15-016
Constrains: PAD-15-007
PAD-15-008 MUST A skill given several Issue numbers MUST implement every member and open one Pull Request whose body carries one Closes #N line per member.

Getting more than one Issue done in a single PR is the entire purpose of bundling; executing one member and discarding the rest defeats it.
PAD-15-018 MUST NOT A skill given several Issue numbers MUST NOT silently work only the first member or silently drop a member.

A member dropped for grain is reported, not silently omitted, so the person who asked for the bundle sees what it did not deliver.
Derives from: PAD-15-008
PAD-15-009 MUST The agent claiming a bundle MUST claim every member onto the single branch named for the first member.

Branch creation is the distributed lock (PAD-04), so one bundle is one lock.
PAD-15-019 MUST A skill working a bundle MUST give each member the tests and acceptance-criteria coverage it would receive if worked alone.

A bundle saves the cost of loading context once per Issue. It does not lower the rigor that each Issue needs.
Extends: PAD-15-008

Project Board Status Path

ID Priority Requirement Related
PAD-16-001 MUST Every non-Epic Issue on GitHub Project #24 MUST carry exactly one Status value: Backlog, Ready, In Progress, In Review, or Done, determined by the first of PAD-16-010, PAD-16-009, PAD-16-008, PAD-16-004/PAD-16-005, and PAD-16-011 whose condition holds.

Schedule answers "which body of work matters now" and lives on Epics. Status answers "where does this piece of work stand" and lives on everything else, so the two paths never describe the same item.
Uses definition from: PAD-16-004
Uses definition from: PAD-16-005
Uses definition from: PAD-16-008
Uses definition from: PAD-16-009
Uses definition from: PAD-16-010
Uses definition from: PAD-16-011
PAD-16-002 MUST An Issue's Status MUST be reproducible from facts recorded elsewhere alone. These facts are its open or closed state, issue type, sub-issues, acceptance-criteria lines, blockedBy relationships and labels. They also include its Epic ancestor, assignee and claim branch, and linked Pull Requests.

A second copy of claim or review state that a person maintains drifts from the branch and PR it describes.
PAD-16-013 MUST A Status value that the PAD-16-002 facts do not produce is drift. An agent or tool that finds drift MUST correct the value to the reproduced value.

A computed copy can drift too, but a new computation repairs it with no human.
Uses definition from: PAD-16-002
PAD-16-003 MUST NOT An agent MUST NOT decide whether an Issue is claimable or selectable from its Status value. Claimability and selection are decided from the facts Status mirrors (PAD-04-003, PAD-08-001, PAD-15-001).

Status is a display of situation for humans. If a stale mirror could cause two agents to claim one Issue, drift would stop being cosmetic.
Constrains: PAD-08-001
Constrains: PAD-04-003
Constrains: PAD-15-001
PAD-16-004 MUST A Task, Feature, or Bug MUST be Ready ("ready to build") when it is open, unassigned, a leaf, has no claim branch (PAD-04-001), has an Epic ancestor, carries at least one - [ ] AC-N: line, has every blockedBy Issue closed, and does not carry the needs-info label.

These are the conditions build already applies privately when it auto-selects work, made visible so that a wrong or missing condition shows on the board instead of in a surprising pick. needs-info ("waiting on a person or decision") is the only hold.
Uses definition from: PAD-04-001
PAD-16-005 MUST An Idea or Concern MUST be Ready ("ready to plan") when it is open, unassigned, has no claim branch (PAD-04-001), has an Epic ancestor, and does not carry the needs-info label.

An Idea or Concern is input to plan-issue, which consumes it, so it can be planned from the moment it is triaged. The board separates ready-to-plan from ready-to-build by issue type, not by a second column.
Uses definition from: PAD-04-001
PAD-16-006 MUST NOT The Schedule tier of an Issue's Epic ancestor MUST NOT affect the Issue's Status. The tier orders selection among Ready Issues only.

"Could this be started?" and "should it be started now?" are different questions. Keeping the tier out of Status means reprioritising an Epic changes no child's Status, and planning a Next-tier Idea early or fixing a Bug under a Later Epic is an ordinary choice among Ready Issues, not an exception.
PAD-16-007 MUST NOT An agent MUST NOT auto-select or claim an Issue carrying the ready-for-human label. The label does not affect the Issue's Status.

The label reserves the Issue for a human, so an agent that claims it takes the work away from that person. The label says who works the Issue, not whether it is ready, so it does not change Status.
PAD-16-008 MUST An open Issue that is claimed (PAD-04-001, PAD-04-002), including a bundle member claimed by its bundle's branch (PAD-15-009), and has no open, non-draft Pull Request that closes it MUST be In Progress. A draft Pull Request keeps the Issue In Progress.

A draft PR says its author is not finished. Marking it ready for review is the author's "done" signal.
Uses definition from: PAD-04-001
Uses definition from: PAD-04-002
Uses definition from: PAD-15-009
PAD-16-009 MUST An open Issue with an open, non-draft Pull Request that closes it MUST be In Review. In Review means pr-ship may be run on that Pull Request.

Review here is agent-driven, so In Review marks work handed to the ship pipeline. Progress through that pipeline is tracked on the PR (PAD-17), not on the Issue, because one bundle PR closes several Issues.
PAD-16-010 MUST A closed Issue MUST be Done, whatever its close reason.

A closed Issue is finished as far as the board is concerned, so one value covers every close.
PAD-16-014 MUST Whoever decides not to action an Issue MUST close it with the "not planned" or "duplicate" close reason, not a label.

GitHub's close reason already records why the Issue closed, and a label would be a second copy that can drift (PAD-16-002).
PAD-16-011 MUST An open, unclaimed Issue that does not meet the Ready conditions (PAD-16-004, PAD-16-005) MUST be Backlog.

Every open non-Epic Issue needs a Status value (PAD-16-001), and an unclaimed one that is not Ready cannot be built or planned yet. Backlog is that remainder, so no item is left without a value.
Uses definition from: PAD-16-004
Uses definition from: PAD-16-005
PAD-16-012 MUST NOT An Epic Issue MUST NOT carry a Status value.

An Epic is a container, not work that is claimed, reviewed, and merged. Its progress is the sub-issue progress GitHub already shows, and an Epic that still needs planning is identified by its needs-planning label.

Pull Request Ship Stage

ID Priority Requirement Related
PAD-17-001 MUST Every open, non-draft Pull Request MUST be an item on GitHub Project #24 carrying a Ship stage value: Awaiting ship, Triage, Execute, Verify, Needs you, or Ready to merge.

pr-ship records its progress in gitignored local files, so no other machine or session can see whether a PR's triage has run, whether it is paused at a gate, or whether it is ready to merge. With several agents working in parallel, "which PRs need me?" is the question the board most needs to answer.
PAD-17-002 MUST pr-ship MUST set a Pull Request's Ship stage to Triage, Execute, or Verify on entering that phase, including when it resumes into it and when its triage reviews only the delta over a pre-push review (PAD-07-007); to Needs you while paused at a gate awaiting a human; and to Ready to merge when verification completes. The pre-push review sets no Ship stage, because no Pull Request exists yet.

The one skill that knows its own phase writes the value, so the field is a mirror of pipeline progress that needs no manual upkeep.
Uses definition from: PAD-07-007
PAD-17-003 MUST Opening a non-draft Pull Request, or marking a draft Pull Request ready for review, MUST add it to GitHub Project #24 with Ship stage set to Awaiting ship.

PAD-17-002 covers only the stages pr-ship itself enters. Without an entry rule, a PR nobody has shipped yet is either absent from the board or has no Ship stage, and PAD-17-001 cannot hold.
Refines: PAD-17-001
PAD-17-004 MUST When a Pull Request is converted to draft, closed, or merged, its Ship stage value MUST be cleared. Marking it ready for review again re-enters it at Awaiting ship (PAD-17-003).

PAD-17-001 covers only open non-draft PRs. Without an exit rule, a PR that leaves that set keeps its last stage, and the board shows a merged or abandoned PR as Ready to merge or Needs you.
Extends: PAD-17-001
See also: PAD-17-003 — restates PAD-17-003's consequence for a re-readied PR

Pipeline Test-Gate Placement

Where the build-to-merge pipeline runs tests locally, and when it merges the base branch into a PR. CI on pull_request runs the full suite against the PR merged into its base as of the push, and GitHub refuses a merge while that run is red or has not run. So a local check is worth its cost only when it answers before CI would (ADR-0209).

ID Priority Requirement Related
PAD-18-001 MUST Before an implementation Pull Request's first push, create-pr MUST gate it with the linters and the branch diff's targeted test set. It pushes only when both pass.

The full local suites took a median of 11.6 minutes, longer than CI takes to run both. The linters and the targeted set keep an obviously broken branch out of CI in a few minutes, and CI's required run tests the rest on the merge with the base.
Uses definition from: PAD-18-026
Uses definition from: PAD-18-002
PAD-18-010 MUST Before a Pull Request that changes no Python is first pushed, create-pr MUST gate it with the linters and prepush-ci-mirror. That gate runs no unit or integration suite.

A docs-only branch has nothing for the suites to catch. The mirror's cheap checks still read its Markdown and specs: generated-file sync, front matter, the ADR index, spec-lint and Markdown lint. Three of the #5580 audit's failures came from docs-typed PRs that ran no local check at all.
PAD-18-002 MUST After a PR's first push, an agent MUST gate each fix commit locally with the linters and the branch diff's targeted test set. The set holds each test file that imports a changed symbol, the mirror test file of each changed module, and each changed test file. It also holds test/architecture/ and test/metadata/. A conflict merge with no fix in it is not a fix commit; PAD-18-015 sets its gate.

After a one-line fix, a full local run costs 9 to 18 minutes on a 2-CPU slot, and CI then runs the full suite again in 6 to 9. The targeted set catches a broken fix first, at a fraction of that cost. The checks in test/architecture/ and test/metadata/ read the tree, not an imported symbol, and nearly every red local full run failed there (ADR-0209). The import index cannot reach a changed test file: no vultron symbol changed, and the mirror lookup covers only vultron/ paths.
See also: PAD-18-015 — scope boundary: a conflict merge's gate is set elsewhere, and PAD-18-002 never binds one, so PAD-18-015 supersedes nothing it requires
PAD-18-011 MUST Every local gate that selects test files MUST select them with the integration marker enabled.

addopts carries -m 'not integration', which drops marker-bearing tests from a file list. Enabling the marker keeps those tests in the gate. Stated over every gate, not the fix-commit gate alone: the first-push gate selects the same way (PAD-18-001), and so does the conflict-merge gate (PAD-18-015), so a rule scoped to one of the three would leave the marker unspecified for the other two.
Uses definition from: PAD-18-002
PAD-18-003 MUST NOT The PAD-18-002 gate MUST NOT escalate to the full unit and integration suites, whatever paths the branch diff touches.

A full local run takes longer than CI's run of both suites, which GitHub requires before the merge. Escalating would make the agent wait for the slower of two runs that give the same answer.
Refines: PAD-18-002
PAD-18-012 MUST When a local test gate's paths include shared test infrastructure, it MUST run the targeted set it can select and the always-selected directories of PAD-18-002. Shared test infrastructure is conftest.py, pyproject.toml, uv.lock, vultron/__init__.py, and the test fixtures, factories, helpers and data files outside those directories.

The import index cannot see the tests that reach a change through fixtures or configuration, so no targeted set bounds such a path. The gate still runs what it can select, and the directories where nearly every red local run failed. CI's required full run covers the rest.
Extends: PAD-18-003
Uses definition from: PAD-18-002
PAD-18-013 MUST When a fix targets a CI failure outside the targeted set, the agent MUST add the failing test's file to the PAD-18-002 gate.

For a CI failure outside the set, the gate runs that test, not the whole suite, because CI runs the rest again on the push.
Extends: PAD-18-002
PAD-18-004 MUST After a Pull Request's first push, an agent MUST merge the base branch into it locally only when the Pull Request conflicts with the base. A conflict means that GitHub reports it CONFLICTING or DIRTY, or that a trial merge (git merge-tree) conflicts. Files changed on both sides without a conflict are not a conflict.

CI already tests the merge of the PR into its base at each push, and no repository rule requires branches to be up to date. A conflict is the only sync that needs an agent, because someone must resolve it. GitHub can make every clean merge, and CI tests it. A merge on file overlap alone would add a local merge and a local test run for paths that the merge did not change.
Extends: PAD-11-001 — PAD-11-001 and PAD-11-006 say how a conflicted PR is synced (merge, never rebase); this adds when a pushed PR is synced at all (on conflict only).
PAD-18-014 MUST When GitHub reports a pushed PR BEHIND without a conflict, the agent MUST update it on GitHub with gh pr update-branch. It does no local merge and no local suite run.

In the BEHIND state, GitHub itself refuses the merge until the branch contains the base. gh pr update-branch makes the same merge commit that a local merge makes, and CI tests it. No ruleset causes BEHIND today.
Extends: PAD-18-004
PAD-18-015 MUST After resolving a conflict, the agent MUST gate the merge with the linters and the targeted set for the conflicted files alone. Each conflicted file counts as wholly changed. The gate also runs test/architecture/ and test/metadata/.

A gate from the whole branch diff would test paths that the merge did not change. The gate treats a conflicted file as wholly changed, because both sides edited it. The rest of the merge changed no line that the PR wrote, and CI runs the full suite on the push.
Extends: PAD-18-004
PAD-18-005 MUST NOT pr-verify MUST NOT compute base-tip containment itself, nor withhold READY-TO-MERGE on the strength of its own containment check, when the PR is conflict-free and PAD-18-004 did not call for a merge. Only GitHub's reported merge state governs: a mergeStateStatus of BEHIND still blocks.

Requiring the base tip in the branch makes every merge to main invalidate every other ready PR, which is the loop PAD-18-004 exists to break. GitHub reports BEHIND only when a ruleset requires up-to-date branches, so deferring to it keeps the one case where being behind genuinely blocks a merge, without re-deriving it on every verify.
Uses definition from: PAD-18-004
PAD-18-006 MUST pr-execute's summary comment MUST record the local suite runs the Pull Request has cost in a fixed line, Suite runs: <N> full, <M> targeted.

Local suite runs are the one pipeline cost GitHub does not record. The execute artifact is gitignored and deleted by pr-verify, so the PR comment is the only place the count survives.
PAD-18-016 MUST The PAD-18-006 count MUST include only runs that happened. The first-push gate of PAD-18-001 counts as one targeted run when create-pr ran the targeted set. A Pull Request that create-pr gated by the linters alone starts both counts at zero.

The first-push run happens in create-pr, before any execute artifact or comment exists, so it has to be counted explicitly. Leaving it out would understate every Pull Request, and counting a run that did not happen would overstate it. PAD-18-007 needs the true figure. No gate can now produce a full local run (PAD-18-003, PAD-18-008, PAD-18-015), so the full count reads zero on every Pull Request; the field stays because merged comments and velocity reporting parse it.
Refines: PAD-18-006
Uses definition from: PAD-18-001
PAD-18-007 SHOULD Velocity reporting SHOULD report, per merged Pull Request and by week: CI runs and failed CI runs, merges from the base branch, local suite runs (PAD-18-006), and open-to-merge time, plus failed CI runs on main.

Without these, the cost of the pipeline is invisible, and a change to gate placement cannot show that it saved time without moving failures onto CI or main.
Uses definition from: PAD-18-006
PAD-18-008 MUST NOT The gates before a Pull Request's first push MUST NOT run the full unit or integration suites.

CI runs both suites on the first push, faster than a local run, and GitHub refuses the merge until they pass. A local full run only makes the agent wait for an answer that CI gives sooner. This retires the one standing exception, a full local run for a change under vultron/demo/ or test/demo/: CI runs those tests, and the required CI gate judges the run. Which workflow depends on the path — demo-integration.yml for vultron/demo/, and python-app.yml's rest part for test/demo/, whose paths demo-integration.yml does not list.
Refines: PAD-18-001
PAD-18-017 MUST NOT A skill that hands off to create-pr MUST NOT run the unit or integration suites itself.

CI runs both suites on the push, and GitHub requires that run. A suite run in a skill before create-pr repeats it more slowly, before the gate that guards the push has even run.
Derives from: PAD-18-008
PAD-18-009 MUST Immediately before merging a Pull Request, the agent merging it MUST check that Pull Request alone against the current base.

The base that the Pull Request lands on is known only at the time of the merge.
PAD-18-018 MUST When the PAD-18-009 check finds a conflict, the agent MUST send the Pull Request back through the review pipeline instead of merging it.

Someone must resolve a conflict, and the resolved tree needs review and CI again before it can merge.
Extends: PAD-18-009
PAD-18-019 MUST When the PR is BEHIND, or the base changed files that it also changes, the agent MUST update it on GitHub before the merge. It uses gh pr update-branch, updates at most once per merge, and merges only after CI passes on the updated head.

Where files overlap, a clean merge is most likely to hide a behavior conflict. An update on GitHub tests that exact combination in CI, with no agent, no local merge and no local suite run. An update each time the base moves during the CI wait would make every merge invalidate every other ready Pull Request.
Extends: PAD-18-009
PAD-18-020 MUST NOT The agent merging a Pull Request MUST NOT re-check or re-sync other open Pull Requests because a merge moved the base.

A sweep of every open Pull Request after each merge makes every merge invalidate every other ready Pull Request. CI on main catches a semantic conflict between files that neither side shares (ADR-0209).
Extends: PAD-18-009
PAD-18-021 MUST Before each push of a Pull Request branch, the agent MUST run prepush-ci-mirror on the whole branch diff and push only when it exits 0. That covers create-pr's first push and each push pr-execute makes.

About one Pull Request in seven spent a push and a CI round on something CI found without running a suite: a line limit, a line ceiling, a link, an ADR epoch. Pre-commit hooks see only staged files, and several of those checks run only in CI, so a local step must run them on the diff the push sends (#5580).
Extends: PAD-18-001
Extends: PAD-18-002
PAD-18-022 MUST Every step that a pull_request run of .github/workflows/ can execute MUST be either mirrored by prepush-ci-mirror or excluded in its registry with a reason.

A mirror that silently misses a new workflow step drifts back into the gap it closes. Checking each step against the registry makes a new CI check a failing test until someone decides whether it runs locally.
Uses definition from: PAD-18-021
PAD-18-023 MUST NOT prepush-ci-mirror MUST NOT run pyright, the spec-corpus suite, its separate guard-test check, the site build, or a check that reads the built site.

These checks took most of the mirror's median 824 seconds on each push, and CI's spec and docs jobs answer them in about two to three minutes. The mirror keeps the cheap checks, which find the most frequent push failures in a few minutes. CI owns the guard tests, on a job reaching the Markdown, specs/, AGENTS.md and notes/ inputs its suite's path filters miss; that job lands with the removal, so PAD-18-031 holds throughout.
Constrains: PAD-18-021
PAD-18-024 MUST NOT An agent MUST NOT run tests on a scratch merge of a Pull Request with its base. A scratch merge is one the agent does not commit.

CI on pull_request tests the merge of the branch into its base on every push, and GitHub requires that run to pass. A local run on a scratch merge repeats it, more slowly. A conflict merge the agent commits is not a scratch merge, so PAD-18-015 still gates one.
PAD-18-025 MUST A conflict check of a Pull Request against its base MUST use a trial merge that moves no branch and writes no worktree.

The check decides whether a merge into the branch is needed, so it must leave no trace in the branch. .git is shared across host and container mounts, and a stray worktree can only be cleaned with git worktree remove, because git worktree prune would destroy live worktrees.
Constrains: PAD-18-004
PAD-18-026 MUST A local gate's linter step MUST run ruff's linter and formatter, and mypy.

These checks find most type and style failures in seconds, before CI would. mypy keeps a cache, so a run on a small change takes seconds.
PAD-18-027 MUST NOT A local gate MUST NOT run pyright.

pyright took a median of two minutes in each local linter step and used enough memory to starve parallel test runs. CI runs it on every push, and GitHub requires that run to pass.
Constrains: PAD-18-026
PAD-18-028 MUST create-pr MUST open an implementation Pull Request as a draft.

No full suite has run on the branch when it is first pushed. The draft state tells a human reviewer that CI has not yet answered. PAD-16-008 keeps such an Issue In Progress and PAD-16-009 grants pr-ship its run on a non-draft Pull Request, so the two read together on a Pull Request opened as a draft here.
Derives from: PAD-18-008
PAD-18-029 MUST An agent MUST mark a draft Pull Request ready for review when, and only when, CI's latest run on its head has passed.

No full suite runs locally, so a CI run is the first proof that the branch works, and the draft state says so until it passes. The obligation runs both ways because each direction answers a different failure: marked ready early, the Pull Request claims an answer nothing gave; left a draft once the run passed, it claims one is still coming, and GitHub refuses to merge a draft, so it cannot merge at all. A failed run leaves it a draft until a fix passes, never for good.
Derives from: PAD-18-028
PAD-18-030 MUST NOT pr-execute's limit on CI rounds MUST NOT count CI's first run on a draft Pull Request.

That run is the full-suite run that the local gate no longer makes, not a round spent on a fix. Counting it would leave one round fewer for fixes than before.
Derives from: PAD-18-028
PAD-18-031 MUST NOT A local gate MUST NOT drop one of its checks in favor of CI unless GitHub requires that check. GitHub requires a check when it refuses a merge into the base while the check is red or has not run.

Never merge on red holds only for a check that something enforces. A check moved to CI that GitHub does not require can be merged past unseen.
PAD-18-032 MUST pr-verify MUST withhold READY-TO-MERGE when GitHub reports a Pull Request BLOCKED and the required CI gate check on its head commit is red, pending, absent or unreadable. An unfinished run makes it pending; only when every run has finished does the newest one decide.

A required check with no bypass actor means GitHub refuses the merge, so a pipeline that calls the Pull Request ready sends the agent to a merge that cannot succeed. A cancelled or superseded run stays on the head commit beside the live one, and an unfinished run carries no usable start time, so ranking the runs before ruling out the pending ones would answer with an older green one.
Uses definition from: PAD-18-031
Extends: PAD-18-005

Epic Claim for an Epic Run

An epic run is work-epic-tasks driving one Epic's open children to completion across several waves. Its plan lives in a gitignored local file, and claiming each child only when its wave starts left later-wave Tasks looking free to every other agent. The Epic claim makes the run visible on GitHub and holds the lane it owns.

ID Priority Requirement Related
PAD-19-001 MUST An epic run MUST claim its Epic after plan approval and before any build starts. It assigns the Epic and posts a claim comment.

The run's plan lives in a gitignored local file. Until the run marks its Epic on GitHub, other agents see the Tasks of later waves as free.
PAD-19-007 MUST NOT An epic run's claim MUST NOT use a label, a branch, or a Project #24 field.

An Epic carries no Status (PAD-16-012) and no claim branch, and the assignee is a fact GitHub keeps rather than a marker someone must maintain.
Extends: PAD-19-001
PAD-19-008 MUST An epic run MUST refuse to claim an Epic that is already assigned.

Refusing an assigned Epic stops a second run on one Epic. The check and the assignment are two calls, so two runs started at the same moment can both pass. A person starts each run, so the project accepts that race and does not lock against it.
Extends: PAD-19-001
PAD-19-002 MUST While an Epic is assigned, every open Task and Feature whose nearest Epic ancestor it is MUST be held. Selection then reports each one as not workable, with the reason.

The run owns the build lane, including Tasks planned for later waves.
PAD-19-009 MUST NOT The epic-run hold (PAD-19-002) MUST NOT apply to a Bug, Idea, or Concern under an assigned Epic.

Bugs, Ideas, and Concerns are left open on purpose so other agents can keep fixing and planning while the run builds.
Extends: PAD-19-002
PAD-19-003 MUST An agent explicitly asked to build a held Task or Feature MUST stop and ask the user, unless the caller passes --epic-run <Epic> for that Epic.

Every agent runs as the same GitHub user, so the Epic's assignee cannot tell the run from a stray session. Asking the user keeps a stray session out of the lane that the run holds.
Refines: PAD-19-002
PAD-19-010 MUST An epic run MUST name its Epic with --epic-run <Epic> for every build it starts.

Only the run knows it is the run. A build that does not name the Epic stops at the PAD-19-003 check, even for the run's own Tasks.
Derives from: PAD-19-003
PAD-19-004 MUST An epic run MUST release its Epic at every stop, finished or not, by removing the assignee and posting a comment with the run's summary.

A claim that outlives its run holds the Epic's Tasks from everyone. Running the skill again claims the Epic again and resumes from its status file, so releasing loses nothing.
PAD-19-005 MUST The stale-claim sweeper (PAD-10) MUST flag an assigned Epic with stale-claim, and comment on it, when the claim is older than 3 days and none of the issues it holds (its descendants whose nearest Epic it is) has an open Pull Request or claim-branch activity within 3 days.

A run that crashes before its release step leaves the Epic assigned. The held issues' activity, not the Epic's, shows whether the run is still working.
Extends: PAD-10-001
PAD-19-006 MUST NOT An epic run MUST NOT hold the Bugs it plans.

Holding Bugs would stop other agents fixing them for the whole run.
PAD-19-011 MUST When a wave starts, an epic run MUST drop each planned Bug that another agent claimed first and report it as taken elsewhere.

Dropping a Bug that was taken is cheaper than coordinating over it.
Derives from: PAD-19-006

Pre-Push Mechanical PR Checks

About one triage finding in ten is mechanical: a tool could have caught it before the first push, and each one found after the push costs an execute round. These checks run before the push and again in triage, so triage stops finding them and judges only what needs judgment.

ID Priority Requirement Related
PAD-20-001 MUST pr-body-lint MUST check, each under a stable rule ID, every rule of .agents/skills/shared/pr-body-guide.md that needs no judgment.

A rule that needs no judgment is one a tool can apply the same way every time. A stable ID lets the guide, a finding and a test name the same rule.
PAD-20-006 MUST .agents/skills/shared/pr-body-guide.md MUST list every rule ID that pr-body-lint checks.

One list in two places drifts. Pinning the guide's rule table to the tool's own rule list makes a rule the tool adds, or one the guide drops, fail a test instead of a later triage.
Extends: PAD-20-001
PAD-20-002 MUST Before a Pull Request's first push, create-pr MUST run pr-body-lint on the composed body and push only when it exits 0.

A gate that is run but not required to pass catches nothing.
Uses definition from: PAD-20-001
PAD-20-007 MUST Before an implementation Pull Request's first push, create-pr MUST run spec-backstop --manifest and push only when it exits 0.

A gate that is run but not required to pass catches nothing. The manifest names the specs that the change claims to follow, so a failed resolution stops the push.
Uses definition from: SR-12-019
PAD-20-008 MUST The ## Specs section of an implementation Pull Request's body MUST carry the manifest file that spec-backstop resolved, verbatim.

A body that reports a tool's result by hand can misstate it. Pasting the file that the tool resolved leaves nothing to retype.
Uses definition from: PAD-20-007
PAD-20-003 MUST Before a Pull Request's first push, create-pr MUST run spec-lint --changed-since <base> and push only when it exits 0, whatever the Pull Request's type.

The marker rule for named tests (MS-10-011), the spec line limit (PD-10-002) and the one-obligation rule for statements (MS-03-007) have a backlog, so plain spec-lint cannot fail on them. Scoped to the branch they can, and a docs Pull Request runs no test suite to catch them otherwise.
Uses definition from: MS-10-027
Uses definition from: PD-10-005
PAD-20-004 MUST pr-triage MUST run pr-body-lint --stage final first in its body phase and report each finding it prints.

A manual reading of a tool-checked rule from the guide can miss findings that the tool catches every time.
Uses definition from: PAD-20-001
PAD-20-009 MUST In its body phase, pr-triage MUST judge by hand only the body rules that pr-body-lint does not check.

Triage keeps every check, but a rule that a tool checks is not a judgment.
Uses definition from: PAD-20-001
PAD-20-005 MUST After it records the Docs: line (PD-03-013), the session that opened a PR MUST run pr-body-lint --stage final on the body and fix every finding.

The placeholder create-pr writes is legal before the push and a FAIL after it. The final stage is the point where the placeholder must be gone, so that is where the check runs.
Extends: PD-03-013

Project Documentation Structure

This specification defines the purpose, scope, and maintenance requirements for key project documentation files that guide AI agents and human developers.

File ID: PD

Append-Only History Write Protocol

ID Priority Requirement Related
PD-05-001 MUST Agents MUST append new entries exclusively to the end of plan/*HISTORY.md files. Inserting content at an arbitrary line number, a specific section heading, or anywhere other than the very end of the file is prohibited.

A history file keeps its entries in time order. An insert at a line number or under a heading breaks that order, and it can put the new text inside another entry. An append at the end cannot change an entry that is already there.
PD-05-002 MUST NOT An agent MUST NOT run a conditional existence check (e.g., ls, test -f, os.path.exists) before it appends.

A check followed by a create or an append gives two paths, and each path is a place for a mistake, for example a create that writes over a file that exists. The prohibited pattern is the ls → if not found: create; if found: append decision tree.
PD-05-006 MUST Before it appends, an agent MUST make sure the file exists with an unconditional guard (e.g., touch plan/HISTORY.md), then proceed directly to the append step.

touch does nothing to a file that exists and creates a file that is missing. Thus one path covers both cases.
Implements: PD-05-002
PD-05-003 MUST NOT Agents MUST NOT read the full content of an append-only file in order to append a new entry. Only the final lines need to be inspected (using view_range with the tail of the file) to locate the exact end-of-file position.

An append-only file grows with no limit. To read all of it only to add text at the end uses context for no purpose. The tail is sufficient to find the end of the file.
PD-05-004 MUST Agents MUST use the following canonical append procedure: 1. Ensure the file exists: touch <file> (no-op if already present). 2. Write the new entry to a temporary file, then append that file to the target using bash("cat /tmp/entry.md >> plan/HISTORY.md") — or use Python open(file, 'a') for content that contains shell-special characters. Do NOT use the edit tool for appending, because edit requires a unique old_str anchor that is not guaranteed in files with repeated structural patterns. 3. Verify the entry was written correctly: read the tail with bash("tail -30 <file>") to confirm the content appears as expected.

The edit tool needs an anchor that occurs one time only. A history file repeats the same structure, so an anchor can match the wrong location or fail to match. An append with >> or mode 'a' always writes at the end. The read of the tail confirms that the entry is correct.
PD-05-005 MUST NOT Agents MUST NOT edit, reorder, or remove any existing entry from a plan/*HISTORY.md file. Once written, a history entry is permanent.

The history is the record of what the project did. If an agent can change or remove an entry, the record stops being evidence, and later readers cannot trust it.

Plan Section Organization

ID Priority Requirement Related
PD-06-004 MUST NOT Priority ordering is the sole responsibility of the Schedule field (Focus/Now/Next/Later/Someday) on Epics in GitHub Project #24 (PAD-02-001); a non-Epic issue takes its nearest Epic's tier. GitHub Issue titles MUST NOT encode priority information as numeric prefixes or rely on ordering to imply priority.

The Schedule field on the board is the one source of priority order. A priority in an issue title is a second ranking, and nothing keeps it in agreement with the board. The two rankings then become different, and a reader cannot tell which one is correct.
Uses definition from: PAD-02-001
PD-06-005 SHOULD Every non-Epic issue on GitHub Project #24 SHOULD be wired to the Epic it belongs to as a sub-issue.

Only Epics carry a Schedule tier (PD-06-004), so a non-Epic issue gets its priority from its Epic. An issue that is not a sub-issue of an Epic has no priority that a reader can trace, and nobody can tell which theme it advances. PAD-01-007 makes the wiring mandatory for every open non-Epic issue.

Task Granularity and GitHub Issues Coordination

ID Priority Requirement Related
PD-09-001 SHOULD Each GitHub Issue SHOULD be scoped to approximately one Pull Request worth of work — a set of changes that can be reviewed and merged in a single PR.

This sizing keeps individual issues reviewable, linkable, and trackable within the GitHub Issues UI. Issues that span multiple PRs are difficult to close cleanly and obscure progress visibility.
PD-09-002 SHOULD When an Issue would require more than one Pull Request to complete, it SHOULD either be split into multiple PR-sized Issues or elevated to a parent Epic Issue with GitHub sub-issues representing each PR-sized chunk.

An issue that spans multiple PRs cannot be closed atomically. Splitting or elevating preserves the one-PR-per-issue invariant without forcing artificial scope reduction.
PD-09-003 SHOULD A multi-step work item that needs coordinated effort across several Issues, or external visibility, SHOULD have a parent Epic GitHub Issue.

Work spread over several Issues has no single place that shows its scope and its progress. A parent Epic gives the team and outside readers that place.
PD-09-006 SHOULD An agent SHOULD link an Epic to its individual Task Issues with GitHub sub-issues.

GitHub sub-issues provide granular traceability within the GitHub UI, making progress visible to collaborators.
Implements: PD-09-003
PD-09-004 MUST An Epic whose scope includes changes to the canonical CaseLedgerEntry commit path (commit call sites, commit authorization/gating, or per-actor ledger content) MUST include a closing sub-issue that reviews a fresh multi-actor demo run's per-actor ledger logs before the Epic is closed. Passing the aggregate invariant test suite alone is NOT sufficient closure evidence for such an Epic. Concretely, an Epic is "in scope" for this rule if any change within it touches CommitCaseLedgerEntryNode, create_guarded_commit_case_ledger_entry_tree, or create_commit_log_entry_tree in vultron/core/behaviors/, or any call site that invokes these directly.

The aggregate invariant suite (the per-scenario harnesses in test/ci/invariants/) can pass on main throughout a ledger-path Epic while protocol-correctness bugs — such as hash-chain forks and RM oscillation loops — remain invisible. Such bugs are only detectable from a direct side-by-side review of each actor's JSONL log. Without a standing rule requiring this review at closure, later commit-path changes (e.g., a new authorization gate touching multiple call sites) can reintroduce the same class of bug undetected.
PD-09-005 SHOULD Before scheduling an Epic whose goal is to deprecate or remove an existing artifact (a field, a class, a write path), an exhaustive inventory of read and write call sites for that artifact, across all layers, including any wire-layer or adapter-layer duplicates, SHOULD be attached to the Epic issue at creation time.

Wire-layer or adapter-layer duplicates of the artifact being removed are routinely discovered mid-epic rather than at scoping time, and they end up as late-arriving prerequisites that block the epic's final removal step. An upfront inventory surfaces these dependencies before work begins rather than after most of the epic is already complete.

Line Length Outside docs/

Prose outside docs/ wraps at 88 characters (AGENTS.md § Markdown Formatting); docs/ keeps one sentence per line with no limit (SG-38). Markdown is held to it by markdownlint; spec YAML and Python doc lines, whose corpus predates the limit, are held to it per added line.

ID Priority Requirement Related
PD-10-001 MUST A Markdown file outside docs/ MUST keep its lines to 88 characters or fewer. Tables, code blocks and an overflow of one unbreakable token, such as a URL, are exempt.

Prose wrapped to one width reads the same in every editor and diff. A table row, a code line or a URL cannot wrap without a change to what it says, so the limit exempts them. docs/ has its own rule of one sentence for each line (SG-38).
PD-10-004 MUST markdownlint's MD013 MUST enforce the PD-10-001 limit in every directory except docs/ and the archives plan/history/, plan/retired-specs/ and archived_notes/.

A line limit that only people check is applied unevenly, and each miss becomes a review finding. MD013 checks the limit on each line in the linted directories. plan/history/ is append-only (HM-01-005) and plan/retired-specs/ keeps retired text as it was (MS-09-005), so nobody can wrap their lines again. The same is true for the retired notes in archived_notes/.
Implements: PD-10-001
PD-10-002 MUST NOT A change MUST NOT add a line over 88 characters with whitespace past the limit to a specs/*.yaml file, or to a comment or docstring of a Python file under vultron/, test/, integration_tests/, scripts/ or .agents/.

Both corpora hold thousands of longer lines written before the limit was checked, so a whole-file rule cannot be turned on. Holding each added or edited line to the limit moves the corpus toward it with no baseline file for concurrent changes to race on.
PD-10-003 MUST A pull-request growth guard MUST fail on each line PD-10-002 forbids that the branch adds, compared with the merge base.

The guard runs in CI for every pull request, so a forbidden line cannot merge unseen.
Verifies: PD-10-002
PD-10-005 MUST spec-lint --changed-since <ref> MUST report each spec YAML line that PD-10-002 forbids and that the branch adds.

The spec-lint flag lets create-pr catch a spec line before a docs pull request is pushed, so the author does not wait for the CI guard.
Verifies: PD-10-002
PD-10-006 MUST The PD-10-003 guard, the root markdownlint MD013 setting and ruff's max-doc-length MUST share one number as the line limit.

If the three checks used different numbers, a line could pass one check and fail another, and the limit would mean different things in different files.
Extends: PD-10-003

Spec Registry

Requirements for the structured spec registry: YAML spec files governed by Pydantic models, with linting, pytest integration, and context-generation tooling. The registry provides a single source of truth for spec IDs, prefixes, titles, and cross-reference validation.

File ID: SR

Spec Statement Semantics

ID Priority Requirement Related
SR-10-001 MUST A spec statement MUST describe an invariant property of the finished system. Such a property states what must always be true, what the system must always do, or what it must never do.

Specs are transferable knowledge for any implementer. Only a property that always holds stays true for every reader at every time.
SR-10-005 MUST NOT A spec statement MUST NOT describe a migration step, a one-time task, or a before-and-after transition.

A statement like "X must be replaced by Y" is meaningless once the replacement is done, and misleading before it is. The correct home for migration tasks is an issue tracker. If a migration produces a lasting architectural rule, that rule, not the migration instruction, belongs in the spec.
Derives from: SR-10-001
SR-10-002 MUST A spec statement MUST be written in the present tense and describe the system as it must perpetually be.

Temporal or conditional framing ("once X holds, Y must go away") creates specs whose satisfaction is permanent after a single event. Such specs cannot be re-tested on subsequent builds and do not communicate ongoing constraints to future maintainers or implementers.
Derives from: SR-10-001
SR-10-004 MUST NOT Phrases that signal migration-task framing — "must be replaced by", "must be removed", "must be updated to", "once X is done", "after migration" — MUST NOT appear in a spec statement unless they refer to a runtime state transition (e.g. a state machine trigger), not a code change.

These phrases usually show that a statement records a code change, not an invariant (SR-10-001). A ban on them outside runtime state transitions makes such statements easy to find. The corpus then describes the system as it must be.
Derives from: SR-10-005
SR-10-003 SHOULD A spec author SHOULD delete a spec whose statement has become vacuously satisfied. A statement is vacuously satisfied when the migration it described is complete and no ongoing constraint survives.

A vacuously satisfied spec creates false confidence: it always passes any check, so it neither constrains nor informs. Deletion keeps the registry honest.
Derives from: SR-10-001
SR-10-006 SHOULD When a residual constraint survives the migration, the spec author SHOULD rewrite the statement to express only that constraint, without any migration-task language.

A partially-stale spec that mixes a completed migration instruction with a surviving rule misleads readers about which clause is still normative. A rewrite keeps only the clause that still binds.
Refines: SR-10-005

Story Traceability

ID Priority Requirement Related
SR-11-003 MUST The spec linter MUST report as a hard error each kind: protocol spec with priority: MUST or priority: MUST_NOT that has no stories: entry.

Protocol-level MUST-tier requirements are the strongest obligations of an implementer. A hard-error gate makes each of them traceable to at least one stakeholder need. The gate covers only protocol, because no user stories exist yet for behavior that Vultron inherits from ActivityStreams, ActivityPub and HTTP (kind: foundation). The gate covers the kinds that the story catalog can support (ADR-0134).
Uses definition from: SR-11-001
Refines: MS-02-003 — MUST_NOT is the MUST tier
SR-11-007 MUST The spec linter MUST let a spec suppress that hard error with lint_suppress: [missing_story_reference].

Some implementation-detail MUST-tier requirements have no direct story. The suppression gives them an exception and records on the spec that the exception is deliberate.
Supersedes: SR-11-003
SR-11-004 SHOULD The spec linter SHOULD emit an advisory warning for each kind: protocol spec with priority: SHOULD, priority: SHOULD_NOT or priority: MAY that has no stories: entry.

Lower-priority protocol requirements still apply to implementers who choose to follow them, so a missing story is worth a flag. A warning, not an error, matches their weaker binding.
Uses definition from: SR-11-001
Refines: MS-02-003 — SHOULD_NOT is the SHOULD tier
SR-11-008 SHOULD The spec linter SHOULD let a spec suppress that warning with lint_suppress: [missing_story_reference].

The suppression records a deliberate exception on the spec, so the warning does not repeat for a requirement that has no story by design.
Supersedes: SR-11-004
SR-11-009 SHOULD The spec linter SHOULD print one advisory line per spec file that counts the file's kind: project and kind: process requirements with no stories: field. The count leaves out kind: protocol and kind: architecture requirements. The advisory does not change the exit code. The IDs are listed only when the --list-no-story-ids flag is set.

Project and process requirements may cite contributor and maintainer stories, but the written rationale stays their required reason, so the link is encouraged and not gated. A count per file shows the backlog without a hard error. One line per file keeps the default output short, and the opt-in ID list gives a worklist when one is wanted. Protocol requirements are left out because SR-11-003 and SR-11-004 cover them.
Uses definition from: SR-11-001

Relationship Type Semantics and Direction

What each rel_type asserts, which end of a relationship is upstream, which end records it, and the spec-lint checks that keep the requirements graph free of loops so that "what does a change to this requirement affect?" has one answer.

ID Priority Requirement Related
SR-13-001 MUST An implements relationship recorded on A naming B MUST mean that A states the concrete mechanism by which B is met; B is the more general requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-002 MUST A supersedes relationship recorded on A naming B MUST mean that A replaces B, wholly or in a case A names, so that where A applies B no longer binds; B is the earlier, upstream requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-003 MUST An extends relationship recorded on A naming B MUST mean that A adds obligations to B without narrowing or changing what B already requires; B is the more general requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-004 MUST A depends_on relationship recorded on A naming B MUST mean that A cannot be met unless B is also met; B is the upstream requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-005 MUST A conflicts relationship recorded on A naming B MUST mean that A and B cannot both be met as written; neither end is upstream.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-006 MUST A refines relationship recorded on A naming B MUST mean that A restates B for a narrower case or with more precision, so that meeting A in that case meets B; B is the more general requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-007 MUST A derives_from relationship recorded on A naming B MUST mean that A states a consequence that follows from B without being a narrower case of B; B is the upstream requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-008 MUST A verifies relationship recorded on A naming B MUST mean that A states a check that confirms B is met; B is the upstream requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-009 MUST A part_of relationship recorded on A naming B MUST mean that A is one component of B, which is met only when all of its parts are met; B is the more general requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-010 MUST A constrains relationship recorded on A naming B MUST mean that A bounds how B may be met without B being a narrower case of A; A is the more general requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-011 MUST A satisfies relationship recorded on A naming B MUST mean that meeting A is sufficient to meet B; B is the upstream requirement.

Eleven type names with no stated meaning let two authors record one fact with opposite verbs, which puts loops into the graph. A definition that names the upstream end gives every edge one direction to point.
SR-13-012 MUST A relationship MUST be recorded in only one of the two requirements it links: in the downstream requirement for every type but constrains and conflicts, in the constraining requirement for constrains, and in either one for conflicts. Neither requirement may then name the other under any type.

A link recorded at both ends is one fact kept twice, and the two copies drift: authors wrote the second copy with an opposite verb, which closed a loop. The links that name a requirement can be found by filtering relation_graph.recorded_relationships() on their target, so a second copy adds nothing.
SR-13-013 MUST Where a requirement is a narrower case of another, the link MUST be recorded as refines on the narrower requirement, and the more general one MUST NOT record constrains naming it.

refines and constrains are mirror images: "A refines B" and "B constrains A" state one fact from opposite ends. Naming one of them for that fact keeps the corpus from holding both. constrains stays for a general rule that bounds a requirement which is not a case of it.
Derives from: SR-13-012
SR-13-017 MUST A uses_definition relationship recorded on A naming B MUST mean that A uses a term or notion that B defines, so that a change to what B defines changes what A requires; B is the upstream requirement.

A requirement that writes "an active participant (CM-10-004)" uses the CM-10-004 meaning of active. Thus a change to CM-10-004 changes that requirement. No other type tells this. A can often be met when B is not met, so depends_on does not apply. Many requirements use a term that a different requirement defines, so the graph needs a type for this use (ADR-0160).
SR-13-018 MUST NOT Where no relationship type's definition holds between two requirements, a relationship MUST NOT be recorded between them under any type.

A link that asserts nothing true gives a false answer to the question "what does a change to this requirement affect?". If the link is not there, the worst result is a missed answer. A see-also mention asserts nothing about what a change affects, so it is not a relationship: the statement still cites the other requirement where a reader needs it, and the citing requirement lists it in see_also with the reason no type fits (SR-13-022). Usually this error is a refines or depends_on link between siblings or unrelated requirements, used as a loose "related to".
SR-13-022 MUST Every requirement ID that a statement writes out, other than its own, MUST be linked to the citing requirement by a relationship recorded at either end, or be listed in the citing requirement's see_also field with the reason no relationship type fits.

A citation is judged when it is written, not found by the next audit. Most citations fit a relationship type, and the link lets the impact walk find the cited requirement. A citation that fits no type, such as a rationale, a scope boundary, an example or a link that would close a loop, must not get a link. The see_also entry records that this was decided, and why, without a false claim in the graph.

Case Event Log Synchronization

Requirements for the append-only canonical recorded case ledger, replication transport, conflict handling, per-peer state tracking, and retry semantics for distributed case state synchronization across Participant Actors.

File ID: SYNC

Leadership and Ownership

ID Priority Requirement Related
SYNC-06-002 SHOULD The conditions under which replication leadership changes SHOULD be documented in notes/sync-ledger-replication.md

A change of leadership changes who may write the ledger. Contributors who change replication code must know when that can occur, so the conditions are written in one place.

Vultron Project Technology Stack

This specification defines the normative technology constraints and implementation requirements for the Vultron reference implementation.

File ID: IMPLTS

Containerization and Deployment

ID Priority Requirement Related
IMPLTS-05-007 MUST Source code MUST be hosted in GitHub using git for version control.

Issues, pull requests, the project board and CI are all on GitHub, and the project tools and agent skills call the GitHub API. Hosting the source there keeps the code and the record of work about it in one place.

Code Quality Tooling

ID Priority Requirement Related
IMPLTS-07-019 MUST Each ruff ignore entry MUST carry an inline comment that states what the rule reports and why this project does not enforce it.

An exclusion with no stated reason looks the same as a mistake. Nobody can tell whether it is safe to delete, so the list only grows. A comment on each entry makes the ignore list the record of what the project chose not to check and why, and a contributor can delete an entry with confidence. CS-23-001 asks the same of a sanctioned broad except.
Extends: IMPLTS-07-017
IMPLTS-07-027 MAY When an exclusion is provisional, its ruff ignore entry MAY cite a tracking issue in place of a standing reason.

A provisional exclusion has no lasting reason yet. The tracking issue holds the plan to remove it, so the comment points there.
Supersedes: IMPLTS-07-019
IMPLTS-07-020 MUST A contributor MUST suppress a ruff finding kept to hold the gate green with a per-line # noqa marker. The marker names the rule and the issue that tracks its removal. A rule excluded project-wide under IMPLTS-07-019 is not such a finding.

A new finding with no marker fails the check because its rule is selected. The issue number on each marker shows that the suppression is planned work, not an unexplained exception. ADR-0094 records why file-wide per-file-ignores cannot do the same job.
Extends: IMPLTS-07-017
See also: IMPLTS-07-019 — scope boundary: a rule excluded project-wide under IMPLTS-07-019 is not such a finding
IMPLTS-07-025 MUST The ruff configuration MUST keep RUF100 selected.

RUF100 reports a # noqa marker that suppresses nothing. With RUF100 selected, a marker left after its finding is fixed fails the check. Each marker then matches a real finding, and nobody keeps a separate list of them.
Extends: IMPLTS-07-020
IMPLTS-07-021 MUST A lint, format or type check MUST declare its scope in its tool's configuration file, not in the arguments of the commands that invoke it. Every caller then invokes the tool with no path operands. Callers are CI jobs, pre-commit hooks, agent skills and documented developer commands.

When each caller passes its own paths, the same scope is written in many places, and nothing checks that they agree. Two callers can then check different files: for example, CI can pass code that the pre-commit hook never lints. With the scope in the tool's configuration file, all callers check the same files, and a scope change is one edit in one file.
Constrains: IMPLTS-07-017
Constrains: IMPLTS-07-005

VINCE Data Handling in the Case Shadow Tool

Rules for data read from a VINCE instance by the case shadow tool's VINCE case reader: what logs may carry, how the API credential is read, and the only ways it may enter the repository or a publication. Readers and retention add no requirement: each VINCE user runs the shadow with their own credential, and nothing is left on the host after the tool's process exits (SHD-01-003).

File ID: VSD

Repository and Publication

ID Priority Requirement Related
VSD-02-001 MUST NOT Data read from a VINCE instance MUST NOT be committed or published unless it is synthetic or its case id is cleared.

A committed response stays in git history until the history is rewritten. Sanitization and per-case clearance are the two gates a test or a person can check before anything leaves.
Uses definition from: VSD-02-002
Uses definition from: VSD-02-005
VSD-02-002 MUST Each cleared-case list entry MUST name one VINCE case id and link the maintainer comment that cleared it.

A clearance covers one case. An entry that names no case or cites no decision clears nothing a reviewer can confirm.
VSD-02-003 MUST The committed-data check MUST refuse a cleared-case entry that lacks a case id or a clearance link.

An entry the check accepts without both would clear data with no decision behind it.
VSD-02-004 MUST NOT A Coding Agent MUST NOT add a cleared-case list entry or post a clearance.

A Coding Agent acts under its operator's GitHub account, so no check can tell its comment from a maintainer's. It may ask a maintainer to clear a case id, and never grants one.
VSD-02-005 MUST The committed-data check MUST accept a marked VINCE-shaped file as synthetic only when the fixture generator or the sanitizer wrote it.

A marker anyone can type proves nothing alone. Tying it to the two tools whose tests prove their output holds no case content is what makes synthetic data safe to commit without clearance.