devflow-kit 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-08-31
+
+### Added
+- **`refresh-anchor` ledger op**: post-promotion reinforcement now reaches rendered output. When the Learning agent reinforces an already-anchored observation (sharpening its `pattern`/`details`), calling `refresh-anchor <anchor_id>` re-projects the updated log row through the same `toLedgerRow` projector as `assign-anchor` and re-renders all three `.md` files. Previously, post-promotion sharpening was written to the log but never projected forward, so the rendered entry silently froze at its first-promotion snapshot.
+
+### Changed
+- **`decisions-ledger.jsonl` is now the anchor registry only (ADR-022)**: `decisions-log.jsonl` is the content authority; the ledger holds anchor numbers and `decisions_status` only. Entry content reaches the ledger exclusively through `assign-anchor` (first promotion) and `refresh-anchor` (post-promotion re-projection) via `toLedgerRow`. The Learning agent's previously sanctioned path of editing ledger rows directly is removed — content changes go to the log, then `refresh-anchor` re-projects. Tooling that reads or writes `decisions-ledger.jsonl` directly is affected.
+- **`/resolve` DUPLICATE verdict**: `/resolve` now collapses duplicate cross-reviewer findings via a new `DUPLICATE` triage verdict — resolution-summary counts unique issues, with a `Duplicates Collapsed` statistics row and a `## Duplicates` section for traceability.
+
+### Fixed
+- **Semicolon-safe `details` field parsing**: the decisions formatter now splits `details` into fields using a segment-aware parser (`segmentDetails`) instead of delimiter regexes. The parser recognises a segment as a new field only when it starts with a known key name followed by `:` (anchored to segment start); semicolons inside values are preserved. Fixes four related defects: truncation at the first internal semicolon, unanchored-key false match (e.g. `reissue:` matching `issue:`), first-match-wins hijack (a key name mentioned inside an earlier value would capture the wrong segment), and newline breakage. Measured blast radius on this repo's own ledger: 111 truncated field extractions before the fix, 0 after. **Installed projects' rendered decisions/pitfalls `.md` may show one-time `--check` drift under the new parser — self-heals on the next ledger op.**
+- **Armed double-assign guard**: `assign-anchor` now writes `anchor_id` back to the log row on promotion, enabling the guard that prevents re-anchoring an already-anchored observation. Previously `anchor_id` was never written back, so the guard was permanently inert and running `assign-anchor` twice on the same observation silently minted two anchors.
+- **Pitfall date stamping and render date-purity**: `assign-anchor` now stamps a `date` field on all entry types (decisions and pitfalls). Previously only decision rows received a date stamp, leaving the 7-day protection window permanently inert for all pitfall entries. Render formatters now use `row.date || ''` (D5) instead of reading the clock, making renders deterministic and avoiding phantom date changes on re-render.
+- **Amendments rendering**: `formatAmendmentsLine` renders the `amendments` field as a `- **Amendments**: ...` line in the entry body. Previously the projected `amendments` field was never rendered, so amendment notes were lost at the `.md` level. Index extraction regexes are now line-anchored (`/m` flag) to prevent amendment text that mentions `- **Status**:` or `- **Area**:` from hijacking the extracted values.
+- **Working memory worker staged-write CAS** (closes #306): the background memory worker now writes to `WORKING-MEMORY.md.new` (staged file, never the real path) and compare-and-swaps into place only if `WORKING-MEMORY.md` is byte-identical to the pre-run snapshot. Previously the success check accepted any mtime bump on a file whose line 1 carried the stamp prefix — including a human's own concurrent edit — and on that false success the worker deleted the unprocessed queue batch and touched `.last-refresh-ok`, producing silent loss of captured turns under a healthy freshness marker.
+- **Stamped pre-compact bootstrap**: `pre-compact-memory` now writes a HEAD SHA stamp on line 1 of `WORKING-MEMORY.md` (guarded by a 40-hex validation gate) and lays out the five canonical sections in fixed order. Previously the bootstrap ran without a stamp, producing "synced @ unknown" at the next SessionStart and an incorrect State-A classification that hid any real drift.
+- **Reconciliation-aware worker prompt**: the memory worker prompt now includes bounded git evidence since the last stamp, explicit reconciliation and expiry guidance, and a strict DONE definition (per PF-010). Addresses unbounded carry-forward, conversation-coined labels promoted to durable state, and no-expiry instruction.
+- **State-C orphaned `.processing` visibility**: `session-start-memory`'s State C queue-depth count now includes lines from any orphaned `.pending-turns.processing` file, not just `.pending-turns.jsonl`. Previously an orphaned `.processing` was invisible to the State C detector, so a CONFLICT-requeued batch did not show in the refresh-failing banner.
+- **`/resolve` base branch token**: resolution summaries now render the base branch name instead of a literal `{base}` token. Step 0b was not extracting `base_branch` while the summary template referenced it.
+- **render summary byte counts**: `render-decisions.cjs` now reports file sizes via `Buffer.byteLength()` instead of `String.length`. The em dash separator in index Area fields (U+2014, 3 UTF-8 bytes, 1 JS character) caused the logged index.md size to be 2 bytes per em dash in the rendered index under the old code.
+
+---
+
+## [2.2.0] - 2026-08-25
+
+### Changed
+- **Orchestrator charter — self-contained delegation**: added an operating rule requiring every subagent delegation to be self-contained (goal, constraints, relevant session facts, exact paths). Deliverables that draw on the conversation (issues, PRs, reports) must carry the substance in the prompt rather than a pointer to it. Charter grows from 2177 → 2452 bytes (~600 tokens), well within the 4096-byte runtime limit.
+- **Skim agent**: one-view-per-file discipline (pseudo/Read tiers), branch-scoped heatmap (`--diff`, `--window`, `--top`), PATH-first `skim` invocation with `npx rskim` fallback, prose/config skim note
+
+---
+
 ## [2.1.0] - 2026-08-25
 
 ### Added
@@ -1184,6 +1215,8 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[2.3.0]: https://github.com/dean0x/devflow/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/dean0x/devflow/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/dean0x/devflow/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/dean0x/devflow/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/dean0x/devflow/compare/v1.8.3...v2.0.0

package/dist/commands/resolve.md

@@ -50,7 +50,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
@@ -186,7 +186,7 @@ Issues are extracted from `{TARGET_DIR}` only — never cross-reference reviews
 ### 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.
 
@@ -205,7 +205,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:
 
@@ -217,7 +217,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."
 ```
@@ -229,11 +229,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.
@@ -247,7 +248,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
@@ -255,7 +256,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`:
 
@@ -284,12 +285,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
@@ -382,7 +385,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"):
@@ -407,6 +410,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)
 
@@ -447,7 +451,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.
 
@@ -466,7 +470,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:
 
@@ -486,6 +490,7 @@ The resolution summary was already written to `{TARGET_DIR}/resolution-summary.m
 | Deferred | {n} |
 | Blocked | {n} |
 | Escalated | {n} |
+| Duplicates Collapsed | {n} |
 
 ### Verification
 Final gate: {PASS | FAILED after N attempts}
@@ -578,9 +583,9 @@ After writing, commit the two files to the current worktree branch yourself by r
 │  └─ 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]
@@ -623,6 +628,8 @@ After writing, commit the two files to the current worktree branch yourself by r
 | 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 |
@@ -651,7 +658,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
@@ -673,8 +680,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 |
@@ -720,6 +728,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 |
 |--------|-----------|---------|--------|
@@ -728,4 +741,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.1.0",
+  "version": "2.3.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": {

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/skim.md

@@ -9,7 +9,7 @@ skills:
 
 # Skim Agent
 
-You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
+You are a codebase orientation specialist. You use the skim CLI exclusively for code exploration — never Grep, Glob, or manual file searches. Prefer the `skim` binary when on PATH (`command -v skim`); fall back to `npx rskim`. Examples below show `npx rskim` — substitute `skim` when available. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
@@ -57,13 +57,16 @@ When the task modifies existing code (refactor, bugfix, extension), run:
 npx rskim heatmap --insights
 ```
 
-Scope with `--path <dir>` when targeting a subdirectory. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
+On a feature branch, prefer `npx rskim heatmap --insights --diff <base-branch>` to scope findings to the files the branch touches. Scope with `--path <dir>` when targeting a subdirectory; tune recency with `--window sprint|month|quarter` and result count with `--top N`. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
 
 ### Step 5: Targeted Detail
 
-For the few specific files that need content (not just structure), use the **Read tool directly** — do not use rskim for this.
+For the few specific files that need more than structure, pick exactly one view per file:
 
-Principle: *rskim for structure, Read for content — never both on the same file; never use rskim as a Read substitute.*
+- Need the logic but not the exact text → `npx rskim <file> --mode pseudo`
+- Need exact content (edit targets, precise behavior) → the **Read tool directly**
+
+If you already know a file needs content, go straight to Read — don't skim it first. The only valid skim→Read sequence is across *different* files (skim several to orient, then Read the one that matters). Skimming and then Reading the same file pays for it twice.
 
 ### Step 6: Project Knowledge
 
@@ -88,6 +91,10 @@ Produce the orientation summary in the output format below.
 | `--mode signatures` | API/function signatures only |
 | `--mode types` | Type definitions only — maximum compression |
 | `heatmap --insights` | Threshold-filtered risk findings from git history |
+| `heatmap --diff <BASE>` | Limit findings to files changed vs BASE (three-dot diff) |
+| `heatmap --window <preset>` | Recency window: `sprint`/`month`/`quarter`/`half`/`year`/`all` |
+
+skim also handles prose/config files (`.md`, `.json`, `.yaml`, `.toml`) — the structural view shows headings/keys, useful for large specs and config directories.
 
 ## Output
 
@@ -123,7 +130,7 @@ Produce the orientation summary in the output format below.
 ## Principles
 
 1. **Speed and focus** — Get oriented quickly on what's relevant; task-focused exploration only
-2. **rskim for structure, Read for content** — never both on the same file
+2. **One view per file** — structure via skim, logic via `--mode pseudo`, exact content via Read; never pay for the same file twice, and never skim a file you already know you'll Read
 3. **Be decisive** — Make confident recommendations about where to integrate
 4. **Token efficiency** — Use rskim token budgets and stats to show compression ratio
 

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