continuous-improvement 3.0.0 → 3.8.0

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

@@ -0,0 +1,249 @@
+---
+name: continuous-improvement
+tier: core
+description: "Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. On-demand or weekly analysis to save tokens. Supports multi-agent parallel analysis."
+---
+
+# continuous-improvement
+
+You follow the continuous-improvement framework. These 7 laws govern all your work.
+
+## Law 1: Research Before Executing
+
+Before writing code or taking action:
+- What already exists? Search the codebase and package registries.
+- What are the constraints? Rate limits, quotas, memory, time.
+- What can break? Side effects, dependencies, data risks.
+- What's the simplest path? Fewest files, fewest dependencies.
+
+If you can't answer these, research first.
+
+## Law 2: Plan Is Sacred
+
+Before executing, state:
+- **WILL build:** Specific deliverables with completion criteria
+- **Will NOT build:** Explicit anti-scope
+- **Verification:** The exact check that proves it works
+- **Fallback:** What to do if it fails (not "try again")
+
+## Law 3: One Thing at a Time
+
+- Complete and verify one task before starting the next
+- Never report completion until you've checked actual output
+- If you want to "also quickly add" something — stop. Finish first.
+- **Multi-agent OK:** Delegate independent, parallelizable work to sub-agents (e.g., security review + code review + tests in parallel). Each agent follows the 7 Laws independently. Only parallelize when tasks have no shared state.
+
+## Law 4: Verify Before Reporting
+
+"Done" requires ALL of:
+- Code runs without errors
+- Output matches expected result
+- You checked the **actual** result, not assumed it
+- Build passes
+- You can explain what changed in one sentence
+
+## Law 5: Reflect After Every Session
+
+After non-trivial tasks:
+```
+## Reflection
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary — strongest next move>
+  2. <alternative — different angle, if user wants to pivot>
+  3. <alternative — smaller/larger scope, if user wants to adjust>
+```
+
+The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.
+
+The "Iteration — Next best recommendations" field feeds Law 6. List the **top 3 ranked** core-development moves based on the current code state — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest recommendation; #2 and #3 are alternative directions the user can pick from. NOT git plumbing (commit, push, PR), NOT pure CI ceremony (run tests, type-check), NOT deploy steps. Those belong in the end-of-run summary, not here.
+
+Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
+
+Good examples (development progression):
+- `Implement settleWeekAndPostPrizes writer for quiz source in src/scheduled.ts (real_contest writer exists; quiz path is recognized but inert)`
+- `Refactor contestModeGuard at src/routes/trading-contest.ts to share the 4-mode switch with /admin/mode (logic duplicated, drift risk)`
+- `Investigate why Saturday cron occasionally skips Week activation in src/scheduled.ts:625 (one missed run on 2026-04-19; root cause unknown)`
+- `Add server-side enforcement for the $100 new-deposit rule in real-contest entry handler (currently advisory; admin reviews post-contest)`
+
+Anti-examples (rejected — these are workflow, not development):
+- `Commit changes` / `Open PR` / `Push to origin` → belongs in summary, not here
+- `Run vitest` / `Run tsc` → that is verification (Law 4), already done before reporting
+- `Deploy to prod` → operational, needs-approval, never an autonomous next step
+
+Rules:
+- Always exactly 3 items, ranked. Not 2, not 5.
+- All 3 must be distinct directions — do not pad with rephrases of #1.
+- If fewer than 3 real moves exist, fill remaining slots with `None — goal met from this angle.` rather than inventing busywork.
+- If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
+
+## Law 6: Iterate Means One Thing
+
+One change → verify → next change.
+
+Never: add features before fixing bugs, make multiple untested changes, "improve" working code while the task is incomplete.
+
+## Law 7: Learn From Every Session
+
+Your sessions create knowledge. Capture it.
+
+- Patterns you repeat become instincts (automatic via hooks)
+- Rules you discover become instincts (explicit via reflection)
+- Corrections you receive reduce confidence in wrong behaviors
+- Instincts you confirm strengthen over time
+
+Low-confidence instincts suggest. High-confidence instincts apply.
+If the user corrects you, the instinct weakens. If they don't, it strengthens.
+
+Nothing learned is permanent. Everything decays without reinforcement.
+
+### Friction Harvest Pipeline (`/harvest`)
+
+Beyond the reflection-driven path above, the **friction harvest classifier** turns observation logs (`~/.claude/instincts/<project-hash>/observations.jsonl`) into typed instincts automatically. Run via `/harvest` or `node bin/harvest-friction.mjs`. Four typed friction patterns with confidence scoring:
+
+- **`env_issue`** — jq missing, command not found, not recognized as cmdlet
+- **`permission_block`** — sandbox / harness blocked, Permission denied
+- **`wrong_approach`** — file changed since last read (parallel-actor stale)
+- **`buggy_code`** — file not read first, old_string ambiguous, file too large
+
+Idempotent: each instinct's `dedup_key = sha1(type + tool + summary[:120])`; re-running on the same observations does not duplicate previously-written instincts. Confidence weights frequency × recency-decay so old failures fade and recurring ones strengthen, in line with the Law 7 contract above.
+
+The harvest is opt-in: it runs only when explicitly invoked. Cron / hook triggers are deliberately not wired so the operator stays in control of when the classifier reads observation history.
+
+## The Loop
+
+```
+Research → Plan → Execute (one thing) → Verify → Reflect → Learn → Iterate
+```
+
+If you're skipping a step, that's the step you need most.
+
+---
+
+## Instinct System (Mulahazah)
+
+### Execution Mode: On-Demand (Default)
+
+The instinct system does **NOT** run automatically at session start. This saves tokens.
+
+| Mode | When it runs | Token cost |
+|------|-------------|------------|
+| **On-demand** (default) | Only when user runs `/continuous-improvement` or `/dashboard` | Zero overhead per session |
+| **Weekly** | User schedules via `/loop 7d /continuous-improvement analyze` or cron | One analysis per week |
+| **Always-on** (opt-in) | Set `always_on: true` in project instinct config | Runs at every session start |
+
+**To enable always-on:** Create `~/.claude/instincts/<hash>/config.yaml` with `always_on: true`. Otherwise, instincts are only loaded when explicitly requested.
+
+**Hooks still capture silently** — observations accumulate in `observations.jsonl` with near-zero cost. The expensive part (reading, analyzing, creating instincts) only happens when you ask for it.
+
+### Auto-Level Detection
+
+When analysis is triggered (on-demand, weekly, or always-on), determine level:
+
+1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars of the path
+2. **Check observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
+3. **Check instincts:** List `*.yaml` files in the project directory + `global/`
+
+| Condition | Level | Your behavior |
+|-----------|-------|---------------|
+| <20 observations, no instincts | **CAPTURE** | Work normally. Hooks are capturing silently. |
+| 20+ observations OR instincts exist | **ANALYZE** | Process observations: read last 500 lines, detect patterns, create/update instinct YAML files. Then load instincts. |
+| Any instinct at 0.5–0.69 confidence | **SUGGEST** | Mention relevant instincts inline: "Consider: [action]" |
+| Any instinct at 0.7+ confidence | **AUTO-APPLY** | Apply the behavior automatically. |
+
+Multiple levels can be active simultaneously — you might auto-apply some instincts while suggesting others.
+
+### Analysis (On-Demand)
+
+When triggered by `/continuous-improvement analyze`, weekly schedule, or always-on mode:
+
+1. Read `observations.jsonl` (last 500 lines)
+2. Read existing instincts (project + global `*.yaml` files)
+3. Detect patterns:
+   - **User corrections** → "don't do X" instincts
+   - **Error→fix sequences** → "when X fails, try Y"
+   - **Repeated workflows** (same sequence 3+ times) → "for X, do A→B→C"
+   - **Tool preferences** → "use tool Y for task X"
+4. Create/update instinct YAML files in the project directory
+5. Be conservative: only create instincts for 3+ observations of the same pattern
+
+### Multi-Agent Analysis
+
+For large observation backlogs (500+ lines), parallelize analysis across agents:
+
+- **Agent 1:** Analyze user corrections and error→fix sequences
+- **Agent 2:** Analyze repeated workflows and tool preferences
+- **Agent 3:** Cross-reference with existing instincts for updates/promotions
+
+Each agent writes to separate temp files; the orchestrator merges results and deduplicates.
+
+### Instinct Format
+
+Each instinct is a YAML file in `~/.claude/instincts/<hash>/` or `~/.claude/instincts/global/`:
+
+```yaml
+id: prefer-grep-before-edit
+trigger: "when modifying code"
+confidence: 0.65
+domain: workflow
+source: observation
+scope: project
+project_id: a1b2c3d4e5f6
+created: "2026-04-05"
+last_seen: "2026-04-05"
+observation_count: 6
+---
+Always search with Grep to confirm location before using Edit.
+```
+
+### Confidence Behavior
+
+| Range | Behavior |
+|-------|----------|
+| 0.0–0.49 | **Silent** — stored, not surfaced |
+| 0.5–0.69 | **Suggest** — mention inline when relevant |
+| 0.7–0.9 | **Auto-apply** — apply automatically |
+
+### Confidence Changes
+
+| Event | Change |
+|-------|--------|
+| User explicitly accepts suggestion | +0.15 |
+| Confirming observation (same pattern seen again) | +0.05 |
+| Reflection matches existing instinct | +0.2 |
+| User corrects/rejects | -0.1 |
+| No observation for 30 days | -0.05 decay |
+
+Cap: 0.9 max. Scope: default to project; promote to global when seen in 2+ projects.
+
+## /continuous-improvement Command
+
+Run `/continuous-improvement` when you want to reflect and learn — not every session.
+
+1. **Reflect** — Generate Law 5 reflection
+2. **Analyze** — Process pending observations into instincts
+3. **Status** — Show all instincts with confidence and current level
+
+Subcommands:
+- `/continuous-improvement status` — Instinct overview only (lightweight, reads YAML only)
+- `/continuous-improvement analyze` — Process pending observations into instincts
+- `/continuous-improvement weekly` — Set up weekly analysis schedule
+- `/continuous-improvement always-on` — Enable/disable always-on mode for this project
+
+## Planning-With-Files (Opt-In)
+
+Use this workflow only when the user explicitly asks for persistent, file-based planning or asks to use Planning-With-Files.
+
+- Detect the project root with `git rev-parse --show-toplevel`; if that fails, use the current working directory.
+- Create and maintain three project-root files:
+  - `task_plan.md` — phases, status, questions, decisions, errors
+  - `findings.md` — research notes, sources, synthesized discoveries
+  - `progress.md` — session log, verification notes, checkpoints
+- Default phases in `task_plan.md`: `Research`, `Plan`, `Execute`, `Verify`, `Reflect`
+- Never create these files automatically for normal work. This workflow is opt-in.
+- Never overwrite existing planning files unless the user explicitly asks to reset or replace them.
+
+When resuming work, read the three files before making major decisions so context survives long tasks and new sessions.

package/plugins/continuous-improvement/skills/deploy-receipt/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: deploy-receipt
+tier: "1"
+description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline at the deploy seam. A merge into a branch that auto-deploys is not "done" until the deploy provider reports the merged commit SHA running and a healthcheck endpoint returns 200. Companion to the vendored `finishing-a-development-branch` skill — does not replace it, runs after it for projects on Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, or any other auto-deploy target.
+origin: https://github.com/naimkatiman/continuous-improvement
+---
+
+# Deploy Receipt — Closing the Merge-to-Production Gap
+
+## Why This Skill Exists
+
+Multiple sessions in the operator's recent telemetry ended in a "partially achieved" state with the same shape: PR merged green, branch deleted, agent reports done — and then hours later the operator discovers the deploy provider never picked up the commit, was building from a stale lockfile, or silently rolled back. The merge happened. The deploy did not.
+
+`finishing-a-development-branch` (vendored from Obra superpowers in `third-party/superpowers/`) ends at the merge. For repos that do not auto-deploy that is the correct boundary. For repos that DO auto-deploy from `main` (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, Cloud Run, App Runner, et al.) the merge is only the trigger — the work is not done until the deployed SHA matches the merged HEAD and the application answers a healthcheck.
+
+This skill defines the receipt that closes that gap, without modifying the vendored upstream file.
+
+## When to Activate
+
+Activate when ALL of the following are true:
+
+1. A merge into the deploy branch (typically `main` or `master`) has just landed
+2. The repo declares an auto-deploy target — detect via any of:
+   - `railway.toml`, `railway.json`, or `RAILWAY_*` env vars in `.env.example`
+   - `wrangler.toml` / `wrangler.jsonc` (Cloudflare Workers)
+   - `vercel.json` or `.vercel/` directory
+   - `netlify.toml`
+   - `fly.toml`
+   - `app.yaml` (App Engine), `apprunner.yaml` (App Runner)
+   - GitHub Actions workflow with `deploy:` job triggered on push to the deploy branch
+3. `finishing-a-development-branch` has reported "merged" — not "PR opened", not "review pending"
+
+Do NOT activate when:
+- Repo is library-only / package-published (npm, PyPI, crates.io) — those have a different verification surface
+- Deploy is manual (operator runs `wrangler deploy` themselves) — the merge is genuinely the boundary
+- Merge target is a non-deploy branch (`develop`, `staging-only`, `experimental`)
+
+## What a Receipt Is
+
+A deploy receipt has three components, all required:
+
+1. **SHA match.** The deploy provider's currently-running revision SHA equals the merge commit SHA on the deploy branch. Not "the latest deploy started after the merge" — the SHA itself.
+2. **Health response.** A documented healthcheck endpoint (project-specific; common shapes: `GET /health`, `GET /api/health`, `GET /version`) returns HTTP 200 within a reasonable timeout (default 5 minutes from merge).
+3. **Build artifact integrity** (when verifiable). If the deploy emits a build hash, log digest, or version string, it matches what was built on the merge commit. If it does not emit one, this component is recorded as `not verifiable for this provider` — it does not block the receipt, but the gap is logged.
+
+A receipt missing any required component is NOT a receipt. The merge is reported as `merged but not deployed — operator action required` per the close-the-loop rule below.
+
+## How to Verify (per provider)
+
+The skill is provider-aware but never hardcodes a specific API key or token shape. Three verification routes, in priority order:
+
+### Route A — Provider CLI (preferred when authenticated)
+
+The CLI is the highest-fidelity source.
+
+| Provider | Command shape | Receipt extraction |
+|---|---|---|
+| Railway | `railway status --json` | `.deployments[0].meta.commitHash` |
+| Cloudflare Workers | `wrangler deployments list --json` | `[0].metadata.deployment_trigger.metadata.commit_hash` |
+| Vercel | `vercel inspect <url> --json` | `.gitSource.sha` |
+| Netlify | `netlify api listSiteDeploys --data='{"site_id":"<id>"}'` | `[0].commit_ref` |
+| Fly.io | `fly releases --json` | `[0].commit_sha` |
+
+If the CLI is not installed or not authenticated in this session, fall through to Route B. Do NOT prompt the operator to install the CLI mid-session — that is a drive-by.
+
+### Route B — GitHub Deployments API (works for any provider that posts back)
+
+```
+gh api repos/{owner}/{repo}/deployments --jq '.[0] | {sha, ref, environment}'
+gh api repos/{owner}/{repo}/deployments/{id}/statuses --jq '.[0] | {state, target_url}'
+```
+
+A `state: success` status whose parent deployment's `sha` matches the merge SHA is a valid receipt component (1).
+
+### Route C — Version endpoint curl (works for any HTTP service)
+
+The most provider-agnostic. Requires the application to expose a version endpoint that returns its build SHA.
+
+```
+curl -fsS https://<deployed-host>/version
+# Expect a JSON body or plain text containing the merge SHA, e.g. {"commit":"a477ec1"}
+# Or a Git-style SHA prefix that matches `git rev-parse --short HEAD`
+```
+
+If no version endpoint exists in the project, log this as a gap and recommend adding one as a deferred follow-up — do not fabricate a receipt from a 200 on `/` or `/health` alone, because both can succeed against the OLD deploy.
+
+## Output Shape (always emit this verbatim block)
+
+After running verification:
+
+```
+## Deploy Receipt — <project name>
+- Merge SHA:        <abbreviated sha>
+- Deployed SHA:     <abbreviated sha or "not retrieved (reason)">
+- SHA match:        yes | no | not verifiable
+- Health endpoint:  <url> → <status code> in <ms>ms
+- Build artifact:   <digest if available, else "not emitted by provider">
+- Receipt status:   COMPLETE | INCOMPLETE — <reason>
+- Verified via:     CLI | GitHub Deployments | version curl | combination
+```
+
+A `COMPLETE` receipt is the only state that lets the merge be reported as `done`. `INCOMPLETE` receipts surface a single named operator-action item (e.g. "Railway last deploy is older than the merge — re-trigger from dashboard or `railway up`").
+
+## Anti-Patterns
+
+- **"Eventually consistent" excuse.** Reporting done with `Deployed SHA: not retrieved` and a comment like "deploy will pick up shortly" is exactly the failure mode this skill prevents. There is no eventually — there is COMPLETE or INCOMPLETE.
+- **Health-only receipts.** A 200 on `/health` against a stale deploy is not a receipt. Without SHA match, the receipt is INCOMPLETE.
+- **Skipping for "small changes."** A docs-only commit still needs a receipt if the deploy branch auto-deploys — small changes have caused stale-build incidents on every provider in the table above.
+- **Recommending the CLI install mid-receipt.** If Route A is unavailable, fall through to B then C. Adding tooling is a separate decision the operator makes outside the receipt loop.
+- **Treating absence of evidence as evidence of success.** If none of the three routes produce a SHA, the receipt is `INCOMPLETE — no provider source available`, not `COMPLETE (assumed)`.
+
+## Pairs With
+
+- `finishing-a-development-branch` (vendored, third-party/superpowers/) — runs first; reports the merge. This skill runs after.
+- `verification-loop` — same Law 4 family; this skill is the deploy-seam specialization
+- `proceed-with-the-recommendation` — routing-table row for "Merge / close branch" should pair `finishing-a-development-branch` with this skill when the project is auto-deploy
+- `safety-guard` — orthogonal; safety-guard prevents destructive ops, this verifies post-deploy state
+
+## Close-the-Loop Rule
+
+If the receipt is INCOMPLETE, the merge is NOT reported as a closed item in the Phase 7 summary of `proceed-with-the-recommendation`. It moves to **What is next → Immediate operator action**, with the named action and the exact command or dashboard step. The operator's session record is what determines done — not the agent's optimism.
+
+## Installation
+
+```bash
+mkdir -p ~/.claude/skills/deploy-receipt
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/deploy-receipt.md \
+  -o ~/.claude/skills/deploy-receipt/SKILL.md
+```
+
+Restart the Claude Code session so the registry picks it up.

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

@@ -0,0 +1,155 @@
+---
+name: gateguard
+tier: "1"
+description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Fact-forcing gate that blocks Edit/Write/Bash (including MultiEdit) and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.
+origin: community
+---
+
+# GateGuard — Fact-Forcing Pre-Action Gate
+
+A PreToolUse hook that forces the agent to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.
+
+## When to Activate
+
+- Working on any codebase where file edits affect multiple modules
+- Projects with data files that have specific schemas or date formats
+- Teams where AI-generated code must match existing patterns
+- Any workflow where the agent tends to guess instead of investigating
+
+## Core Concept
+
+LLM self-evaluation doesn't work. Ask "did you violate any policies?" and the answer is always "no." This is verified experimentally.
+
+But asking "list every file that imports this module" forces the LLM to run Grep and Read. The investigation itself creates context that changes the output.
+
+**Three-stage gate:**
+
+```
+1. DENY  — block the first Edit/Write/Bash attempt
+2. FORCE — tell the model exactly which facts to gather
+3. ALLOW — permit retry after facts are presented
+```
+
+No competitor does all three. Most stop at deny.
+
+## Evidence
+
+Two independent A/B tests, identical agents, same task:
+
+| Task | Gated | Ungated | Gap |
+| --- | --- | --- | --- |
+| Analytics module | 8.0/10 | 6.5/10 | +1.5 |
+| Webhook validator | 10.0/10 | 7.0/10 | +3.0 |
+| **Average** | **9.0** | **6.75** | **+2.25** |
+
+Both agents produce code that runs and passes tests. The difference is design depth.
+
+## Gate Types
+
+### Edit / MultiEdit Gate (first edit per file)
+
+MultiEdit is handled identically — each file in the batch is gated individually.
+
+```
+Before editing {file_path}, present these facts:
+
+1. List ALL files that import/require this file (use Grep)
+2. List the public functions/classes affected by this change
+3. If this file reads/writes data files, show field names, structure,
+   and date format (use redacted or synthetic values, not raw production data)
+4. Quote the user's current instruction verbatim
+```
+
+### Write Gate (first new file creation)
+
+```
+Before creating {file_path}, present these facts:
+
+1. Name the file(s) and line(s) that will call this new file
+2. Confirm no existing file serves the same purpose (use Glob)
+3. If this file reads/writes data files, show field names, structure,
+   and date format (use redacted or synthetic values, not raw production data)
+4. Quote the user's current instruction verbatim
+```
+
+### Destructive Bash Gate (every destructive command)
+
+Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
+
+```
+1. List all files/data this command will modify or delete
+2. Write a one-line rollback procedure
+3. Quote the user's current instruction verbatim
+```
+
+### Routine Bash Gate (once per session)
+
+```
+Quote the user's current instruction verbatim.
+```
+
+### Parallel-Actor Gate (first mutation per session, then divergence-checked)
+
+A second Claude/Codex/Maulana session can be running on the same host and the same working tree. On this operator's setup that is the common case, not the edge case (multi-clauding observed at 67% of recent messages). A mutation that looks safe in isolation can land on top of an upstream commit, an unstaged change, or a branch advance that this session never saw.
+
+**On the first Edit / Write / mutating Bash of a session:**
+
+```
+Baseline these three values and quote them in your response:
+
+1. `git rev-parse HEAD` — record the commit you started on
+2. `git rev-parse @{u}` (if branch tracks an upstream) — record where origin was
+3. `git status --porcelain` — record the working tree state
+
+If any value is "unknown" (detached HEAD, no upstream, untracked-only tree),
+say so explicitly. Do not proceed past the baseline silently.
+```
+
+**On every subsequent Edit / Write / mutating Bash, before allowing the action:**
+
+```
+Re-check the three baselines against current state:
+
+1. `git rev-parse HEAD` — has it advanced past your baseline without your commits?
+2. `git rev-parse @{u}` — did upstream move while you worked?
+3. `git status --porcelain` — are there modifications you did not introduce?
+
+If ANY of those drifted from baseline, HALT. Emit:
+"Parallel-actor divergence: <field> moved from <baseline> to <current>.
+Working tree may belong to another session. Stop, surface to operator,
+get clearance before next mutation."
+```
+
+This gate is what catches the squash-merge / ahead-of-origin trap recorded in the operator's memory (`feedback_pre_branch_check.md`, `feedback_parallel_actor.md`) — both classes of failure occurred because a baseline was never captured at session start.
+
+## Quick Start
+
+### Option A: Use the continuous-improvement hook (zero install)
+
+The hook at `scripts/hooks/gateguard-fact-force.js` is included in this plugin. Enable it via hooks.json.
+
+### Option B: Full package with config
+
+```bash
+pip install gateguard-ai
+gateguard init
+```
+
+This adds `.gateguard.yml` for per-project configuration (custom messages, ignore paths, gate toggles).
+
+## Anti-Patterns
+
+- **Don't use self-evaluation instead.** "Are you sure?" always gets "yes." This is experimentally verified.
+- **Don't skip the data schema check.** Both A/B test agents assumed ISO-8601 dates when real data used `%Y/%m/%d %H:%M`. Checking data structure (with redacted values) prevents this entire class of bugs.
+- **Don't gate every single Bash command.** Routine bash gates once per session. Destructive bash gates every time. This balance avoids slowdown while catching real risks.
+
+## Best Practices
+
+- 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/`.
+
+## Related Skills
+
+- `safety-guard` — Runtime safety checks (complementary, not overlapping)
+- `code-reviewer` — Post-edit review (GateGuard is pre-edit investigation)

package/plugins/continuous-improvement/skills/para-memory-files/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: para-memory-files
+tier: "1"
+description: >
+  Enforces Law 5 (Reflect After Every Session) and Law 7 (Learn From Every Session)
+  of the 7 Laws of AI Agent Discipline by giving the agent a durable file-based
+  memory it can read on resume and write at session end.
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.