continuous-improvement 3.17.0 → 3.19.0

package/plugins/continuous-improvement/lib/typecheck-gate.mjs

@@ -0,0 +1,62 @@
+/**
+ * Pure decision helpers for the typecheck Stop gate (RISA 4 / G4).
+ *
+ * The hook (src/hooks/typecheck-stop.mts) does the I/O — git, spawning the
+ * typecheck, emitting the decision. Everything here is pure and unit-tested so
+ * the mode/selection/formatting logic is provable without spawning a compiler.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   - off   : no-op. The default. The global ~/.claude typecheck-changed.sh
+ *             already emits an advisory systemMessage; this hook stays silent
+ *             until opted in, so there is no double-advisory and no regression.
+ *   - warn  : print a one-line notice to stderr; never blocks.
+ *   - block : emit {"decision":"block","reason":...} so the failure re-enters
+ *             model context — the fix headless/autonomous -p loops need.
+ */
+export function resolveTypecheckMode(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    return value === "block" || value === "warn" ? value : "off";
+}
+// Matches the extensions typecheck-changed.sh screens for. `.d.ts` ends in
+// `.ts` so it counts — a changed ambient declaration can still break the build.
+const TS_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+export function hasChangedTsFile(files) {
+    return files.some((file) => TS_FILE_RE.test(file.trim()));
+}
+// Split a `git diff --name-only` blob into a clean path list (drops blank lines).
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// Prefer the project's own `typecheck` npm script (authoritative — it encodes
+// the project's exact flags), else a local tsc, else null (a TS project with no
+// runnable typecheck stays silent rather than guessing).
+export function pickTypecheckKind(hasNpmTypecheckScript, hasLocalTsc) {
+    if (hasNpmTypecheckScript)
+        return "npm";
+    if (hasLocalTsc)
+        return "tsc";
+    return null;
+}
+export function formatTypecheckReason(output, maxLines = 15) {
+    const tail = (output ?? "")
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .slice(-maxLines)
+        .join("\n");
+    return `Typecheck FAILED on changed TS files — fix before ending the turn:\n${tail}`;
+}
+// The single decision point. `ranTypecheck` is false when the gate short-circuited
+// (mode off, no TS project, no changed TS file, no runnable typecheck, or the run
+// timed out) — all of which allow. A conclusive non-zero rc maps to the mode.
+export function decideTypecheckAction(input) {
+    if (input.mode === "off")
+        return "allow";
+    if (!input.ranTypecheck)
+        return "allow";
+    if (input.rc === 0)
+        return "allow";
+    return input.mode;
+}

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.19.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.

package/templates/portfolio_event.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/templates/portfolio_event.schema.json",
+  "title": "PortfolioEvent",
+  "description": "Shared event schema for all repos in the portfolio. Every CI run, deploy, incident, experiment, agent action, security finding, release, decision, and metric snapshot is one event.",
+  "type": "object",
+  "required": ["eventId", "repo", "eventType", "occurredAt", "source"],
+  "additionalProperties": false,
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "description": "Globally unique id (uuid or <repo>-<timestamp>-<n>)."
+    },
+    "repo": {
+      "type": "string",
+      "description": "GitHub repo in owner/name form, e.g. naimkatiman/tradeclaw."
+    },
+    "eventType": {
+      "type": "string",
+      "enum": ["ci", "deploy", "incident", "experiment", "agent", "security", "release", "decision", "metric"]
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC timestamp."
+    },
+    "source": {
+      "type": "string",
+      "description": "What emitted the event: github-actions, wrangler, manual, agent:<name>, cron:<name>."
+    },
+    "actor": {
+      "type": "string",
+      "description": "Human or agent responsible, e.g. naimkatiman or agent:portfolio-health."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["success", "failure", "in_progress", "cancelled", "n/a"],
+      "description": "Outcome where applicable."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "low", "medium", "high", "critical"],
+      "description": "Required in practice for incident and security events."
+    },
+    "title": {
+      "type": "string",
+      "description": "One-line human-readable summary."
+    },
+    "evidenceUrl": {
+      "type": "string",
+      "description": "Link to the receipt: CI run, release receipt file, experiment file, dashboard."
+    },
+    "commitSha": {
+      "type": "string"
+    },
+    "metricName": {
+      "type": "string",
+      "description": "For metric events: stable snake_case metric name."
+    },
+    "metricValue": {
+      "type": "number",
+      "description": "For metric events: numeric value."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Event-type-specific payload. Keep flat and JSON-serializable."
+    }
+  }
+}

package/templates/release_receipt_template.md

@@ -0,0 +1,37 @@
+# Release Receipt
+
+> One receipt per release/deploy. Copy this file to `.releases/<YYYY-MM-DD>-<version-or-slug>.md`, fill every field, commit it with the release. A release without a receipt did not happen.
+
+## Identity
+
+| Field | Value |
+|---|---|
+| Repo | |
+| Version / tag | |
+| Commit SHA | |
+| Environment | production / staging / preview |
+| Released at (UTC) | |
+| Owner | |
+
+## What shipped
+
+- User-visible impact (one sentence, outcome not mechanism):
+- Feature flags changed (name, old value, new value):
+- Migrations run (file names, or "none"):
+
+## Verification
+
+- Tests run (exact commands + result):
+- Security scans run (tool + result, or "none"):
+- Manual verification performed:
+
+## Risk
+
+- Known risks accepted at release time:
+- Rollback command (exact, copy-pasteable):
+- Monitoring link (dashboard/logs to watch after release):
+
+## Sign-off
+
+- [ ] All fields above are filled (no blanks — use "none" explicitly)
+- [ ] Rollback command was verified to exist (not just guessed)