Split patch rebasing to reference, fence Block F, add changed_files_pass gate

TAG=agy
CONV=3520bd51-372a-49aa-9bdb-dfd183f66aff

Change-Id: I27ee34cccd2732ee767accccc04b68ccd28d79fb

Author: nickg-ca

AGENTS.md

@@ -16,3 +16,29 @@ If the hook modifies files, stage the changes and amend your commit.
 Blocks A/B/C/D/E/F/G are wrapped in ```` ``` ```` fences and must stay
 **character-identical** across all skills. Never insert content *inside* their
 fences — add notes *after* the closing ```` ``` ```` instead.
+
+## Reference files
+
+Skills may split on-demand content into `references/` subdirectories (e.g.
+`mantis-calibrate/references/calibration_rules.md`). Before committing, verify
+that every `references/*.md` link target in a `SKILL.md` file exists on disk and
+is tracked by git (`git ls-files --error-unmatch <path>`).
+
+### Extraction criteria
+
+Extract a block into a `references/` file only if ALL three hold:
+
+1. **Off the fail-closed safety-critical path** — the extracted content is not
+   the sole authority for a security-critical invariant (e.g. the
+   `VERIFIED_SECURE => reattack_status = failed_to_bypass` gate).
+2. **Restates no invariant** — the extracted content does not restate any rule
+   that is also stated in the SKILL.md (no invariant may appear in both a
+   SKILL.md and its reference; if a rule must be referenced, state it once and
+   point to it).
+3. **Clean fail-safe fallback** — if the reference cannot be loaded, the skill
+   falls back to safe behavior without the reference (e.g. patch rebasing falls
+   back to fresh patch generation, verified by Block G).
+
+`mantis-patch/references/patch_rebasing.md` qualifies (pure mechanics, no
+invariant restated, fails safe to Phase-1). Do not extract content that restates
+a crown-jewel invariant — trim it inline instead.

mantis-architecture/SKILL.md

@@ -46,9 +46,9 @@ a canonical, interlinked Markdown Knowledge Base (`workspace/kb/`).
     current KB was last built against; absent on a first/legacy KB).
   - `workspace/.mantis_state.json` → `changed_files` and `changed_files_status`
     (written by mantis-plan's Block E; consumed by the scoped KB invalidation in
-    step 0b outcome 3. Absent on the Stage-2 invocation before planning — the
-    guardrail falls back to full rebuild. Present on the Stage-15 invocation
-    after planning — enables scoped invalidation).
+    step 0b outcome 3. Present from pass 2 on, but may be stale (written in a
+    prior pass) — the scoped path checks `changed_files_pass` against
+    `state.pass_number` and falls back to full rebuild if they differ.)
 - **Writes**:
   - Markdown files under `workspace/kb/` (`architecture.md`,
     `entities/[component_name].md`, `vulnerabilities/[CWE-ID].md`, `index.md`).
@@ -173,13 +173,16 @@ VCS):**
      unstamped / legacy. Choose full or scoped:
      - **Scoped invalidation (Phase 2 incremental efficiency):** If
        `changed_files_status` is known (not UNKNOWN) AND the KB already has a
-       `KB_SNAPSHOT` stamp (KB_ID was non-empty, just different), attempt a
-       SCOPED rebuild: only invalidate KB entries whose source files are in
-       `changed_files`, plus their parent-rollup dependents (KB entities that
-       import/reference the changed files). Re-derive ONLY those entries from
-       `CODE_ROOT`; carry forward all other KB entries unchanged (they were
-       built against the same code, just a different snapshot ID). Re-stamp
-       `KB_SNAPSHOT: CUR` on every (re)written file.
+       `KB_SNAPSHOT` stamp (KB_ID was non-empty, just different) AND
+       `changed_files_pass` equals the current `state.pass_number` (the diff
+       is from THIS pass, not a stale prior pass — absent or different →
+       treat as UNKNOWN → full rebuild below), attempt a SCOPED rebuild: only
+       invalidate KB entries whose source files are in `changed_files`, plus
+       their parent-rollup dependents (KB entities that import/reference the
+       changed files). Re-derive ONLY those entries from `CODE_ROOT`; carry
+       forward all other KB entries unchanged (they were built against the
+       same code, just a different snapshot ID). Re-stamp `KB_SNAPSHOT: CUR`
+       on every (re)written file.
         - **Parent-rollup (2-hop, matching plan's fan-out):** When
           invalidating a KB entry for changed file F, also invalidate any KB
           entry that REFERENCES F directly (1-hop) AND any entry that

mantis-patch/SKILL.md

@@ -434,28 +434,12 @@ Execute the patching and verification stage as follows:
      is an optimization for the common case where a prior fix still applies with
      minor line-number shifts.
 
-     - **How:** Locate the prior pass's `patch_diff` from the archived finding
-       (the finding JSON in `workspace/archive/findings_pass_<N-1>/`).
-       `patch_diff` is a unified DIFF, not a whole file. Reconstruct the three
-       3-way-merge inputs as SCRATCH copies (never edit the archived copies or
-       either snapshot in place):
-       - `base` = the PRIOR snapshot's unpatched version of the file, copied to
-         a scratch path (requires the prior snapshot dir on disk — see the
-         reachability check; if absent, fall back to fresh generation).
-       - `ours` = a copy of `base` with the archived `patch_diff` applied
-         (`patch <base_copy> < patch_diff`, or `git apply`). This reconstructs
-         the prior PATCHED file. If the diff does not apply cleanly to `base`,
-         fall back to fresh generation.
-       - `theirs` = the CURRENT snapshot's unpatched version of the same file,
-         copied to a scratch path. Then run
-         `git merge-file -p <ours> <base> <theirs> > <result>` — the `-p` flag
-         writes the merged result to stdout so it does NOT overwrite `<ours>` in
-         place (argument order is ours, base, theirs). If `git` is unavailable,
-         use `diff3 -m <ours> <base> <theirs> > <result>` or any 3-way merge
-         tool that writes to a SEPARATE output. If the merge produces no
-         conflict markers, `<result>` is the current file with the fix rebased
-         onto it. If no 3-way merge tool is available, fall back to fresh patch
-         generation (Phase-1 behavior).
+     - **How:** If ALL reachability conditions (a)-(d) below hold, read
+       [3-Way Patch Rebasing](references/patch_rebasing.md) with your
+       file-reading tool for the 3-way merge mechanics (`base`/`ours`/`theirs`
+       scratch copies, `git merge-file` / `diff3` invocation, conflict-marker
+       handling). On ANY uncertainty or if the reference cannot be loaded, fall
+       back to fresh patch generation (Phase-1 behavior).
      - **When to use (reachability by OBSERVABLE state, not a flag the patcher
        cannot read):** attempt rebasing ONLY when ALL hold: (a) the prior pass's
        snapshot directory AND the file's prior unpatched version actually EXIST
@@ -485,19 +469,13 @@ Execute the patching and verification stage as follows:
        read from `workspace/.mantis_state.json` (the same state object read for
        `active_snapshot`).
 
-   - **When rebasing SUCCEEDS** (clean 3-way merge): use the rebased patch as
-     the starting point for verification. Still run Block G (unpatched baseline
-     \+ post-patch gate) to confirm the rebased patch is correct. Mark the
-     finding with a history note `patch-rebased-from: pass_<N-1>`.
-
-   - **When rebasing FAILS** (merge conflict, file deleted, file renamed beyond
-     recognition, or the patched function no longer exists): fall back to
-     generating a fresh patch from scratch (Phase-1 behavior). Never use a
-     conflicting or ambiguous rebased patch.
-
-   - **Guardrail:** On ANY uncertainty, fall back to Phase-1 patch generation.
-     Never apply a rebased patch that has unresolved conflicts or that touches
-     code unrelated to the original fix.
+   - **When rebasing SUCCEEDS / FAILS / Guardrail:** See
+     [3-Way Patch Rebasing](references/patch_rebasing.md) for the success (clean
+     merge → use rebased patch, still run Block G, history note
+     `patch-rebased-from: pass_<N-1>`), failure (merge conflict / file deleted /
+     renamed → fall back to fresh patch generation), and guardrail (on ANY
+     uncertainty, fall back to Phase-1; never apply a rebased patch with
+     unresolved conflicts or unrelated changes).
 
    - **Unpatched-Baseline Re-run in `--reattack` (Phase 2):** When the
      `@mantis-reproduce --reattack` sub-agent is re-attacking a patch on a NEW

mantis-patch/references/patch_rebasing.md

@@ -0,0 +1,50 @@
+# 3-Way Patch Rebasing (Phase 2 Incremental Efficiency)
+
+> **Load trigger:** This reference is loaded when `/mantis-patch` determines
+> that ALL reachability conditions for 3-way patch rebasing are satisfied (see
+> `mantis-patch/SKILL.md` Step 2 for the inline reachability gate). The
+> procedure below is the 3-way merge mechanics and success/failure handling.
+>
+> **Safe fallback:** If the agent forgets to load this reference, the correct
+> behavior is to fall back to fresh patch generation (Phase-1 behavior). This is
+> documented in the SKILL.md guardrail.
+
+## How: 3-Way Merge Mechanics
+
+- **How:** Locate the prior pass's `patch_diff` from the archived finding (the
+  finding JSON in `workspace/archive/findings_pass_<N-1>/`). `patch_diff` is a
+  unified DIFF, not a whole file. Reconstruct the three 3-way-merge inputs as
+  SCRATCH copies (never edit the archived copies or either snapshot in place):
+  - `base` = the PRIOR snapshot's unpatched version of the file, copied to a
+    scratch path (requires the prior snapshot dir on disk — see the reachability
+    check; if absent, fall back to fresh generation).
+  - `ours` = a copy of `base` with the archived `patch_diff` applied
+    (`patch <base_copy> < patch_diff`, or `git apply`). This reconstructs the
+    prior PATCHED file. If the diff does not apply cleanly to `base`, fall back
+    to fresh generation.
+  - `theirs` = the CURRENT snapshot's unpatched version of the same file, copied
+    to a scratch path. Then run
+    `git merge-file -p <ours> <base> <theirs> > <result>` — the `-p` flag writes
+    the merged result to stdout so it does NOT overwrite `<ours>` in place
+    (argument order is ours, base, theirs). If `git` is unavailable, use
+    `diff3 -m <ours> <base> <theirs> > <result>` or any 3-way merge tool that
+    writes to a SEPARATE output. If the merge produces no conflict markers,
+    `<result>` is the current file with the fix rebased onto it. If no 3-way
+    merge tool is available, fall back to fresh patch generation (Phase-1
+    behavior).
+
+## When Rebasing SUCCEEDS / FAILS / Guardrail
+
+- **When rebasing SUCCEEDS** (clean 3-way merge): use the rebased patch as the
+  starting point for verification. Still run Block G (unpatched baseline +
+  post-patch gate) to confirm the rebased patch is correct. Mark the finding
+  with a history note `patch-rebased-from: pass_<N-1>`.
+
+- **When rebasing FAILS** (merge conflict, file deleted, file renamed beyond
+  recognition, or the patched function no longer exists): fall back to
+  generating a fresh patch from scratch (Phase-1 behavior). Never use a
+  conflicting or ambiguous rebased patch.
+
+- **Guardrail:** On ANY uncertainty, fall back to Phase-1 patch generation.
+  Never apply a rebased patch that has unresolved conflicts or that touches code
+  unrelated to the original fix.

mantis-plan/SKILL.md

@@ -196,7 +196,9 @@ Execute the planning stage as follows:
        live tree). Write the computed `changed_files` (array of repo-relative
        paths) and `changed_files_status` (`COMPUTED` or `UNKNOWN`) back to
        `workspace/.mantis_state.json`, then use them for the rest of the stage.
-       Use the following to know which files changed since the previous pass:
+       Also write `changed_files_pass` = the current `pass_number` from state,
+       so consumers can detect a stale (prior-pass) diff. Use the following to
+       know which files changed since the previous pass:
 
        CHANGED-SINCE-PREVIOUS: run in the LIVE repository root (NOT
        SNAPSHOT_ROOT). CUR = current commit/revision; PREV = snapshot_history