sdd: never commit the plan workspace to the project repo

skills/subagent-driven-development/SKILL.md

@@ -133,6 +133,15 @@ a ledger file, not only in todos.
   plan's progress: leave it in place and start your own, fresh.
 - Create the ledger with its identity as the first line:
   `# SDD ledger — plan: <plan file path>`.
+- During that same Setup read, copy the plan's Global Constraints section
+  verbatim into `<workspace>/constraints.md`. Every dispatch's binding
+  constraint values paste from that file — the plan itself stays closed
+  after Setup, even across compaction.
+- The workspace is never committed to the project repo. Do not `git add`
+  anything under it, and never write a commit whose purpose is to record,
+  correct, or tidy a workspace artifact — reports and ledgers are session
+  records, not deliverables. If the repo lacks a `.gitignore` entry for
+  `.superpowers/`, leave the directory untracked rather than committing it.
 - The ledger is your recovery map: the commits it names exist in git even
   when your context no longer remembers creating them. After compaction,
   trust the ledger and `git log` over your own recollection.
@@ -140,7 +149,11 @@ a ledger file, not only in todos.
   that happens, recover from `git log`.
 
 Read the plan once, note its context and Global Constraints, and create a
-todo per task.
+todo per task. That is the plan's one full read for the whole session:
+after Setup, the ledger and `scripts/task-brief` extracts are your working
+memory — re-reading the plan or spec late in the run (to "double-check"
+completion, to rebuild the final-review dispatch) re-buys context you
+already paid for and is forbidden.
 
 Before dispatching Task 1, scan the plan once for conflicts:
 
@@ -195,7 +208,10 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
 
 Everything you paste into a dispatch prompt — and everything a subagent
 prints back — stays resident in your context for the rest of the session
-and is re-read on every later turn. Hand artifacts over as files.
+and is re-read on every later turn. Hand artifacts over as files. The same
+tax applies to your own words: checkpoint in one short line, keep
+bookkeeping in the ledger file, and never paste back into the conversation
+what a file already holds.
 
 ### 1. Dispatch the implementer
 
@@ -211,9 +227,15 @@ and fix-round diffs need it.
   first — it is your requirements, with the exact values to use verbatim";
   (3) interfaces and decisions from earlier tasks that the brief cannot
   know; (4) your resolution of any ambiguity you noticed in the brief;
-  (5) the report-file path and report contract. Exact values (numbers,
+  (5) the report-file path and report contract; (6) the plan's binding
-  magic strings, signatures, test cases) appear only in the brief. Never
+  constraint values — any Global Constraint that mandates an exact
-  make a subagent read the whole plan file.
+  mechanical form (commit-message rules, naming rules, fixed literals) —
+  pasted verbatim. Task-specific exact values (numbers, magic strings,
+  signatures, test cases) appear only in the brief; binding constraint
+  values are the one exception — they ride in EVERY dispatch, because a
+  subagent that must recall a constraint from memory will reconstruct it
+  from its own priors instead. Never make a subagent read the whole plan
+  file.
 - **Report file:** name the implementer's report file after the brief
   (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
   the dispatch prompt. The implementer writes the full report there and
@@ -273,6 +295,10 @@ needed.
 - **Reviewer inputs:** the task reviewer gets three paths — the same brief
   file, the report file, and the review package — plus the global
   constraints that bind the task.
+- **Persist the verdict:** when the review returns, write its full text to
+  `<workspace>/task-<N>-review.md` before acting on it. The file is the
+  gate: completion checks for the artifact, not for your memory of a
+  verdict.
 - The global-constraints block you hand the reviewer is its attention
   lens. Copy the binding requirements verbatim from the plan's Global
   Constraints section or the spec: exact values, exact formats, and the
@@ -323,22 +349,26 @@ scoped re-review. Five rounds maximum per task:
 verbatim. Its context is intact: it knows the task, the code, and its own
 choices. If your harness cannot send another message to a live subagent,
 dispatch a fresh implementer carrying the brief path, the report-file path,
-and the findings — the report file is the persistent memory either way.
+the findings, and the binding constraint values verbatim — the report file
+is the persistent memory either way.
 
 **Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
 Model Selection), with the brief path, the report-file path, the open
-findings, and this framing: "A prior implementer attempted this task
+findings, the binding constraint values verbatim, and this framing: "A
-[N] times; you own it now. Read the report file for what was tried." A loop
+prior implementer attempted this task [N] times; you own it now. Read the
-that survives three resumes usually means the implementer cannot see its
+report file for what was tried." A loop that survives three resumes usually
-own problem — fresh eyes and a capability bump in one move.
+means the implementer cannot see its own problem — fresh eyes and a
+capability bump in one move.
 
 **Every round, either way:** the implementer fixes, re-runs the tests
 covering the amended code, appends its fix report to the same report file,
 and returns the short contract. Before re-dispatching the reviewer, confirm
-the fix report contains the covering tests, the command run, and the
+the fix report contains the covering tests, the command run, and the output;
-output; dispatch the re-review once all three are present. Name the
+dispatch the re-review once all three are present. Name the covering test
-covering test files in the fix message — a one-line fix does not need the
+files in the fix message — a one-line fix does not need the whole suite.
-whole suite.
+Append the re-review's returned text to `<workspace>/task-<N>-review.md` as
+well — the artifact accumulates every verdict, and the file's last entry is
+the one completion relies on.
 
 **The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD`
 where FIX_BASE is the head the previous review saw, and dispatch
@@ -383,10 +413,20 @@ message as your other bookkeeping:
 - `Task <N>: complete (commits <base7>..<head7>, review clean)`
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
   tripped breaker
+- `Task <N>: complete (commits <base7>..<head7>, deviation parked: <rule>)`
+  when a landed commit violates a mechanical constraint that nothing
+  downstream builds on. Record the ruling in the ledger. A green build with
+  a parked, recorded deviation is complete — do not fail the task, and do
+  not rewrite landed history to chase cosmetics. A load-bearing violation
+  is different: that is a BLOCKED, not a deviation. This valve is not the
+  breaker: it needs no exhausted fix rounds — a mechanical deviation
+  discovered at completion parks here directly, with its ruling in the ledger.
 
-Then mark the todo complete and move on. Never move to the next task while
+Then mark the todo complete and move on — but only once
-the review has open Critical/Important issues that are neither fixed nor
+`<workspace>/task-<N>-review.md` exists; a completion line without its review
-parked-with-ruling at the cap.
+artifact is invalid, whatever you remember about the review. Never move to
+the next task while the review has open Critical/Important issues that are
+neither fixed nor parked-with-ruling at the cap.
 
 ## Final Review
 
@@ -399,17 +439,25 @@ on the most capable available model (see Model Selection), using
 superpowers:requesting-code-review's
 [code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
 the ledger's deferred-minor and parked lines so it can triage which must be
-fixed before merge.
+fixed before merge. Build that dispatch from the ledger alone — the
+completion lines, parked rulings, and deferred minors are the whole-run
+summary; do not re-read the plan, the spec, or per-task reports to
+reconstruct what the ledger already states. Write the returned review to
+`<workspace>/final-review.md` before dispatching any fix wave — the merge
+decision cites the artifact, not a recollection.
 
 If the final whole-branch review returns findings, dispatch ONE fix subagent
-with the complete findings list — not one fixer per finding.
+with the complete findings list and the binding constraint values
+verbatim — not one fixer per finding.
 Per-finding fixers each rebuild context and re-run suites; a real
 session's final-review fix wave cost more than all its tasks combined.
 Then run exactly one scoped re-review of the fix wave
 (`scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
 [re-review-prompt.md](re-review-prompt.md)).
 Adjudicate any residual findings as in the task loop's breaker: park with
-rulings, or stop on load-bearing ones. There is no second fix wave —
+rulings, or stop on load-bearing ones. The same valve applies to
+mechanical-constraint misses discovered at the end: non-load-bearing means
+parked with a ruling, not a failed branch. There is no second fix wave —
 residual load-bearing findings surface to your human partner when
 finishing-a-development-branch presents the options.
 

skills/subagent-driven-development/implementer-prompt.md

@@ -15,6 +15,12 @@ Subagent (general-purpose):
     Read your task brief first: [BRIEF_FILE]
     It contains the full task text from the plan.
 
+    ## Binding Constraint Values
+
+    [CONSTRAINT_VALUES — the plan's mechanical constraints, pasted verbatim
+    by the dispatcher. If a rule here mandates an exact form (commit-message
+    text, naming, fixed literals), reproduce it exactly — never from memory.]
+
     ## Context
 
     [Scene-setting: where this fits, dependencies, architectural context]
@@ -36,8 +42,12 @@ Subagent (general-purpose):
     2. Write tests (following TDD if task says to)
     3. Verify implementation works
     4. Commit your work
-    5. Self-review (see below)
+    5. Immediately after each commit, verify it against the Binding Constraint
-    6. Report back
+       Values above (commit-message rules, naming rules, fixed literals) while
+       history is still local. A miss is cheap now — amend or forward-fix at
+       once — and expensive after your work is delivered.
+    6. Self-review (see below)
+    7. Report back
 
     Work from: [directory]
 
@@ -96,6 +106,10 @@ Subagent (general-purpose):
     - Did I only build what was requested?
     - Did I follow existing patterns in the codebase?
 
+    **Constraints:**
+    - Does every commit message satisfy the Binding Constraint Values exactly?
+    - Did I reproduce mandated literals from the constraint text, not from memory?
+
     **Testing:**
     - Do tests actually verify behavior (not just mock behavior)?
     - Did I follow TDD if required?
@@ -104,6 +118,12 @@ Subagent (general-purpose):
 
     If you find issues during self-review, fix them now before reporting.
 
+    If a constraint violation is already in a landed commit you cannot safely
+    amend, forward-fix it in a new commit when possible; when it is not, report
+    the deviation explicitly with Status DONE_WITH_CONCERNS — never report the
+    task incomplete solely for a cosmetic miss on an otherwise green build.
+    Whether the deviation parks or blocks is the dispatching controller's call.
+
     ## After Review Findings
 
     If the task review finds issues, you will be resumed with the findings.
@@ -136,7 +156,8 @@ Subagent (general-purpose):
     If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
     itself — the controller acts on it directly.
 
-    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
+    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness, or
+    when you are reporting a known deviation you could not safely fix.
     Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
     information that wasn't provided. Never silently produce work you're unsure about.
 ```

skills/writing-plans/SKILL.md

@@ -71,7 +71,11 @@ independently testable deliverable.
 [The spec's project-wide requirements — version floors, dependency limits,
 naming and copy rules, platform requirements — one line each, with exact
 values copied verbatim from the spec. Every task's requirements implicitly
-include this section.]
+include this section. Three things may never enter it: cosmetic absolutes
+on every commit (a fixed trailer or byline the work does not need), your
+own identity or model name promoted into a rule, and environment
+constraints (versions, platforms, paths) you have not verified against the
+environment the plan will execute in.]
 
 ---
 ```
@@ -125,6 +129,8 @@ git commit -m "feat: add specific feature"
 ```
 ````
 
+Commit messages describe the change. Never mandate session boilerplate — trailers, bylines, model names — as a per-commit rule; what your session stamps on its commits is not a requirement of the work.
+
 ## No Placeholders
 
 Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
@@ -145,6 +151,8 @@ After writing the complete plan, look at the spec with fresh eyes and check the
 
 **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
 
+**4. Constraint hygiene:** Does any Global Constraint mandate a per-commit cosmetic absolute, name the authoring model or session, or assert an environment fact (version floor, platform, path) you did not verify? Cut or verify it.
+
 If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
 
 ## Execution Handoff