continuous-improvement 3.16.0 → 3.18.0

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.16.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/intent-driven-development.md

@@ -0,0 +1,161 @@
+---
+name: intent-driven-development
+tier: "2"
+description: "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."
+origin: continuous-improvement
+user-invocable: true
+argument-hint: "[the change to scope into acceptance criteria]"
+---
+
+# /intent-driven-development: scope the change before you build it
+
+Law 2 says the plan is sacred: once a goal and its acceptance conditions are agreed, you do not silently drift from them. The cheapest way to honor that is to make the plan verifiable in the first place. A goal phrased as "make export work" cannot be held sacred because nobody can tell when it is met. This skill converts an ambiguous or high-impact request into observable acceptance criteria (`AC-001`, `AC-002`, ...) with named verification methods, so "done" is a fact two people would agree on, and a criterion can never be quietly dropped mid-build.
+
+It produces useful criteria without turning specification into ceremony: inspect available context first, expose only genuine ambiguity, and choose verification that fits the work and its risk.
+
+## When to activate
+
+- The user asks to clarify a feature, define acceptance criteria, or de-risk a change before implementation.
+- The request touches security, authentication, persistent data, migrations, external APIs, or compliance.
+- The user wants a handoff artifact another agent or team can implement without inventing requirements.
+- The request is ambiguous enough that the expected outcome is not yet observable or testable.
+- The user types `/intent-driven-development`, "define acceptance criteria", "scope this change", or "make this testable".
+
+Do not activate for trivial edits, one-line fixes, active debugging, code review, or implementation requests whose acceptance conditions are already clear.
+
+## How it works
+
+1. **Inspect context first.** Read the repository, docs, schemas, and test infrastructure for technical facts before asking any question. Treat product and business constraints as something only the user or a product artifact can supply.
+2. **Choose depth.** Quick Capture (3-7 criteria, low or moderate risk) or Full Acceptance Brief (security, data, migration, cross-system, or handoff).
+3. **Ask minimally.** Only ask questions whose answers cannot be inferred and that materially change scope or behavior. Group related questions into one batch.
+4. Write observable criteria. Each AC-NNN names a scenario, a trigger, an expected observable result, a prohibited side effect when meaningful, a verification method, and a priority. Do not use "correctly" or "securely" without defined evidence.
+5. **Proceed or hand off.** For a clear request with no blocking risk, record the criteria and continue. For a risky change, present the blockers and wait for confirmation.
+6. **Hold the plan sacred.** If a criterion cannot be met due to a constraint found mid-build, do not silently drop or work around it. Mark it `[revised]`, state the constraint, adjust scope or verification, increment the revision number, and re-present only the changed criteria before continuing.
+
+## Operating rules
+
+1. Inspect available repository, docs, issue, design, and test context before asking for technical facts that can be discovered locally.
+2. Do not infer product or business constraints from code. Business rules, compliance obligations, contractual SLAs, pricing, data-retention policy, prioritization, and target users cannot be read from a repository. Record them as assumptions flagged for confirmation, never as discovered facts. The repository tells you how the system behaves today, not what the business requires it to do.
+3. Ask only questions whose answers are required and cannot be safely inferred.
+4. Do not block implementation by default. When the user has asked to implement a sufficiently clear change, record key assumptions and criteria briefly, then proceed or hand them to the implementation workflow.
+5. Require explicit confirmation before proceeding only when an unresolved decision could create material security exposure, data loss, irreversible migration, contractual or API breakage, meaningful cost, or destructive external action.
+6. Do not write an acceptance document into a repository, alter project files, create a branch, commit, or invoke another skill unless the user requests it or the active workflow requires it.
+7. Treat automated tests as evidence, not truth. Prefer automation when reliable and proportionate; allow manual UX, accessibility, security, legal, or operational verification where automation cannot establish the outcome.
+8. Never include real secrets, credentials, tokens, private keys, personal data, or production payloads in criteria, fixtures, examples, or saved artifacts. Use redacted or synthetic values.
+9. Do not run destructive tests, migrations, security probes, load tests, paid external calls, or operations against production data without explicit authorization and an identified safe environment.
+10. When a criterion cannot be satisfied due to a constraint discovered during implementation, update it (`[revised]`, state the constraint, adjust scope or verification), increment the revision, and re-present only the changed criteria. Require confirmation only if the revision changes a blocking decision or reduces a safety or correctness guarantee.
+
+## Choose the depth
+
+Use the smallest useful output.
+
+### Quick Capture
+
+For a clear but non-trivial change with low or moderate risk. Produce: Goal; In scope and out of scope; Assumptions; 3-7 acceptance criteria with verification methods; blocking questions if any. Do not delay implementation for approval unless a blocking risk exists or the user asked for a spec first.
+
+### Full Acceptance Brief
+
+For ambiguous, cross-system, security-sensitive, data-changing, migration, compliance, or high-cost changes, or when the user wants a handoff artifact. Produce the full template below and request confirmation for unresolved blocking decisions before risky implementation.
+
+### Existing specification review
+
+When the user already supplied a PRD, issue, plan, or criteria: review it instead of restarting discovery. Identify missing scope boundaries, unsafe assumptions, contradictions, and unverifiable requirements. Return corrected or supplemental criteria.
+
+## Write acceptance criteria
+
+Use `AC-001`, `AC-002`, and so on. Criteria and tests need not map one-to-one. For each applicable criterion include: scenario or starting condition; action or trigger; expected observable behavior; prohibited side effect when meaningful; verification method (automated test, integration check, manual UX review, accessibility check, security review, operational check, or stakeholder acceptance); environment or safety constraint when verification could affect data, services, cost, or secrets; priority (Required, Important, or Optional).
+
+Do not use "correctly", "securely", "fast", "intuitive", or "robust" without defining observable evidence or recording them as a human-review judgment.
+
+Cover only the boundaries that apply:
+
+| Category | Include when | Typical evidence |
+| --- | --- | --- |
+| Happy path | New or changed user-visible behavior | Successful workflow or state transition |
+| Validation | The change accepts input | Malformed or boundary value rejected without mutation |
+| Authorization/privacy | Data or actions have access boundaries | Denied access and no sensitive disclosure |
+| Persistence/migration | Stored data or schemas change | Backward read, migration, rollback, or backup behavior |
+| Compatibility | Public APIs, files, events, or clients may break | Existing contract or fixture stays valid |
+| Failure recovery | Network, service, or async failure exists | No partial state, or clear retry and degraded behavior |
+| Idempotency/concurrency | Repeats or simultaneous writes are plausible | No duplicate side effect or invalid final state |
+| Performance | A user or service threshold matters | Defined measurement conditions and threshold |
+| UX/accessibility | A person interacts with the result | Keyboard, feedback, error recovery, visual or manual review |
+
+## Output template (Full Acceptance Brief)
+
+Omit irrelevant sections for Quick Capture.
+
+```markdown
+# Acceptance Brief: <Change Name>
+
+**Status:** Draft | Approved | Implemented | Verified
+**Revision:** <number>
+**Prepared for:** <user/team/agent, when known>
+
+## Goal
+<One observable outcome sentence.>
+
+## Scope
+**In scope:** <behavior included>
+**Out of scope:** <adjacent work excluded>
+
+## Context
+**Discovered facts** (technical, verified from repository or artifact)
+**Product/business constraints** (supplied by user or artifact, never inferred from code, or "none supplied yet")
+**Assumptions** (unverified claims to confirm)
+**Dependencies and constraints**
+
+## Risk Review
+| Risk area | Applies? | Required handling |
+| --- | --- | --- |
+| Security/privacy | Yes/No | <redaction, authorization, review> |
+| Persistent data/migration | Yes/No | <compatibility, backup, rollback> |
+| External effects/cost | Yes/No | <sandbox, test environment, authorization> |
+| Compatibility/API | Yes/No | <contract to preserve or version> |
+| UX/accessibility | Yes/No | <manual or automated evidence> |
+
+## Acceptance Criteria
+### AC-001: <observable behavior>
+- **Scenario:** <starting condition>
+- **Action:** <single trigger>
+- **Expected:** <observable result>
+- **Must not:** <prohibited side effect, if applicable>
+- **Verification:** <method and intended evidence>
+- **Environment/safety:** <constraints, if applicable>
+- **Priority:** Required | Important | Optional
+
+## Blocking Decisions
+- [ ] <only decisions that prevent safe or correct progress>
+
+## Verification Plan
+| Criterion | Verification evidence | Status |
+| --- | --- | --- |
+| AC-001 | <test, check, or review command or evidence type> | Pending |
+```
+
+## Pass/fail rubric
+
+A brief passes only if every answer is "yes". Any "no" means revise before returning it.
+
+- [ ] Does every required criterion have a scenario, an observable expected result, and a named verification method?
+- [ ] Are vague terms ("correctly", "secure", "fast", "robust") either replaced with observable evidence or marked as human judgment?
+- [ ] Are product and business constraints listed as supplied or assumed, with none silently inferred from code?
+- [ ] Is scope explicit, with out-of-scope items named?
+- [ ] Are blocking decisions limited to choices that actually affect safety or correctness, not preferences?
+
+A failing criterion: `AC-001: The export works correctly and is secure.` (no scenario, no observable result, no verification, "correctly" and "secure" undefined). A passing one names the scenario, the expected result, the prohibited side effect, and the verification method, so two people would agree it was met.
+
+## How it fits the 7 Laws
+
+| Law | Role of this skill |
+|---|---|
+| Law 2 (Plan Is Sacred) | The acceptance brief **is** the sacred plan: observable criteria, explicit scope, and a `[revised]` protocol that forbids silently dropping or working around a criterion mid-build. |
+| Law 1 (Research Before Executing) | Rule 1 inspects repo, docs, schemas, and tests for technical facts before asking, and refuses to infer business rules from code. |
+| Law 4 (Verify Before Reporting) | Every criterion carries a named verification method and a pass/fail rubric, so "done" is falsifiable rather than asserted. |
+
+## Pairs with
+
+- [`grill-me`](./grill-me.md): interviews a fuzzy request to a shippable spec. Reach for `grill-me` when the input is unclear, then this skill to turn the agreed intent into verifiable criteria.
+- [`roast`](./roast.md): validates whether the idea should exist at all. Roast first, then scope the survivor into acceptance criteria.
+- [`goal-monitor`](./goal-monitor.md): the runtime drift gate. The `## Goal` and criteria this skill produces are what goal-monitor scores a session against.
+- [`verification-loop`](./verification-loop.md): runs the per-project verify ladder. The criteria's verification methods feed its evidence step.

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)