Runtime primer: AGENTS.md §Artifact Conventions. This file is the expanded canonical reference for rationale, exceptions, and remediation details; it is not a required read for ordinary workflow execution. scripts/drift-report.mjs --strict checks parity for the runtime-critical contract.

Artifact Convention Rules

These rules apply whenever an agent reads or modifies files inside a Feature Workspace at specs/<feature-folder>/. The ADR preservation rules in this file also apply to standalone ADRs under specs/adrs/. They protect the integrity of cross-referenced identifiers, gating state, and structural conventions that downstream phases depend on. They do not apply to other Project Context Specs such as specs/prd.md, specs/sad.md, specs/dod.md, specs/project-plan.md, or epic detail files under specs/plan/.

Preservation Rules

These are non-negotiable guardrails — violating them breaks cross-artifact traceability and phase gating.

Feature Reruns and Migrations

• Reruns are refinements. Snapshot existing IDs, checkbox lines/state, phase headers, checklist paths, BUG tasks, and downstream references before writing; preserve them and append only genuinely new IDs above the current maximum.
• AUTOPILOT = true never permits destructive regeneration or infers approval. Existing spec.md, plan.md, tasks.md, data models, contracts, checklist queues, and checklist files must be refined or reconciled in place.
• Destructive regeneration is an explicit interactive-only migration. Before writing, show the affected files and a complete old-ID → new-ID mapping, require explicit user approval for that exact mapping, update all downstream references atomically, then verify no checked line, unmapped ID, or referenced path was removed. Any missing mapping, failed update, or failed validation leaves the original bytes unchanged.
• Never add compatibility aliases for silently renumbered IDs.

Checkbox State Transitions

The only valid checkbox transitions during implementation are:

• - [ ] → - [X] (task completed, checklist item satisfied)
• Never - [X] → - [ ] (reverting completion state requires explicit user approval)
• Never delete a checkbox line entirely

Format Rules

These formats are structural contracts consumed by parsers, trackers, and cross-reference tools.

Bug task severity: CRITICAL | ERROR | WARNING. Categories: test-failure | lint-error | security-vuln | coverage-gap | requirement-gap | pi-violation | runtime-error.

Bug task modifier tags are optional and only apply to QC-generated bug work:

• [RECURRING]: a previously resolved bug regressed
• [ESCALATED]: repeated fix attempts failed and the task needs higher attention
• [DEFERRED]: excluded from the active Implement → QC loop and tracked under ## Deferred Issues

Bug tasks include blockquote context lines (not part of the task ID line):

  > Error: [actual error message, ≤200 chars]
  > Fix hint: [suggested approach]

Section Rules

These sections are structurally required — removing them breaks downstream tooling and gating.

spec.md

• Determine spec_type from frontmatter. If it is absent, treat the spec as product.
• Allowed top-level sections vary by spec_type:
  • Product: Problem Statement, Scope, User Scenarios & Testing, Requirements, Assumptions & Risks, Implementation Signals, Success Criteria, optional Glossary, optional Clarifications, optional Compliance Check, optional Stress-Test Findings
  • Technical: Problem Statement, Scope, Technical Objectives, Integration Points, Requirements, Assumptions & Risks, Implementation Signals, Success Criteria, optional Glossary, optional Clarifications, optional Compliance Check, optional Stress-Test Findings
  • Operational: Problem Statement, Scope, Operational Objectives, Integration Points, Requirements, Assumptions & Risks, Implementation Signals, Success Criteria, optional Glossary, optional Clarifications, optional Compliance Check, optional Stress-Test Findings
• Mandatory sections must remain even if empty for the active spec_type.
• Size budget: ≤ 10KB.

plan.md

• Do NOT remove the Instructions Check section — it is a gating checkpoint that must be present and evaluated
• Do NOT remove the Technical Context metadata block
• Do NOT remove the Requirement Coverage Map section — it is the primary input for task generation AND the traceability matrix consumed by the Developer (self-verify) and the Story Verifier (QC starting map)
• The Requirement Coverage Map File Path(s) and Function(s)/Symbol(s) columns MUST be populated for every requirement row; empty values are Plan Readiness gaps
• Do NOT remove the Acceptance Test Stubs section — it is consumed by /sddp-tasks (emits a stub-creation task per P1 row) and /sddp-implement (parses it into STUB_MAP to feed the Developer). When populated, every P1 requirement from spec.md MUST have a row; Test File follows the ## Testing Strategy Unit tier convention; Stub Blocks embed the reqID; RED Status is one of pending/failing-assertion/skip. When the spec has no P1 requirements, the section body is N/A — no P1 requirements. reqID links in Stub Blocks are stable cross-references subject to the preservation rules.
• Self-healing allowance (during /sddp-implement only): when the Developer reports a structured Divergence, /sddp-implement may update cell VALUES in the Requirement Coverage Map (File Path(s), Function(s)/Symbol(s)) and the ## API Surface Summary table, append new feature-local AD-### rows to ## Architecture Decisions, and update ## Project Structure Source Code entries. Cross-referenced IDs (FR-###/TR-###/OR-###/RR-###, task IDs, existing AD-### IDs, ADR-NNNN) MUST stay immutable; only cell values and newly appended AD-### rows may change. Every such edit MUST be logged to divergence-log.md. Outside /sddp-implement self-healing, these cells follow normal preservation rules.
• Do NOT change Architecture Decision IDs (AD-###) — they may be referenced by tasks
• Size budget: ≤ 10KB

tasks.md

• Do NOT remove the Dependencies section — it defines the phase graph that implementation agents traverse
• Do NOT remove phase headers that exist — they delineate execution boundaries. Optional empty phases may be omitted at generation time, but present phase headers must be preserved.
• Size budget: ≤ 6KB and 40 tasks.

checklist files

• Do NOT remove or renumber CHK### items — external references depend on stable IDs
• Do NOT change the quality dimension tags in square brackets
• Checklist file paths are immutable. Select a unique path before generation and fail rather than overwrite if it appears concurrently.

qc-report.md

• On re-runs, the prior report is overwritten with the new report. If run history is needed, the agent should note the prior verdict in the "Re-run detection" step of the QC workflow.
• Do NOT manually edit qc-report.md — it is generated exclusively by /sddp-qc
• The report structure must follow the template at .github/sddp/workflows/quality-control/assets/qc-report-template.md

manual-test.md

• Generated conditionally by /sddp-qc when manual verification is required
• May be updated on re-runs if new manual test scenarios are detected
• Do NOT remove existing test scenarios on re-run — append new ones or update existing entries

.completed / .qc-passed markers

• These are gating markers managed exclusively by /sddp-implement and /sddp-qc
• Do NOT manually create, delete, or edit these files
• .completed is deleted by QC on failure and recreated by a successful implementation re-run; deferred CRITICAL/ERROR bugs block it
• .qc-passed is invalidated at QC start and on every FAIL/BLOCKED outcome, then atomically created only after PASS
• .qc-passed stores SHA-256 digests for the exact qc-report.md bytes, its sorted QC Evidence Manifest, and the relevant Git repository state, plus its HEAD baseline; consumers must recompute all before trusting it
• Pending manual verification or deferred CRITICAL/ERROR bugs can never produce a valid .qc-passed

divergence-log.md

• Managed exclusively by /sddp-implement self-healing (implement-tasks/references/self-healing-amendments.md)
• Append-only: each divergence/amendment adds one table row; never edit or delete prior rows
• Schema: | Timestamp | TaskID | ReqID | Category | Original | Actual | AffectedArtifact | Rationale |
• Category vocabulary: file-path | symbol | api-shape | architecture
• Do NOT manually create or edit this file outside /sddp-implement; /sddp-analyze may read it but must not modify it

autopilot-log.md

• Managed by autopilot-enabled runs of the SDD pipeline phases
• Append-only decision audit log; never edit or delete prior rows
• Initialize only when absent; reruns append a dated run boundary, validated seven-column rows, and a run summary without rewriting history
• Rows use only the canonical Autopilot Phase/Event vocabularies and repository-contained relative artifact links; append each complete row atomically so interrupted runs remain readable

specs/adrs/*.md

• Apply only the ADR preservation rules from this file when editing standalone ADRs
• Do NOT apply feature-artifact section requirements (spec.md, plan.md, tasks.md, checklist, QC marker rules) to ADR files

When These Rules Apply

These rules are active whenever an agent:

1. Edits any .md file inside a specs/ feature directory
2. Runs a workflow that modifies spec artifacts (specify, clarify, plan, tasks, implement, analyze)
3. Performs remediation on analysis findings

Violation Severity

Violations of these rules during /sddp-analyze are classified as: