git:20260904.60cdc34 to git:20261013.420fd80

- # SDD Pilot — Agent Context

-

- Apply the Spec-Driven Development rules below during feature delivery. Enforce the lifecycle order, phase gates, conventions, and execution policy. If any rule here conflicts with `project-instructions.md`, follow `project-instructions.md`.

-

- ## Lifecycle

-

- `Specify → Clarify → Plan → Checklist (optional) → Tasks → Analyze (optional) → Implement → QC`

-

- Treat this order as strict. If a required artifact for the next phase is missing, stop and return the work to the phase that owns it.

-

- ## Runtime Preflight

-

- Every public `/sddp-*` command must run this preflight exactly once before reading or writing any SDD Pilot artifact, delegating a phase, or running another SDD Pilot script. Nested phases inherit the successful in-turn result and must not run it again:

-

- ```sh

- if ! command -v node >/dev/null 2>&1; then

- printf '%s\n' 'SDD Pilot requires Node.js 22 or newer available as node. Detected: not found. Install a supported Node.js LTS release: https://github.com/attilaszasz/sdd-pilot#prerequisites. No SDD Pilot artifact was modified.'

- exit 1

- fi

- node scripts/runtime-preflight.mjs

- ```

-

- On a non-zero result, halt without reading or modifying SDD Pilot artifacts. Do not install Node or use an editor-bundled runtime.

-

- ## Phase Gates

-

- Each phase boundary runs a mandatory structural validator before the next phase may start. A FAIL blocks the next phase: in autopilot the pipeline halts; interactively the user may override with "Proceed anyway" (the bypass is recorded in the conversation only — no persistent marker is written).

-

- - `spec.md` must exist before Clarify or Plan.

- - **Spec → Plan gate**: `/sddp-plan` delegates the **Spec Validator** (`_spec-validator.md`) — allows 0–3 unresolved `[NEEDS CLARIFICATION: ...]` markers and fails at 4+, independently fails any unresolved CRITICAL/HIGH stress-test finding, and enforces concrete acceptance criteria for all P1 stories and frontmatter completeness. FAIL blocks Plan.

- - `plan.md` must exist before Tasks.

- - **Plan → Tasks gate**: `/sddp-tasks` delegates the **Plan Validator** (`_plan-validator.md`) — enforces 100% P1 requirement coverage in the Requirement Coverage Map, no orphaned Architecture Decisions, and all declared dependencies installable. FAIL blocks Tasks.

- - `tasks.md` must exist before Implement.

- - **Tasks → Implement gate**: `/sddp-implement` (via `references/gates.md`) delegates the **Tasks Validator** (`_tasks-validator.md`) — enforces complete task parsing, ≤40 tasks, every P1 requirement has ≥1 task, no circular `after:` chains, `tasks.md` ≤ 6 KB, valid phase structure, and semantic reconciliation of checked task provenance against current spec/plan requirements, coverage, imports/exports, and dependencies. FAIL blocks Implement.

- - If `checklists/` exists, all checklist items must be complete before Implement unless the user explicitly overrides.

- - `.completed` must exist before QC.

- - Do not treat a feature as release-ready until `.qc-passed` exists and its report/evidence SHA-256 digests, Git baseline, and repository-state digest validate.

- - Any `project-instructions.md` violation is CRITICAL severity.

-

- ## Core Conventions

-

- - Store Feature Workspace artifacts in `specs/<feature-folder>/`.

- - New Feature Workspaces use `00001-feature-name` folder names.

- - If the active branch matches `#####-feature-name`, use `specs/<branch-name>/`.

- - Existing non-prefixed Feature Workspaces remain valid when already present.

- - P1 is the most critical priority and should be sufficient for a viable MVP. Each user story or objective must be independently testable.

-

- Markers:

-

- - `.completed` means implementation is complete with no unresolved CRITICAL/ERROR bugs.

- - `qc-report.md` records QC results.

- - `.qc-passed` means current QC has passed only when its report/evidence SHA-256 digests, Git baseline, and repository-state digest validate; pending manual verification and deferred CRITICAL/ERROR bugs block it.

-

- ## Artifact Conventions

-

- The rules below are the ambient runtime primer for feature artifacts. The expanded canonical reference is `.github/skills/artifact-conventions/SKILL.md`; read it only for rationale, exceptions, or remediation details not covered here. `scripts/drift-report.mjs --strict` checks that this primer retains the required contract sentinels.

-

- These rules apply to `specs/<feature-folder>/` feature artifacts and standalone ADRs under `specs/adrs/`. They do not apply to 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

-

- - Do not reorder product story or non-product objective priorities (`P1`, `P2`, `P3`) without explicit user approval.

- - Do not change `T###`, `CHK###`, `FR-###`, `TR-###`, `OR-###`, `RR-###`, `SC-###`, `AD-###`, `ADR-NNNN`, or `STF-###` IDs.

- - Do not rename, renumber, or delete standalone ADR files; do not write them outside the ADR Author subagent.

- - `[VERIFY: <command>]` text is executable and may be corrected; it is not a cross-referenced ID.

- - Resolve `[NEEDS CLARIFICATION]` only with user-approved answers.

- - Feature reruns default to refinement: preserve existing IDs, checkbox lines/state, phase headers, checklist paths, BUG history, and downstream references. Autopilot never authorizes destructive regeneration.

- - Destructive regeneration is an interactive-only migration: require explicit user approval, snapshot affected artifacts, provide a complete old-ID → new-ID mapping, update every downstream reference atomically, and validate that no checked line or unmapped ID was lost. Otherwise halt without writes.

-

- ### Checkbox State

-

- - The only valid implementation transition is `- [ ]` → `- [X]`.

- - Never reverse `- [X]` → `- [ ]` or delete a checkbox line without explicit user approval.

-

- ### Format Grammars

-

- - Task: `- [ ] T### [P?] [US#|OBJ#?] {(FR|TR|OR|RR)-###?} [COMPLETES req?] Description [after:T###?] [← T###:Symbol?] [→ exports: Symbol?] [VERIFY: <command>]?*`

- - Requirement: `- **(FR|TR|OR|RR)-###** [US#|OBJ#]: ...` (owner determines priority)

- - Success criterion: `SC-### [US#|OBJ#]: [Measurable, technology-agnostic outcome]`

- - Checklist item: `- [ ] CHK### <question> [Quality Dimension, Spec §X.Y]`

- - Bug task: `- [ ] T### [BUG:severity] [RECURRING?] [ESCALATED?] [DEFERRED?] {(FR|TR|OR|RR)-###} [category] Description — file:line`

- - Stress-test finding: `STF-###: [Category] (Severity) — Affected: [IDs] — [summary]`

- - Bug severities are `CRITICAL` | `ERROR` | `WARNING`; categories are `test-failure` | `lint-error` | `security-vuln` | `coverage-gap` | `requirement-gap` | `pi-violation` | `runtime-error`.

-

- ### Required Structure

-

- - `spec.md`: honor `spec_type` (default `product`), keep its type-specific mandatory top-level sections, and do not add unauthorized top-level sections.

- - Product specs require `Problem Statement`, `Scope`, `User Scenarios & Testing`, `Requirements`, `Assumptions & Risks`, `Implementation Signals`, and `Success Criteria`; technical specs use `Technical Objectives` and `Integration Points`; operational specs use `Operational Objectives` and `Integration Points`.

- - `plan.md`: preserve `Instructions Check`, `Technical Context`, `Requirement Coverage Map`, and `Acceptance Test Stubs`; populate coverage paths and symbols. Size limit: ≤ **10KB**.

- - `tasks.md`: preserve `Dependencies` and existing phase headers. Size limit: ≤ **6KB** and 40 tasks.

- - Checklist files: preserve `CHK###` IDs and quality-dimension tags.

- - Checklist output paths are immutable. Every new checklist uses a unique path; never overwrite an existing checklist file.

- - `qc-report.md` is generated only by `/sddp-qc`; `.completed` and `.qc-passed` are managed only by `/sddp-implement` and `/sddp-qc`.

- - `divergence-log.md` and `autopilot-log.md` are append-only; self-healing artifact edits are limited to `/sddp-implement`.

-

- Violations are **CRITICAL** for changed cross-referenced IDs, unauthorized priority changes, removed required sections, or ADR file mutations; **HIGH** for ADR writes outside the ADR Author, removed clarification markers, or reversed checkboxes; **MEDIUM** for unauthorized spec sections or format deviations.

-

- ## Communication Style

-

- Follow `project-instructions.md` section IV (Agent Output Style). That section is authoritative; do not duplicate or paraphrase its rules elsewhere.

-

- Runtime communication from any skill or sub-agent MUST also follow the contract below. These rules are ambient — they apply without re-reading any file.

-

- ### Default Rules

-

- - Lead with outcome, verdict, or delta.

- - Prefer short sentences, fragments, and flat bullets.

- - Report only changed state, counts, blockers, and next action.

- - Do not restate workflow steps unless status changed.

- - Keep file paths, requirement IDs, task IDs, commands, URLs, headings, and markers exact.

- - Keep fenced code blocks and inline code exact.

- - When a machine-readable contract exists (JSON, table schema, checklist grammar), obey it exactly and add no extra prose.

-

- ### Preferred Output Patterns

-

- - Progress update: done, issue, next.

- - Validation or audit: PASS/FAIL first, then only failing or risky items.

- - Research: recommendation, avoid, sources.

- - Review finding: location, severity, problem, fix.

- - Summary: counts, deltas, blockers, next step.

- ### Writing Quality

- Apply a writing-quality pass to user-facing text and newly written or changed prose before delivery. The expanded reference is `.github/skills/writing-quality/SKILL.md`; do not reload it during routine workflow execution.

- - Preserve meaning, scope, certainty, evidence, citations, and the user's voice.

- - Prefer concrete facts, plain words, active voice, and natural sentence rhythm. Remove puffery, stock AI phrasing, filler, vague attribution, forced symmetry, and generic conclusions.

- - Say what a project-specific mechanism does. If a sentence could appear unchanged in another project's docs, make it specific or cut it.

- - Avoid em dashes, decorative emoji, excessive boldface, title case for newly authored narrative headings, and chatbot or sycophantic openers.

- - Edit only narrative spans created or changed by the current task. Never use a style pass to resolve ambiguity, strengthen a claim, alter requirements or priorities, or remove a caveat.

- - Preserve frontmatter, required headings and section order, tables, checkbox lines, IDs, markers, paths, commands, URLs, citations, code, quoted text, and machine-readable content exactly.

- - `project-instructions.md` remains authoritative. Security, legal, policy, and compliance language keeps its required precision even when that prose is less conversational.

- - Before finishing, ask: "What makes this obviously AI generated?" Fix the remaining tells without changing meaning.

- ### Auto-Clarity

- Drop compression and use normal explicit prose when brevity could create ambiguity for:

- - security warnings

- - destructive or irreversible actions

- - ordered multi-step instructions

- - user questions showing confusion or repetition

- - policy, compliance, or safety-sensitive nuance

- Resume compact mode after the risky section is clear.

- ### Boundaries

- - Never compress or mutate artifact grammars, IDs, checkbox state, or required section headers.

- - For parser-sensitive files under `specs/`, write concise normal prose; do not rewrite them into stylized shorthand.

- - Readability beats maximum compression for persisted artifacts.

- - For allowlisted narrative Markdown, prefer validator-backed compression via `.github/skills/markdown-compression/SKILL.md` instead of ad hoc rewrites.

- ## Continuous Execution Policy

- Execute routine repository operations for real: file edits, build/test/lint commands, git commands, task updates, marker files, and local package installs. Do not simulate completion, test results, QC results, or pass states. Stop only for ambiguity, destructive actions, system-level installs, or actions outside the project boundary. Report progress at phase boundaries.