@jwilger/pi-development-system 0.83.0 → 0.85.0

package/README.md

@@ -19,8 +19,20 @@ Everything the system offers is reachable without remembering a command. Describ
 plain words: when a prompt asks for new work, a fix or a review, the system adds a guideline
 naming the tool to use (`devsys_intake`, `devsys_review_start`). A `devsys` tool always shows
 what the current phase expects. When you say a slice is finished with no review round recorded,
-it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`)
-are shortcuts to the same tools.
+it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
+`/devsys-lens-review`, `/devsys-adr`) are shortcuts to the same tools.
+
+Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
+terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
+writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
+a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
+
+A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
+(review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
+and red-first stays on throughout. A push of a clean tree closes a delivered slice by itself (a commit
+in `local-only` mode; CI is not awaited), and `devsys_finish_slice` closes it explicitly or, with a
+reason, abandons it. A plan's increments each end in a push, so each increment is its own slice: the
+next one starts with `devsys_intake`.
 
 With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely used tools are
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode

package/extensions/development-system.ts

@@ -27,9 +27,12 @@ import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
 import { createJudgeTools } from "../src/jev/judge-tools.ts";
+import { createAdrNewTool } from "../src/planning/adr-tool.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
+import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice-close.ts";
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
+import { createLensReviewTool } from "../src/review/lens-review-tool.ts";
 import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
@@ -156,6 +159,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     },
   });
   registerRedFirstGuard({ pi, state });
+  registerSliceClose({ pi, state, exec });
   registerLintSuppressionGuard({ pi, state });
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
@@ -174,6 +178,11 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   }
   pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
+  pi.registerTool(createAdrNewTool({ now: () => new Date() }));
+  pi.registerTool(createFinishSliceTool({ state, exec }));
+  pi.registerTool(
+    createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),
+  );
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
   const reviewDeps = {
     state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.83.0",
+  "version": "0.85.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-adr.md

@@ -0,0 +1,12 @@
+---
+description: Record a hard-to-reverse technical decision as the next numbered ADR
+argument-hint: "<decision title>"
+---
+Record an architecture decision with the product-planning skill.
+
+1. Call `devsys_adr_new` with the title: $ARGUMENTS. It creates `docs/adr/NNNN-<slug>.md` from the template and returns the path.
+2. Fill in Context (the forces and the problem), Decision (stated plainly), Consequences (positive and negative), Alternatives (each with why it was rejected) and Revisit when (a concrete condition), then link related ADRs and plan sections.
+3. Set the status to `accepted` only when the user has agreed; leave it `proposed` otherwise.
+4. Report the path and a one-line summary of the decision.
+
+Use an ADR for a boundary, dependency, data format or protocol that is hard to reverse. Product decisions belong in the decision register instead.

package/prompts/devsys-lens-review.md

@@ -0,0 +1,12 @@
+---
+description: Run the five product lenses over the brief and record the packets
+argument-hint: "[brief path] [round 1|2]"
+---
+Review the product brief with the product-planning skill.
+
+1. Call `devsys_lens_review` (brief path and round: $ARGUMENTS; omit either for `docs/product/brief.md` and round 1).
+2. Run the codemode script it returns, unchanged. It spawns the lens agents, waits, writes the packets to `docs/product/reviews/<date>-round<n>.md` and returns only a verdict per lens and the path. If codemode is unavailable, use the `agent_spawn` payloads it lists.
+3. Read the review file, not the agents' full output. Report each lens verdict and the findings with their `path:line`.
+4. After round 2, write the synthesis (R-table and a one-question agenda) from the template in the reply, then ask the user that one question.
+
+Agreement among agents is useful critique, not customer evidence.

package/prompts/devsys-plan.md

@@ -9,4 +9,4 @@ Write the plan for the current work with the work-intake-and-slicing skill.
 3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
 4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
 5. Stop and ask the user to review the plan before any implementation starts. Do not start a goal yet: a goal tool may continue on its own and begin implementing before the review.
-6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the plan is built; it does nothing if the work is already implementing). Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.

package/skills/product-planning/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: product-planning
+description: Plan a product or capability before building it - discovery interview, brief, decision register, follow-ups, terminology, journey inventory, lens review and ADRs. Use when sizing says capability or product, when asked for a brief or a discovery interview, when an answer must be recorded as a decision, or when a plan needs a product review.
+---
+
+# Product planning
+
+Planning here finds out what is worth building. It is not a spec for code. The artifacts are a small set of
+linked documents; each has one job and a template under `references/`.
+
+| Artifact | Job | Template |
+|---|---|---|
+| Brief | The one narrative: outcome, customers, four risks, assumptions, scope, non-goals | [brief](references/brief.md) |
+| Decision register | The spine: D (decisions), Q (questions), F (scheduling and exclusions) | [decisions](references/decisions.md) |
+| Follow-ups | P items and R review findings: not lost, not now | [followups](references/followups.md) |
+| Terminology | One meaning per word | [terminology](references/terminology.md) |
+| Journeys | J items: a user, actions, an outcome | [journeys](references/journeys.md) |
+
+Put them under `docs/product/` (`brief.md`, `decisions.md`, `followups.md`, `terminology.md`, `journeys.md`).
+Copy a template only when the work needs that artifact: `capability` work gets a short brief and journeys,
+`product` work gets the lot. Skipping one is a recorded departure (`artifact.skipped`).
+
+## The interview loop
+
+Quote this rule and follow it exactly:
+
+> Update docs after each answer, ask one next question, yield.
+
+1. Ask one question. Make it the most decision-relevant open Q item.
+2. Stop. Wait for the answer. Do not ask a second question or guess ahead.
+3. Record the answer as a D-item in the register, in the owner's words, and add a dated line to the interview log.
+4. Edit the brief **only where the answered question touches it**. Bump its version. Nothing else changes.
+5. Ask the next question and yield again.
+
+Every answer becomes a D-item, including "no" and "not now" (a Deferred item with a revisit point).
+
+## Do not over-edit the brief
+
+The commonest failure is an agent that rewrites the brief between answers. It misframed the team, moved the
+timing boundary, let later-phase ideas leak in and relocated the business case, and the owner had to find and
+undo each one. So:
+
+- An edit is limited to the answered question. If you notice something else that is wrong, add a Q item, do not fix it silently.
+- Ideas for later go to follow-ups. Nothing speculative goes in the brief.
+- Show the brief diff after each answer so the owner can see exactly what moved.
+- The owner owns judgements about the domain; you own process and where things are filed.
+
+## Outcome, risks, assumptions
+
+- Open with an **outcome** (direction plus target), not a feature. State the problem to solve, not the solution to build.
+- Assess the four risks (value, usability, feasibility, viability). "Unassessed" is a legal, recorded state.
+- Write assumptions specifically; the smaller the assumption, the smaller the test. Test the riskiest first
+  (critical to success, least evidence). Compare at least two solutions, and record why when you only had one.
+- Say whether the work builds to learn (disposable, fewer gates) or builds to earn (full gates). That is a decision, never an inference.
+
+## Deferral is not exclusion
+
+Postponing the details of a capability does not remove it from scope. Only an explicit scope decision does.
+A deferred item records who deferred it, why, the interim constraint and when to revisit. A non-goal is
+something we decided not to do.
+
+## Journeys
+
+Cut the backlog from journeys, not features. A journey passes if it tells the story of a user performing a
+set of actions to achieve an outcome. Decide journeys before generating tasks; feature-shaped backlogs had to
+be thrown away and redone.
+
+## Lens review
+
+Run `devsys_lens_review` (or `/devsys-lens-review`) on the brief when the outcome, scope or risks are settled
+enough to be wrong in an interesting way. Five fresh agents read it, each through one lens (Cagan, Torres,
+Pichler, Perri, Rumelt). Round one is independent; round two is a peer exchange; you then synthesise an R table
+and a one-question agenda, and the interview loop resumes. **Agreement among agents is useful critique, not
+customer evidence.** Record rejected recommendations in the register instead of dropping them.
+
+## Decisions that need an ADR
+
+A decision about how the code is built that is hard to reverse (a boundary, a dependency, a data format, a
+protocol) gets an ADR through `devsys_adr_new`. Product decisions stay in the register. Do not write an ADR
+for something the register already holds, or the other way round.
+
+## Status words
+
+Everything produced here is "proposed" or "advisory" until a person approves a specific revision. Say
+"readiness" for declared checks, "approval" for a person's decision on a named revision, and never let one
+stand in for the other.

package/skills/product-planning/references/brief.md

@@ -0,0 +1,48 @@
+# Brief: <product or change name>
+
+- **Context:** <which product or process this brief is about>
+- **Status:** v0.1 · <date> · links: [decisions](decisions.md), [follow-ups](followups.md)
+- **Not an authorisation:** this brief records what is understood so far. It does not approve building anything.
+
+## Outcome
+
+One sentence: the change in customer behaviour or business result we want, with a direction and a target
+(for example "first-session success from 22% to 25%"). An output ("ship X") is not an outcome.
+
+## Customers and the problem
+
+Who has the problem, what they do today, and the evidence for it (link the source, date it). Say plainly what
+is evidence and what is belief.
+
+## Four risks
+
+| Risk | What could be wrong | Evidence so far | Cheapest test |
+|---|---|---|---|
+| Value | Nobody wants or uses it | unassessed | |
+| Usability | People cannot work it out | unassessed | |
+| Feasibility | We cannot build it | unassessed | |
+| Viability | It does not work for the business | unassessed | |
+
+"Unassessed" is a legal state. Writing it is better than guessing.
+
+## Assumptions
+
+Each assumption is specific, tagged with a risk category and a test status. Riskiest first (critical to
+success, little evidence). Every assumption gets a D-item in the register once answered.
+
+| ID | Assumption | Category | Test status |
+|---|---|---|---|
+| A01 | | desirability / viability / feasibility / usability / ethical | untested |
+
+## Scope
+
+What the first release does, in the customer's words.
+
+## Non-goals
+
+Things we have decided not to do. Only an explicit scope decision belongs here.
+**Deferral is not exclusion:** an item that is merely later goes to [follow-ups](followups.md), not here.
+
+## Open questions
+
+Pointers only (Q-ids in [decisions](decisions.md)). The question text lives in the register, not the brief.

package/skills/product-planning/references/decisions.md

@@ -0,0 +1,33 @@
+# Decision register
+
+The referential spine: every brief, review and journey cites these ids.
+
+## Closure rules
+
+- **Resolved:** the owner answered or accepted it.
+- **Deferred:** postponed to a later phase. State who decided, why, the interim constraint and the revisit
+  point. Deferring the specification does not defer the capability; only an explicit scope decision does.
+- **Open:** not yet answered.
+- Superseding keeps the old row and points at the new one (`D06 → D56`). Rows are never deleted.
+
+## Decisions (D)
+
+| ID | Decision | Status | Source |
+|---|---|---|---|
+| D01 | | Resolved | <answer, date> |
+
+## Questions (Q)
+
+| ID | Question | Status | Needed for closure |
+|---|---|---|---|
+| Q01 | | Open | |
+
+## Scheduling, conditional scope and exclusions (F)
+
+| ID | Item | Disposition | Rationale | Revisit when |
+|---|---|---|---|---|
+| F01 | | true exclusion / conditional / scheduled | | |
+
+## Interview log
+
+One dated bullet per answer: the question, the answer in the owner's words, and "Recorded as D<nn>".

package/skills/product-planning/references/followups.md

@@ -0,0 +1,16 @@
+# Planning follow-ups
+
+Where "do not lose it, do not do it now" goes. **Scheduled planning work is not an MVP exclusion.**
+
+| ID | Question or work | Appropriate phase | Revisit when | Decision refs |
+|---|---|---|---|---|
+| P01 | | modelling / design / architecture / pilot / commercial | | D01 |
+
+## Review findings (R)
+
+Findings from a lens review and where each was routed (decision register, follow-up, interview question,
+rejected). A rejected recommendation is recorded with the reason, never silently dropped.
+
+| ID | Finding | Route | Disposition |
+|---|---|---|---|
+| R01 | | | |

package/skills/product-planning/references/journeys.md

@@ -0,0 +1,14 @@
+# Journey inventory
+
+A journey passes this test: **it tells the story of a user performing a set of actions to achieve an outcome.**
+A feature, a screen or a technical layer does not pass it. Do this before cutting any backlog.
+
+| ID | User and starting need | Actions | Outcome |
+|---|---|---|---|
+| J01 | | | |
+
+## Per journey
+
+- Alternative outcomes (what happens when it goes wrong).
+- The decision ids it rests on.
+- Approval is of a specific revision, recorded with person and date; drafting is not approval.

package/skills/product-planning/references/terminology.md

@@ -0,0 +1,10 @@
+# Terminology
+
+Words used in the brief, register and journeys, each with one meaning. Label a document with the sense of a
+word it uses when the word has more than one.
+
+| Term | Meaning | Not to be confused with |
+|---|---|---|
+| Deferred item | Scheduled to a later phase | Exclusion |
+| Readiness | Declared checks pass | Human approval of a specific revision |
+| Lens | An advisory reviewing perspective | A review by the person it is named for |

package/src/context/phase-guide.ts

@@ -10,11 +10,11 @@ export function phaseGuide(phase: Phase): string {
     case "planning":
       return "Planning. Produce the artifacts the sizing asked for, write task records (check each with devsys_task_check), and when the user approves the plan call devsys_begin_work.";
     case "implementing":
-      return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push small, verified increments.";
+      return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push when the slice is complete and reviewed: a push of a clean tree closes it (devsys_finish_slice closes it explicitly).";
     case "reviewing":
-      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding, and repeat until the round is clean.";
+      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
     case "delivering":
-      return "Delivering. Commit with a rationale, push to trunk, wait for CI to go green, and release before starting the next slice. A red trunk is repaired first.";
+      return "Delivering. The review is satisfied. Commit with a rationale, push, and release; a push of a clean tree closes the slice (devsys_finish_slice closes it explicitly, or abandons it with a reason). Editing source reopens implementing. A red trunk (CI) is repaired first.";
     default:
       return assertNever(phase);
   }

package/src/context/turn-verifier.ts

@@ -149,17 +149,23 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
   let evidence: ToolEvidence[] = [];
   let corrected = 0;
   let justCorrected = false;
+  let inFlightThisRun = false;
 
   deps.pi.on("session_start", () => {
     corrected = 0;
     justCorrected = false;
+    inFlightThisRun = false;
     evidence = [];
   });
   deps.pi.on("agent_start", () => {
+    // A push in this run may close the slice; its delivery report is still the claim to check.
+    inFlightThisRun = VERIFIED_PHASES.has(deps.state.get().phase);
     evidence = [];
     justCorrected = false;
   });
   deps.pi.on("tool_result", (event) => {
+    // The slice can start inside this run (intake, begin) and be closed by its own push; note it was open.
+    if (VERIFIED_PHASES.has(deps.state.get().phase)) inFlightThisRun = true;
     evidence = [...evidence, evidenceOf(event)].slice(-MAX_EVIDENCE);
   });
 
@@ -167,7 +173,7 @@ export function registerTurnVerifier(deps: TurnVerifierDeps): void {
     // An aborted or errored turn is dropped by pi; judging it would delay the abort and spend a correction.
     if (event.outcome !== "completed") return undefined;
     const state = deps.state.get();
-    if (!VERIFIED_PHASES.has(state.phase)) return undefined;
+    if (!(VERIFIED_PHASES.has(state.phase) || inFlightThisRun)) return undefined;
     const parts = assistantParts(event.message);
     if (parts === undefined || parts.callsTools || parts.text.trim() === "") return undefined;
     if (justCorrected) {

package/src/core/lifecycle.ts

@@ -0,0 +1,51 @@
+import type { ReviewAction } from "./review.ts";
+import type { DevsysState, SliceRef } from "./types.ts";
+
+/**
+ * How a slice moves through the phases once it is implementing. Pure: the tools and guards that observe the
+ * events (a review round, an edit, a push) call these and write the result to state.
+ *
+ *   implementing → reviewing   a review round starts or is recorded without being satisfied
+ *   reviewing    → delivering  the review is satisfied on the current diff
+ *   delivering   → reviewing   a later round finds something again
+ *   delivering   → implementing  production source is edited (the review no longer covers it)
+ *   any open     → idle        the slice is delivered or abandoned (`closeSlice`)
+ */
+
+const IN_FLIGHT = new Set<DevsysState["phase"]>(["implementing", "reviewing", "delivering"]);
+
+/** The state after a review round was started or recorded; `action` is `nextAction` for the diff as it is now. */
+export function afterReviewRound(
+  state: DevsysState,
+  action: ReviewAction,
+  slice: SliceRef | undefined = state.activeSlice,
+): DevsysState {
+  if (state.activeSlice === undefined || slice !== state.activeSlice) return state;
+  if (!IN_FLIGHT.has(state.phase)) return state;
+  return { ...state, phase: action === "done" ? "delivering" : "reviewing" };
+}
+
+/** Editing production source after review reopens the slice, so red-first applies to the edit again. */
+export const afterSourceEdit = (state: DevsysState): DevsysState =>
+  state.phase === "delivering" ? { ...state, phase: "implementing" } : state;
+
+/** Back to idle: the slice, its sizing and its slice-scoped departures are done. Review history is kept. */
+export function closeSlice(state: DevsysState): DevsysState {
+  const { activeSlice, sizing: _sizing, ...rest } = state;
+  return {
+    ...rest,
+    phase: "idle",
+    openDepartures: state.openDepartures.filter(
+      (d) => d.scope.kind !== "slice" || d.scope.slice !== activeSlice,
+    ),
+  };
+}
+
+/** A recorded `review.unsatisfied` departure covers this slice, so no review is owed before it ships. */
+export const reviewWaived = (state: DevsysState): boolean =>
+  state.openDepartures.some(
+    (d) =>
+      d.gate === "review.unsatisfied" &&
+      (d.scope.kind === "session" ||
+        (d.scope.kind === "slice" && d.scope.slice === state.activeSlice)),
+  );

package/src/gates/commit-guard.ts

@@ -17,6 +17,7 @@ import { resolveGit } from "../core/git-invocations.ts";
 import { DECISION_LOG, reviewGap } from "../core/review-flow.ts";
 import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
+import { ARCHITECTURE_THRESHOLD, judgeArchitectureShaping } from "../jev/questions/architecture.ts";
 import { judgeCommit, MIX_THRESHOLD, RATIONALE_FLOOR } from "../jev/questions/commit.ts";
 import { snapshotDiff } from "../review/digest.ts";
 import type { SessionState } from "../state/session-state.ts";
@@ -40,6 +41,13 @@ const gateId = (id: string): GateId => {
 const RATIONALE = gateId("commit.rationale");
 const MIXED = gateId("commit.mixed-change");
 const REVIEW = gateId("review.unsatisfied");
+const ADR_MISSING = gateId("adr.missing");
+
+/** A new `docs/adr/NNNN-*.md` among the pending changes; editing an older ADR is not recording a new decision. */
+const addsAdr = (diff: string): boolean =>
+  /^diff --git a\/docs\/adr\/\d{4}-\S+\.md b\/\S+\n(?:new file mode|rename from |similarity index)/m.test(
+    diff,
+  );
 
 const readMessageFile = (cwd: string, path: string): string | undefined => {
   try {
@@ -72,25 +80,85 @@ const stagesEverything = (command: string): boolean =>
     command,
   );
 
+/**
+ * The pathspecs a `git add` in the command stages new files under: `.` for `-A` with no path, else the named
+ * paths. Empty when nothing in the command can add an untracked file (`-u` stages only tracked files, `-n` nothing).
+ */
+const addedPathspecs = (command: string): string[] =>
+  [...command.matchAll(/\bgit\s+add\b([^;&|\n]*)/g)].flatMap((m) => {
+    const words = (m[1] ?? "")
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((w) => w.replace(/^(["'])(.*)\1$/, "$2")); // `git add "docs/adr/0005-x.md"` names the same file
+    if (words.some((w) => ["-u", "--update", "-n", "--dry-run"].includes(w))) return [];
+    const paths = words.filter((w) => !w.startsWith("-"));
+    if (paths.length === 0) return words.some((w) => w === "-A" || w === "--all") ? ["."] : [];
+    return paths.map((p) => p.replace(/^\.\//, "").replace(/\/$/, "") || ".");
+  });
+
+type PendingDiff = { stat: string; diff: string; untrackedAdr: boolean };
+
 /** What is about to be committed: the staged changes, or every tracked change when the commit stages them itself. */
 async function pendingDiff(
   exec: Exec,
   cwd: string,
   command: string,
-): Promise<{ stat: string; diff: string } | undefined> {
+): Promise<PendingDiff | undefined> {
   try {
-    const base = stagesEverything(command) ? ["diff", "HEAD"] : ["diff", "--cached"];
-    const [stat, diff] = await Promise.all([
+    const widened = stagesEverything(command);
+    const specs = addedPathspecs(command);
+    // Fixed prefixes and no external driver: `addsAdr` reads the headers, and git config can change them.
+    const fixed = ["--no-ext-diff", "--no-color", "--src-prefix=a/", "--dst-prefix=b/"];
+    const base = widened ? ["diff", ...fixed, "HEAD"] : ["diff", ...fixed, "--cached"];
+    const [stat, diff, untracked] = await Promise.all([
       exec("git", [...base, "--stat"], { cwd, timeout: 10_000 }),
       exec("git", base, { cwd, timeout: 10_000 }),
+      // `git diff HEAD` leaves out files git does not track yet, such as a new module or an ADR just created.
+      specs.length > 0
+        ? exec("git", ["ls-files", "--others", "--exclude-standard", "--", ...new Set(specs)], {
+            cwd,
+            timeout: 10_000,
+          })
+        : Promise.resolve(undefined),
     ]);
-    if (stat.code !== 0 || diff.code !== 0 || diff.stdout.trim() === "") return undefined;
-    return { stat: stat.stdout, diff: diff.stdout };
+    if (stat.code !== 0 || diff.code !== 0) return undefined;
+    const added = untracked?.code === 0 ? untracked.stdout.trim() : "";
+    if (diff.stdout.trim() === "" && added === "") return undefined;
+    return {
+      stat:
+        added === ""
+          ? stat.stdout
+          : // First, because Jev clips the stat: a long list of tracked files must not push new files out of view.
+            `New files this commit adds (untracked):\n${added}\n\n${stat.stdout}`,
+      diff: diff.stdout,
+      untrackedAdr: /^docs\/adr\/\d{4}-\S+\.md$/m.test(added),
+    };
   } catch {
     return undefined;
   }
 }
 
+/** Non-negotiable 9 as a soft gate: the judgement is probabilistic, so a departure can answer it. */
+async function adrNeeds(
+  deps: CommitGuardDeps,
+  ctx: ExtensionContext,
+  pending: PendingDiff,
+): Promise<Need[]> {
+  if (addsAdr(pending.diff) || pending.untrackedAdr) return [];
+  const judged = await judgeArchitectureShaping(deps.jev(ctx), {
+    diffStat: pending.stat,
+    diff: pending.diff,
+  });
+  if (!judged.ok || judged.value < ARCHITECTURE_THRESHOLD) return [];
+  return [
+    {
+      gate: ADR_MISSING,
+      why: "Jev reads this diff as an architecture-shaping decision (a boundary, dependency, data format or protocol) and it adds no ADR",
+    },
+  ];
+}
+
 async function jevNeeds(
   deps: CommitGuardDeps,
   ctx: ExtensionContext,
@@ -100,13 +168,13 @@ async function jevNeeds(
 ): Promise<Need[]> {
   const pending = await pendingDiff(deps.exec, ctx.cwd, command);
   if (pending === undefined) return [];
-  const judged = await judgeCommit(deps.jev(ctx), {
-    message,
-    diffStat: pending.stat,
-    diff: pending.diff,
-  });
-  if (!judged.ok) return [];
-  const needs: Need[] = [];
+  // Both ask Jev; run them together so a hung provider costs one timeout, not two.
+  const [judged, adr] = await Promise.all([
+    judgeCommit(deps.jev(ctx), { message, diffStat: pending.stat, diff: pending.diff }),
+    adrNeeds(deps, ctx, pending),
+  ]);
+  const needs: Need[] = adr;
+  if (!judged.ok) return needs;
   if (bodyPresent && judged.value.rationale < RATIONALE_FLOOR) {
     needs.push({ gate: RATIONALE, why: "Jev reads the body as restating what changed, not why" });
   }
@@ -126,7 +194,8 @@ async function reviewNeeds(
   command: string,
 ): Promise<Need[]> {
   const { phase, activeSlice } = deps.state.get();
-  if ((phase !== "implementing" && phase !== "reviewing") || activeSlice === undefined) return [];
+  const inFlight = phase === "implementing" || phase === "reviewing" || phase === "delivering";
+  if (!inFlight || activeSlice === undefined) return [];
   const snap = await snapshotDiff(deps.exec, ctx.cwd, "HEAD");
   // An unreadable diff cannot be compared; the gate asks for a departure rather than guessing.
   const gap = reviewGap(
@@ -247,13 +316,22 @@ const reviewReason = (need: Need): string =>
   "and repeat until the review is satisfied. If skipping review is deliberate call devsys_record_departure " +
   `with gate "${need.gate}", what you are doing instead, why, and the cost if wrong; then retry.`;
 
-const blockReason = (need: Need): string =>
-  need.gate === REVIEW
-    ? reviewReason(need)
-    : `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
-      "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
-      `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
-      "instead, why, and the cost if wrong; then retry.";
+const adrReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Hard-to-reverse decisions are recorded as an ADR in the same change. ` +
+  "Call devsys_adr_new with the decision's title, fill in the ADR and stage it. If this diff is not " +
+  `architecture-shaping, call devsys_record_departure with gate "${need.gate}", what you are doing instead, ` +
+  "why, and the cost if wrong; then retry.";
+
+const commitReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
+  "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
+  `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
+  "instead, why, and the cost if wrong; then retry.";
+
+function blockReason(need: Need): string {
+  if (need.gate === REVIEW) return reviewReason(need);
+  return need.gate === ADR_MISSING ? adrReason(need) : commitReason(need);
+}
 
 const forbiddenReason = (found: readonly string[]): string =>
   `commit.forbidden-trailer: this commit carries an AI attribution (${found.join("; ")}). ` +

package/src/gates/red-first-guard.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { afterSourceEdit } from "../core/lifecycle.ts";
 import { classifyPath } from "../core/path-class.ts";
 import { normalizeRepoPath } from "../core/test-paths.ts";
 import type { SessionState } from "../state/session-state.ts";
@@ -57,7 +58,7 @@ const JUDGED_EXEMPTIONS =
   "straightforward CI scripting, a simple dev-environment utility, or a behaviour-preserving refactor with green coverage";
 
 /**
- * Soft gate `tdd.red-first`: while implementing, production source is edited only after a failing
+ * Soft gate `tdd.red-first`: while a slice is in flight (implementing, reviewing, delivering), production source is edited only after a failing
  * test run has been observed. Test, docs, config and generated files are exempt by path; the
  * judged exemptions go through one recorded departure, which covers its whole slice.
  */
@@ -69,11 +70,13 @@ export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
   deps.pi.on("tool_call", (event, ctx) => {
     if (!(isToolCallEventType("edit", event) || isToolCallEventType("write", event)))
       return undefined;
-    const { phase, lastTestRun, activeSlice } = deps.state.get();
-    if (phase !== "implementing") return undefined;
-    if (lastTestRun !== undefined && lastTestRun.exitCode !== 0) return undefined;
+    const { phase, activeSlice } = deps.state.get();
+    if (phase !== "implementing" && phase !== "reviewing" && phase !== "delivering")
+      return undefined;
     const path = normalizeRepoPath(ctx.cwd, event.input.path, homedir());
     if (classifyPath(path) !== "source") return undefined;
+    const { lastTestRun } = deps.state.get();
+    if (lastTestRun !== undefined && lastTestRun.exitCode !== 0) return undefined;
     if (touchesInlineTest(event.input, () => existing(ctx.cwd, path))) return undefined;
     if (departure.covers()) return undefined;
     const seen =
@@ -90,4 +93,17 @@ export function registerRedFirstGuard(deps: RedFirstGuardDeps): void {
         `departure covers the rest of the ${scope}.`,
     };
   });
+
+  // The review covered the code as it was: source that was really written puts the slice back to implementing.
+  deps.pi.on("tool_result", (event, ctx) => {
+    if (event.isError || (event.toolName !== "edit" && event.toolName !== "write"))
+      return undefined;
+    if (deps.state.get().phase !== "delivering") return undefined;
+    const given = (event.input as { path?: unknown }).path;
+    if (typeof given !== "string") return undefined;
+    if (classifyPath(normalizeRepoPath(ctx.cwd, given, homedir())) === "source") {
+      deps.state.update(afterSourceEdit);
+    }
+    return undefined;
+  });
 }