continuous-improvement 3.17.0 → 3.18.0

package/plugins/continuous-improvement/commands/reconcile.md

@@ -1,22 +1,22 @@
 ---
 name: reconcile
-description: Establish git ground truth (branch, status, stashes, worktrees, ahead/behind) before any mutation, halt on protected or destructive operations, and verify a push actually landed. Enforces Law 1 (Research Before Executing).
+description: Establish git ground truth (branch, status, stashes, worktrees, ahead/behind) before any mutation, halt on protected or destructive operations, then carry the known-good state through a single-concern commit, a push, an open PR, and — after the PR merges — a fast-forward of the default branch. Enforces Law 1 (Research Before Executing).
 ---
 
-# /reconcile — Ground-Truth Git State Before You Touch It
+# /reconcile — Ground Truth, Then Commit, Push, and Open the PR
 
-Read the repo's real state before acting on it: a branch that shifted, a push that did not land, or another session mid-merge will burn a whole session if you assume instead of check.
+Read the repo's real state before acting on it: a branch that shifted, a push that did not land, or another session mid-merge will burn a whole session if you assume instead of check. Once the state is known, `/reconcile` carries the work through to an open PR and back to an up-to-date default branch.
 
 ## What it does
 
-Snapshots the full git state in one pass, detects a concurrent writer, classifies the upstream relationship, then acts only on the known state — stopping at every operation that is hard to reverse. Backed by the `reconcile` skill.
+Snapshots the full git state in one pass, detects a concurrent writer, classifies the upstream relationship, then acts only on the known state — stopping at every operation that is hard to reverse. When work is ready, it stages by filename, commits one concern, pushes a feature branch, verifies the push landed, and opens a PR. After a human merges, it fast-forwards the default branch and checks it out. Backed by the `reconcile` skill.
 
 ## Establish ground truth
 
 ```
 git branch --show-current
 git status --porcelain=v1                     # but trust git diff --stat for real drift (autocrlf)
-git rev-list --left-right --count @{u}...HEAD  # behind / ahead
+git rev-list --left-right --count '@{u}...HEAD'  # behind / ahead (quote the ref — bare @{u} trips the Bash parser)
 git stash list
 git worktree list
 ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null  # in-progress op = another actor; do not race
@@ -31,7 +31,22 @@ behind    -> git pull --ff-only
 diverged  -> rebase/merge deliberately; never blind --force
 ```
 
-STOP for authorization before: pushing to a protected branch (this repo = feature branch + PR, never direct push to main), `--force` / `--force-with-lease`, `reset --hard`, `clean -fd`, or removing a dirty worktree. Never stage with `git add -A` on a Windows autocrlf tree (it commits phantom line-ending-only changes) — stage by explicit filename.
+STOP for authorization before: pushing to a protected branch (this repo = feature branch + PR, never direct push to main), merging the PR you opened, `--force` / `--force-with-lease`, `reset --hard`, `clean -fd`, force-deleting a branch (`branch -D`), or removing a dirty worktree. Never stage with `git add -A` on a Windows autocrlf tree (it commits phantom line-ending-only changes) — stage by explicit filename.
+
+## Commit and open the PR (self-contained)
+
+Reimplements the commit → push → PR tail inline, so it works with no companion plugin installed:
+
+```
+git switch main && git pull --ff-only origin main   # branch from a fresh base
+git switch -c <type>/<slug>                          # only if not already on a feature branch
+git add path/one path/two                            # stage by name, one concern
+git commit -m "feat(scope): <observable outcome>"    # single-line -m; never a multi-line here-doc on Windows
+git push -u origin <type>/<slug>
+gh pr create --fill --base main                      # open one PR, then STOP — the merge is a human decision
+```
+
+`/reconcile` never merges the PR, never uses `--admin` / `--force` / `--no-verify`, never auto-merges on green CI, and never deploys.
 
 ## Verify the push landed
 
@@ -39,9 +54,21 @@ STOP for authorization before: pushing to a protected branch (this repo = featur
 git ls-remote origin refs/heads/<branch>   # remote tip must equal local HEAD, else it did not land
 ```
 
+## Sync the default branch after the PR merges
+
+"Latest work on main" is true only once the PR merges, and on a protected branch that merge is a human action. After it lands:
+
+```
+git switch main                        # or master
+git pull --ff-only origin main         # fast-forward only; if it will not ff, main diverged — re-survey, do not force
+git rev-parse HEAD                     # confirm this equals the squash-merge SHA
+git branch -d <type>/<slug>            # delete the merged feature branch (safe -d, never -D)
+```
+
 ## Pairs with
 
 - **`reconcile`** skill — the discipline this command runs.
 - **`gateguard`** / **`safety-guard`** — runtime + destructive-op guardrails.
 - **`recall`** — recall whether the same git op failed here before.
-- **`audit`** — the loop that often produces the fix `reconcile` then ships.
+- **`audit`** — the loop that often produces the fix `/reconcile` then ships.
+- **`/ship`** — the TDD-gated single-defect variant; `commit-commands:commit-push-pr` is the external-plugin equivalent of the commit → PR tail.

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -35,7 +35,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { MAX_CLEARED_FILES, canonicalizeFileKey, isCapReached, isFileCleared, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, canonicalizeProjectRoot, isCapReached, isFileCleared, loadState, markFileCleared, resolveProjectRoot, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
     Grep: "allow",
@@ -69,8 +69,20 @@ const DESTRUCTIVE_PATTERNS = [
     "Remove-Item -Recurse",
     "Remove-Item -Force",
 ];
+// Flags whose VALUE is human prose (a commit message, a PR body) or a filename —
+// never a command to execute. Their contents must not trip the destructive scan:
+// `git commit -m "drop the stale format helper"` and `gh pr create --body "…"`
+// were stranding finished work on their own wording. `-c` is deliberately
+// EXCLUDED — `bash -c "rm -rf /"` carries a real command and must still gate.
+const MESSAGE_FLAG_RE = /(^|\s)(-m|--message|-F|--file|--body|--body-file|--title|--notes|-C|--reuse-message)(=|\s+)('[^']*'|"[^"]*"|\S+)/g;
+// Blank the value of every message/body flag so only executable command syntax
+// remains for the destructive-pattern scan. The flag itself is preserved so a
+// flag like `-F` never accidentally merges with its neighbours.
+function stripMessageArgs(command) {
+    return command.replace(MESSAGE_FLAG_RE, (_match, lead, flag) => `${lead}${flag} `);
+}
 function isDestructiveBash(command) {
-    const lower = command.toLowerCase();
+    const lower = stripMessageArgs(command).toLowerCase();
     return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
 }
 function classifyTool(toolName, toolInput) {
@@ -95,6 +107,60 @@ function extractFilePaths(toolInput) {
         return [toolInput.command];
     return [];
 }
+// --- Path exclusions -------------------------------------------------------
+// Opt-in: skip the fact-forcing gate for low-risk paths a user edits
+// constantly (an LLM-maintained prose wiki, a generated scratch dir). Set the
+// CI_GATEGUARD_EXCLUDE env var to a comma-separated list of path substrings;
+// each is matched case-insensitively against the forward-slash-normalized file
+// path. Unset/empty (the default) changes nothing — every mutating file call is
+// gated exactly as before. A call whose targets mix excluded and non-excluded
+// paths still gates the non-excluded ones.
+const EXCLUDE_FRAGMENTS = String(process.env.CI_GATEGUARD_EXCLUDE ?? "")
+    .split(",")
+    .map((fragment) => fragment.trim().replace(/\\/g, "/").toLowerCase())
+    .filter((fragment) => fragment !== "");
+function isExcludedPath(filePath) {
+    if (EXCLUDE_FRAGMENTS.length === 0 || typeof filePath !== "string" || filePath === "") {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+    return EXCLUDE_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}
+// --- Target lock (opt-in) --------------------------------------------------
+// A fact-list can't catch a wrong-repo / wrong-worktree write — you can present
+// perfect facts about the wrong file. CI_GATEGUARD_TARGET_LOCK=block denies a
+// mutating call whose ABSOLUTE target canonicalizes outside the session project
+// root. Default (unset) checks nothing, so existing sessions — including
+// legitimate out-of-root edits to ~/.claude or /tmp — are unaffected. This is
+// the warn-first rollout: ship non-enforcing, flip to block per session.
+const TARGET_LOCK_ON = String(process.env.CI_GATEGUARD_TARGET_LOCK ?? "").toLowerCase() === "block";
+// Relative paths resolve under cwd (= the project root) and always pass; only an
+// absolute path into a different tree can be out-of-root. Drive-letter (d:/,
+// D:\), POSIX-absolute (/x), and UNC (\\host) forms all count as absolute.
+function isAbsolutePathString(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("/") || p.startsWith("\\\\");
+}
+function isTargetOutsideRoot(filePath, projectRoot) {
+    if (!isAbsolutePathString(filePath))
+        return false;
+    const root = canonicalizeProjectRoot(projectRoot);
+    if (root === "global" || root === "")
+        return false; // no known root — do not guess
+    const target = canonicalizeFileKey(filePath);
+    return target !== root && !target.startsWith(`${root}/`);
+}
+function buildTargetLockReason(strayPath, projectRoot) {
+    return [
+        `Target is outside the session project root — refusing a possible wrong-repo / wrong-worktree write.`,
+        "",
+        `  Target: ${strayPath.replace(/\\/g, "/")}`,
+        `  Session root: ${canonicalizeProjectRoot(projectRoot)}`,
+        "",
+        "If this is intentional, confirm you are in the right worktree (cwd / CLAUDE_PROJECT_DIR),",
+        "or unset CI_GATEGUARD_TARGET_LOCK for this session. Target lock is opt-in; it fires only",
+        "when CI_GATEGUARD_TARGET_LOCK=block.",
+    ].join("\n");
+}
 // The call site only reads this inside the block branch, where at least one
 // path is uncleared; an all-cleared batch returns "" and is never consumed.
 function firstUnclearedFilePath(toolInput, state) {
@@ -144,6 +210,47 @@ function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
         "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
     ].join("\n");
 }
+function findUnquotedBraceRef(command) {
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "@" && command[i + 1] === "{") {
+            // Expand to the whitespace-delimited word that carries this @{ ref, then
+            // single-quote that whole word in the suggested fix.
+            let wordStart = i;
+            while (wordStart > 0 && !/\s/.test(command[wordStart - 1]))
+                wordStart--;
+            let wordEnd = i;
+            while (wordEnd < command.length && !/\s/.test(command[wordEnd]))
+                wordEnd++;
+            const word = command.slice(wordStart, wordEnd);
+            const braceEnd = command.indexOf("}", i);
+            const ref = braceEnd === -1 ? command.slice(i, wordEnd) : command.slice(i, braceEnd + 1);
+            const fixed = `${command.slice(0, wordStart)}'${word}'${command.slice(wordEnd)}`;
+            return { ref, fixed };
+        }
+    }
+    return null;
+}
+function buildBraceRefReason(hit) {
+    return [
+        `Unquoted git ref ${hit.ref} — Claude Code's Bash parser trips on the braces and blocks this`,
+        "post-hoc, costing a retry. Quote the ref and run the SAME command:",
+        "",
+        `  ${hit.fixed}`,
+        "",
+        "Single quotes stop the shell from touching the braces; git reads the ref as-is.",
+    ].join("\n");
+}
 function buildDestructiveBashReason(command) {
     return [
         `Destructive command requested: ${command}`,
@@ -199,6 +306,16 @@ function main() {
     const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
     const toolInput = payload.tool_input ?? {};
     const gate = classifyTool(toolName, toolInput);
+    // Unquoted @{…} refs trip the built-in Bash parser — catch them first, for
+    // both routine and destructive commands, so the quoted fix surfaces before the
+    // opaque post-hoc block (and before the destructive rollback demand).
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        const braceHit = findUnquotedBraceRef(toolInput.command);
+        if (braceHit) {
+            emitDeny(buildBraceRefReason(braceHit));
+            return;
+        }
+    }
     if (gate === "allow") {
         emitAllow();
         return;
@@ -215,7 +332,24 @@ function main() {
     const sessionDir = resolveSessionDir(sessionId);
     const stateFilePath = join(sessionDir, "gateguard-session.json");
     const state = loadState(sessionDir);
-    const filePaths = extractFilePaths(toolInput);
+    const allTargetPaths = extractFilePaths(toolInput);
+    const filePaths = allTargetPaths.filter((path) => !isExcludedPath(path));
+    if (allTargetPaths.length > 0 && filePaths.length === 0) {
+        emitAllow(); // every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate
+        return;
+    }
+    // Target lock runs before the fact gate and independent of clearance: a
+    // wrong-repo write is wrong even with perfect facts. Excluded paths were
+    // already filtered out above, so an explicitly-excluded scratch dir outside
+    // the root is never target-locked.
+    if (TARGET_LOCK_ON) {
+        const projectRoot = resolveProjectRoot();
+        const stray = filePaths.find((path) => isTargetOutsideRoot(path, projectRoot));
+        if (stray) {
+            emitDeny(buildTargetLockReason(stray, projectRoot));
+            return;
+        }
+    }
     const filePath = firstUnclearedFilePath(toolInput, state);
     const factsFlagged = toolInput._gateguard_facts_presented === true;
     const alreadyCleared = filePaths.length > 0 && filePaths.every((path) => isFileCleared(state, path));

package/plugins/continuous-improvement/lib/gateguard-state.mjs

@@ -59,7 +59,11 @@ function sanitizeSessionId(sessionId) {
         return "";
     return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
 }
-function resolveProjectRoot() {
+// Exported for the target-lock gate (RISA 2 / G2): the hook compares a mutating
+// call's absolute target against this root to catch wrong-repo / wrong-worktree
+// writes. Returns "global" when no CLAUDE_PROJECT_DIR and no git toplevel — the
+// caller treats that as "no known root, do not guess".
+export function resolveProjectRoot() {
     const fromEnv = process.env.CLAUDE_PROJECT_DIR;
     if (fromEnv)
         return fromEnv;

package/plugins/continuous-improvement/skills/README.md

@@ -30,7 +30,7 @@ skill set on disk.
 - `grill-with-docs` — Enforces Law 1 (Research Before Executing) and Law 7 (Learn From Every Session) of the 7 Laws of AI Agent Discipline. Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates CONTEXT.md + ADRs inline as decisions crystallise. Ported from mattpocock/skills under MIT.
 - `handoff` — Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline. Compact the current conversation into a handoff document for another agent to pick up. Ported from mattpocock/skills under MIT.
 - `intent-driven-development` — Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Turn an ambiguous or high-impact change into scoped, verifiable acceptance criteria (observable AC-NNN, explicit in/out scope, named verification methods, and a [revised] protocol that forbids silently dropping a criterion) before or alongside implementation, so the plan that gets built is the plan that was agreed, not an invented default. Use when clarifying a feature, defining acceptance criteria, de-risking a security/data/migration/integration change, or preparing implementation requirements for another agent. Do not trigger for trivial edits, straightforward fixes, active debugging, or code review.
-- `reconcile` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, and verifies a push actually landed instead of assuming it did.
+- `reconcile` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, then carries the known-good state through to a landed PR: stage by filename, commit one concern, push the feature branch, verify the push landed, open the PR, and after the PR merges fast-forward the default branch and check it out.
 - `recovery-classification` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. After any failure in the verification ladder or auto-loop, classify the failure class before retrying — provider, tool-schema, deterministic-policy, git, worktree, runtime — so retry-vs-pause-vs-self-heal-vs-stop is an intentional decision, not a generic 'try again'.
 - `roast` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Convene a 5-persona adversarial council (Contrarian, Expansionist, Logician, Researcher, Buyer) that attacks an idea from every angle, then a Judge returns one GO / RESHAPE / KILL verdict plus the cheapest 48-hour test to de-risk it — so you pressure-test an idea before sinking time into building the wrong thing.
 - `safety-guard` — Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.

package/plugins/continuous-improvement/skills/gateguard/SKILL.md

@@ -150,6 +150,14 @@ The block reason prints the exact `gateguard-session.json` path and the clearanc
 
 The inline `_gateguard_facts_presented: true` retry still works on harnesses that forward unknown tool params, but Claude Code's strict tool schema (`additionalProperties: false`) rejects it with `InputValidationError` — use one of the above on Claude Code.
 
+### Excluding low-risk paths
+
+Set the `CI_GATEGUARD_EXCLUDE` environment variable to opt specific low-risk paths out of the gate entirely — an LLM-maintained prose wiki, a generated scratch directory, anything where the fact-forcing pause costs more than it saves. The value is a comma-separated list of path substrings, each matched case-insensitively against the forward-slash-normalized file path, so `/mywiki/` excludes `D:\Vault\MyWiki\notes\x.md`. Unset or empty (the default) changes nothing: every mutating file call is gated exactly as before, and a call that touches a mix of excluded and non-excluded paths still gates the non-excluded ones. Set it per project in `.claude/settings.json` under `env`, or globally in `~/.claude/settings.json`.
+
+### Locking edits to the current repo
+
+A fact-list can't catch a wrong-repo or wrong-worktree write — you can present perfect facts about the wrong file, in the wrong checkout. Set `CI_GATEGUARD_TARGET_LOCK=block` to make the runtime hook (`hooks/gateguard.mjs`) refuse any mutating call whose **absolute** target canonicalizes outside the session project root (`CLAUDE_PROJECT_DIR`, or the git toplevel). Relative paths resolve under the current directory (= the root) and always pass; only an absolute path into a different tree is denied, and the deny reason names both the stray target and the expected root. This runs before the fact gate and independent of clearance — a wrong-repo write is wrong even with facts. Unset (the default) checks nothing, so legitimate out-of-root edits (`~/.claude`, a `/tmp` scratch file, a sibling repo) are unaffected; turn it on per session in a multi-worktree or headless run where cross-repo writes are the real risk. Paths already covered by `CI_GATEGUARD_EXCLUDE` are never target-locked.
+
 ### Limitations and guarantees
 
 - **Honor system.** Clearance is recorded by `ci_gateguard_clear`, the `gateguard-clear.mjs` CLI, a manual state-file write, or the inline `_gateguard_facts_presented` flag where the harness allows it (see "Clearing the gate" above). The hook can't verify the investigation actually happened; the 50-file cap — counted per session — bounds damage from stuck loops or rogue agents.
@@ -175,6 +183,8 @@ The standalone `gateguard-ai` Python/CLI package referenced in earlier drafts of
 - Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
 - Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
 - Use `.gateguard.yml` to ignore paths like `.venv/`, `node_modules/`, `.git/`.
+- For the shipped runtime hook, set `CI_GATEGUARD_EXCLUDE` (comma-separated path substrings) to exclude low-risk paths from the gate — see [Excluding low-risk paths](#excluding-low-risk-paths).
+- In multi-worktree or headless runs, set `CI_GATEGUARD_TARGET_LOCK=block` so a write into the wrong repo/worktree is refused — see [Locking edits to the current repo](#locking-edits-to-the-current-repo).
 
 ## Related Skills
 

package/plugins/continuous-improvement/skills/reconcile/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: reconcile
 tier: "2"
-description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, and verifies a push actually landed instead of assuming it did.
+description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, then carries the known-good state through to a landed PR: stage by filename, commit one concern, push the feature branch, verify the push landed, open the PR, and after the PR merges fast-forward the default branch and check it out.
 origin: continuous-improvement
 user-invocable: true
 ---
 
-# Reconcile — Ground-Truth Git State Before You Touch It
+# Reconcile — Ground Truth, Then Commit, Push, and Open the PR
 
-Law 1 says research before executing. The most expensive skipped research is the state of your own repo: a branch that shifted under you, a push that silently did not land, a stash from a session you forgot. This skill establishes git ground truth first, acts only on a known state, and stops at every operation that is hard to reverse.
+Law 1 says research before executing. The most expensive skipped research is the state of your own repo: a branch that shifted under you, a push that silently did not land, a stash from a session you forgot. This skill establishes git ground truth first, acts only on a known state, stops at every operation that is hard to reverse, and then carries that known-good state all the way through a single-concern commit, a push, and an open PR — ending back on an up-to-date default branch once the PR merges.
 
 ## When to Activate
 
 - Before any branch/merge/rebase/push when more than one session, loop, or agent may be writing to the tree.
 - When the working tree looks different from what you expect (unexpected branch, surprise modifications, a half-finished merge).
 - Before cleaning up: consolidating branches, dropping stashes, removing worktrees.
+- When finished work needs to land: stage it, commit one concern, push a feature branch, open a PR, and return to an up-to-date default branch.
 - After a push, to confirm it actually landed on the remote.
 
 ## Establish Ground Truth First
@@ -24,7 +25,7 @@ Read before you write. Capture the full state in one pass:
 ```
 git branch --show-current
 git status --porcelain=v1
-git rev-list --left-right --count @{u}...HEAD     # behind / ahead of upstream
+git rev-list --left-right --count '@{u}...HEAD'     # behind / ahead of upstream (quote the ref — bare @{u} trips the Bash parser)
 git stash list
 git worktree list
 ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null   # in-progress operation?
@@ -57,10 +58,43 @@ Branch from a base only after confirming `local <base>` equals `origin/<base>`
 STOP and get explicit authorization before:
 
 - Pushing to a protected branch (e.g. `main`) — this repo's flow is feature branch + PR, never direct push.
+- Merging the PR you opened, or force-deleting a branch (`git branch -D`) — both stay human decisions, never auto-actions on green CI.
 - `git push --force` / `--force-with-lease`, `git reset --hard`, `git clean -fd`, `worktree remove` on a dirty worktree, or dropping a stash with uncommitted value.
 
 If a rebase has diverged and force-push is gated, do not force-recover — supersede via a new branch + new PR.
 
+## Commit and Open the PR
+
+Once ground truth is known and the halt gates are clear, carry the work to an open PR without leaving the known-good state. This tail is self-contained — it reimplements the commit → push → PR steps with plain git/`gh` and depends on no companion plugin.
+
+1. **Cut or confirm a feature branch from a fresh base.** Never commit onto a protected branch. Sync the default branch first so the feature branch is not born stale:
+   ```
+   git switch main && git pull --ff-only origin main    # master on older repos
+   git switch -c <type>/<slug>                           # only if not already on a feature branch
+   ```
+   Confirm `local main` equals `origin/main` before branching — a squash-merge otherwise bundles ahead-of-origin commits.
+
+2. **Stage by explicit filename.** One concern per commit. On an `autocrlf` tree `git add -A` / `git add .` commits phantom line-ending-only changes — name each path and read real drift with `git diff --stat`.
+   ```
+   git add path/one path/two
+   ```
+
+3. **Commit with a Windows-safe message.** Lead with the observable outcome. Use a single-line `-m` (repeat `-m` for paragraphs) or `git commit -F <tempfile>` — never a multi-line here-doc/here-string, which CRLF and shell quoting corrupt on Windows.
+   ```
+   git commit -m "feat(scope): <observable outcome>"
+   ```
+
+4. **Push the feature branch** (never the protected branch), then verify it landed via the section below:
+   ```
+   git push -u origin <type>/<slug>
+   ```
+
+5. **Open one PR** citing the plan or issue, then stop:
+   ```
+   gh pr create --fill --base main
+   ```
+   **Stop here.** The merge is a human decision. `reconcile` never merges the PR, never uses `--admin` / `--force` / `--no-verify`, never auto-merges on green CI, and never deploys.
+
 ## Verify the Push Actually Landed
 
 A push that printed no error is still a claim. Confirm:
@@ -72,9 +106,23 @@ git ls-remote origin refs/heads/<branch>     # remote tip must equal local HEAD
 
 If the remote ref is absent or behind, the push did not land — investigate before reporting success.
 
+## Sync the Default Branch After the PR Merges
+
+"All the latest work on main" is only true once the PR actually merges — and on a protected branch that merge is a human action, not something `reconcile` performs. After the merge lands, return to an up-to-date default branch:
+
+```
+git switch main                        # or master on older repos
+git pull --ff-only origin main         # fast-forward only; never a merge commit or --force
+git rev-parse HEAD                     # confirm this equals the squash-merge SHA from the PR
+git branch -d <type>/<slug>            # delete the merged feature branch (safe -d, never -D)
+```
+
+`--ff-only` is deliberate: if the pull would not fast-forward, main diverged under you — stop and re-survey from **Establish Ground Truth First** instead of forcing it. You end on the default branch with every merged change present and the feature branch cleaned up.
+
 ## Pairs With
 
 - **`recall`** (Law 1) — before a risky git op, recall whether the same operation failed on this repo before.
 - **`gateguard`** (Law 1) — the runtime gate (`hooks/gateguard.mjs`); `reconcile` is the procedure you run once a destructive git action is in play.
 - **`safety-guard`** — destructive-operation guardrails for production and autonomous runs.
 - **`audit`** (Law 4) — when an audit ends in a fix, `reconcile` is the safe path from branch to landed PR.
+- **`commit-commands:commit-push-pr`** — the external-plugin equivalent of the commit → push → PR tail; `reconcile` reimplements it inline so the flow works with no companion installed. For a TDD-gated single-defect variant, use `/ship`.

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
   "tools": [

package/skills/gateguard.md

@@ -150,6 +150,14 @@ The block reason prints the exact `gateguard-session.json` path and the clearanc
 
 The inline `_gateguard_facts_presented: true` retry still works on harnesses that forward unknown tool params, but Claude Code's strict tool schema (`additionalProperties: false`) rejects it with `InputValidationError` — use one of the above on Claude Code.
 
+### Excluding low-risk paths
+
+Set the `CI_GATEGUARD_EXCLUDE` environment variable to opt specific low-risk paths out of the gate entirely — an LLM-maintained prose wiki, a generated scratch directory, anything where the fact-forcing pause costs more than it saves. The value is a comma-separated list of path substrings, each matched case-insensitively against the forward-slash-normalized file path, so `/mywiki/` excludes `D:\Vault\MyWiki\notes\x.md`. Unset or empty (the default) changes nothing: every mutating file call is gated exactly as before, and a call that touches a mix of excluded and non-excluded paths still gates the non-excluded ones. Set it per project in `.claude/settings.json` under `env`, or globally in `~/.claude/settings.json`.
+
+### Locking edits to the current repo
+
+A fact-list can't catch a wrong-repo or wrong-worktree write — you can present perfect facts about the wrong file, in the wrong checkout. Set `CI_GATEGUARD_TARGET_LOCK=block` to make the runtime hook (`hooks/gateguard.mjs`) refuse any mutating call whose **absolute** target canonicalizes outside the session project root (`CLAUDE_PROJECT_DIR`, or the git toplevel). Relative paths resolve under the current directory (= the root) and always pass; only an absolute path into a different tree is denied, and the deny reason names both the stray target and the expected root. This runs before the fact gate and independent of clearance — a wrong-repo write is wrong even with facts. Unset (the default) checks nothing, so legitimate out-of-root edits (`~/.claude`, a `/tmp` scratch file, a sibling repo) are unaffected; turn it on per session in a multi-worktree or headless run where cross-repo writes are the real risk. Paths already covered by `CI_GATEGUARD_EXCLUDE` are never target-locked.
+
 ### Limitations and guarantees
 
 - **Honor system.** Clearance is recorded by `ci_gateguard_clear`, the `gateguard-clear.mjs` CLI, a manual state-file write, or the inline `_gateguard_facts_presented` flag where the harness allows it (see "Clearing the gate" above). The hook can't verify the investigation actually happened; the 50-file cap — counted per session — bounds damage from stuck loops or rogue agents.
@@ -175,6 +183,8 @@ The standalone `gateguard-ai` Python/CLI package referenced in earlier drafts of
 - Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
 - Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
 - Use `.gateguard.yml` to ignore paths like `.venv/`, `node_modules/`, `.git/`.
+- For the shipped runtime hook, set `CI_GATEGUARD_EXCLUDE` (comma-separated path substrings) to exclude low-risk paths from the gate — see [Excluding low-risk paths](#excluding-low-risk-paths).
+- In multi-worktree or headless runs, set `CI_GATEGUARD_TARGET_LOCK=block` so a write into the wrong repo/worktree is refused — see [Locking edits to the current repo](#locking-edits-to-the-current-repo).
 
 ## Related Skills
 

package/skills/reconcile.md

@@ -1,20 +1,21 @@
 ---
 name: reconcile
 tier: "2"
-description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, and verifies a push actually landed instead of assuming it did.
+description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Establishes git ground truth — branch, status, stashes, worktrees, ahead/behind — before any mutation, halts on protected or destructive operations, then carries the known-good state through to a landed PR: stage by filename, commit one concern, push the feature branch, verify the push landed, open the PR, and after the PR merges fast-forward the default branch and check it out.
 origin: continuous-improvement
 user-invocable: true
 ---
 
-# Reconcile — Ground-Truth Git State Before You Touch It
+# Reconcile — Ground Truth, Then Commit, Push, and Open the PR
 
-Law 1 says research before executing. The most expensive skipped research is the state of your own repo: a branch that shifted under you, a push that silently did not land, a stash from a session you forgot. This skill establishes git ground truth first, acts only on a known state, and stops at every operation that is hard to reverse.
+Law 1 says research before executing. The most expensive skipped research is the state of your own repo: a branch that shifted under you, a push that silently did not land, a stash from a session you forgot. This skill establishes git ground truth first, acts only on a known state, stops at every operation that is hard to reverse, and then carries that known-good state all the way through a single-concern commit, a push, and an open PR — ending back on an up-to-date default branch once the PR merges.
 
 ## When to Activate
 
 - Before any branch/merge/rebase/push when more than one session, loop, or agent may be writing to the tree.
 - When the working tree looks different from what you expect (unexpected branch, surprise modifications, a half-finished merge).
 - Before cleaning up: consolidating branches, dropping stashes, removing worktrees.
+- When finished work needs to land: stage it, commit one concern, push a feature branch, open a PR, and return to an up-to-date default branch.
 - After a push, to confirm it actually landed on the remote.
 
 ## Establish Ground Truth First
@@ -24,7 +25,7 @@ Read before you write. Capture the full state in one pass:
 ```
 git branch --show-current
 git status --porcelain=v1
-git rev-list --left-right --count @{u}...HEAD     # behind / ahead of upstream
+git rev-list --left-right --count '@{u}...HEAD'     # behind / ahead of upstream (quote the ref — bare @{u} trips the Bash parser)
 git stash list
 git worktree list
 ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null   # in-progress operation?
@@ -57,10 +58,43 @@ Branch from a base only after confirming `local <base>` equals `origin/<base>`
 STOP and get explicit authorization before:
 
 - Pushing to a protected branch (e.g. `main`) — this repo's flow is feature branch + PR, never direct push.
+- Merging the PR you opened, or force-deleting a branch (`git branch -D`) — both stay human decisions, never auto-actions on green CI.
 - `git push --force` / `--force-with-lease`, `git reset --hard`, `git clean -fd`, `worktree remove` on a dirty worktree, or dropping a stash with uncommitted value.
 
 If a rebase has diverged and force-push is gated, do not force-recover — supersede via a new branch + new PR.
 
+## Commit and Open the PR
+
+Once ground truth is known and the halt gates are clear, carry the work to an open PR without leaving the known-good state. This tail is self-contained — it reimplements the commit → push → PR steps with plain git/`gh` and depends on no companion plugin.
+
+1. **Cut or confirm a feature branch from a fresh base.** Never commit onto a protected branch. Sync the default branch first so the feature branch is not born stale:
+   ```
+   git switch main && git pull --ff-only origin main    # master on older repos
+   git switch -c <type>/<slug>                           # only if not already on a feature branch
+   ```
+   Confirm `local main` equals `origin/main` before branching — a squash-merge otherwise bundles ahead-of-origin commits.
+
+2. **Stage by explicit filename.** One concern per commit. On an `autocrlf` tree `git add -A` / `git add .` commits phantom line-ending-only changes — name each path and read real drift with `git diff --stat`.
+   ```
+   git add path/one path/two
+   ```
+
+3. **Commit with a Windows-safe message.** Lead with the observable outcome. Use a single-line `-m` (repeat `-m` for paragraphs) or `git commit -F <tempfile>` — never a multi-line here-doc/here-string, which CRLF and shell quoting corrupt on Windows.
+   ```
+   git commit -m "feat(scope): <observable outcome>"
+   ```
+
+4. **Push the feature branch** (never the protected branch), then verify it landed via the section below:
+   ```
+   git push -u origin <type>/<slug>
+   ```
+
+5. **Open one PR** citing the plan or issue, then stop:
+   ```
+   gh pr create --fill --base main
+   ```
+   **Stop here.** The merge is a human decision. `reconcile` never merges the PR, never uses `--admin` / `--force` / `--no-verify`, never auto-merges on green CI, and never deploys.
+
 ## Verify the Push Actually Landed
 
 A push that printed no error is still a claim. Confirm:
@@ -72,9 +106,23 @@ git ls-remote origin refs/heads/<branch>     # remote tip must equal local HEAD
 
 If the remote ref is absent or behind, the push did not land — investigate before reporting success.
 
+## Sync the Default Branch After the PR Merges
+
+"All the latest work on main" is only true once the PR actually merges — and on a protected branch that merge is a human action, not something `reconcile` performs. After the merge lands, return to an up-to-date default branch:
+
+```
+git switch main                        # or master on older repos
+git pull --ff-only origin main         # fast-forward only; never a merge commit or --force
+git rev-parse HEAD                     # confirm this equals the squash-merge SHA from the PR
+git branch -d <type>/<slug>            # delete the merged feature branch (safe -d, never -D)
+```
+
+`--ff-only` is deliberate: if the pull would not fast-forward, main diverged under you — stop and re-survey from **Establish Ground Truth First** instead of forcing it. You end on the default branch with every merged change present and the feature branch cleaned up.
+
 ## Pairs With
 
 - **`recall`** (Law 1) — before a risky git op, recall whether the same operation failed on this repo before.
 - **`gateguard`** (Law 1) — the runtime gate (`hooks/gateguard.mjs`); `reconcile` is the procedure you run once a destructive git action is in play.
 - **`safety-guard`** — destructive-operation guardrails for production and autonomous runs.
 - **`audit`** (Law 4) — when an audit ends in a fix, `reconcile` is the safe path from branch to landed PR.
+- **`commit-commands:commit-push-pr`** — the external-plugin equivalent of the commit → push → PR tail; `reconcile` reimplements it inline so the flow works with no companion installed. For a TDD-gated single-defect variant, use `/ship`.

package/templates/actions_security_checklist.md

@@ -0,0 +1,39 @@
+# GitHub Actions Security Checklist
+
+> Apply to every workflow in `.github/workflows/`. Each item is checkable by reading the YAML — no runtime access needed. The `audit-actions` command automates the mechanical checks; this checklist is the human review layer.
+
+## Permissions
+
+- [ ] Workflow (or every job) declares explicit `permissions:` — never relies on the default token grant
+- [ ] Default is `permissions: contents: read`; write scopes are added per-job only where provably needed
+- [ ] No `permissions: write-all`
+- [ ] Workflows triggered by `pull_request_target`, `issue_comment`, or `issues` do NOT get write tokens or secrets unless a maintainer-approval gate exists
+
+## Untrusted input
+
+- [ ] No direct interpolation of `github.event.*` text (issue/PR title, body, comment, branch name, commit message) inside `run:` shell — pass through `env:` and quote as `"$VAR"`
+- [ ] Untrusted content passed to agents/LLMs is wrapped in a prompt boundary and stripped of tool-invocation-looking text
+- [ ] `actions/checkout` of PR head refs in privileged contexts is treated as executing untrusted code
+
+## Supply chain
+
+- [ ] Third-party actions are pinned to a full commit SHA (tags are mutable); first-party `actions/*` at minimum pinned to a major version
+- [ ] No `curl | bash` of unpinned remote scripts
+- [ ] Artifacts downloaded from other workflows are treated as untrusted input
+
+## Runaway control
+
+- [ ] Every job has `timeout-minutes`
+- [ ] Workflows that deploy or mutate state declare `concurrency:` with a stable group key
+- [ ] Scheduled/agentic workflows have an explicit cost ceiling (matrix size, iteration cap)
+
+## Agentic workflows
+
+- [ ] Agent runs triggered by issue/PR/comment text run with read-only tokens
+- [ ] A human approves before any agent-generated change is pushed or merged
+- [ ] Prompt boundary and tool boundary are logged for each agent run
+
+## Secrets
+
+- [ ] Secrets are not exposed to workflows runnable by untrusted PRs
+- [ ] No secrets echoed to logs or written to artifacts

package/templates/experiment_template.md

@@ -0,0 +1,38 @@
+# Experiment
+
+> One file per experiment. Copy to `.experiments/<YYYY-MM-DD>-<slug>.md`. No experiment record = no claim of learning.
+
+## Definition
+
+| Field | Value |
+|---|---|
+| Experiment name | |
+| Lane | trading / quran / workflow / infra |
+| Repo | |
+| Owner | |
+| Feature flag (if any) | |
+| Start date | |
+| Stop date (hard stop — decide even if inconclusive) | |
+
+## Hypothesis
+
+State as: "If we [change], then [segment] will [measurable behavior], because [reasoning]."
+
+## Metrics
+
+- Primary metric (one only):
+- Pass threshold (exact number):
+- Guardrail metric (what must NOT get worse):
+- Segment (who is measured):
+
+## Result
+
+Fill after stop date. Do not leave open past the stop date.
+
+- Observed primary metric:
+- Guardrail status:
+- Evidence links (dashboards, exports, screenshots):
+
+## Decision
+
+One of: **ship** / **iterate** / **kill**. State the decision and the single next action.