devflow-kit 2.2.0 → 2.4.0

package/dist/targets/claude-code/post-install.js

@@ -712,10 +712,95 @@ export async function stripUserSecurityDenyList(settingsPath) {
     await writeFileAtomicExclusive(settingsPath, stripped);
     return { removed };
 }
+/** True for a non-null, non-array object literal. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Every `command` string carried by a hook matcher, tolerating foreign shapes.
+ * Returns an empty array for anything that is not `{ hooks: [{ command: string }] }`.
+ */
+function hookCommandsOf(matcher) {
+    if (!isPlainObject(matcher) || !Array.isArray(matcher.hooks))
+        return [];
+    return matcher.hooks
+        .filter(isPlainObject)
+        .map((h) => h.command)
+        .filter((c) => typeof c === 'string');
+}
+/**
+ * Merge Devflow's template hook entries and top-level fields into an existing
+ * parsed settings object. Idempotent by exact command string — a hook that is
+ * already present is skipped. Sets `statusLine` only when the user has no existing
+ * value. Attribution is NOT injected here — managed by the flags pipeline (D27).
+ * Mutates `existing` in place.
+ *
+ * D-SETTINGS-1: merge strategy — never replace; only add devflow entries that are absent.
+ * Returns { changed: true } when any field was added.
+ *
+ * `existing` comes from a hand-editable file, so every branch is shape-guarded:
+ * a `hooks` value (or per-event value) that is not the expected object/array shape
+ * is left untouched rather than overwritten or thrown on (applies PF-023 — validate
+ * at the sink that mutates).
+ *
+ * Exported for testing.
+ */
+export function mergeDevflowSettingsTemplate(existing, template) {
+    let changed = false;
+    // Merge hook entries — idempotent by exact command string
+    const tmplHooks = isPlainObject(template.hooks) ? template.hooks : {};
+    const existingHooksRaw = existing.hooks;
+    if (existingHooksRaw === undefined || isPlainObject(existingHooksRaw)) {
+        const existingHooks = existingHooksRaw ?? {};
+        let hooksChanged = false;
+        for (const [event, matchers] of Object.entries(tmplHooks)) {
+            if (!Array.isArray(matchers))
+                continue;
+            for (const matcher of matchers) {
+                const cmd = hookCommandsOf(matcher)[0];
+                if (!cmd)
+                    continue;
+                const current = existingHooks[event];
+                if (current !== undefined && !Array.isArray(current))
+                    break; // foreign shape — leave the event alone
+                const eventArr = current ?? [];
+                if (eventArr.some((m) => hookCommandsOf(m).includes(cmd)))
+                    continue;
+                eventArr.push(matcher);
+                existingHooks[event] = eventArr;
+                hooksChanged = true;
+            }
+        }
+        // Attach only when something was actually added — never introduce an empty
+        // `hooks` key into a settings.json that had none.
+        if (hooksChanged) {
+            existing.hooks = existingHooks;
+            changed = true;
+        }
+    }
+    // Set statusLine only if the user has none
+    if (existing.statusLine === undefined && template.statusLine !== undefined) {
+        existing.statusLine = template.statusLine;
+        changed = true;
+    }
+    // attribution: owned exclusively by the flags pipeline (applyFlags/stripFlags, D27) — a second writer here would race it.
+    return { changed };
+}
 /**
  * Install or update settings.json with Devflow configuration.
- * Prompts interactively in TTY mode when settings already exist.
- * In non-TTY mode, skips override (safe default).
+ *
+ * Strategy (D-SETTINGS-1: merge, never overwrite wholesale):
+ * - Fresh file: write the template directly.
+ * - Existing file: MERGE devflow hook entries and fields into the parsed object.
+ *   Idempotent by exact command string — existing hooks are never duplicated or removed.
+ *   Preserves every user key (env, permissions, apiKeyHelper, model, etc.) untouched.
+ * - Parse failure: warn and skip; file left byte-identical (never clobber a broken file).
+ *
+ * The merge is additive only, so it runs without a confirmation prompt: init is called
+ * from inside an active spinner (a prompt would render on top of it), and declining
+ * could not protect the file anyway — init's own settings pass rewrites the hook set
+ * unconditionally right afterwards. A prompt whose answer changes nothing is worse
+ * than no prompt.
  *
  * The deny list is handled by init's dedicated security step
  * (applyUserSecurityDenyList / installManagedSettings) after installSettings completes.
@@ -741,38 +826,30 @@ export async function installSettings(claudeDir, rootDir, devflowDir, verbose) {
             }
             return;
         }
-        // Settings exist — check if they already have hooks
-        let hasHooks = false;
+        // Settings exist — parse and merge (never overwrite wholesale)
+        let existingParsed;
         try {
-            const existing = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
-            hasHooks = !!existing.hooks;
+            existingParsed = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
         }
-        catch { /* parse error = treat as no hooks */ }
-        if (hasHooks) {
-            // Settings already configured with hooks — nothing to do
+        catch {
+            // Parse failure — warn and skip; file left byte-identical (D-SETTINGS-1)
+            if (verbose) {
+                p.log.warn('settings.json could not be parsed — Devflow hooks not added. ' +
+                    'Fix the JSON manually and re-run devflow init.');
+            }
             return;
         }
-        // Settings exist without hooks — prompt in TTY, warn in non-TTY
-        if (process.stdin.isTTY) {
-            const confirmed = await p.confirm({
-                message: 'settings.json exists without hooks (Working Memory needs hooks). Override?',
-                initialValue: true,
-            });
-            if (p.isCancel(confirmed)) {
-                p.cancel('Installation cancelled.');
-                process.exit(0);
-            }
-            if (confirmed) {
-                await fs.writeFile(settingsPath, settingsContent, 'utf-8');
-                p.log.success('Settings overridden');
-            }
-            else {
-                p.log.info('Keeping existing settings');
-            }
+        const templateParsed = JSON.parse(settingsContent);
+        // Merge template into existing (mutates existingParsed in place).
+        // If nothing needs to be added the write is skipped entirely.
+        const { changed } = mergeDevflowSettingsTemplate(existingParsed, templateParsed);
+        if (!changed) {
+            // Already fully configured — nothing to do
+            return;
         }
-        else {
-            p.log.warn('Settings exist without hooks. Working Memory requires hooks.');
-            p.log.info('Re-run interactively to configure, or manually add hooks to settings.json');
+        await writeFileAtomicExclusive(settingsPath, JSON.stringify(existingParsed, null, 2) + '\n');
+        if (verbose) {
+            p.log.success('Settings updated with Devflow hooks and HUD');
         }
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
     "@clack/prompts": "^0.9.1",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
-    "subswitch": "0.2.0"
+    "subswitch": "0.4.0"
   },
   "devDependencies": {
     "@mdscript/mds": "0.2.0",

package/src/assets/agents/learning.md

@@ -18,7 +18,7 @@ skills:
 You process the pending decisions queue for one project: claim it atomically, detect
 decision/pitfall patterns worth keeping, curate the existing ledger, and delete the claimed
 queue as your final act. You read and edit the data files directly — no script reads,
-validates, or applies anything on your behalf. The only executables you call are the three
+validates, or applies anything on your behalf. The only executables you call are the four
 ledger ops below.
 
 ## Iron Law
@@ -26,11 +26,12 @@ ledger ops below.
 > **assign-anchor OWNS NUMBERING; render OWNS THE .md; NEVER HAND-EDIT decisions.md, pitfalls.md, or index.md**
 >
 > ADR and PF numbers are assigned exclusively by `assign-anchor`. The `.md` files are written
-> exclusively by `render-decisions.cjs` (invoked internally by `assign-anchor`/`retire-anchor`).
-> One `assign-anchor` invocation claims one number and re-renders all three files atomically
-> (decisions.md, pitfalls.md, index.md). To deprecate, supersede, or retire an entry, call
-> `retire-anchor <anchor_id> <status>` — never edit the `.md` files directly. Manual re-render
-> via `render-decisions.cjs render "$(pwd)"` also refreshes index.md.
+> exclusively by `render-decisions.cjs` (invoked internally by `assign-anchor`/`retire-anchor`/`refresh-anchor`).
+> One `assign-anchor` invocation claims one number and re-renders all three files
+> (decisions.md, pitfalls.md, index.md — each write atomic; the sequence is not transactional:
+> a crash between writes self-heals on the next op). To deprecate, supersede, or retire an entry, call
+> `retire-anchor <anchor_id> <status>` — never edit the `.md` files directly. Every ledger op
+> re-renders all three files internally; there is no separate render step for you to run.
 
 ## Environment
 
@@ -39,6 +40,7 @@ are relative to it. The ledger ops live at `$HOME/.devflow/scripts/hooks/json-he
 
 - `assign-anchor <type> <obs_id>` — claims the next ADR/PF number and re-renders all three `.md` files (decisions.md, pitfalls.md, index.md)
 - `retire-anchor <anchor_id> <status>` — flips a ledger row's rendered status and re-renders
+- `refresh-anchor <anchor_id> [<anchor_id>...]` — variadic: re-projects one or more anchored log rows through the same projector as `assign-anchor` in a single lock/parse/render pass; use after reinforcing already-anchored observations (ADR-022)
 - `rotate-observations` — archives `observing` log rows older than 30 days
 
 Each op self-locks internally. Call them plainly — never wrap them in a lock of your own,
@@ -119,6 +121,23 @@ rewrite the whole file:
   timestamps are UTC ISO (`date -u +%Y-%m-%dT%H:%M:%SZ`). Estimate `confidence` honestly —
   it is curation metadata only, NOT a gate; do not inflate it.
 
+  **`details` grammar**: use `Key: value` segments separated by `;`. Recognised keys are per
+  type and disjoint — decisions: `context:`, `decision:`, `rationale:`; pitfalls: `area:`,
+  `issue:`, `impact:`, `resolution:`. A segment that begins with a key recognised FOR THAT TYPE
+  starts a new field; any other segment (including a key from the opposite type) is appended to
+  the previous field's value, so semicolons inside a value are preserved. Keep prose out of key
+  positions — do not start a value with text that looks like a recognised key for that type. The
+  parser has a recovery pass for legacy mid-segment keys.
+
+  **`amendments` field**: when reinforcing an already-anchored observation with a dated
+  correction or ratification that should remain visible as history (rather than silently
+  rewriting `details`), APPEND `{ "date": "YYYY-MM-DD", "note": "..." }` to the log row's
+  `amendments` array (create the array if absent). The shape is exactly `{date, note}` — the
+  schema guard rejects bare strings. Amendments render at the end of the entry body in
+  `decisions.md`/`pitfalls.md`; they never appear in `index.md` lines. A follow-up
+  `refresh-anchor <anchor_id>` is required to propagate the addition to the rendered files
+  (ADR-022).
+
 - **Reinforce an existing row** — use the Edit tool to replace that row's single line:
   increment `observations`, union `evidence` (dedupe, cap 10), update `last_seen`, and
   refresh `pattern`/`details`/`confidence` only where the new evidence sharpens them.
@@ -134,12 +153,32 @@ node "$HOME/.devflow/scripts/hooks/json-helper.cjs" assign-anchor "pitfall" "obs
 NEVER hand-edit `decisions.md` or `pitfalls.md`. NEVER invent an ADR-NNN/PF-NNN number
 yourself — `assign-anchor` is the only source of numbering.
 
+**After reinforcing already-anchored observations**: once you have updated all target log rows
+(incrementing `observations`, refreshing `pattern`/`details`, updating `last_seen`), collect
+all anchor ids and make ONE variadic call:
+
+```bash
+node "$HOME/.devflow/scripts/hooks/json-helper.cjs" refresh-anchor <anchor_id1> [<anchor_id2> ...]
+```
+
+This re-projects all sharpened log rows in a single lock/parse/render pass, propagating
+improvements to `decisions.md`/`pitfalls.md`/`index.md`. BATCH: do not call once per row — N
+calls pay N full-corpus renders; one variadic call pays one. Refresh calls do not consume
+curation slots; however, at most 10 anchors may be refreshed per run — stop if the cap is
+reached.
+
 ## Part 2 — Curation
 
 Periodic housekeeping of the ledger and rendered `.md` files. Bounds: **≤5 curation changes
 per run**. **7-day protection window** — never touch any entry whose `date` field in the
 ledger (`.devflow/learning/decisions-ledger.jsonl`) is within the past 7 days. The window key
-is the ledger row's `date` field (YYYY-MM-DD), not anything in the `.md` file.
+is the ledger row's `date` field (YYYY-MM-DD), not anything in the `.md` file. If the ledger
+row lacks a `date` field (pitfall rows promoted before date-stamping was added), use the
+observation log row's `last_seen` date for the window. If `last_seen` is also unavailable, the
+entry predates date-stamping and is outside the protection window (no backfill: a fabricated date would be worse than an unprotected entry — ADR-022).
+Example: a pitfall row with no ledger `date` whose log row has `last_seen: "2026-08-27"` → window
+key 2026-08-27 (protected if within 7 days of today); no ledger `date` AND no log `last_seen`
+→ outside the window, eligible for curation.
 
 Ground yourself first, all by direct reads:
 - Active entries and counts: `decisions.md` / `pitfalls.md` — what is rendered is what is active.
@@ -148,6 +187,13 @@ Ground yourself first, all by direct reads:
   those files still exist (Glob). An entry whose referenced files are gone is a preferred
   retirement candidate — a signal to prefer, not an automatic retirement.
 
+**PF-040 pointer-vs-citation gate**: before acting on a missing-path signal (a file cited in
+`details`/`evidence` no longer exists), determine whether the reference is a live POINTER (a
+file a reader should follow today) or a HISTORICAL CITATION (the file the entry recorded
+deleting, replacing, or retiring). A missing live pointer is drift — repair the reference. A
+missing historical citation is confirmation that the decision was implemented — leave the entry
+intact.
+
 **Rotate stale observations first** (before selecting curation candidates):
 
 ```bash
@@ -180,10 +226,13 @@ node "$HOME/.devflow/scripts/hooks/json-helper.cjs" retire-anchor <anchor_id> <s
 
 `retire-anchor` is atomic and idempotent. Call it once per entry.
 
-**Citation preservation**: if an entry being retired has inbound `applies ADR-NNN` citations
-in other entries, update those entries' `pattern`/`details` to reference the surviving entry
-instead — edit those ledger rows directly (one line at a time), then re-render via
-`node "$HOME/.devflow/scripts/hooks/lib/render-decisions.cjs" render "$(pwd)"`.
+**Citation preservation** (ADR-022 — log is content authority): if an entry being retired
+has inbound `applies ADR-NNN` citations in other entries' `pattern`/`details`, update those
+other entries to reference the surviving entry — do this by editing their **log rows** in
+`decisions-log.jsonl` (one line at a time), then collecting all updated anchor ids and calling
+ONCE: `node "$HOME/.devflow/scripts/hooks/json-helper.cjs" refresh-anchor <anchor_id1> [<anchor_id2> ...]`
+Batch all ids into the single variadic call — one lock/parse/render pass for the whole set.
+Never edit the ledger directly for content changes; the log is the authority.
 
 **Cap enforcement**: stop after 5 changes regardless of remaining candidates.
 
@@ -191,8 +240,9 @@ instead — edit those ledger rows directly (one line at a time), then re-render
 
 1. Run `rotate-observations` if you have not already this run (Part 2 covers it — never run
    it twice).
-2. Delete the claim file as your FINAL act, strictly after every other write (bare `rm` is
-   blocked by devflow's recommended deny-list — PF-003):
+2. Delete the claim file as your FINAL act, strictly after every other write (`rm -f` is
+   denied by devflow's recommended deny-list; `unlink` and a flagless `rm` both pass — use
+   `unlink` (PF-003)):
    `unlink .devflow/learning/.pending-turns.processing`
    If deletion is denied, finish normally and note the leftover claim file in your summary —
    the next run's stale-merge recovery folds it in.

package/src/assets/agents/triage.md

@@ -28,10 +28,22 @@ You receive from orchestrator:
 
 1. **Read context per issue**: For each issue, Read 30 lines around the reported file:line to understand the actual code.
 2. **Apply Decisions**: Scan the DECISIONS_CONTEXT index to identify relevant ADR and PF entries. Read full bodies on demand. Cite `applies ADR-NNN` / `avoids PF-NNN` in your Reasoning column. Skip when DECISIONS_CONTEXT is empty or `(none)`. Use only verbatim IDs from the index — do not fabricate.
-3. **Assign disposition**: Apply the blast-radius matrix below. Every issue gets exactly one verdict — none may vanish.
+3. **Assign disposition**: Run the duplicate grouping pre-pass, then apply the blast-radius matrix to each group's primary. Every issue gets exactly one verdict (DUPLICATE included) — none may vanish.
 4. **Document evidence**: FALSE_POSITIVE requires cited grep/file:line. BY_DESIGN requires an ADR or inline comment/doc citation.
 5. **Assign risk tier**: For every FIX_NOW issue, annotate Standard or Careful.
 
+## Duplicate Grouping Pre-Pass
+
+Run this pre-pass **before** the disposition matrix. It is a relation between issues, not a matrix row.
+
+1. **Group by same defect**: cluster issues that share the same root cause — typically the same or adjacent file:line reported by different review foci, or the same logical error in different phrasings.
+2. **Select primary**: from each group, designate as primary the most specific and complete report — but when a group mixes security and non-security findings (a 'security member' is one that would trigger the Security Gate), the security member is always the primary. All other members are non-primary duplicates.
+3. **Security gate applies to the whole group**: if ANY member is a security finding, the group's primary passes through the Security Gate (→ FIX_NOW or ESCALATED only). Never downgrade a group because non-security members outnumber the security finding.
+4. **Non-primary members**: assign verdict **DUPLICATE** with `duplicate_of: <primary-id>`. Never chain — `duplicate_of` must reference a non-DUPLICATE issue. A DUPLICATE inherits its primary's outcome.
+5. **Single-member groups**: if an issue has no duplicates it is its own primary — apply the matrix directly.
+
+Apply the disposition matrix to each group's **primary only**.
+
 ## Blast-Radius Disposition Matrix
 
 **First match wins. Apply in the order listed.**
@@ -117,6 +129,11 @@ Return the verdict ledger grouped by disposition:
 |----------|-----------|----------------------|
 | {id} | {file}:{line} | {why requires complete redesign} |
 
+### DUPLICATE
+| Issue ID | Duplicate Of | File:Line | Reason |
+|----------|-------------|-----------|--------|
+| {id} | {primary-id} | {file}:{line} | {same defect as {primary-id}, reported by {focus}} |
+
 ### Summary
 - Total Issues: {n}
 - ESCALATED: {n}
@@ -125,6 +142,7 @@ Return the verdict ledger grouped by disposition:
 - BY_DESIGN: {n}
 - FIX_SEPARATE: {n}
 - TECH_DEBT: {n}
+- DUPLICATE: {n}
 ```
 
 ## Boundaries

package/src/assets/commands/resolve.mds

@@ -56,7 +56,7 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par
 
 **If BLOCKED:** In single-worktree mode, stop and report the blocker to user. If no reviews found, suggest `/code-review` or `/bug-analysis` first. In multi-worktree mode, report the failure but continue with other worktrees.
 
-**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count`, `diff_files` per worktree.
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number`, `review_count`, `diff_files` per worktree.
 
 **Fetch PR body** (after extracting `pr_number`):
 ```bash
@@ -138,7 +138,7 @@ Issues are extracted from `\{TARGET_DIR\}` only — never cross-reference review
 ### Phase 1b: Fetch External Review Threads (Compliance-gated)
 
 **Produces:** THREAD_MAP
-**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+**Requires:** BRANCH_INFO, COMPLIANCE_SKILL_INSTALLED
 
 Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
 
@@ -157,7 +157,7 @@ Parse `THREAD_MAP` from Git agent output. If Git agent returns `TRACEABILITY: DE
 ### Phase 2: Global Triage
 
 **Produces:** TRIAGE_RESULTS
-**Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, BRANCH_INFO
+**Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION
 
 Spawn a single global Triage agent for ALL issues:
 
@@ -169,7 +169,7 @@ WORKTREE_PATH: {worktree_path}  (omit if cwd)
 DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
-Triage every issue using the blast-radius disposition matrix. Assign exactly one verdict per issue.
+Triage every issue: collapse duplicates first, then apply the blast-radius disposition matrix to each group's primary. Assign exactly one verdict per issue.
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE."
 ```
@@ -181,11 +181,12 @@ Wait for Triage agent to complete before proceeding. Parse verdict ledger from T
 - **BY_DESIGN**: Intentional code (with ADR or code doc citation)
 - **FIX_SEPARATE**: Valid but out of blast-radius scope (must become manage-debt ticket)
 - **TECH_DEBT**: Architectural overhaul only — LAST RESORT
+- **DUPLICATE**: Collapsed duplicate issue — carries `duplicate_of: <primary-id>` referencing the non-DUPLICATE primary; inherits the primary's outcome
 
 Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning columns.
 
 **Triage agent completeness assertion (avoids PF-002):** Verify the parsed ledger against ISSUES before proceeding:
-1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets.
+1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets. DUPLICATE is a valid bucket; a valid DUPLICATE entry must name its `duplicate_of` primary (the `Duplicate Of` column of the ledger's DUPLICATE table) and that primary must be a non-DUPLICATE issue id. A missing `duplicate_of` or one that chains to another DUPLICATE is a **Triage agent failure** (retry-then-abort as below).
 2. If the Triage agent output is empty, contains a skill re-entrancy guard string (e.g., contains `already running`), or is missing any issue IDs from ISSUES: treat as a **Triage agent failure**:
    - Retry the Triage agent once with the same inputs.
    - If the retry also fails the completeness check: abort with a clear error message listing the missing issue IDs and failure reason — never proceed with dropped issues.
@@ -199,7 +200,7 @@ Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning c
 
 If FIX_NOW list is empty: skip to Phase 5 — write full summary (Phase 5), run manage-debt (Phase 9) if FIX_SEPARATE/TECH_DEBT exist, run thread resolution + resolution comment (Phase 9b), run merge readiness (Phase 9c), display results (Phase 10).
 
-Otherwise, batch FIX_NOW issues for Code agent execution:
+Otherwise, batch FIX_NOW issues for Code agent execution. **DUPLICATE issues are never dispatched** — they inherit the primary's outcome:
 - **Same-file issues** → one batch (one Code agent per file, sequential for same-file pairs)
 - **Distinct-file issues** → parallel Code agents
 - **Max 5 issues per batch** — chunk large sets
@@ -207,7 +208,7 @@ Otherwise, batch FIX_NOW issues for Code agent execution:
 ### Phase 4: Fix (Code agent × N)
 
 **Produces:** CODE_AGENT_RESULTS
-**Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, BRANCH_INFO
+**Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
 For each batch, spawn Code agent with `OPERATION: issue-fix` and `PUSH: false`:
 
@@ -236,12 +237,14 @@ Collect from each Code agent:
 ### Phase 5: Write resolution-summary.md
 
 **Produces:** RESOLUTION_FILE (early write for compaction safety)
-**Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS
+**Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS, TARGET_DIR, BRANCH_INFO
 
 **Immediately write `resolution-summary.md`** to `\{TARGET_DIR\}` using the Write tool. Do this now — not in Phase 9 — while results are fresh in context. This ensures the record is persisted even if later phases (Simplify, Verification Gate, CI gate, Tech Debt) trigger context compaction.
 
 Set `Tracked` for FIX_SEPARATE and TECH_DEBT items to `(pending)` — to be backfilled after Phase 9 manage-debt.
 
+DUPLICATE issues are listed **only** in `## Duplicates` — never in `## Fixed Issues`, `## False Positives`, `## By Design`, `## Fix Separately`, `## Deferred to Tech Debt`, `## Escalations`, or `## Blocked`. A duplicate of a FALSE_POSITIVE primary therefore leaves only the primary in the `False Positive` row and the `## False Positives` section; the same holds for every other outcome the duplicate inherits.
+
 Use the template from the Output Artifact section below.
 
 ### Phase 6: Simplify
@@ -334,7 +337,7 @@ Otherwise, for each worktree with fixes:
 
 **IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts.
 
-If any issues are FIX_SEPARATE or TECH_DEBT, spawn Git agent:
+If any issues are FIX_SEPARATE or TECH_DEBT, spawn Git agent. **DUPLICATE issues never create their own debt tickets** — a duplicate of a deferred primary is covered by the primary's ticket:
 
 ```
 Agent(subagent_type="Git"):
@@ -359,6 +362,7 @@ Skip this step if `COMPLIANCE_SKILL_INSTALLED` is false or THREAD_MAP is empty.
 
 Prepare THREAD_MAP with verdicts from triage/code agent results:
 - For each `ext-\{N\}`: match to an issue verdict (FIXED, FALSE_POSITIVE, BY_DESIGN, ESCALATED) by `file:line` correlation
+- If the matched issue has verdict DUPLICATE, use the **primary's** verdict and verification status for the reply — do not expose DUPLICATE to the thread author (avoids PF-024; caller-side mapping — git.md contracts unchanged)
 - Include `commit_sha` from Code agent results for FIXED verdicts
 - Unmatched threads: ESCALATED (human review)
 
@@ -399,7 +403,7 @@ Update `## Third-Party Threads` section in resolution-summary.md with thread res
 ### Phase 9c: Merge Readiness (Compliance-gated, Report-only)
 
 **Produces:** MERGE_READINESS_REPORT
-**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+**Requires:** BRANCH_INFO, COMPLIANCE_SKILL_INSTALLED
 
 Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
 
@@ -418,7 +422,7 @@ If Git agent returns `TRACEABILITY: DEGRADED`: warn, proceed to Phase 10.
 
 ### Phase 10: Report
 
-**Requires:** TARGET_DIR
+**Requires:** BRANCH_INFO, TARGET_DIR
 
 The resolution summary was already written to `\{TARGET_DIR\}/resolution-summary.md` in Phase 5 (updated by Phase 7 and Phase 9). Display results to the user:
 
@@ -438,6 +442,7 @@ The resolution summary was already written to `\{TARGET_DIR\}/resolution-summary
 | Deferred | {n} |
 | Blocked | {n} |
 | Escalated | {n} |
+| Duplicates Collapsed | {n} |
 
 ### Verification
 Final gate: {PASS | FAILED after N attempts}
@@ -483,9 +488,9 @@ In multi-worktree mode, report results per worktree with aggregate summary.
 │  └─ Git agent (fetch-review-threads) → THREAD_MAP
 │
 ├─ Phase 2: Global Triage [Triage agent, opus, single agent]
-│  └─ ALL issues → verdict ledger by disposition
+│  └─ ALL issues → verdict ledger by disposition (incl. DUPLICATE with duplicate_of)
 │
-├─ Phase 3: Batch FIX_NOW issues (skip if empty)
+├─ Phase 3: Batch FIX_NOW issues (skip if empty; DUPLICATE issues never dispatched)
 │  └─ same-file sequential, distinct-file parallel, max 5/batch
 │
 ├─ Phase 4: Fix [Code agent × N, OPERATION: issue-fix, PUSH: false]
@@ -528,6 +533,8 @@ In multi-worktree mode, report results per worktree with aggregate summary.
 | Worktree pre-flight fails | Report failure, continue with other worktrees |
 | Empty FIX_NOW list | Skip Phases 3-4/6-8; still write full summary + run manage-debt if FIX_SEPARATE/TECH_DEBT exist |
 | ESCALATED security issues | Surfaced in ## Escalations + display callout; never routed to manage-debt |
+| DUPLICATE verdict without duplicate_of, or chained to another DUPLICATE | Treated as Triage failure — same retry-then-abort as a vanished id |
+| DUPLICATE issues in THREAD_MAP | Map ext-\{N\} to primary's verdict/verification status for thread reply |
 | Verification Gate FAILED after 2 attempts | Recorded as FAILED in ## Verification + blocking callout; CI gate skipped; proceed to Phase 9 (manage-debt) then Phase 10 (display) |
 | gh/GitHub absent | manage-debt fails gracefully; Tracked stays "(pending)" + noted — recorded, not dropped |
 | COMPLIANCE_SKILL_INSTALLED false | Phases 1b, 9b-step-1, and 9c are skipped; post-resolution-summary (Phase 9b step 2) still runs if a PR is known |
@@ -556,7 +563,7 @@ Written in Phase 5 (Collect Results) to `\{TARGET_DIR\}/resolution-summary.md`:
 ```markdown
 # Resolution Summary
 
-**Branch**: {branch} -> {base}
+**Branch**: {branch} -> {base_branch}
 **Date**: {timestamp}
 **Review**: {TARGET_DIR}
 **Command**: /resolve
@@ -578,8 +585,9 @@ Written in Phase 5 (Collect Results) to `\{TARGET_DIR\}/resolution-summary.md`:
 | Deferred | {n} |
 | Blocked | {n} |
 | Escalated | {n} |
+| Duplicates Collapsed | {n} |
 
-_(Note: `Deferred` = `## Fix Separately` count + `## Deferred to Tech Debt` count combined — the two sections are distinct by scope, but the Statistics row aggregates both for the convergence parser.)_
+_(Note: `Deferred` = `## Fix Separately` count + `## Deferred to Tech Debt` count combined — the two sections are distinct by scope, but the Statistics row aggregates both for the convergence parser. `Total Issues` counts every triaged issue including collapsed duplicates; every row **between** `Total Issues` and `Duplicates Collapsed` counts UNIQUE (non-DUPLICATE) issues only, so `Total Issues` equals the sum of the rows below it. Excluding duplicates from `Fixed`, `False Positive`, and `Deferred` de-skews the fp\_ratio convergence formula in code-review without any parser change.)_
 
 ## Verification
 | Command | Result |
@@ -625,6 +633,11 @@ Final gate: PASS | FAILED after {n} attempts
 |-------|-----------|---------|
 | {description} | {file}:{line} | {why} |
 
+## Duplicates
+| Issue | Duplicate Of | File:Line |
+|-------|-------------|-----------|
+| {description} | {primary-id} | {file}:{line} |
+
 ## Third-Party Threads
 | Thread | File:Line | Verdict | Status |
 |--------|-----------|---------|--------|
@@ -633,4 +646,4 @@ Final gate: PASS | FAILED after {n} attempts
 
 _(Omit `## Third-Party Threads` if `COMPLIANCE_SKILL_INSTALLED` is false or no external threads were found.)_
 
-**Statistics mapping (parser contract)**: the `Deferred` row = FIX_SEPARATE + TECH_DEBT (both deferral dispositions combined); By Design and Escalated are counted separately and excluded from `Deferred`. The `/code-review` convergence parser reads the `Deferred`, `Fixed`, and `False Positive` Statistics rows plus the `## Fixed Issues` / `## False Positives` headings — keep those labels byte-stable.
+**Statistics mapping (parser contract)**: the `Deferred` row = FIX_SEPARATE + TECH_DEBT (both deferral dispositions combined); By Design and Escalated are counted separately and excluded from `Deferred`. The `Duplicates Collapsed` row is additive — the `/code-review` convergence parser reads only `Deferred`, `Fixed`, and `False Positive` rows plus `## Fixed Issues` / `## False Positives` headings — keep those labels byte-stable. All rows that the parser reads count UNIQUE (non-DUPLICATE) issues only, so collapsed duplicates do not inflate fp\_ratio.