artifact-conventions

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.

Rule	Rationale
Do NOT reorder product user story priorities or non-product objective priorities (P1, P2, P3) without explicit user approval	Priority order drives task phasing and MVP scope — reordering silently changes what ships first
Do NOT change task IDs (T001, T002…)	Task IDs are cross-referenced in coverage maps, dependency graphs, and issue trackers
Do NOT change checklist IDs (CHK001, CHK002…)	Checklist IDs are referenced externally by quality-assurance checks and test evaluators
Preserve checkbox state (- [ ] vs - [X])	Checkbox state is a gating signal — flipping it can unblock or block downstream phases
Do NOT change requirement IDs (FR-001, TR-001, OR-001, RR-001)	Requirement IDs are mapped to tasks, coverage reports, and compliance checks
Do NOT change success criteria IDs (SC-001, SC-002…)	Success criteria IDs are referenced in phase reviews and validation
Do NOT change architecture decision IDs (AD-001, AD-002…)	Architecture decision IDs may be referenced by tasks and implementation agents
Do NOT rename, renumber, or delete standalone ADR files under specs/adrs/	ADR file paths are stable references; ADR-NNNN numbers are monotonic, never reused, and cross-referenced by project-plan epics, plan traceability tags {SAD:ADR-NNNN}, and sad.md catalog rows
Do NOT write standalone ADR files outside the ADR Author subagent	All ADR file mutations must flow through .github/agents/_adr-author.md per the MADR authoring contract
Do NOT change stress-test finding IDs (STF-001, STF-002…)	Stress-test finding IDs are referenced by [NEEDS CLARIFICATION: STF-###] markers and adversarial analysis reports
[VERIFY: <command>] command text is NOT a cross-referenced ID — it may be edited/corrected to reflect the real check	Unlike T###/FR-###/AD-### IDs, VERIFY command text is an executable assertion, not a stable reference; updating a broken command (wrong path, stale flag) is a normal maintenance edit, not an ID violation
Respect [NEEDS CLARIFICATION] markers — only resolve with user-approved answers	Silently removing a marker hides unresolved ambiguity that may affect scope, security, or UX

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.

Artifact	Format	Example
Task	- [ ] T### [P?] [US#|OBJ#?] {(FR|TR|OR|RR)-###?} [COMPLETES req?] Description [after:T###?] [← T###:Symbol?] [→ exports: Symbol?] [VERIFY: <command>]?*	- [ ] T012 [P] [OBJ1] {TR-005} Create migration harness in src/migrations/harness.py → exports: MigrationHarness.run() [VERIFY: grep "class MigrationHarness" src/migrations/harness.py]
Requirement	`- **(FR	TR
Success Criterion	`SC-### [US#	OBJ#]: [Measurable, technology-agnostic outcome]`
Checklist Item	- [ ] CHK### <question> [Quality Dimension, Spec §X.Y]	- [ ] CHK001 Is the error handling strategy defined? [Completeness, Spec §3.2]
Bug Task	`- [ ] T### [BUG:severity] [RECURRING?] [ESCALATED?] [DEFERRED?] {(FR	TR
Stress-Test Finding	STF-###: [Category] (Severity) — Affected: [IDs] — [summary]	STF-001: Cross-Requirement Contradiction (CRITICAL) — Affected: FR-002, TR-001 — Real-time sync vs 50ms latency cap at 10k items

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:

Violation	Severity
Changed or removed a cross-referenced ID (T###, FR-###, TR-###, OR-###, RR-###, SC-###, CHK###, AD-###, ADR-NNNN, STF-###)	CRITICAL
Reordered user story or objective priorities without approval	CRITICAL
Removed a required section (Instructions Check, Dependencies)	CRITICAL
Renamed, renumbered, or deleted a standalone ADR file under specs/adrs/	CRITICAL
Wrote a standalone ADR file outside the ADR Author subagent	HIGH
Silently removed [NEEDS CLARIFICATION] marker	HIGH
Reversed checkbox state ([X] → [ ]) without approval	HIGH
Added unauthorized top-level section to spec.md	MEDIUM
Format deviation from structural contracts	MEDIUM