ai-fob 1.7.0 → 1.7.1

package/assets/pi/extensions/task-state/reconcile.ts

@@ -27,14 +27,47 @@ export type ReconcileAction = {
   reason: string;
 };
 
+/**
+ * Per-step resume verdict — contract with
+ * `references/resume-reconciliation-table.md` §1/§2/§4/§5. The recipe
+ * (`prompts/build-phase-pi.md`) gates STATE.md mutation on the
+ * `requires_confirmation` / `reset` cases.
+ */
+export type StepVerdict =
+  | "valid"
+  | "valid_lenient"
+  | "stale"
+  | "missing"
+  | "reset"
+  | "requires_confirmation";
+
+export type StepReconcile = {
+  n: number; // 0..6
+  marker: "[ ]" | "[~]" | "[x]";
+  artifact: string; // canonical artifact path the matrix names
+  verdict: StepVerdict;
+  reason?: string; // human-readable; surfaced in renderResult + recipe confirmation prompt
+};
+
 export type ReconcileResult = {
   scan: ArtifactScan;
-  entryStep: number; // 0..6
+  entryStep: number; // 0..6 — preserved for legacy consumers (mirrors details.resumeAt)
   actions: ReconcileAction[];
   specialCases: string[];
   table: string; // expanded cross-reference table (markdown)
+  // Additive: per-step verdict array and deterministic resume-step integer.
+  steps: StepReconcile[];
+  resumeAt: number; // 0..6 — first step whose verdict is NOT in {valid, valid_lenient}
 };
 
+// Internal classification — separates on-disk absence from content-check
+// failure so decideVerdict() can map (marker, classification) ⇒ StepVerdict.
+type ArtifactClassification =
+  | { kind: "valid" }
+  | { kind: "valid_lenient"; reason: string }
+  | { kind: "stale"; reason: string }
+  | { kind: "missing"; reason: string };
+
 // Canonical 4-value Step 5 result vocabulary — see
 // .pi/skills/phase-build-workflow/references/result-vocabulary.md. Mirrors
 // state-md.ts's STEP5_COMPLETE_RESULTS exactly (Coordination Note 6 of the
@@ -229,13 +262,28 @@ export async function reconcile(
   const scan = await scanArtifacts(cwd, task, phase, onProgress);
   const stateMarkers = readStepMarkers(stateText, task, phase);
   const actions: ReconcileAction[] = [];
+  const steps: StepReconcile[] = [];
 
   // Walk steps 0..6 deciding per matrix in resume-reconciliation-table.md §2.
   for (let step = 0; step <= 6; step++) {
     const marker = stateMarkers[step] ?? " ";
     const artifact = primaryArtifactStatus(scan, step);
-    const verdict = decide(marker, artifact);
-    actions.push({ step, action: verdict.action, reason: verdict.reason });
+    const decision = decide(marker, artifact);
+    actions.push({ step, action: decision.action, reason: decision.reason });
+
+    // Per-step verdict (additive, recipe-facing). Classification keeps the
+    // file-on-disk check (missing) separate from the content-check-miss case
+    // (valid_lenient / stale), so the recipe can gate STATE.md mutation on
+    // requires_confirmation/reset without blindly cascading a reset.
+    const classification = classifyStep(scan, step);
+    const verdict = decideVerdict(marker, classification);
+    steps.push({
+      n: step,
+      marker: `[${marker}]` as "[ ]" | "[~]" | "[x]",
+      artifact: primaryArtifactName(step),
+      verdict: verdict.verdict,
+      reason: verdict.reason,
+    });
   }
 
   // Special cases §3.1–3.4 — fold into actions/specialCases list.
@@ -264,14 +312,27 @@ export async function reconcile(
     specialCases.push("Interrupted Step 4 (§3.3): post-build-sha pending.");
   }
 
-  // Entry step — first step whose final action is "run" or "reset".
-  let entryStep = 6;
-  for (const a of actions) {
-    if (a.action === "run" || a.action === "reset") {
-      entryStep = a.step;
+  // resumeAt — first step whose verdict is NOT in {valid, valid_lenient}.
+  // If every step is valid/valid_lenient, resumeAt = lastCompletedStep + 1
+  // (preserves the "everything is fine, advance" semantic). entryStep mirrors
+  // resumeAt so legacy consumers (index.ts renderer, recipe fallback) keep
+  // reading the same integer.
+  let resumeAt = -1;
+  for (const s of steps) {
+    if (s.verdict !== "valid" && s.verdict !== "valid_lenient") {
+      resumeAt = s.n;
       break;
     }
   }
+  if (resumeAt < 0) {
+    // All steps valid/valid_lenient — find the last [x] and advance.
+    let lastCompleted = -1;
+    for (const s of steps) {
+      if (s.marker === "[x]") lastCompleted = s.n;
+    }
+    resumeAt = Math.min(6, lastCompleted + 1);
+  }
+  const entryStep = resumeAt;
 
   const tableHead =
     "| step | marker | artifact | action | reason |\n| ---- | ------ | -------- | ------ | ------ |";
@@ -289,6 +350,8 @@ export async function reconcile(
     actions,
     specialCases,
     table: `${tableHead}\n${tableRows}`,
+    steps,
+    resumeAt,
   };
 }
 
@@ -309,8 +372,17 @@ function primaryArtifactStatus(scan: ArtifactScan, step: number): ArtifactStatus
     if (stepEntries.some((e) => e.status === "invalid")) return "invalid";
     return "missing";
   }
+  // Step 1 has two canonical entries (`explorer_findings.md` required +
+  // `docs_research.md` optional companion). Mirror Step 4's OR-pattern so a
+  // present-on-disk explorer artifact reports Step 1 as "present" even if the
+  // optional docs companion is absent (kanban-core regression facet).
+  if (step === 1) {
+    const stepEntries = scan.entries.filter((e) => e.step === 1);
+    if (stepEntries.some((e) => e.status === "present")) return "present";
+    if (stepEntries.some((e) => e.status === "invalid")) return "invalid";
+    return "missing";
+  }
   const PRIMARY: Record<number, string> = {
-    1: "explorer_findings.md",
     2: "plan_V1.md",
     3: "plan_validation_report.md",
     5: "build_validation_report.md",
@@ -320,6 +392,82 @@ function primaryArtifactStatus(scan: ArtifactScan, step: number): ArtifactStatus
   return e?.status ?? "missing";
 }
 
+/** Canonical artifact name surfaced in details.steps[].artifact. */
+function primaryArtifactName(step: number): string {
+  if (step === 0) return "(none — Step 0 has no artifact)";
+  const NAMES: Record<number, string> = {
+    1: "explorer_findings.md",
+    2: "plan_V1.md",
+    3: "plan_validation_report.md",
+    4: "build_report.md",
+    5: "build_validation_report.md",
+    6: "phase_completion_report.md",
+  };
+  return NAMES[step] ?? "";
+}
+
+// Map ArtifactStatus → ArtifactClassification. Bug-fix behaviour: a
+// present-on-disk artifact that failed a content check is `valid_lenient`
+// (non-fatal); escalated to `stale` only on STRUCTURAL frontmatter mismatch.
+function classifyStep(scan: ArtifactScan, step: number): ArtifactClassification {
+  if (step === 0) return { kind: "valid" };
+  const status = primaryArtifactStatus(scan, step);
+  if (status === "present") return { kind: "valid" };
+  // Find a representative entry to source the reason string and decide
+  // lenient vs stale.
+  const stepEntries = scan.entries.filter((e) => e.step === step);
+  if (status === "missing") {
+    const reason =
+      stepEntries.find((e) => e.status === "missing")?.reason ??
+      `${primaryArtifactName(step)} not present on disk`;
+    return { kind: "missing", reason };
+  }
+  // status === "invalid" — file exists, content check missed.
+  const invalidEntry = stepEntries.find((e) => e.status === "invalid");
+  const reason = invalidEntry?.reason ?? "content check failed";
+  // Heuristic: structural frontmatter mismatches escalate to `stale`
+  // (requires_confirmation); coarse line-count or schema-version drift is
+  // `valid_lenient` (non-fatal, no reset).
+  const structural =
+    /unparseable frontmatter|missing frontmatter|missing checks-passed|not in pass/.test(reason);
+  if (structural) return { kind: "stale", reason };
+  return { kind: "valid_lenient", reason };
+}
+
+// Cross-reference matrix from references/resume-reconciliation-table.md §2.
+// Validity is DATA — never throws.
+function decideVerdict(
+  marker: " " | "~" | "x",
+  status: ArtifactClassification,
+): { verdict: StepVerdict; reason?: string } {
+  if (marker === "x") {
+    // [x] + valid                ⇒ valid (skip)
+    // [x] + valid_lenient        ⇒ valid_lenient (continue past; no reset)
+    // [x] + stale                ⇒ requires_confirmation (gated reset)
+    // [x] + missing              ⇒ requires_confirmation (gated reset)
+    if (status.kind === "valid") return { verdict: "valid" };
+    if (status.kind === "valid_lenient")
+      return { verdict: "valid_lenient", reason: status.reason };
+    return { verdict: "requires_confirmation", reason: status.reason };
+  }
+  if (marker === "~") {
+    // [~] markers are always re-runnable; classify as `reset` so the recipe
+    // can re-run without prompting for in-progress crashes.
+    if (status.kind === "valid")
+      return { verdict: "reset", reason: "crash before STATE.md updated; re-run" };
+    return { verdict: "reset", reason: status.reason ?? "mid-execution interrupt" };
+  }
+  // marker === " ": untouched semantic — this row is not the bug. If the
+  // artifact exists, mark valid (recipe promotes via existing actions[]);
+  // otherwise this is the resume entry point.
+  if (status.kind === "valid") return { verdict: "valid" };
+  if (status.kind === "valid_lenient")
+    return { verdict: "valid_lenient", reason: status.reason };
+  if (status.kind === "stale")
+    return { verdict: "stale", reason: status.reason };
+  return { verdict: "missing", reason: status.reason };
+}
+
 function decide(
   marker: " " | "~" | "x",
   status: ArtifactStatus,

package/assets/pi/prompts/build-phase-pi.md

@@ -42,11 +42,25 @@ Call the `state` tool three times with arguments shaped like:
 { "operation": "reconcile", "task": "<slug>", "phase": $2 }
 ```
 
-After `reconcile` returns, read `details.reconcile.entryStep` (0..6) as the
-starting step. If `entryStep > 0`, present `details.reconcile.table` to the
-user as a banner (echo $@ for context) and resume at `entryStep`. Do NOT
-re-execute any step `< entryStep`. The reconciler is the single source of
-truth for resume.
+After `reconcile` returns, branch on `details.reconcile` as follows:
+
+- Read `details.reconcile.resumeAt` (preferred) or `details.reconcile.entryStep`
+  (legacy fallback) as the starting step. Both fields are integers 0..6 and
+  (when both present) MUST agree.
+- Inspect `details.reconcile.steps[]`. If ANY entry has
+  `verdict ∈ {requires_confirmation, reset}`, STOP and present the per-step
+  verdict table (step number, marker, artifact, verdict, reason) verbatim to
+  the user, plus `details.reconcile.table` for context (echo $@ as a banner).
+  For each `requires_confirmation` entry, ask the user to confirm or skip the
+  proposed reset. ONLY AFTER explicit confirmation may you mutate STATE.md.
+- If all verdicts ∈ `{valid, valid_lenient}`, present `details.reconcile.table`
+  as a banner (echo $@) and resume directly at `resumeAt` without prompting.
+  `valid_lenient` means the artifact exists on disk but a coarse content check
+  downgraded — its `reason` has already been surfaced via `renderResult`; no
+  recipe action is required.
+- Do NOT re-execute any step `< resumeAt`. The reconciler is the single source
+  of truth for resume DETERMINATION; the recipe is the gatekeeper for STATE.md
+  MUTATION.
 
 When Step 0 is complete:
 
@@ -859,6 +873,10 @@ summary as your final assistant message. Include:
 Do NOT:
 
 - Skip Step 0 (reconcile is mandatory; resume detection drives the entry).
+- Mutate STATE.md (mark any step as `[ ]` or `[~]`) based on a reconciler
+  verdict of `requires_confirmation` or `reset` without first obtaining
+  explicit user confirmation. The reconciler DETERMINES; the recipe gates
+  the MUTATION.
 - Bypass either validator — `phase-plan-validator` and `phase-build-validator`
   MUST be called.
 - Continue past 3 fix cycles in either loop — escalate to the user instead.

package/assets/pi/skills/phase-build-workflow/SKILL.md

@@ -243,11 +243,14 @@ browser/UI verification check OR the phase has a Frontend domain
 ## Resume / Reconciliation (summary)
 
 On every invocation, the workflow reconciles STATE.md against the on-disk
-artifacts in `PHASE_DIR` using a six-row decision matrix
-(STATE marker × artifact validity ⇒ action). Special cases handled:
-phase already complete, partial Step 1, interrupted Step 4 with
-`post-build-sha: (pending)`. Full table, the per-step artifact validity
-rules, and the resume decision tree live in
+artifacts in `PHASE_DIR`. `state.reconcile` returns per-step verdicts
+(`valid | valid_lenient | stale | missing | reset | requires_confirmation`)
+plus a deterministic `details.resumeAt` integer. Verdicts `valid` and
+`valid_lenient` advance past the step without re-execution;
+`requires_confirmation` and `reset` cascades MUST be surfaced to the user
+and gated on explicit confirmation BEFORE STATE.md is mutated. Full table,
+the per-step artifact validity rules, the resume decision tree, and the
+extension contract live in
 [references/resume-reconciliation-table.md](references/resume-reconciliation-table.md).
 
 ## Fix-Loop Budgets

package/assets/pi/skills/phase-build-workflow/references/resume-reconciliation-table.md

@@ -12,16 +12,32 @@ A Step is "valid" only when its primary artifact exists on disk AND meets
 the line / frontmatter requirements below. Validity is the input to the
 decision matrix in Section 2.
 
-| Step | Primary Artifact                                            | Validity Rule                                                                                  |
-|------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------|
-| 1    | `{PHASE_DIR}/explorer_findings.md`                          | exists AND > 10 lines                                                                          |
-| 1    | `{PHASE_DIR}/docs_research.md` (optional companion)         | exists AND > 10 lines (absent is acceptable — only required when HL plan cites third-party APIs)|
-| 2    | `{PHASE_DIR}/plan_V1.md`                                    | exists AND > 20 lines AND frontmatter `type: phase-implementation-plan`                        |
-| 3    | `{PHASE_DIR}/plan_validation_report.md`                     | frontmatter `result: pass` AND `checks-passed:` present                                        |
-| 4    | `{PHASE_DIR}/build_report.md` (single)                      | exists AND > 5 lines                                                                           |
-| 4    | `{PHASE_DIR}/build_report_*.md` (parallel — per domain)     | each file exists AND > 5 lines; at least one such file present                                 |
-| 5    | `{PHASE_DIR}/build_validation_report.md`                    | frontmatter `result: pass` OR `result: fail-asset` AND `checks-passed:` present (see [result-vocabulary.md](result-vocabulary.md))    |
-| 6    | `{PHASE_DIR}/phase_completion_report.md`                    | exists AND > 10 lines AND frontmatter `type: phase-report`                                     |
+**Verdict vocabulary (per-step).** `reconcile.ts` classifies each step's
+artifact into one of four classifications:
+
+- `valid`         — file exists AND content checks pass.
+- `valid_lenient` — file exists; a coarse content check missed but the
+  miss is NON-FATAL (e.g. line-count threshold). Resume continues past
+  this step; the reason is surfaced once via `renderResult`.
+- `stale`         — file exists; the mismatch is STRUCTURAL (missing
+  required frontmatter key, unparseable frontmatter, wrong `type:`,
+  wrong `result:` enum value). The matrix in §2 escalates `stale` to
+  `requires_confirmation` for completed (`[x]`) markers.
+- `missing`       — file ABSENT on disk.
+
+§2 then maps `(marker, classification)` to one of the user-facing
+verdicts `{valid, valid_lenient, stale, missing, reset, requires_confirmation}`.
+
+| Step | Primary Artifact                                            | Validity Rule                                                                                  | Classification |
+|------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------|----------------|
+| 1    | `{PHASE_DIR}/explorer_findings.md`                          | exists AND > 10 lines                                                                          | absent ⇒ `missing`; ≤10 lines ⇒ `valid_lenient`; otherwise `valid` |
+| 1    | `{PHASE_DIR}/docs_research.md` (optional companion)         | exists AND > 10 lines (absent is acceptable — only required when HL plan cites third-party APIs)| absent ⇒ `missing` (acceptable for Step 1 as long as `explorer_findings.md` is `valid` — Step 1 OR's over its canonical entries); ≤10 lines ⇒ `valid_lenient` |
+| 2    | `{PHASE_DIR}/plan_V1.md`                                    | exists AND > 20 lines AND frontmatter `type: phase-implementation-plan`                        | absent ⇒ `missing`; ≤20 lines ⇒ `valid_lenient`; missing/wrong frontmatter `type:` ⇒ `stale`; otherwise `valid` |
+| 3    | `{PHASE_DIR}/plan_validation_report.md`                     | frontmatter `result: pass` AND `checks-passed:` present                                        | absent ⇒ `missing`; missing `checks-passed:` or `result:` not in accepted enum ⇒ `stale`; otherwise `valid` |
+| 4    | `{PHASE_DIR}/build_report.md` (single)                      | exists AND > 5 lines                                                                           | absent ⇒ `missing`; ≤5 lines ⇒ `valid_lenient`; otherwise `valid` |
+| 4    | `{PHASE_DIR}/build_report_*.md` (parallel — per domain)     | each file exists AND > 5 lines; at least one such file present                                 | Step 4 OR's over single + per-domain entries (any `valid` ⇒ Step 4 `valid`) |
+| 5    | `{PHASE_DIR}/build_validation_report.md`                    | frontmatter `result: pass` OR `result: fail-asset` AND `checks-passed:` present (see [result-vocabulary.md](result-vocabulary.md))    | (Step 5 row is the result-vocabulary cross-reference — see [result-vocabulary.md](result-vocabulary.md). Do NOT alter this row.) |
+| 6    | `{PHASE_DIR}/phase_completion_report.md`                    | exists AND > 10 lines AND frontmatter `type: phase-report`                                     | absent ⇒ `missing`; ≤10 lines ⇒ `valid_lenient`; missing/wrong frontmatter `type:` ⇒ `stale`; otherwise `valid` |
 
 Notes:
 
@@ -43,17 +59,29 @@ Notes:
 ## 2. Cross-Reference Reconciliation Matrix
 
 For each Step, combine the STATE.md marker with the artifact-validity
-verdict and look up the action below. The recipe applies these row by row
-in step order (0 → 6) at startup.
-
-| STATE.md marker     | Artifact      | Action                                                                                            |
-|---------------------|---------------|---------------------------------------------------------------------------------------------------|
-| `[x]` (completed)   | valid         | Trust both. Skip the step.                                                                        |
-| `[x]` (completed)   | invalid / missing | STATE.md is wrong. Warn the user. Reset Step to `[ ]`. Re-run it.                              |
-| `[~]` (in_progress) | valid         | Crash occurred after the artifact was written but before STATE.md was updated. Mark `[x]`. Skip.   |
-| `[~]` (in_progress) | invalid / missing | Mid-execution interrupt. Reset Step to `[ ]`. Re-run it.                                       |
-| `[ ]` (pending)     | valid         | Unexpected (artifact present without STATE.md tracking). Warn. Mark `[x]`. Skip.                  |
-| `[ ]` (pending)     | missing       | Not started. Run the step normally.                                                                |
+classification (§1) and look up the verdict below. The recipe walks Steps
+0 → 6 in order at startup and consumes the per-step verdict from
+`details.steps[].verdict`.
+
+| STATE.md marker     | Artifact classification | Verdict                  | Recipe action                                                                                                                                                       |
+|---------------------|-------------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `[x]` (completed)   | `valid`                 | `valid`                  | OK. Continue past this step (no execution, no mutation).                                                                                                            |
+| `[x]` (completed)   | `valid_lenient`         | `valid_lenient`          | OK with note. Continue past this step. The `reason` is recorded in `details.steps[i].reason` for the user-facing `renderResult` table; no recipe action required.   |
+| `[x]` (completed)   | `stale`                 | `requires_confirmation`  | Surface the per-step `reason` to the user verbatim and OBTAIN EXPLICIT CONFIRMATION before resetting Step to `[ ]`. No implicit reset.                              |
+| `[x]` (completed)   | `missing`               | `requires_confirmation`  | Surface the missing-artifact path to the user and OBTAIN EXPLICIT CONFIRMATION before resetting Step to `[ ]`. No implicit reset.                                   |
+| `[~]` (in_progress) | any                     | `reset`                  | Reset Step to `[ ]` unconditionally. Re-run it. In-progress markers are always re-runnable; no user confirmation needed.                                            |
+| `[ ]` (pending)     | `valid`                 | `valid`                  | Unexpected (artifact present without STATE.md tracking). Warn. Mark `[x]`. Skip.                                                                                    |
+| `[ ]` (pending)     | `valid_lenient`         | `valid_lenient`          | Treat as `valid` for resume; surface the reason once.                                                                                                                |
+| `[ ]` (pending)     | `stale`                 | `stale`                  | This is the resume entry point; the structural mismatch will be re-emitted by the step's writer.                                                                    |
+| `[ ]` (pending)     | `missing`               | `missing`                | Not started. This step is the resume entry point if no later step is `[x]`.                                                                                          |
+
+> Footnote: the pre-repair single-row "`[x]` + invalid/missing ⇒ reset"
+> was the source of the resume-cascade bug (the kanban-core Phase-2
+> regression). This matrix replaces it. See
+> `extensions/task-state/reconcile.ts`'s `decideVerdict()` (formerly
+> `decide()` lines 323–346) for the runtime implementation. Every
+> verdict name in this matrix MUST appear verbatim in `reconcile.ts`'s
+> exported `StepVerdict` type.
 
 Cascade behaviour: each row's "Mark `[x]`" or "Reset to `[ ]`" goes
 through `task-state.MARK_STEP_COMPLETE` / direct write so that Phase and
@@ -120,13 +148,31 @@ Once per invocation, after STATE.md is loaded:
 2. **Check Phase-already-complete.** If Section 3.1 applies, stop with
    the "phase complete" message.
 3. **Walk Steps 0 → 6 in order.** For each Step:
-   - Compute artifact validity (Section 1).
-   - Apply the matrix row (Section 2) — Skip, Mark `[x]`, or Reset.
+   - Compute artifact classification (Section 1).
+   - Apply the matrix row (Section 2) to derive the per-step verdict.
    - For Step 1, additionally apply Section 3.2 (partial research).
    - For Step 4, additionally apply Section 3.3 (interrupted build).
-4. **Determine entry point.** The first Step whose post-matrix state is
-   `[ ]` is the entry point — the recipe begins execution there.
-5. **Plan / Build aborted-loop re-entry.** If the entry point is Step 3
+4. **Compute `details.resumeAt`.** The first Step whose verdict is NOT
+   in `{valid, valid_lenient}` is the entry point. If every step is
+   `valid`/`valid_lenient`, `resumeAt = lastCompletedStep + 1` (preserves
+   the "everything is fine, advance" semantic). `entryStep` mirrors
+   `resumeAt` for legacy consumers.
+5. **User-confirmation gate (mandatory before any STATE.md mutation).**
+   If ANY step's verdict ∈ `{requires_confirmation, reset}`, the recipe
+   MUST:
+   a. Present `details.steps[]` verbatim to the user (use the
+      `renderResult` table).
+   b. For each `requires_confirmation` entry, ask the user to confirm
+      or skip the proposed reset.
+   c. ONLY AFTER explicit confirmation may the recipe call
+      `state.mark_step_reset` (or equivalent) to mutate STATE.md.
+   `reset` verdicts (only emitted for `[~]` markers) do not require user
+   confirmation but must still be reported in the same banner.
+6. **Re-execution boundary.** The recipe begins re-execution at
+   `resumeAt`. Steps with verdict `valid_lenient` are NOT re-executed
+   (their reasons are surfaced once via `renderResult` and the run
+   continues).
+7. **Plan / Build aborted-loop re-entry.** If `resumeAt` is Step 3
    or Step 5 and the previous validation report exists with a non-passing
    result for its own vocabulary (Step 3: `result: fail`; Step 5:
    `result: fail-code`), apply Section 3.4: start a fresh fix loop from
@@ -134,20 +180,34 @@ Once per invocation, after STATE.md is loaded:
    `result: fail-asset` is NOT an aborted-loop case (Section 3.4 does not
    apply) — it is a closed Step 5; the resume table treats that artifact
    as valid (Section 1).
-6. **Report the resume decision** to the user before any agent is
-   spawned: "Resuming Phase N at Step K. Skipped: <list>. Reset:
-   <list>." Wait for explicit confirmation only if any Reset occurred.
+8. **Report the resume decision** to the user before any agent is
+   spawned: "Resuming Phase N at Step `resumeAt`. Skipped: <list>.
+   Confirmed reset: <list>." Wait for explicit confirmation only if any
+   `requires_confirmation` verdict occurred (per step 5 above).
 
 ## 5. `task-state` Extension Contract
 
 The `task-state` extension (Phase 11) MUST expose, at minimum:
 
-- `state.reconcile(phase_dir, phase_number)` — returns the resume entry
-  point (an integer 0-6) AND a structured summary of every Skip / Mark /
-  Reset decision applied.
+- `state.reconcile(phase_dir, phase_number)` — returns a `ReconcileResult`
+  whose `details` carries:
+  - `details.steps[]` — per-step verdict array; each entry has
+    `{ n, marker, artifact, verdict, reason? }`.
+    `verdict ∈ {valid, valid_lenient, stale, missing, reset, requires_confirmation}`
+    — every name MUST match `reconcile.ts`'s exported `StepVerdict` type
+    byte-for-byte.
+  - `details.resumeAt` — integer 0–6; the first step whose verdict is
+    NOT in `{valid, valid_lenient}` (else `lastCompletedStep + 1`).
+  - Preserved fields (legacy consumers): `entryStep` (mirrors
+    `resumeAt`), `actions[]`, `scan`, `specialCases`, `table`.
 - The matrix and the special-case rules above are the spec; the
   extension MUST NOT introduce additional resume heuristics without
-  updating this file.
+  updating this file. Any change to the matrix MUST be applied to
+  `reconcile.ts`'s `decideVerdict()` in the SAME change set.
 - Reconciliation MUST be idempotent: invoking it twice in a row on the
-  same state produces the same entry point and the same (empty on the
-  second call) set of actions.
+  same state produces the same `resumeAt`, the same per-step verdict
+  set, and the same (empty on the second call) set of mutating actions.
+- The extension PROPOSES verdicts via `details.steps[]`; the RECIPE
+  gates STATE.md mutation. The extension MUST NOT mutate STATE.md based
+  on a `requires_confirmation` verdict without recipe-mediated user
+  confirmation.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.0",
+  "version": "1.7.1",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-fob",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Deploy research-driven AI coding assistant assets (skills, agents, commands) into your projects",
   "bin": {
     "ai-fob": "bin/install.js"