feat(sdd): accept Claude plan documents via plan:provided marker

[norrietaylor]

Summary

Adds a plan:provided marker and a "Specification (from Claude plan)" issue template (spec.md). The marker puts sdd-spec and sdd-triage into translation mode: instead of authoring a spec and architecture from a slim issue body, they translate a Claude plan document pasted into the tracking issue.

Implements issue #102 as written, honoring its three confirmed decisions:

• Marker label is plan:provided (not spec:provided).
• Full Phase A architecture-translation in sdd-triage (translate the plan's architecture section into architecture.md; fall back to author-from-scratch when absent or thin).
• No-leakage gate relaxed only when each leaked statement carries a (translated from plan: step N) citation; absent the citation it stays a Warning.

Design

Solutions S1–S5 from the issue:

• S1 — both agents honor the marker. sdd-spec translation mode (steps 3b/5a); sdd-triage Phase A architecture-translation mode (step 2). One orthogonal marker, two readers on different code paths — the same shape as model:*. Phase transitions leave the marker untouched, so propagation sdd:spec → sdd:triage is automatic.
• S2 — conditional gate handling. No-leakage (Warning) relaxed only for citation-carrying leakage. Empty-PR rule on proof artifacts (Blocker) unchanged: health-check verifications are rejected and a behavioral artifact synthesized, or needs-human. Documented in shared/sdd-gates.md and sdd-spec.md step 5a.
• S3 — lifecycle ownership (the sdd:dispatched model). Set by the template; read by sdd-spec and sdd-triage Phase A; cleared by sdd-triage Phase A when the architecture PR opens (full path) or by sdd-spec when the stub spec PR opens (fast path). sdd-spec does NOT clear it on full-path completion, so sdd-triage can still see it. Both agents add plan:provided to remove-labels.allowed. Declared under markers: in lifecycle-states.yml.
• S4 — fast-path precedence. Step 3a proposal text adjusts under the marker ("/fastpath to dispatch the plan directly, or /spec to write a translated full spec first"). On /fastpath, step 7a runs in plan-lift mode: stub R-IDs and proof artifacts lifted from the plan, the [sdd-spec:fastpath-plan] comment is the plan reformatted; the marker is cleared on stub-spec exit.
• S5 — R-ID rule (codified, not enforced). One R-ID per plan step per demoable unit; sub-bullets get R-IDs only when independently testable; a non-testable step gets no R-ID and triggers needs-human. Downstream R-ID validation is presence-based, so no downstream agent changes.

Files

NEW       templates/.github/ISSUE_TEMPLATE/spec.md
MODIFIED  templates/.github/labels.yml
MODIFIED  scripts/lifecycle-states.yml
MODIFIED  scripts/quick-setup.sh
MODIFIED  .github/workflows/sdd-spec.md
MODIFIED  .github/workflows/sdd-triage.md
MODIFIED  shared/sdd-gates.md
MODIFIED  shared/sdd-interaction.md
MODIFIED  docs/sdd/index.md
REGEN     .github/workflows/sdd-spec.lock.yml
REGEN     .github/workflows/sdd-triage.lock.yml

Note: editing shared/sdd-interaction.md and shared/sdd-gates.md produced no lock changes in this PR. Locks import shared/* via the pinned-ref @main form (ADR 0002/0004), so a shared-fragment edit propagates into the inlined locks only after merge, on the next compile. The two shared edits are committed alongside the source edits; this matches the established pattern (e.g. commit 772facf). The CI drift gate passes because CI's gh aw compile resolves the same @main import cache.

Verification

gh aw compile                    0 error(s), 0 warning(s); 4 locks changed
                                 (sdd-spec, sdd-triage, sdd-execute-opus,
                                 sdd-execute-sonnet); re-compile drift-stable
runtime-import in changed locks  none
"Check workflow lock file" step  pre-existing in all locks (gh-aw v0.74.3
                                 standard step), unchanged vs origin/main
markdownlint-cli2 "**/*.md"      0 errors (54 files)
actionlint (non-lock wrappers)   exit 0
shellcheck (*.sh)                exit 0
leak-scan.sh                     exit 0 (denylist.txt is a CI secret, absent
                                 locally; script exits 0 with no denylist)
test-lifecycle-state-machine.py  OK (8 states, 12 transitions);
                                 plan:provided recognized as a marker
test-safe-output-allowlists.py   OK
test-command-table.py            OK (7 commands)
mkdocs build --strict            exit 0
quick-setup --dry-run            exit 0; reports four templates (feature,
                                 bug, chore, spec) and the plan:provided label

Drive-by

Separate commit fix(sdd-execute-opus): correct variant list typo. The opus variant list read (sdd-execute-opus, sdd-execute-sonnet, sdd-execute-opus) — the first entry duplicated opus and omitted haiku. The sonnet variant had the same defect (sdd-execute-sonnet first). Both fixed to the canonical (sdd-execute-haiku, sdd-execute-sonnet, sdd-execute-opus); haiku was already correct. Regenerated sdd-execute-opus.lock.yml and sdd-execute-sonnet.lock.yml. Isolated from the feature commits.

References

• Closes sdd-spec: accept Claude plan documents via a 'Specification' issue template #102
• ADR 0001 (needs-human), ADR 0002 (imports), ADR 0004 (distribution), ADR 0012 (fast-path)

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added "Specification (from Claude plan)" issue template for users with existing Claude plans
  • Introduced a new plan:provided marker to enable translating pasted plans into spec/architecture content
  • Installer now includes the spec template when setting up the SDD suite

• Documentation

  • Updated workflows and guides to describe plan:provided translation modes, fast-path behavior, and label-clear rules
  • Clarified gate behavior for translated plan content (implementation-leakage and proof-artifact rules)

Walkthrough

Adds a plan:provided orthogonal marker, a new Specification (from Claude plan) issue template and label, sdd-spec translation steps (detection, R-ID mapping, proof-lift, fast-path plan-lift), sdd-triage architecture-translation Phase A behavior, conditional gate adjustments, docs/installer updates, and regenerated compiled workflow artifacts.

Changes

Plan-provided translation mode for spec and architecture

Layer / File(s)	Summary
Marker infrastructure and contract scripts/lifecycle-states.yml, shared/sdd-interaction.md	New plan:provided orthogonal marker declared in lifecycle states with documentation of survival/clearing semantics across workflow phases and conditions under which different agents remove it.
Issue template and label registration templates/.github/ISSUE_TEMPLATE/spec.md, templates/.github/labels.yml	New "Specification (from Claude plan)" template with default labels (sdd:spec, kind:feature, plan:provided); new plan:provided label registered in label inventory.
sdd-spec: plan detection and translation steps .github/workflows/sdd-spec.md, .github/workflows/sdd-spec.lock.yml	Step 3b detects plan:provided and adjusts fast-path proposal text; new step 5a translates plan steps into requirement IDs and lifts proof artifacts; fast-path plan-lift mode embeds plan directly in execution comment; marker cleared on fast-path exit, retained for sdd-triage on full-path.
sdd-triage Phase A: architecture translation mode .github/workflows/sdd-triage.md, .github/workflows/sdd-triage.lock.yml	Phase A now translates plan's architecture section into architecture.md when plan:provided is present, with fallback-to-author-from-scratch when plan section missing or thin; marker removed when architecture PR opens, with correct /revise re-run semantics.
Quality gate modifications for translation mode shared/sdd-gates.md, shared/sdd-interaction.md	"No implementation leakage" warning gate conditionally relaxes under plan:provided when leaked statements cite (translated from plan: step N); empty-PR proof-artifact blocker remains strict; interaction contract documents marker semantics.
User-facing documentation and installer updates docs/sdd/index.md, scripts/quick-setup.sh	Public documentation explains template usage and marker behavior; install_issue_templates() updated to include new spec template in SDD suite installation.
Workflow lock file regeneration .github/workflows/sdd-spec.lock.yml, .github/workflows/sdd-triage.lock.yml, .github/workflows/sdd-execute-*.lock.yml	Regenerated compiled workflows with updated prompt content, safe-output tool constraints (some remove_labels max increased and plan:provided added to allowed labels in relevant workflows), and refreshed auto-generated heredoc identifiers and MCP gateway configuration.

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• norrietaylor/spectacles#16: Introduced the core sdd-spec reusable workflow that this PR extends with plan-translation steps and fast-path plan-lift behavior.
• norrietaylor/spectacles#160: Overlaps on regenerated sdd-execute-* compiled workflow prompt artifacts and heredoc marker changes.
• norrietaylor/spectacles#101: Related fast-path stub-spec machinery that this PR extends with plan:provided plan-lift and marker-clearing logic.

"🐰
A plan arrives, neatly penned and bright,
Translated steps hop into spec's light.
Cite the source when a leak shows its face,
From Claude's blueprint we map each R-ID's place.
One marker guides phases till arch takes flight."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly summarizes the main change: accepting Claude plan documents via a plan:provided marker, which matches the primary objective of implementing issue #102.
Description check	✅ Passed	The PR description is comprehensive and directly related to the changeset, explaining the implementation of issue #102 with design decisions, file changes, verification steps, and references.
Linked Issues check	✅ Passed	The PR implements all objectives from issue #102: adds plan:provided marker and spec.md template [S1], implements conditional gate handling [S2], defines lifecycle ownership [S3], handles fast-path precedence [S4], and codifies R-ID derivation rules [S5].
Out of Scope Changes check	✅ Passed	All changes are within scope of implementing issue #102. The separate fix commit correcting execute-variant lists is properly isolated and documented as a drive-by fix, not affecting the main feature implementation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/102-plan-provided

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}