@static-var/keystone 0.1.0

package/skills/keystone/modules/debug.md

@@ -0,0 +1,198 @@
+# Keystone Debug Module
+
+## Core principle
+Find the root cause before fixing. Debugging is an evidence ladder: observe the failure, reproduce it, minimize it, trace the mechanism, test falsifiable hypotheses, prove the cause, fix narrowly, guard against regression, verify with exact output, and clean up. No guess-and-check, no cargo-cult edits, no shipping/finalization work.
+
+Quick start:
+1. Capture the exact symptom and smallest known failing command/input.
+2. Reproduce or preserve the best available evidence if reproduction is blocked.
+3. Minimize, then test one falsifiable hypothesis at a time.
+4. Prove the mechanism before fixing; add a regression guard and verify with exact output.
+
+## Load when
+Load when the user reports an error, failing test, broken behavior, regression, flaky result, performance anomaly, unexpected output, integration failure, suspicious logs, silent failure, data corruption, or asks to troubleshoot why something happened.
+
+Also load when the task involves:
+- deciding whether a failure is local, historical, environmental, data-dependent, timing-dependent, or cross-system;
+- diagnosing nondeterminism, race conditions, retries, timeouts, queues, caches, or distributed boundaries;
+- interpreting logs/traces/metrics to explain a symptom;
+- proving whether a suspected fix actually addresses the cause.
+
+## Not for
+- Implementing new behavior unrelated to the failure.
+- General code improvements without a reproduced problem.
+- Shipping, release finalization, merge strategy, or deployment handoff; use `ship` after proof/review.
+- Broad repository audits; use `health`.
+- Spec decisions where no failure exists; use `shape`.
+- Replacing review, test strategy, or gate validation modules.
+
+## Outcome contract
+Deliver a debug report with:
+- symptom, impact, affected users/systems, and failure classification;
+- reproduction steps, exact command/input/environment, or why reproduction was not possible;
+- minimized failing case when feasible, including what was removed and what still fails;
+- evidence gathered through logs, tests, code inspection, history, metrics, traces, or instrumentation;
+- hypotheses considered, which were disproven, and the surviving root-cause hypothesis;
+- proof that the root cause explains the symptom and predicts observed behavior;
+- exact fix made or proposed, scoped to the proven cause;
+- regression test, guard, monitor, or explicit reason none is feasible;
+- verification commands and exact results/output evidence;
+- cleanup performed, temporary diagnostics removed, and remaining uncertainty or escalation.
+
+Stop only when one of these is true:
+- the root cause is proven, the narrow fix is verified, and regression protection is in place or justified;
+- reproduction is impossible after documented attempts and the best available evidence has been preserved;
+- escalation criteria are met.
+
+## Modes
+- **Triage:** classify severity, scope, reproducibility, recency, ownership, and risk before fixing.
+- **Reproduce/minimize:** create the smallest reliable case that demonstrates the failure.
+- **Instrument/trace:** add temporary logs, probes, traces, assertions, metrics, or diagnostics to observe reality.
+- **Hypothesis test:** test one falsifiable explanation at a time and record pass/fail evidence.
+- **Fix:** make the smallest change that addresses the proven root cause.
+- **Stabilize flaky behavior:** collect repeated runs, isolate nondeterminism, and prove the stabilizing change.
+- **Performance investigation:** measure baseline, localize bottleneck, prove causality, then optimize narrowly.
+- **Log/silent-failure investigation:** reconstruct the timeline from logs/traces/state when direct failure output is absent.
+- **Escalation:** stop local edits and ask for data, access, owner input, incident handling, or risk approval.
+
+## Process
+1. **Classify the failure.** Decide whether it is deterministic, flaky, regression, environment-specific, data-dependent, multi-system boundary, performance, silent/log-only, data corruption, security-sensitive, or destructive. Record severity, scope, recency, and owner.
+2. **Capture the exact symptom.** Include command, input, error text, expected vs actual, environment, versions, seed/timezone/locale, frequency, affected data, and recent changes.
+3. **Reproduce before fixing.** Run the smallest known failing command or scenario. If reproduction is impossible, state the constraint, preserve available evidence, and switch to log/history/data analysis.
+4. **Minimize the case.** Reduce inputs, files, flags, mocks, services, data rows, timing windows, browser/device matrix, or integration surface while keeping the failure. Do not minimize away the bug.
+5. **Inspect code, data, and history.** Distinguish trigger from cause. If the failure is likely historical, use bisect or targeted history review before guessing.
+6. **Trace/instrument narrowly.** Add the smallest temporary diagnostic that can confirm or falsify a hypothesis. Prefer assertions, structured logs, counters, spans, query plans, snapshots, or deterministic seeds over broad logging.
+7. **Form falsifiable hypotheses.** A good hypothesis names a mechanism and prediction. Test one at a time. Record disproven hypotheses instead of silently abandoning them.
+8. **Prove the root cause.** Show that the cause explains the symptom, reproduces or predicts the failure, and that removing/changing the cause removes the failure. Symptoms alone are not proof.
+9. **Fix narrowly.** Change only the code/config/data handling required by the proven cause. Avoid opportunistic refactors, rewrites, or unrelated cleanup.
+10. **Add a regression guard.** Prefer a failing-before/passing-after test. If impractical, add an assertion, monitor, fixture, replay, seed, contract test, migration check, or documented manual proof.
+11. **Verify with exact output.** Run focused verification first, then broader commands if risk warrants. Capture command names and result snippets, not just “tests pass.”
+12. **Clean up.** Remove temporary diagnostics, revert failed experiments, leave useful permanent observability only when justified, and report remaining uncertainty.
+
+Debug decision tree / failure classification:
+- **Cannot reproduce?** Verify environment/input parity, collect logs/traces/state, check recent changes, ask for missing data, and escalate if still blocked.
+- **Reproduces reliably now but worked before?** Treat as historical regression; run targeted history review or bisect.
+- **Fails intermittently?** Treat as flaky/race; run many iterations, fix seed/time/timezone/network where possible, and look for shared state, ordering, async waits, retries, clocks, locks, caches, and resource leaks.
+- **Fails at a service boundary?** Trace request IDs across systems, compare contracts, schemas, auth, serialization, retries, timeouts, idempotency, and partial failure handling.
+- **Slow or resource-heavy?** Measure before changing, identify the bounded bottleneck, compare profiles/plans/metrics, and prove the optimization changes the measured bottleneck.
+- **Only logs show failure or behavior is silent?** Reconstruct timeline from logs, traces, metrics, state transitions, audit records, and exit codes; add diagnostics only to close evidence gaps.
+- **Data is wrong or corrupted?** Freeze destructive actions, preserve samples, identify writer/read path, migration/import history, concurrency, validation gaps, and blast radius before fixing.
+
+Operational playbook:
+- **Reproduce:** exact command/input/environment; note frequency and baseline output.
+- **Minimize:** remove variables until the smallest failing case remains; document removed variables.
+- **Trace/instrument:** observe the suspected mechanism with scoped, reversible diagnostics.
+- **Hypothesize:** write falsifiable mechanism + prediction; test one hypothesis per experiment.
+- **Prove:** connect evidence to cause; show why alternatives fail or are less likely.
+- **Fix narrowly:** edit only the proven mechanism.
+- **Regression guard:** create failing-before/passing-after proof or equivalent guard.
+- **Cleanup:** remove debug litter and failed experiments; keep only justified observability.
+
+Bisect strategy when historical regression is likely:
+- Establish one known-good and one known-bad revision using the same command, data, and environment.
+- Make the reproduction deterministic enough for `git bisect`; if flaky, use a looped script with a clear pass/fail threshold.
+- Keep the bisect command side-effect safe; reset generated files between runs.
+- When bisect identifies a commit, inspect the diff for mechanism and still prove causality in current code.
+- Do not treat the first bad commit as the root cause until the mechanism explains the symptom.
+
+Scenario checklists:
+- **Regression:** What changed? Is there a known-good revision? Can the same command prove good vs bad? Is the failing behavior tied to code, dependency, config, data, or environment?
+- **Flaky test/race:** How often does it fail over 20/50/100 runs? Does order, parallelism, clock, seed, async wait, network, cache, filesystem, or shared state affect it? Does instrumentation change timing?
+- **Multi-system boundary:** What is the correlation/request ID? Which system first diverges from expected state? Are contracts, schemas, auth, encoding, idempotency, retries, timeout budgets, and partial failures aligned?
+- **Performance:** What metric is bad and by how much? What is the baseline? Is the bottleneck CPU, memory, IO, network, DB, lock contention, rendering, bundle size, or algorithmic complexity? Does the fix improve that metric?
+- **Logs/silent failure:** What timeline do logs/traces/metrics imply? Are there swallowed exceptions, ignored return values, missing awaits, nonzero exits, dropped events, sampling gaps, or log-level/config differences?
+- **Data corruption:** What data is affected? Is the source of truth known? Which writer last touched it? Are migrations, backfills, imports, concurrent writes, validation, serialization, timezone/locale, or precision involved? Is rollback/destructive repair safe?
+
+Good/bad hypotheses:
+- **Good:** “The checkout total is doubled because retrying `capturePayment` replays a non-idempotent side effect; if true, two calls with the same request ID will create two ledger rows.”
+- **Bad:** “Payments are broken.”
+- **Good:** “The test flakes because it asserts before the debounce timer fires; if true, using fake timers or awaiting the debounce settles it across 100 runs.”
+- **Bad:** “Probably async weirdness.”
+- **Good:** “The query slowed after commit X because the new filter prevents index `idx_orders_account_created` from being used; if true, `EXPLAIN` will show a sequential scan and restoring the predicate shape will restore the plan.”
+- **Bad:** “The database is slow.”
+
+Good/bad minimization:
+- **Good:** Reduce a failing import from a production-sized CSV to three rows that preserve the bad encoding, duplicate key, and null timestamp that trigger the failure.
+- **Bad:** Replace the import with a mock that no longer exercises parsing, deduplication, or timestamp handling.
+- **Good:** Reduce a browser failure to one route, one viewport, one user role, and one API response fixture while keeping the visible defect.
+- **Bad:** Disable authentication, caching, and the API client so the boundary bug disappears.
+- **Good:** For a flaky test, run the same test alone, in file order, shuffled, with fixed seed, and in parallel to identify the minimal timing/order dependency.
+- **Bad:** Add arbitrary sleeps until the failure stops appearing once.
+
+Escalation/stuck criteria:
+- Escalate after **three disproven hypotheses** without a stronger next test.
+- Escalate when there is **no reproduction** and required logs/data/access are unavailable.
+- Escalate immediately for destructive actions, data-loss risk, security/privacy exposure, production incident impact, legal/compliance concerns, or uncertain repair of corrupted data.
+- Escalate when the next diagnostic requires credentials, production data, high-cost infrastructure, schema/data mutation, or owner approval.
+- Escalation output must include symptom, impact, attempts, disproven hypotheses, missing evidence, requested help/access, and safest next action.
+
+## Subagents and reasoning
+Default reasoning: `high`. Use oracle/debug subagents for independent root-cause analysis, log review, performance profile interpretation, bisect planning, or hypothesis generation. Use `xhigh` for intermittent, cross-system, security, performance, data-loss, privacy, destructive, or production-impacting failures.
+
+Subagents may inspect and reason independently, but fixes should converge on one evidence-backed root cause. Ask subagents for competing hypotheses and evidence gaps, not broad code review. When subagents disagree, run the smallest test that distinguishes their explanations. Do not let parallel analysis become parallel guess-and-check edits.
+
+## Hard rules
+- No fix before evidence supports the root cause.
+- No “try this” edits unless explicitly labeled as diagnostic experiments and reverted if disproven.
+- Symptoms are not root causes; keep asking what mechanism produced the symptom.
+- One hypothesis per experiment; record the prediction and result.
+- Three disproven hypotheses without progress triggers escalation or a new evidence source.
+- Regression coverage is required when practical; if impractical, explain why and provide alternate proof.
+- Temporary instrumentation must be removed or clearly documented before handoff.
+- Do not declare fixed without command output, exact output proof, metric delta, trace evidence, or equivalent verification evidence.
+- Do not broaden scope into feature work, refactoring, shipping, finalization, or unrelated cleanup.
+- For data-loss/security/destructive risk, preserve evidence and escalate before mutation.
+
+## Failure modes
+- **Guess-and-check spiral:** changing code until symptoms disappear without knowing why.
+- **Confirmation bias:** keeping the first hypothesis despite contradictory evidence.
+- **No-op advice:** saying “check logs,” “add tests,” or “investigate further” without specifying which evidence, command, owner, or stop condition.
+- **Overbroad fix:** refactoring or redesigning more than the failure requires.
+- **Unreproducible confidence:** claiming success from one weak signal on flaky behavior.
+- **Minimization that removes the bug:** simplifying the case until the relevant boundary, data shape, or timing condition disappears.
+- **Instrumentation Heisenbug:** diagnostics change timing, ordering, load, or state enough to hide the failure.
+- **First-bad-commit tunnel vision:** assuming bisect output is the mechanism without proof.
+- **Boundary blame ping-pong:** assuming another service owns the issue without request-level evidence.
+- **Diagnostic litter:** leaving logs, probes, sleeps, flags, generated data, or debug-only state behind.
+
+## Output format
+```markdown
+## Debug report
+Symptom: ...
+Impact/scope: ...
+Failure classification: ...
+Stop condition: fixed / blocked / escalated ...
+
+### Reproduction
+- Steps/command: ...
+- Environment/input: ...
+- Frequency: ...
+- Minimal case: ...
+
+### Evidence and root cause
+- Evidence ladder:
+  1. Observation: ...
+  2. Trace/minimization: ...
+  3. Hypothesis test: ...
+  4. Proof: ...
+- Disproven hypotheses: ...
+- Root cause: ...
+
+### Fix
+- Changed: ...
+- Why this addresses the cause: ...
+- Scope intentionally not changed: ...
+
+### Regression protection
+- Test/guard: ...
+- Failing-before/passing-after proof or alternate guard: ...
+
+### Verification
+- Command/result: ...
+- Exact output proof: ...
+
+### Cleanup / remaining uncertainty
+- Temporary diagnostics removed: ...
+- Remaining risk/uncertainty: ...
+- Escalation needed, if any: ...
+```

package/skills/keystone/modules/gates/isolation.md

@@ -0,0 +1,56 @@
+# Isolation Gate
+
+## Purpose
+Confirm mutation can happen safely before the first file change.
+
+This gate protects user work, local experiments, and unrelated files. It is binary: either the workspace is isolated for the requested blast radius, or mutation stops.
+
+## Required checks
+1. Identify the workspace:
+   - Run `git rev-parse --show-toplevel`.
+   - Run `git branch --show-current`.
+   - Run `git worktree list` or compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`.
+2. Capture dirty state:
+   - Run `git status --porcelain` before editing.
+   - Treat every listed path as user-owned until proven otherwise.
+3. State the planned blast radius:
+   - List the exact files or directories expected to change.
+   - List protected files, generated files, scripts, tests, and modules that must not change.
+4. Compare dirty files to planned changes:
+   - Planned + clean: safe to edit.
+   - Planned + already dirty: ask whether to build on, inspect, or avoid those changes.
+   - Unplanned + dirty: do not touch.
+5. Build a collision matrix before mutation.
+
+## Collision matrix
+
+| Dirty path | Planned to edit? | Owner known? | Action |
+| --- | --- | --- | --- |
+| No dirty paths | N/A | N/A | Pass |
+| Dirty path inside blast radius | Yes | User/unknown | Ask before editing that file |
+| Dirty path outside blast radius | No | User/unknown | Leave untouched |
+| Dirty path is generated artifact | Maybe | Tool/unknown | Do not delete unless user approved |
+| Dirty path conflicts with requested scope | Yes | Unknown | Fail until clarified |
+
+## Pass condition
+Pass only when all are true:
+- Workspace root, branch, and worktree state are known.
+- `git status --porcelain` has been captured.
+- Planned blast radius is explicit.
+- Dirty files are either absent, inside approved scope, or guaranteed untouched.
+- No auto-stash, auto-commit, reset, checkout, cleanup, or generated-file deletion is needed.
+
+## Fail action
+Stop before changing files. Do not auto-stash, auto-commit, reset, or "clean up" user work.
+
+Report:
+
+```text
+Isolation Gate: FAIL
+Workspace: <root>
+Branch/worktree: <branch and worktree state>
+Planned blast radius: <files/dirs>
+Dirty files: <git status --porcelain output>
+Collision: <which dirty paths overlap or create risk>
+Needed decision: <ask user to approve, narrow scope, or provide a clean workspace>
+```

package/skills/keystone/modules/gates/proof.md

@@ -0,0 +1,54 @@
+# Proof Gate
+
+## Purpose
+Verify claims with evidence before reporting success.
+
+This gate rejects vibe-based completion. Code inspection can support a claim, but inspection alone is not proof that behavior works. Proof must connect the intended outcome to observable evidence.
+
+## Required checks
+1. Name the claim:
+   - What changed?
+   - What user-visible or maintainer-visible outcome is now true?
+2. Choose evidence that matches the scope:
+   - Logic: unit tests, integration tests, property checks, reproduction scripts, or before/after examples.
+   - UI: browser/app interaction, screenshots, accessibility checks, visual diff, or manual steps with observed result.
+   - Config/build: validation command, dry run, parser/linter, build, deploy preview, or tool output.
+   - Docs/content: link/render check, validator, examples that exercise the documented path, or human-readable diff against requirements.
+3. Run the strongest practical verification.
+4. Capture concrete output:
+   - Command name.
+   - Pass/fail result.
+   - Relevant output, screenshot path, or inspected artifact.
+5. Disclose gaps:
+   - Untested paths.
+   - Commands unavailable.
+   - Manual assumptions.
+
+## Not proof
+- "The code looks right."
+- "I updated the file."
+- "This should work."
+- "No errors in my editor."
+- Reviewing a diff without executing or validating the affected behavior.
+
+## Good proof examples
+- `pytest tests/test_pricing.py -q` passes and includes the changed rule.
+- Browser flow: open checkout, apply discount, observe total updates to `$42`.
+- `python3 scripts/validate-keystone.py` passes after editing skill modules.
+- Config proof: `terraform plan` exits 0 and shows only expected resource changes.
+
+## Pass condition
+Pass only when the success claim is backed by evidence that directly exercises or validates the changed scope, and all known gaps are disclosed.
+
+## Fail action
+Do not claim completion. If verification cannot be run, provide a fallback proof plan instead of pretending.
+
+```text
+Proof Gate: FAIL
+Claim needing proof: <claim>
+Attempted evidence: <commands/inspection/manual steps>
+Result: <output or blocker>
+Unverified risk: <what may still be wrong>
+Fallback proof plan: <exact command/manual check/human verification needed>
+Completion language allowed: <"implemented, not verified" or "blocked pending proof">
+```

package/skills/keystone/modules/gates/red.md

@@ -0,0 +1,59 @@
+# Red Gate
+
+## Purpose
+Establish a meaningful failing signal before implementation when practical.
+
+The red signal proves the current system lacks the desired behavior and that the chosen check can detect the fix. It is binary: either a red-capable check exists, or an explicit alternative proof plan is recorded.
+
+## Required checks
+1. State expected behavior in concrete terms.
+2. Identify a red-capable check:
+   - Test that should fail before the change.
+   - Reproduction command or script.
+   - Acceptance example with expected/actual output.
+   - UI flow that currently shows the defect.
+   - Validator that rejects the current artifact.
+3. Run or document the check before implementation when safe.
+4. Confirm the failure is meaningful:
+   - It fails for the right reason.
+   - It would pass after the intended behavior exists.
+   - It is not only testing mocks, fixtures, snapshots, or implementation details.
+5. Preserve the red evidence in notes, test output, or commit/PR description.
+
+## Good red examples
+- A unit test expects tax to round half-up and currently receives half-even.
+- A browser flow submits an empty required field and currently allows submission.
+- A docs validator fails because a required gate file lacks a failure report template.
+
+## Bad red examples
+- A test that only checks a mocked service was called.
+- A snapshot update with no behavioral assertion.
+- A failing linter unrelated to the requested change.
+- A test that fails because the test setup is broken.
+
+## When red is impractical
+Red may be impractical for copy-only changes, emergency fixes, unavailable environments, non-deterministic external systems, or when writing the check would exceed the change risk.
+
+If red is skipped, name the reason and substitute a stronger proof plan:
+- targeted validator,
+- manual reproduction steps,
+- review checklist,
+- before/after artifact comparison,
+- deploy-preview or staging verification.
+
+## Pass condition
+Pass only when either:
+- a meaningful red-capable signal is documented before implementation, or
+- red is explicitly impractical and an alternative proof plan is concrete enough to verify the outcome later.
+
+## Fail action
+Do not proceed as if behavior is proven. Stop or record the exception before implementation.
+
+```text
+Red Gate: FAIL
+Expected behavior: <specific outcome>
+Proposed red check: <test/repro/validator/manual flow>
+Why it is not usable: <reason>
+Risk of skipping red: <what could regress or remain unproven>
+Alternative proof plan: <exact post-change evidence required>
+```

package/skills/keystone/modules/gates/review.md

@@ -0,0 +1,56 @@
+# Review Gate
+
+## Purpose
+Confirm work has received the required review before finalization.
+
+Review is evidence, not a feeling. This gate separates blocking findings from non-blocking follow-ups and prevents shipping work that needs independent review.
+
+This gate is binary: pass or fail.
+
+## Required checks
+1. Identify required review type:
+   - Self-review is sufficient only for docs-only changes, low-risk config, or tiny low-risk refactors with green proof.
+   - Independent review is required for security, data, public API, billing/payment, auth/permissions, architecture, migrations, releases, broad refactors, or user-impacting changes.
+   - Use a human reviewer, automated reviewer, domain owner, security review, design review, or read-only review pointer as appropriate.
+2. Provide review input:
+   - Scope summary.
+   - Files changed.
+   - Requirements or acceptance criteria.
+   - Proof evidence already gathered.
+   - Known risks and skipped checks.
+3. Capture review evidence:
+   - Reviewer name/tool.
+   - Date or run identifier.
+   - Link, comment, command output, or quoted findings.
+4. Separate findings:
+   - Blockers: correctness, scope violation, data loss, security, broken verification, missing required proof.
+   - Non-blockers: style, cleanup, future refactors, optional docs, nice-to-have tests.
+5. Resolve or explicitly accept blockers before shipping.
+
+## Read-only review pointer
+When review cannot be performed by the worker, leave a read-only pointer that lets a reviewer inspect without changing work:
+
+```text
+Review requested for: <branch/worktree/PR/diff>
+Scope: <requested change>
+Changed files: <files>
+Proof: <commands and results>
+Known gaps: <unverified items>
+Please classify findings as BLOCKER or NON-BLOCKER.
+```
+
+## Pass condition
+Pass only when the required review evidence exists and no blocking findings remain unresolved, or the user explicitly accepts the remaining blockers.
+
+## Fail action
+Return to the appropriate module or gate. Do not ship while blockers are open.
+
+```text
+Review Gate: FAIL
+Review source: <human/tool/pending>
+Evidence: <link/output/comment or "none">
+Blockers: <list>
+Non-blockers: <list>
+Required next action: <fix, re-review, user acceptance, or request review>
+Read-only review pointer: <branch/PR/diff path if review is pending>
+```

package/skills/keystone/modules/gates/ship.md

@@ -0,0 +1,57 @@
+# Ship Gate
+
+## Purpose
+Ensure finalization happens only after completed, verified, reviewed work is ready for delivery.
+
+Shipping is a handoff decision. This gate confirms the work can be understood, verified, rolled back, and continued by someone else. It is binary: ready to hand off or not ready.
+
+## Required checks
+1. Proof gate status:
+   - Evidence commands and results are recorded.
+   - Unverified areas are disclosed.
+   - Any proof exception is explicit.
+2. Review gate status:
+   - Review evidence is recorded.
+   - Blockers are resolved or explicitly accepted by the user.
+   - Non-blockers are listed as follow-ups.
+3. Delivery notes:
+   - What changed.
+   - Why it changed.
+   - Files changed.
+   - Validation performed.
+   - Risks and limitations.
+4. Rollback or recovery evidence:
+   - Revert commit/PR guidance, feature flag, config rollback, backup path, or "docs-only revert is safe" note.
+   - Data migrations, destructive actions, or irreversible steps are called out.
+5. Handoff evidence:
+   - Next human action, deployment step, release note, PR link, or review pointer.
+   - Owners for follow-ups are identified when known.
+6. No stealth fix:
+   - Do not include unrelated fixes.
+   - Do not hide failed checks.
+   - Do not silently modify files outside the approved blast radius.
+
+## Good ship note
+```text
+Changed: Expanded five Keystone gate docs into operational pass/fail gates.
+Validation: python3 scripts/validate-keystone.py passed.
+Review: Pending human review; no automated blockers found.
+Rollback: Revert this docs-only change; no migration or runtime state.
+Follow-ups: Human reviewer to confirm wording matches Keystone doctrine.
+```
+
+## Pass condition
+Pass only when proof, review, delivery notes, rollback/handoff evidence, and scope compliance are all present.
+
+## Fail action
+Stop finalization and route to the missing gate. Do not merge, release, mark complete, or imply production readiness.
+
+```text
+Ship Gate: FAIL
+Missing proof: <none or details>
+Missing review: <none or details>
+Missing delivery notes: <none or details>
+Rollback/handoff gap: <none or details>
+Scope violation or stealth fix risk: <none or details>
+Required next action: <which gate/module to run before shipping>
+```

package/skills/keystone/modules/health.md

@@ -0,0 +1,124 @@
+# Keystone Health Module
+
+## Core principle
+Health is a read-only, whole-project condition scan. It turns repository evidence into mechanical findings about system drift, fragility, and maintenance risk; it does not repair, refactor, update, or reconfigure anything by default.
+
+Health answers “what is the condition of this project or subsystem?” Review answers “is this specific change acceptable?” If the task centers on a PR/diff/patch, use `review`; if it centers on repo-wide readiness, drift, tooling, docs, tests, releases, or operational condition, use `health`.
+
+## Load when
+Load when the user asks for a health check, readiness scan, risk assessment, project status audit, tooling audit, dependency/config review, maintenance assessment, drift detection, “what should we worry about?”, or “is this repo in good shape?”
+
+## Not for
+- Fixing issues found during the audit.
+- Reviewing a specific change, PR, patch, or commit; use `review`.
+- Debugging a specific failure to root cause; use `debug`.
+- Shipping a completed branch; use `ship`.
+- Designing new product behavior; use `shape`.
+- Research briefs about a narrow question; use `research`.
+
+## Outcome contract
+Deliver a health report where every finding maps:
+
+`finding -> evidence -> impact -> confidence -> next Keystone module`
+
+The report must include:
+- audit scope and evidence inspected;
+- concrete checklist status for tooling/CI drift, docs-vs-reality, config/env rot, dependency health, test health/flakiness, package/release health, and instruction/skill drift;
+- risks ranked by severity and confidence using the Health priority rubric;
+- checks not run and why;
+- explicit no-fix confirmation unless repairs were requested.
+
+Health priority rubric:
+- **Critical:** Broken now, release-blocking, security-sensitive, data-loss-prone, or prevents required project operation. Urgency: act before `ship` or before depending on the affected subsystem. Next Keystone module: usually `debug` for failing behavior or `build` for repairs; use `ship` only for release gate follow-up after the issue is fixed.
+- **Watch:** Risky, stale, drifting, or likely to become blocking, but not proven broken under current evidence. Urgency: schedule remediation or investigation soon; do not let it become untracked backlog. Next Keystone module: usually `research` to verify unknowns, `breakdown` to plan multi-step remediation, or `build` for contained repairs.
+- **Info:** Healthy signal, minor inconsistency, low-impact cleanup, or explicitly unknown/unchecked area. Urgency: no immediate action unless priorities change. Next Keystone module: `no-op` when informational, or `review`/`ship` when the next step is validation rather than repair.
+
+## Modes
+- **Project snapshot:** summarize structure, active areas, scripts, tests, CI, docs, and current branch state.
+- **Tooling/CI drift audit:** compare manifests, scripts, Make targets, task runners, hooks, CI workflows, matrix versions, cache keys, and required checks against actual files and commands.
+- **Docs-vs-reality audit:** compare README, contributor docs, runbooks, release docs, examples, and command snippets with actual repo layout and executable scripts.
+- **Config/env rot audit:** inspect templates, `.env.example`, config schemas, secrets documentation, Docker/compose/devcontainer files, SDK/runtime pins, and environment assumptions for staleness or inconsistency.
+- **Dependency health audit:** inspect manifests, lockfiles, version pins, deprecated packages, engine/toolchain constraints, known update pressure, and manifest-lock consistency.
+- **Test health/flakiness audit:** inspect test commands, skipped/quarantined tests, retries, snapshots, coverage signals, slow/flaky markers, CI-only behavior, and failure history when available.
+- **Package/release health audit:** inspect package metadata, allowlists, build artifacts, version/changelog flow, release scripts, publish dry-run support, tags, and multi-target release paths.
+- **Instruction/skill drift audit:** inspect project instructions, agent docs, skill/module docs, validator rules, and examples for contradictions or stale references.
+- **Release readiness health:** assess project-level risk categories before `ship`, without preparing release artifacts.
+- **Risk triage:** rank issues by impact, likelihood, evidence strength, and recommended next module.
+
+## Process
+1. Define scope: whole repo, subsystem, tooling, release readiness, dependencies, docs, instructions, or operational process.
+2. Confirm read-only posture. Say what will be inspected and avoid state-changing commands unless the user explicitly requested repairs.
+3. Inspect before judging: read manifests, scripts, CI, tests, docs, configs, package/release files, instruction files, recent status, and relevant gates.
+4. Apply the concrete audit checklists:
+   - **Tooling/CI drift:** declared scripts exist; CI calls valid commands; local and CI tool versions align; required checks match current project; generated/cache paths are current; hooks and Make/package targets agree.
+   - **Docs-vs-reality:** documented setup/test/build/release commands exist; referenced paths still exist; examples match current APIs/CLIs; screenshots/output snippets are not misleading; contributor docs match workflow.
+   - **Config/env rot:** sample env files cover required variables; config names match code; defaults are safe; obsolete variables are not documented as required; runtime/container/dev environment pins are current.
+   - **Dependency health:** manifests and lockfiles agree; package managers are not mixed accidentally; runtime engine constraints are plausible; deprecated/abandoned/high-risk dependencies are called out with evidence; update risk is separated from breakage.
+   - **Test health/flakiness:** test entrypoints are discoverable; skips/todos/quarantine/retry settings are listed; flaky markers or timing-sensitive tests are noted; coverage signals are reported only if measured; CI-only gaps are identified.
+   - **Package/release health:** package allowlists include required files and exclude junk; build artifacts are reproducible or documented; version/changelog/release scripts align; publish dry-run or validation exists; multi-target outputs are accounted for.
+   - **Instruction/skill drift:** AGENTS/CLAUDE/GEMINI/Codex/plugin docs and Keystone skill docs agree; module boundaries are current; validators and examples match required headings/behavior.
+5. Run safe focused checks when useful and allowed, such as `git status --short`, listing workflow files, reading manifests, `--help`, dry-run validation, or project validators. Avoid install/update/format/fix/publish commands by default.
+6. Detect drift mechanically: documentation pointing to missing scripts, scripts referencing missing files, stale generated assets, inconsistent versions, orphaned configs, CI mismatch, package metadata mismatch, or contradictory instructions.
+7. For each finding, write the required chain: severity, finding, evidence, impact, confidence, and next Keystone module (`research`, `debug`, `shape`, `breakdown`, `build`, `review`, `ship`, or no-op). Assign severity from the Health priority rubric; do not produce unranked findings. If the finding is about tests or package metadata, still route to one of those modules, usually `build` for repairs, `debug` for failing behavior, `review` for validation, or `ship` for final package readiness.
+8. Separate statuses: **broken now**, **risky**, **stale**, **unknown**, and **healthy**. Map broken-now items to Critical unless evidence shows low impact; map risky or stale items to Watch unless release/security impact makes them Critical; map healthy, minor, and unchecked informational notes to Info. Do not convert unknowns into failures.
+9. Stop at reporting unless the user explicitly requested fixes. If repairs are requested, route to the appropriate module instead of silently switching modes.
+
+## Subagents and reasoning
+Default reasoning: `medium`. Use read-only scout subagents for broad inventory and reviewer subagents for independent risk triage. Use `high` for release readiness, security-sensitive audits, large monorepos, severe tooling drift, instruction drift affecting agent behavior, or when health findings affect go/no-go decisions. Subagents must remain read-only unless repairs are explicitly requested.
+
+## Hard rules
+- Read-only by default: no fixing, formatting, dependency updates, cleanup, generation, or config changes unless explicitly requested.
+- Health is whole-project/system condition; Review is a specific change. Do not use Health to approve a PR diff.
+- Every finding must include severity, finding, evidence, impact, confidence, and next Keystone module.
+- Use only the Health priority rubric for severity (`Critical`, `Watch`, `Info`) unless the user explicitly requests equivalent labels; do not emit unranked dumps.
+- Evidence categories must be named; unchecked areas must be listed with reasons.
+- Do not overstate confidence. Label inferred risks and explain what would verify them.
+- Prefer safe read-only or focused validation commands.
+- Separate “broken now,” “risky,” “stale,” and “unknown.”
+- Health can recommend `ship`, but does not replace ship proof gates.
+
+## Failure modes
+- **Audit-as-fix:** making opportunistic changes during a scan.
+- **Review confusion:** judging a specific PR/change instead of system condition.
+- **Checklist theater:** listing categories without evidence.
+- **Evidence gaps:** reporting findings that lack impact, confidence, or next module.
+- **False certainty:** declaring healthy because a narrow check passed.
+- **Drift blindness:** missing mismatches between docs, scripts, CI, package metadata, instructions, and actual files.
+- **Unranked dump:** overwhelming the user with findings but no severity or next module.
+
+## Output format
+```markdown
+## Health report
+Scope: ...
+No-fix status: confirmed / repairs requested
+Boundary: Health system-condition scan, not Review of a specific change
+
+### Evidence inspected
+- ...
+
+### Checklist status
+| Checklist | Status | Evidence | Confidence |
+|---|---|---|---|
+| Tooling/CI drift | ... | ... | ... |
+| Docs-vs-reality | ... | ... | ... |
+| Config/env rot | ... | ... | ... |
+| Dependency health | ... | ... | ... |
+| Test health/flakiness | ... | ... | ... |
+| Package/release health | ... | ... | ... |
+| Instruction/skill drift | ... | ... | ... |
+
+Classify findings using the Health priority rubric above: `Critical`, `Watch`, or `Info`.
+
+### Findings
+1. Critical / Watch / Info — finding
+   - Evidence:
+   - Impact:
+   - Confidence: High / Medium / Low
+   - Next Keystone module:
+
+### Checks not run
+- ...
+
+### Overall assessment
+Healthy / Watch / At risk / Blocked — rationale
+```