From e021460cc6dc7af719a8cab728a211d7959e50fa Mon Sep 17 00:00:00 2001 From: danielvm-git Date: Tue, 7 Jul 2026 00:21:22 -0300 Subject: [PATCH] =?UTF-8?q?feat(e45):=20quality=20core=20=E2=80=94=20skill?= =?UTF-8?q?=20hardening=20and=20verification=20patterns=20(s01=E2=80=93s41?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implement all 41 stories from epic e45: run-benchmark delta grading, CSO description gates, PreToolUse hooks, plan-work consistency checks, adversarial gap-finding, task ledgers, dual-blind review, red/green commits, lifecycle gates, reference sync, orchestration circuit breakers, import boundaries, Context7 retry/cache, rule matrix compilation, and P2 optional patterns. Co-authored-by: Cursor --- .continue/rules/context7-mcp.md | 0 .continue/rules/diagnose-stall.md | 0 .cursor/rules/audit-code.mdc | 30 +- .cursor/rules/change-request.mdc | 4 +- .cursor/rules/compose-workflow.mdc | 15 + .cursor/rules/context7-mcp.mdc | 55 + .cursor/rules/craft-skill.mdc | 28 + .cursor/rules/deepen-architecture.mdc | 20 + .cursor/rules/delegate-task.mdc | 14 + .cursor/rules/deploy.mdc | 8 + .cursor/rules/develop-tdd.mdc | 19 +- .cursor/rules/diagnose-stall.mdc | 54 + .cursor/rules/dispatch-agents.mdc | 68 +- .cursor/rules/gate-trace.mdc | 10 +- .cursor/rules/guard-git.mdc | 14 + .cursor/rules/migrate-spec.mdc | 12 + .cursor/rules/plan-work.mdc | 64 +- .cursor/rules/publish-package.mdc | 11 + .cursor/rules/release-branch.mdc | 82 +- .cursor/rules/request-review.mdc | 74 +- .cursor/rules/run-benchmark.mdc | 6 +- .cursor/rules/run-evals.mdc | 32 +- .cursor/rules/security-review.mdc | 64 +- .cursor/rules/seed-conventions.mdc | 61 + .cursor/rules/session-state.mdc | 15 +- .cursor/rules/slice-tasks.mdc | 3 + .cursor/rules/smoke-test.mdc | 11 + .cursor/rules/stocktake-skills.mdc | 3 +- .cursor/rules/validate-contracts.mdc | 12 + .cursor/rules/validate-fix.mdc | 2 + .cursor/rules/verify-work.mdc | 51 +- .cursor/rules/wire-ci.mdc | 11 + .cursor/rules/write-document.mdc | 10 + .../bigpowers/commands/context7-mcp.toml | 2 + .../bigpowers/commands/diagnose-stall.toml | 2 + .../bigpowers/commands/prompts/audit-code.md | 30 +- .../commands/prompts/change-request.md | 4 +- .../commands/prompts/compose-workflow.md | 15 + .../commands/prompts/context7-mcp.md | 50 + .../bigpowers/commands/prompts/craft-skill.md | 28 + .../commands/prompts/deepen-architecture.md | 20 + .../commands/prompts/delegate-task.md | 14 + .../bigpowers/commands/prompts/deploy.md | 8 + .../bigpowers/commands/prompts/develop-tdd.md | 19 +- .../commands/prompts/diagnose-stall.md | 49 + .../commands/prompts/dispatch-agents.md | 68 +- .../bigpowers/commands/prompts/gate-trace.md | 10 +- .../bigpowers/commands/prompts/guard-git.md | 14 + .../commands/prompts/migrate-spec.md | 12 + .../bigpowers/commands/prompts/plan-work.md | 64 +- .../commands/prompts/publish-package.md | 11 + .../commands/prompts/release-branch.md | 82 +- .../commands/prompts/request-review.md | 74 +- .../commands/prompts/run-benchmark.md | 6 +- .../bigpowers/commands/prompts/run-evals.md | 32 +- .../commands/prompts/security-review.md | 64 +- .../commands/prompts/seed-conventions.md | 61 + .../commands/prompts/session-state.md | 15 +- .../bigpowers/commands/prompts/slice-tasks.md | 3 + .../bigpowers/commands/prompts/smoke-test.md | 11 + .../commands/prompts/stocktake-skills.md | 3 +- .../commands/prompts/validate-contracts.md | 12 + .../commands/prompts/validate-fix.md | 2 + .../bigpowers/commands/prompts/verify-work.md | 51 +- .../bigpowers/commands/prompts/wire-ci.md | 11 + .../commands/prompts/write-document.md | 10 + .../bigpowers/gemini-extension.json | 2 +- .../bigpowers/skills/audit-code/SKILL.md | 30 +- .../bigpowers/skills/change-request/SKILL.md | 4 +- .../skills/compose-workflow/SKILL.md | 15 + .../bigpowers/skills/context7-mcp/SKILL.md | 55 + .../bigpowers/skills/craft-skill/SKILL.md | 28 + .../skills/deepen-architecture/SKILL.md | 20 + .../bigpowers/skills/delegate-task/SKILL.md | 14 + .../bigpowers/skills/deploy/SKILL.md | 8 + .../bigpowers/skills/develop-tdd/SKILL.md | 19 +- .../bigpowers/skills/diagnose-stall/SKILL.md | 54 + .../bigpowers/skills/dispatch-agents/SKILL.md | 68 +- .../bigpowers/skills/gate-trace/SKILL.md | 10 +- .../bigpowers/skills/guard-git/SKILL.md | 14 + .../bigpowers/skills/migrate-spec/SKILL.md | 12 + .../bigpowers/skills/plan-work/SKILL.md | 64 +- .../bigpowers/skills/publish-package/SKILL.md | 11 + .../bigpowers/skills/release-branch/SKILL.md | 82 +- .../bigpowers/skills/request-review/SKILL.md | 74 +- .../bigpowers/skills/run-benchmark/SKILL.md | 6 +- .../bigpowers/skills/run-evals/SKILL.md | 32 +- .../bigpowers/skills/security-review/SKILL.md | 64 +- .../skills/seed-conventions/SKILL.md | 61 + .../bigpowers/skills/session-state/SKILL.md | 15 +- .../bigpowers/skills/slice-tasks/SKILL.md | 3 + .../bigpowers/skills/smoke-test/SKILL.md | 11 + .../skills/stocktake-skills/SKILL.md | 3 +- .../skills/validate-contracts/SKILL.md | 12 + .../bigpowers/skills/validate-fix/SKILL.md | 2 + .../bigpowers/skills/verify-work/SKILL.md | 51 +- .../bigpowers/skills/wire-ci/SKILL.md | 11 + .../bigpowers/skills/write-document/SKILL.md | 10 + .github/workflows/sync-references.yml | 17 + .kilocode/rules/context7-mcp.md | 0 .kilocode/rules/diagnose-stall.md | 0 .pi/package.json | 2 +- .pi/prompts/audit-code.md | 30 +- .pi/prompts/change-request.md | 4 +- .pi/prompts/compose-workflow.md | 15 + .pi/prompts/context7-mcp.md | 54 + .pi/prompts/craft-skill.md | 28 + .pi/prompts/deepen-architecture.md | 20 + .pi/prompts/delegate-task.md | 14 + .pi/prompts/deploy.md | 8 + .pi/prompts/develop-tdd.md | 19 +- .pi/prompts/diagnose-stall.md | 53 + .pi/prompts/dispatch-agents.md | 68 +- .pi/prompts/gate-trace.md | 10 +- .pi/prompts/guard-git.md | 14 + .pi/prompts/migrate-spec.md | 12 + .pi/prompts/plan-work.md | 64 +- .pi/prompts/publish-package.md | 11 + .pi/prompts/release-branch.md | 82 +- .pi/prompts/request-review.md | 74 +- .pi/prompts/run-benchmark.md | 6 +- .pi/prompts/run-evals.md | 32 +- .pi/prompts/security-review.md | 64 +- .pi/prompts/seed-conventions.md | 61 + .pi/prompts/session-state.md | 15 +- .pi/prompts/slice-tasks.md | 3 + .pi/prompts/smoke-test.md | 11 + .pi/prompts/stocktake-skills.md | 3 +- .pi/prompts/validate-contracts.md | 12 + .pi/prompts/validate-fix.md | 2 + .pi/prompts/verify-work.md | 51 +- .pi/prompts/wire-ci.md | 11 + .pi/prompts/write-document.md | 10 + .pi/skills/audit-code/SKILL.md | 30 +- .pi/skills/change-request/SKILL.md | 4 +- .pi/skills/compose-workflow/SKILL.md | 15 + .pi/skills/context7-mcp/SKILL.md | 56 + .pi/skills/craft-skill/SKILL.md | 28 + .pi/skills/deepen-architecture/SKILL.md | 20 + .pi/skills/delegate-task/SKILL.md | 14 + .pi/skills/deploy/SKILL.md | 8 + .pi/skills/develop-tdd/SKILL.md | 19 +- .pi/skills/diagnose-stall/SKILL.md | 55 + .pi/skills/dispatch-agents/SKILL.md | 68 +- .pi/skills/gate-trace/SKILL.md | 10 +- .pi/skills/guard-git/SKILL.md | 14 + .pi/skills/migrate-spec/SKILL.md | 12 + .pi/skills/plan-work/SKILL.md | 64 +- .pi/skills/publish-package/SKILL.md | 11 + .pi/skills/release-branch/SKILL.md | 82 +- .pi/skills/request-review/SKILL.md | 74 +- .pi/skills/run-benchmark/SKILL.md | 6 +- .pi/skills/run-evals/SKILL.md | 32 +- .pi/skills/security-review/SKILL.md | 64 +- .pi/skills/seed-conventions/SKILL.md | 61 + .pi/skills/session-state/SKILL.md | 15 +- .pi/skills/slice-tasks/SKILL.md | 3 + .pi/skills/smoke-test/SKILL.md | 11 + .pi/skills/stocktake-skills/SKILL.md | 3 +- .pi/skills/validate-contracts/SKILL.md | 12 + .pi/skills/validate-fix/SKILL.md | 2 + .pi/skills/verify-work/SKILL.md | 51 +- .pi/skills/wire-ci/SKILL.md | 11 + .pi/skills/write-document/SKILL.md | 10 + CLAUDE.md | 60 +- CONVENTIONS.md | 76 + README.md | 2 +- SKILL-INDEX.md | 2 +- docs/countable-story-format.md | 3 + docs/references/.sync-stamp | 1 + docs/references/context-engineering.md | 2 + docs/references/model-profiles.md | 6 +- docs/templates/AGENTS.md | 19 + scripts/bp-churn-rank.sh | 49 + scripts/check-import-boundaries.sh | 64 + scripts/compile-rule-matrix.sh | 114 ++ scripts/hooks/rtk-rewrite.sh | 11 + scripts/hooks/token-mgmt-pre-tool-use.sh | 53 + scripts/install.sh | 6 + scripts/lib/completeness-critic.sh | 62 + scripts/lib/doc-fetch-cache.sh | 71 + scripts/lib/golden-suite-gates.sh | 4 +- scripts/lib/parallel-review-worktrees.sh | 34 + scripts/lib/plan-consistency-check.sh | 88 + scripts/lib/run-benchmark.py | 210 +++ scripts/lib/sync-context-engineering-ref.sh | 19 + scripts/references-manifest.yaml | 19 + scripts/run-benchmark.sh | 6 + scripts/sync-references.sh | 25 + scripts/validate-skill-catalog.sh | 147 ++ scripts/validate-skill-description.sh | 70 + skills-lock.json | 54 +- skills/audit-code/SKILL.md | 32 +- skills/change-request/SKILL.md | 4 +- skills/compose-workflow/SKILL.md | 15 + skills/context7-mcp/SKILL.md | 57 + skills/craft-skill/SKILL.md | 29 + skills/deepen-architecture/SKILL.md | 22 + skills/delegate-task/SKILL.md | 14 + skills/deploy/SKILL.md | 9 + skills/develop-tdd/SKILL.md | 22 +- skills/diagnose-stall/SKILL.md | 56 + skills/dispatch-agents/SKILL.md | 70 +- skills/gate-trace/SKILL.md | 12 +- skills/guard-git/REFERENCE.md | 14 + skills/migrate-spec/REFERENCE.md | 12 + skills/plan-work/REFERENCE.md | 31 +- skills/plan-work/SKILL.md | 38 + skills/publish-package/REFERENCE.md | 11 + skills/release-branch/REFERENCE.md | 14 + skills/release-branch/SKILL.md | 71 +- skills/request-review/SKILL.md | 76 +- skills/run-benchmark/SKILL.md | 8 +- skills/run-evals/REFERENCE.md | 18 +- skills/run-evals/SKILL.md | 15 +- .../REFERENCE-false-positives.md | 17 +- .../REFERENCE-vuln-categories.md | 4 + skills/security-review/SKILL.md | 45 + .../fixtures/CWE-79-xss-negative.js | 6 + .../fixtures/CWE-79-xss-positive.js | 6 + .../fixtures/CWE-89-sqli-negative.py | 8 + .../fixtures/CWE-89-sqli-positive.py | 9 + skills/seed-conventions/REFERENCE.md | 40 + skills/seed-conventions/SKILL.md | 22 + skills/session-state/SKILL.md | 15 +- skills/slice-tasks/SKILL.md | 3 + skills/smoke-test/REFERENCE.md | 11 + skills/stocktake-skills/SKILL.md | 4 +- skills/validate-contracts/REFERENCE.md | 12 + skills/validate-fix/SKILL.md | 3 + skills/verify-work/REFERENCE.md | 17 + skills/verify-work/SKILL.md | 38 +- skills/wire-ci/REFERENCE.md | 11 + skills/write-document/REFERENCE.md | 10 + specs/SKILL-SEARCH-INDEX_LATEST.md | 2 + specs/TRACEABILITY_LATEST.md | 111 +- specs/agent-guide/context-routing.md | 18 + specs/agent-guide/index.md | 3 + specs/agent-guide/learned-user-preferences.md | 17 + specs/agent-guide/token-management.md | 4 +- specs/agent-guide/workspace-facts.md | 17 + .../BENCHMARK-survey-context-2026-07-06.yaml | 26 + .../benchmarks/reports/GOLDEN-2026-07-06.yaml | 22 +- .../benchmarks/reports/GOLDEN-2026-07-07.yaml | 64 + .../reports/benchmark-survey-context.json | 1 + specs/blind-spots.json | 307 +++- specs/codebase-wiki/e45s01.md | 25 + specs/codebase-wiki/e45s02.md | 27 +- specs/codebase-wiki/e45s03.md | 5 + specs/codebase-wiki/e45s04.md | 10 + specs/codebase-wiki/e45s05.md | 17 +- specs/codebase-wiki/e45s06.md | 17 +- specs/codebase-wiki/e45s07.md | 17 +- specs/codebase-wiki/e45s08.md | 12 +- specs/codebase-wiki/e45s09.md | 17 +- specs/codebase-wiki/e45s10.md | 27 +- specs/codebase-wiki/e45s11.md | 7 +- specs/codebase-wiki/e45s12.md | 17 +- specs/codebase-wiki/e45s13.md | 7 +- specs/codebase-wiki/e45s14.md | 12 +- specs/codebase-wiki/e45s15.md | 12 +- specs/codebase-wiki/e45s16.md | 17 +- specs/codebase-wiki/e45s17.md | 12 +- specs/codebase-wiki/e45s18.md | 212 ++- specs/codebase-wiki/e45s19.md | 7 +- specs/codebase-wiki/e45s20.md | 12 +- specs/codebase-wiki/e45s21.md | 37 +- specs/codebase-wiki/e45s22.md | 7 +- specs/codebase-wiki/e45s23.md | 37 +- specs/codebase-wiki/e45s25.md | 17 +- specs/codebase-wiki/e45s26.md | 47 +- specs/codebase-wiki/e45s27.md | 32 +- specs/codebase-wiki/e45s28.md | 27 +- specs/codebase-wiki/e45s29.md | 82 +- specs/codebase-wiki/e45s30.md | 57 +- specs/codebase-wiki/e45s31.md | 212 ++- specs/codebase-wiki/e45s32.md | 12 +- specs/codebase-wiki/e45s33.md | 17 +- specs/codebase-wiki/e45s34.md | 7 +- specs/codebase-wiki/e45s35.md | 7 +- specs/codebase-wiki/e45s36.md | 12 +- specs/codebase-wiki/e45s37.md | 7 +- specs/codebase-wiki/e45s38.md | 12 +- specs/codebase-wiki/e45s39.md | 12 +- specs/codebase-wiki/e45s40.md | 7 +- specs/codebase-wiki/e45s41.md | 7 +- specs/codebase-wiki/e48s01.md | 10 +- specs/codebase-wiki/e48s02.md | 20 + specs/codebase-wiki/e48s03.md | 5 + specs/codebase-wiki/e48s05.md | 25 + specs/codebase-wiki/e48s06.md | 5 + specs/codebase-wiki/index.md | 90 +- .../docs-references-ssot-sync-e45s10.md | 20 + .../documentation-responsibilities-e45s36.md | 32 + specs/conventions-wiki/index.md | 7 + .../p0-critical-never-violate.md | 15 + .../p1-high-fix-before-merge.md | 15 + .../p2-medium-address-in-same-epic-or-next.md | 15 + specs/conventions-wiki/p3-low-best-effort.md | 14 + .../risk-tiers-effective-rule-matrix.md | 18 + specs/epics/e45-quality-core/epic.yaml | 84 +- specs/execution-status.yaml | 84 +- specs/import-boundaries.json | 42 + specs/release-plan.yaml | 2 +- specs/rule-matrix.json | 129 ++ specs/state.yaml | 17 +- specs/traceability-matrix.json | 1496 +++++++++++++++-- 307 files changed, 9131 insertions(+), 1288 deletions(-) create mode 100644 .continue/rules/context7-mcp.md create mode 100644 .continue/rules/diagnose-stall.md create mode 100644 .cursor/rules/context7-mcp.mdc create mode 100644 .cursor/rules/diagnose-stall.mdc create mode 100644 .gemini/extensions/bigpowers/commands/context7-mcp.toml create mode 100644 .gemini/extensions/bigpowers/commands/diagnose-stall.toml create mode 100644 .gemini/extensions/bigpowers/commands/prompts/context7-mcp.md create mode 100644 .gemini/extensions/bigpowers/commands/prompts/diagnose-stall.md create mode 100644 .gemini/extensions/bigpowers/skills/context7-mcp/SKILL.md create mode 100644 .gemini/extensions/bigpowers/skills/diagnose-stall/SKILL.md create mode 100644 .github/workflows/sync-references.yml create mode 100644 .kilocode/rules/context7-mcp.md create mode 100644 .kilocode/rules/diagnose-stall.md create mode 100644 .pi/prompts/context7-mcp.md create mode 100644 .pi/prompts/diagnose-stall.md create mode 100644 .pi/skills/context7-mcp/SKILL.md create mode 100644 .pi/skills/diagnose-stall/SKILL.md create mode 100644 docs/references/.sync-stamp create mode 100755 scripts/bp-churn-rank.sh create mode 100755 scripts/check-import-boundaries.sh create mode 100755 scripts/compile-rule-matrix.sh create mode 100755 scripts/hooks/rtk-rewrite.sh create mode 100755 scripts/hooks/token-mgmt-pre-tool-use.sh create mode 100755 scripts/lib/completeness-critic.sh create mode 100755 scripts/lib/doc-fetch-cache.sh create mode 100755 scripts/lib/parallel-review-worktrees.sh create mode 100755 scripts/lib/plan-consistency-check.sh create mode 100755 scripts/lib/run-benchmark.py create mode 100755 scripts/lib/sync-context-engineering-ref.sh create mode 100644 scripts/references-manifest.yaml create mode 100755 scripts/run-benchmark.sh create mode 100755 scripts/sync-references.sh create mode 100755 scripts/validate-skill-catalog.sh create mode 100755 scripts/validate-skill-description.sh create mode 100644 skills/context7-mcp/SKILL.md create mode 100644 skills/diagnose-stall/SKILL.md create mode 100644 skills/security-review/fixtures/CWE-79-xss-negative.js create mode 100644 skills/security-review/fixtures/CWE-79-xss-positive.js create mode 100644 skills/security-review/fixtures/CWE-89-sqli-negative.py create mode 100644 skills/security-review/fixtures/CWE-89-sqli-positive.py create mode 100644 specs/agent-guide/context-routing.md create mode 100644 specs/agent-guide/learned-user-preferences.md create mode 100644 specs/agent-guide/workspace-facts.md create mode 100644 specs/benchmarks/reports/BENCHMARK-survey-context-2026-07-06.yaml create mode 100644 specs/benchmarks/reports/GOLDEN-2026-07-07.yaml create mode 100644 specs/benchmarks/reports/benchmark-survey-context.json create mode 100644 specs/conventions-wiki/docs-references-ssot-sync-e45s10.md create mode 100644 specs/conventions-wiki/documentation-responsibilities-e45s36.md create mode 100644 specs/conventions-wiki/p0-critical-never-violate.md create mode 100644 specs/conventions-wiki/p1-high-fix-before-merge.md create mode 100644 specs/conventions-wiki/p2-medium-address-in-same-epic-or-next.md create mode 100644 specs/conventions-wiki/p3-low-best-effort.md create mode 100644 specs/conventions-wiki/risk-tiers-effective-rule-matrix.md create mode 100644 specs/import-boundaries.json create mode 100644 specs/rule-matrix.json diff --git a/.continue/rules/context7-mcp.md b/.continue/rules/context7-mcp.md new file mode 100644 index 00000000..e69de29b diff --git a/.continue/rules/diagnose-stall.md b/.continue/rules/diagnose-stall.md new file mode 100644 index 00000000..e69de29b diff --git a/.cursor/rules/audit-code.mdc b/.cursor/rules/audit-code.mdc index 54bcdb61..6acd8f91 100644 --- a/.cursor/rules/audit-code.mdc +++ b/.cursor/rules/audit-code.mdc @@ -12,11 +12,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -108,24 +124,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/.cursor/rules/change-request.mdc b/.cursor/rules/change-request.mdc index 21a518d2..2a791b63 100644 --- a/.cursor/rules/change-request.mdc +++ b/.cursor/rules/change-request.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -18,7 +20,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/.cursor/rules/compose-workflow.mdc b/.cursor/rules/compose-workflow.mdc index c8cb9794..67d724d4 100644 --- a/.cursor/rules/compose-workflow.mdc +++ b/.cursor/rules/compose-workflow.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -20,6 +22,19 @@ alwaysApply: false > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/.cursor/rules/context7-mcp.mdc b/.cursor/rules/context7-mcp.mdc new file mode 100644 index 00000000..21a338e9 --- /dev/null +++ b/.cursor/rules/context7-mcp.mdc @@ -0,0 +1,55 @@ +--- +description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc." +alwaysApply: false +--- + + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/.cursor/rules/craft-skill.mdc b/.cursor/rules/craft-skill.mdc index c10babc2..a30ba7a4 100644 --- a/.cursor/rules/craft-skill.mdc +++ b/.cursor/rules/craft-skill.mdc @@ -8,6 +8,19 @@ alwaysApply: false > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -39,6 +52,12 @@ alwaysApply: false - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -52,12 +71,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify + +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` --- diff --git a/.cursor/rules/deepen-architecture.mdc b/.cursor/rules/deepen-architecture.mdc index 6fdf21ad..532445b7 100644 --- a/.cursor/rules/deepen-architecture.mdc +++ b/.cursor/rules/deepen-architecture.mdc @@ -44,6 +44,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -92,6 +98,20 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + --- # Deepening diff --git a/.cursor/rules/delegate-task.mdc b/.cursor/rules/delegate-task.mdc index 27ce9f8f..f631aff0 100644 --- a/.cursor/rules/delegate-task.mdc +++ b/.cursor/rules/delegate-task.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -12,6 +14,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/.cursor/rules/deploy.mdc b/.cursor/rules/deploy.mdc index 129d6572..f339d793 100644 --- a/.cursor/rules/deploy.mdc +++ b/.cursor/rules/deploy.mdc @@ -104,6 +104,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + --- # Deploy — Reference diff --git a/.cursor/rules/develop-tdd.mdc b/.cursor/rules/develop-tdd.mdc index 54b08f42..176a2af7 100644 --- a/.cursor/rules/develop-tdd.mdc +++ b/.cursor/rules/develop-tdd.mdc @@ -50,16 +50,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/.cursor/rules/diagnose-stall.mdc b/.cursor/rules/diagnose-stall.mdc new file mode 100644 index 00000000..ab25a569 --- /dev/null +++ b/.cursor/rules/diagnose-stall.mdc @@ -0,0 +1,54 @@ +--- +description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned." +alwaysApply: false +--- + + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/.cursor/rules/dispatch-agents.mdc b/.cursor/rules/dispatch-agents.mdc index f14bc7df..f992ec0c 100644 --- a/.cursor/rules/dispatch-agents.mdc +++ b/.cursor/rules/dispatch-agents.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -35,30 +37,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -72,13 +101,14 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/.cursor/rules/gate-trace.mdc b/.cursor/rules/gate-trace.mdc index 8282543c..111017a9 100644 --- a/.cursor/rules/gate-trace.mdc +++ b/.cursor/rules/gate-trace.mdc @@ -37,7 +37,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/.cursor/rules/guard-git.mdc b/.cursor/rules/guard-git.mdc index 1576b327..f6394dd5 100644 --- a/.cursor/rules/guard-git.mdc +++ b/.cursor/rules/guard-git.mdc @@ -47,6 +47,20 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/.cursor/rules/migrate-spec.mdc b/.cursor/rules/migrate-spec.mdc index ca8ab14d..14aa75fc 100644 --- a/.cursor/rules/migrate-spec.mdc +++ b/.cursor/rules/migrate-spec.mdc @@ -239,6 +239,18 @@ These GSD artifacts are not migrated — they are execution records, not plannin # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/.cursor/rules/plan-work.mdc b/.cursor/rules/plan-work.mdc index f4a02757..83452372 100644 --- a/.cursor/rules/plan-work.mdc +++ b/.cursor/rules/plan-work.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -45,14 +47,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff @@ -64,6 +97,17 @@ Writes: state.yaml handoff.next_skill = kickoff-branch # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -75,14 +119,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -153,6 +197,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/.cursor/rules/publish-package.mdc b/.cursor/rules/publish-package.mdc index e63daf02..3603ce06 100644 --- a/.cursor/rules/publish-package.mdc +++ b/.cursor/rules/publish-package.mdc @@ -78,6 +78,17 @@ See [REFERENCE.md](REFERENCE.md) # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/.cursor/rules/release-branch.mdc b/.cursor/rules/release-branch.mdc index 366e4b4d..b707b5dc 100644 --- a/.cursor/rules/release-branch.mdc +++ b/.cursor/rules/release-branch.mdc @@ -53,6 +53,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -73,9 +75,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -91,55 +110,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL - -### 8. Clean up worktree - -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -After landing, record delivery metrics with the git-derived, additive script: +### 8. Clean up & return -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." @@ -151,6 +133,20 @@ Report: "Branch released." # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/.cursor/rules/request-review.mdc b/.cursor/rules/request-review.mdc index 015d4e03..fe18becb 100644 --- a/.cursor/rules/request-review.mdc +++ b/.cursor/rules/request-review.mdc @@ -4,21 +4,44 @@ alwaysApply: false --- +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. + +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -28,12 +51,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | + +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -55,18 +91,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." + +## Verify -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/.cursor/rules/run-benchmark.mdc b/.cursor/rules/run-benchmark.mdc index 7b142430..968f8cb0 100644 --- a/.cursor/rules/run-benchmark.mdc +++ b/.cursor/rules/run-benchmark.mdc @@ -28,9 +28,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/.cursor/rules/run-evals.mdc b/.cursor/rules/run-evals.mdc index f1a66f67..2134fb29 100644 --- a/.cursor/rules/run-evals.mdc +++ b/.cursor/rules/run-evals.mdc @@ -15,8 +15,18 @@ alwaysApply: false - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact @@ -30,16 +40,26 @@ alwaysApply: false # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/.cursor/rules/security-review.mdc b/.cursor/rules/security-review.mdc index 33d94be6..c0b1228c 100644 --- a/.cursor/rules/security-review.mdc +++ b/.cursor/rules/security-review.mdc @@ -4,12 +4,24 @@ alwaysApply: false --- +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -24,6 +36,37 @@ alwaysApply: false Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. @@ -175,14 +218,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules @@ -234,6 +278,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -243,6 +289,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/.cursor/rules/seed-conventions.mdc b/.cursor/rules/seed-conventions.mdc index b54575a6..dcdf5218 100644 --- a/.cursor/rules/seed-conventions.mdc +++ b/.cursor/rules/seed-conventions.mdc @@ -62,7 +62,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention @@ -76,8 +97,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain --- # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/.cursor/rules/session-state.mdc b/.cursor/rules/session-state.mdc index d2dc569a..4bb98c6a 100644 --- a/.cursor/rules/session-state.mdc +++ b/.cursor/rules/session-state.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -18,6 +20,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -64,6 +68,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -130,16 +135,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/.cursor/rules/slice-tasks.mdc b/.cursor/rules/slice-tasks.mdc index 88533436..5f0af76b 100644 --- a/.cursor/rules/slice-tasks.mdc +++ b/.cursor/rules/slice-tasks.mdc @@ -4,6 +4,8 @@ alwaysApply: false --- +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -36,6 +38,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/.cursor/rules/smoke-test.mdc b/.cursor/rules/smoke-test.mdc index 7278dd3f..c117608e 100644 --- a/.cursor/rules/smoke-test.mdc +++ b/.cursor/rules/smoke-test.mdc @@ -69,6 +69,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/.cursor/rules/stocktake-skills.mdc b/.cursor/rules/stocktake-skills.mdc index 320313b3..83566fa1 100644 --- a/.cursor/rules/stocktake-skills.mdc +++ b/.cursor/rules/stocktake-skills.mdc @@ -20,6 +20,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -51,7 +52,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/.cursor/rules/validate-contracts.mdc b/.cursor/rules/validate-contracts.mdc index 9b725180..188fd69e 100644 --- a/.cursor/rules/validate-contracts.mdc +++ b/.cursor/rules/validate-contracts.mdc @@ -114,6 +114,18 @@ bash scripts/validate-contracts.sh # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/.cursor/rules/validate-fix.mdc b/.cursor/rules/validate-fix.mdc index 2cadb3c0..08f0dd5b 100644 --- a/.cursor/rules/validate-fix.mdc +++ b/.cursor/rules/validate-fix.mdc @@ -10,6 +10,8 @@ alwaysApply: false Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/.cursor/rules/verify-work.mdc b/.cursor/rules/verify-work.mdc index 61d9c49e..3cf0bfba 100644 --- a/.cursor/rules/verify-work.mdc +++ b/.cursor/rules/verify-work.mdc @@ -44,12 +44,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -92,6 +100,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -113,26 +126,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify @@ -167,3 +161,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/.cursor/rules/wire-ci.mdc b/.cursor/rules/wire-ci.mdc index 0c8e8314..916cd507 100644 --- a/.cursor/rules/wire-ci.mdc +++ b/.cursor/rules/wire-ci.mdc @@ -107,6 +107,17 @@ Add the following to the project's documentation or CLAUDE.md after setup: # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/.cursor/rules/write-document.mdc b/.cursor/rules/write-document.mdc index 4fbf34ee..822e1c5b 100644 --- a/.cursor/rules/write-document.mdc +++ b/.cursor/rules/write-document.mdc @@ -81,6 +81,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`. Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/.gemini/extensions/bigpowers/commands/context7-mcp.toml b/.gemini/extensions/bigpowers/commands/context7-mcp.toml new file mode 100644 index 00000000..5b17a638 --- /dev/null +++ b/.gemini/extensions/bigpowers/commands/context7-mcp.toml @@ -0,0 +1,2 @@ +description = "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc." +prompt = "@{commands/prompts/context7-mcp.md}" diff --git a/.gemini/extensions/bigpowers/commands/diagnose-stall.toml b/.gemini/extensions/bigpowers/commands/diagnose-stall.toml new file mode 100644 index 00000000..6948751f --- /dev/null +++ b/.gemini/extensions/bigpowers/commands/diagnose-stall.toml @@ -0,0 +1,2 @@ +description = "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned." +prompt = "@{commands/prompts/diagnose-stall.md}" diff --git a/.gemini/extensions/bigpowers/commands/prompts/audit-code.md b/.gemini/extensions/bigpowers/commands/prompts/audit-code.md index 161ac0ea..b517e5f9 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/audit-code.md +++ b/.gemini/extensions/bigpowers/commands/prompts/audit-code.md @@ -7,11 +7,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -103,24 +119,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/.gemini/extensions/bigpowers/commands/prompts/change-request.md b/.gemini/extensions/bigpowers/commands/prompts/change-request.md index 1b80dcf3..a5bc2301 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/change-request.md +++ b/.gemini/extensions/bigpowers/commands/prompts/change-request.md @@ -1,4 +1,6 @@ +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -13,7 +15,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/.gemini/extensions/bigpowers/commands/prompts/compose-workflow.md b/.gemini/extensions/bigpowers/commands/prompts/compose-workflow.md index 26248138..049ecae1 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/compose-workflow.md +++ b/.gemini/extensions/bigpowers/commands/prompts/compose-workflow.md @@ -1,4 +1,6 @@ +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -15,6 +17,19 @@ > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/.gemini/extensions/bigpowers/commands/prompts/context7-mcp.md b/.gemini/extensions/bigpowers/commands/prompts/context7-mcp.md new file mode 100644 index 00000000..dd543614 --- /dev/null +++ b/.gemini/extensions/bigpowers/commands/prompts/context7-mcp.md @@ -0,0 +1,50 @@ + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md b/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md index 4710d6c8..892e4558 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md +++ b/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md @@ -3,6 +3,19 @@ > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -34,6 +47,12 @@ - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -47,12 +66,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify + +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` --- diff --git a/.gemini/extensions/bigpowers/commands/prompts/deepen-architecture.md b/.gemini/extensions/bigpowers/commands/prompts/deepen-architecture.md index f78f4c22..62aa10a0 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/deepen-architecture.md +++ b/.gemini/extensions/bigpowers/commands/prompts/deepen-architecture.md @@ -39,6 +39,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -87,6 +93,20 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + --- # Deepening diff --git a/.gemini/extensions/bigpowers/commands/prompts/delegate-task.md b/.gemini/extensions/bigpowers/commands/prompts/delegate-task.md index cab9a1ac..d4d14408 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/delegate-task.md +++ b/.gemini/extensions/bigpowers/commands/prompts/delegate-task.md @@ -1,4 +1,6 @@ +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -7,6 +9,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/.gemini/extensions/bigpowers/commands/prompts/deploy.md b/.gemini/extensions/bigpowers/commands/prompts/deploy.md index 7a0236bc..a74cb219 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/deploy.md +++ b/.gemini/extensions/bigpowers/commands/prompts/deploy.md @@ -99,6 +99,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + --- # Deploy — Reference diff --git a/.gemini/extensions/bigpowers/commands/prompts/develop-tdd.md b/.gemini/extensions/bigpowers/commands/prompts/develop-tdd.md index 595b7a0e..b67a8dc6 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/develop-tdd.md +++ b/.gemini/extensions/bigpowers/commands/prompts/develop-tdd.md @@ -45,16 +45,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/.gemini/extensions/bigpowers/commands/prompts/diagnose-stall.md b/.gemini/extensions/bigpowers/commands/prompts/diagnose-stall.md new file mode 100644 index 00000000..00adffc0 --- /dev/null +++ b/.gemini/extensions/bigpowers/commands/prompts/diagnose-stall.md @@ -0,0 +1,49 @@ + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/.gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md b/.gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md index 95cb25c4..7985036a 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md +++ b/.gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md @@ -1,4 +1,6 @@ +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -30,30 +32,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -67,13 +96,14 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/.gemini/extensions/bigpowers/commands/prompts/gate-trace.md b/.gemini/extensions/bigpowers/commands/prompts/gate-trace.md index 65f21cd7..a8a6c943 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/gate-trace.md +++ b/.gemini/extensions/bigpowers/commands/prompts/gate-trace.md @@ -32,7 +32,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/.gemini/extensions/bigpowers/commands/prompts/guard-git.md b/.gemini/extensions/bigpowers/commands/prompts/guard-git.md index f6abdadf..9901d4ac 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/guard-git.md +++ b/.gemini/extensions/bigpowers/commands/prompts/guard-git.md @@ -42,6 +42,20 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/.gemini/extensions/bigpowers/commands/prompts/migrate-spec.md b/.gemini/extensions/bigpowers/commands/prompts/migrate-spec.md index 0273ef93..6a60e02e 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/migrate-spec.md +++ b/.gemini/extensions/bigpowers/commands/prompts/migrate-spec.md @@ -234,6 +234,18 @@ These GSD artifacts are not migrated — they are execution records, not plannin # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/.gemini/extensions/bigpowers/commands/prompts/plan-work.md b/.gemini/extensions/bigpowers/commands/prompts/plan-work.md index e28f0145..f6dab54c 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/plan-work.md +++ b/.gemini/extensions/bigpowers/commands/prompts/plan-work.md @@ -1,4 +1,6 @@ +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -40,14 +42,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff @@ -59,6 +92,17 @@ Writes: state.yaml handoff.next_skill = kickoff-branch # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -70,14 +114,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -148,6 +192,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/.gemini/extensions/bigpowers/commands/prompts/publish-package.md b/.gemini/extensions/bigpowers/commands/prompts/publish-package.md index fba6bc44..5c7dff19 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/publish-package.md +++ b/.gemini/extensions/bigpowers/commands/prompts/publish-package.md @@ -73,6 +73,17 @@ See [REFERENCE.md](REFERENCE.md) # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/.gemini/extensions/bigpowers/commands/prompts/release-branch.md b/.gemini/extensions/bigpowers/commands/prompts/release-branch.md index 9a807eb7..5a2afa8c 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/release-branch.md +++ b/.gemini/extensions/bigpowers/commands/prompts/release-branch.md @@ -48,6 +48,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -68,9 +70,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -86,55 +105,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL - -### 8. Clean up worktree - -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -After landing, record delivery metrics with the git-derived, additive script: +### 8. Clean up & return -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." @@ -146,6 +128,20 @@ Report: "Branch released." # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/.gemini/extensions/bigpowers/commands/prompts/request-review.md b/.gemini/extensions/bigpowers/commands/prompts/request-review.md index 1b574680..0bc67032 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/request-review.md +++ b/.gemini/extensions/bigpowers/commands/prompts/request-review.md @@ -1,19 +1,42 @@ +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. + +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -23,12 +46,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | + +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -50,18 +86,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." + +## Verify -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/.gemini/extensions/bigpowers/commands/prompts/run-benchmark.md b/.gemini/extensions/bigpowers/commands/prompts/run-benchmark.md index 874f1ff1..14da844c 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/run-benchmark.md +++ b/.gemini/extensions/bigpowers/commands/prompts/run-benchmark.md @@ -23,9 +23,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/.gemini/extensions/bigpowers/commands/prompts/run-evals.md b/.gemini/extensions/bigpowers/commands/prompts/run-evals.md index 28415f71..7df6f169 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/run-evals.md +++ b/.gemini/extensions/bigpowers/commands/prompts/run-evals.md @@ -10,8 +10,18 @@ - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact @@ -25,16 +35,26 @@ # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/.gemini/extensions/bigpowers/commands/prompts/security-review.md b/.gemini/extensions/bigpowers/commands/prompts/security-review.md index f7ea7615..5878e1af 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/security-review.md +++ b/.gemini/extensions/bigpowers/commands/prompts/security-review.md @@ -1,10 +1,22 @@ +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -19,6 +31,37 @@ Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. @@ -170,14 +213,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules @@ -229,6 +273,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -238,6 +284,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/.gemini/extensions/bigpowers/commands/prompts/seed-conventions.md b/.gemini/extensions/bigpowers/commands/prompts/seed-conventions.md index 0f6df1a7..ec3731e8 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/seed-conventions.md +++ b/.gemini/extensions/bigpowers/commands/prompts/seed-conventions.md @@ -57,7 +57,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention @@ -71,8 +92,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain --- # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/.gemini/extensions/bigpowers/commands/prompts/session-state.md b/.gemini/extensions/bigpowers/commands/prompts/session-state.md index e7a066a4..7e807043 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/session-state.md +++ b/.gemini/extensions/bigpowers/commands/prompts/session-state.md @@ -1,4 +1,6 @@ +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -13,6 +15,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -59,6 +63,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -125,16 +130,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/.gemini/extensions/bigpowers/commands/prompts/slice-tasks.md b/.gemini/extensions/bigpowers/commands/prompts/slice-tasks.md index 9fb08990..5fd91be9 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/slice-tasks.md +++ b/.gemini/extensions/bigpowers/commands/prompts/slice-tasks.md @@ -1,4 +1,6 @@ +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -31,6 +33,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/.gemini/extensions/bigpowers/commands/prompts/smoke-test.md b/.gemini/extensions/bigpowers/commands/prompts/smoke-test.md index 470fdd15..294c1461 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/smoke-test.md +++ b/.gemini/extensions/bigpowers/commands/prompts/smoke-test.md @@ -64,6 +64,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/.gemini/extensions/bigpowers/commands/prompts/stocktake-skills.md b/.gemini/extensions/bigpowers/commands/prompts/stocktake-skills.md index e47119d9..88bea3ba 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/stocktake-skills.md +++ b/.gemini/extensions/bigpowers/commands/prompts/stocktake-skills.md @@ -15,6 +15,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -46,7 +47,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/.gemini/extensions/bigpowers/commands/prompts/validate-contracts.md b/.gemini/extensions/bigpowers/commands/prompts/validate-contracts.md index 060f918c..4ceb1e3b 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/validate-contracts.md +++ b/.gemini/extensions/bigpowers/commands/prompts/validate-contracts.md @@ -109,6 +109,18 @@ bash scripts/validate-contracts.sh # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/.gemini/extensions/bigpowers/commands/prompts/validate-fix.md b/.gemini/extensions/bigpowers/commands/prompts/validate-fix.md index 674d2688..7412fef0 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/validate-fix.md +++ b/.gemini/extensions/bigpowers/commands/prompts/validate-fix.md @@ -5,6 +5,8 @@ Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/.gemini/extensions/bigpowers/commands/prompts/verify-work.md b/.gemini/extensions/bigpowers/commands/prompts/verify-work.md index 527f1e66..abbd6c19 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/verify-work.md +++ b/.gemini/extensions/bigpowers/commands/prompts/verify-work.md @@ -39,12 +39,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -87,6 +95,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -108,26 +121,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify @@ -162,3 +156,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/.gemini/extensions/bigpowers/commands/prompts/wire-ci.md b/.gemini/extensions/bigpowers/commands/prompts/wire-ci.md index 43fd6a93..0c65e395 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/wire-ci.md +++ b/.gemini/extensions/bigpowers/commands/prompts/wire-ci.md @@ -102,6 +102,17 @@ Add the following to the project's documentation or CLAUDE.md after setup: # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/.gemini/extensions/bigpowers/commands/prompts/write-document.md b/.gemini/extensions/bigpowers/commands/prompts/write-document.md index 679d61e8..b94b3b89 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/write-document.md +++ b/.gemini/extensions/bigpowers/commands/prompts/write-document.md @@ -76,6 +76,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`. Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/.gemini/extensions/bigpowers/gemini-extension.json b/.gemini/extensions/bigpowers/gemini-extension.json index a82f8567..6324d2bc 100644 --- a/.gemini/extensions/bigpowers/gemini-extension.json +++ b/.gemini/extensions/bigpowers/gemini-extension.json @@ -1,5 +1,5 @@ { "name": "bigpowers", "version": "2.73.9", - "description": "75 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers" + "description": "77 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers" } diff --git a/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md b/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md index 03a81a45..e6a23ee0 100644 --- a/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md @@ -12,11 +12,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -108,24 +124,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/.gemini/extensions/bigpowers/skills/change-request/SKILL.md b/.gemini/extensions/bigpowers/skills/change-request/SKILL.md index 728f61a5..63d620cc 100644 --- a/.gemini/extensions/bigpowers/skills/change-request/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/change-request/SKILL.md @@ -4,6 +4,8 @@ description: "Add a new requirement or reorder epics by WSJF against specs/relea --- +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -18,7 +20,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/.gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md b/.gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md index ef16a32f..5e79e9ef 100644 --- a/.gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md @@ -4,6 +4,8 @@ description: "Chain multiple bigpowers skills into a custom workflow recipe save --- +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -20,6 +22,19 @@ description: "Chain multiple bigpowers skills into a custom workflow recipe save > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/.gemini/extensions/bigpowers/skills/context7-mcp/SKILL.md b/.gemini/extensions/bigpowers/skills/context7-mcp/SKILL.md new file mode 100644 index 00000000..433ce790 --- /dev/null +++ b/.gemini/extensions/bigpowers/skills/context7-mcp/SKILL.md @@ -0,0 +1,55 @@ +--- +name: context7-mcp +description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc." +--- + + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md b/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md index 343067c7..8944da04 100644 --- a/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md @@ -8,6 +8,19 @@ description: "Create new bigpowers skills with proper structure, progressive dis > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -39,6 +52,12 @@ description: "Create new bigpowers skills with proper structure, progressive dis - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -52,12 +71,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify + +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` --- diff --git a/.gemini/extensions/bigpowers/skills/deepen-architecture/SKILL.md b/.gemini/extensions/bigpowers/skills/deepen-architecture/SKILL.md index c8684095..1084b49b 100644 --- a/.gemini/extensions/bigpowers/skills/deepen-architecture/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/deepen-architecture/SKILL.md @@ -44,6 +44,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -92,6 +98,20 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + --- # Deepening diff --git a/.gemini/extensions/bigpowers/skills/delegate-task/SKILL.md b/.gemini/extensions/bigpowers/skills/delegate-task/SKILL.md index 1cc012e1..07e2cdf6 100644 --- a/.gemini/extensions/bigpowers/skills/delegate-task/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/delegate-task/SKILL.md @@ -4,6 +4,8 @@ description: "Delegate one complex task to a single subagent, review its work in --- +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -12,6 +14,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/.gemini/extensions/bigpowers/skills/deploy/SKILL.md b/.gemini/extensions/bigpowers/skills/deploy/SKILL.md index b36872fb..4d30999c 100644 --- a/.gemini/extensions/bigpowers/skills/deploy/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/deploy/SKILL.md @@ -104,6 +104,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + --- # Deploy — Reference diff --git a/.gemini/extensions/bigpowers/skills/develop-tdd/SKILL.md b/.gemini/extensions/bigpowers/skills/develop-tdd/SKILL.md index 56a4d69d..99d4ddd6 100644 --- a/.gemini/extensions/bigpowers/skills/develop-tdd/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/develop-tdd/SKILL.md @@ -50,16 +50,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/.gemini/extensions/bigpowers/skills/diagnose-stall/SKILL.md b/.gemini/extensions/bigpowers/skills/diagnose-stall/SKILL.md new file mode 100644 index 00000000..5b851e06 --- /dev/null +++ b/.gemini/extensions/bigpowers/skills/diagnose-stall/SKILL.md @@ -0,0 +1,54 @@ +--- +name: diagnose-stall +description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned." +--- + + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/.gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md b/.gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md index 3f1d7a55..d4135f5c 100644 --- a/.gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md @@ -4,6 +4,8 @@ description: "Dispatch multiple subagents in parallel on independent tasks. No w --- +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -35,30 +37,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -72,13 +101,14 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/.gemini/extensions/bigpowers/skills/gate-trace/SKILL.md b/.gemini/extensions/bigpowers/skills/gate-trace/SKILL.md index c0b04337..3bc7af45 100644 --- a/.gemini/extensions/bigpowers/skills/gate-trace/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/gate-trace/SKILL.md @@ -37,7 +37,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md b/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md index 7d7e56e6..a875f4ad 100644 --- a/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md @@ -47,6 +47,20 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/.gemini/extensions/bigpowers/skills/migrate-spec/SKILL.md b/.gemini/extensions/bigpowers/skills/migrate-spec/SKILL.md index 1a4cdf98..53a455c3 100644 --- a/.gemini/extensions/bigpowers/skills/migrate-spec/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/migrate-spec/SKILL.md @@ -239,6 +239,18 @@ These GSD artifacts are not migrated — they are execution records, not plannin # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/.gemini/extensions/bigpowers/skills/plan-work/SKILL.md b/.gemini/extensions/bigpowers/skills/plan-work/SKILL.md index 88e0c8a9..69af81e9 100644 --- a/.gemini/extensions/bigpowers/skills/plan-work/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/plan-work/SKILL.md @@ -4,6 +4,8 @@ description: "\"PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed imp --- +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -45,14 +47,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff @@ -64,6 +97,17 @@ Writes: state.yaml handoff.next_skill = kickoff-branch # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -75,14 +119,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -153,6 +197,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/.gemini/extensions/bigpowers/skills/publish-package/SKILL.md b/.gemini/extensions/bigpowers/skills/publish-package/SKILL.md index d6adefc4..4516c453 100644 --- a/.gemini/extensions/bigpowers/skills/publish-package/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/publish-package/SKILL.md @@ -78,6 +78,17 @@ See [REFERENCE.md](REFERENCE.md) # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/.gemini/extensions/bigpowers/skills/release-branch/SKILL.md b/.gemini/extensions/bigpowers/skills/release-branch/SKILL.md index 19764ba3..76770f16 100644 --- a/.gemini/extensions/bigpowers/skills/release-branch/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/release-branch/SKILL.md @@ -53,6 +53,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -73,9 +75,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -91,55 +110,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL - -### 8. Clean up worktree - -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -After landing, record delivery metrics with the git-derived, additive script: +### 8. Clean up & return -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." @@ -151,6 +133,20 @@ Report: "Branch released." # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/.gemini/extensions/bigpowers/skills/request-review/SKILL.md b/.gemini/extensions/bigpowers/skills/request-review/SKILL.md index a35e1783..b24b8065 100644 --- a/.gemini/extensions/bigpowers/skills/request-review/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/request-review/SKILL.md @@ -4,21 +4,44 @@ description: "Dispatch a fresh reviewer agent with a clean context to critique t --- +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. + +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -28,12 +51,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | + +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -55,18 +91,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." + +## Verify -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/.gemini/extensions/bigpowers/skills/run-benchmark/SKILL.md b/.gemini/extensions/bigpowers/skills/run-benchmark/SKILL.md index d2e12a85..5c0a35b0 100644 --- a/.gemini/extensions/bigpowers/skills/run-benchmark/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/run-benchmark/SKILL.md @@ -28,9 +28,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/.gemini/extensions/bigpowers/skills/run-evals/SKILL.md b/.gemini/extensions/bigpowers/skills/run-evals/SKILL.md index ad521061..7b5e1695 100644 --- a/.gemini/extensions/bigpowers/skills/run-evals/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/run-evals/SKILL.md @@ -15,8 +15,18 @@ description: "Eval-Driven Development — define capability and regression evals - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact @@ -30,16 +40,26 @@ description: "Eval-Driven Development — define capability and regression evals # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/.gemini/extensions/bigpowers/skills/security-review/SKILL.md b/.gemini/extensions/bigpowers/skills/security-review/SKILL.md index 93c38635..ed9dfb06 100644 --- a/.gemini/extensions/bigpowers/skills/security-review/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/security-review/SKILL.md @@ -4,12 +4,24 @@ description: ">" --- +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -24,6 +36,37 @@ description: ">" Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. @@ -175,14 +218,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules @@ -234,6 +278,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -243,6 +289,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/.gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md b/.gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md index 31aa1b03..b16b6d43 100644 --- a/.gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md @@ -62,7 +62,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention @@ -76,8 +97,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain --- # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/.gemini/extensions/bigpowers/skills/session-state/SKILL.md b/.gemini/extensions/bigpowers/skills/session-state/SKILL.md index 2dd45241..6ec02653 100644 --- a/.gemini/extensions/bigpowers/skills/session-state/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/session-state/SKILL.md @@ -4,6 +4,8 @@ description: "Track implementation decisions and progress in specs/state.yaml to --- +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -18,6 +20,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -64,6 +68,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -130,16 +135,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/.gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md b/.gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md index ef840c42..883ad56c 100644 --- a/.gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md @@ -4,6 +4,8 @@ description: "\"PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PR --- +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -36,6 +38,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/.gemini/extensions/bigpowers/skills/smoke-test/SKILL.md b/.gemini/extensions/bigpowers/skills/smoke-test/SKILL.md index 050c0979..fbdbd818 100644 --- a/.gemini/extensions/bigpowers/skills/smoke-test/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/smoke-test/SKILL.md @@ -69,6 +69,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/.gemini/extensions/bigpowers/skills/stocktake-skills/SKILL.md b/.gemini/extensions/bigpowers/skills/stocktake-skills/SKILL.md index d2d8d969..1d0b7448 100644 --- a/.gemini/extensions/bigpowers/skills/stocktake-skills/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/stocktake-skills/SKILL.md @@ -20,6 +20,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -51,7 +52,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/.gemini/extensions/bigpowers/skills/validate-contracts/SKILL.md b/.gemini/extensions/bigpowers/skills/validate-contracts/SKILL.md index c2a9017c..3e3db28a 100644 --- a/.gemini/extensions/bigpowers/skills/validate-contracts/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/validate-contracts/SKILL.md @@ -114,6 +114,18 @@ bash scripts/validate-contracts.sh # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/.gemini/extensions/bigpowers/skills/validate-fix/SKILL.md b/.gemini/extensions/bigpowers/skills/validate-fix/SKILL.md index 5c846f4b..9a376815 100644 --- a/.gemini/extensions/bigpowers/skills/validate-fix/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/validate-fix/SKILL.md @@ -10,6 +10,8 @@ description: "Prove a fix works before declaring done — re-run the failing tes Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/.gemini/extensions/bigpowers/skills/verify-work/SKILL.md b/.gemini/extensions/bigpowers/skills/verify-work/SKILL.md index 9d015231..13bff14e 100644 --- a/.gemini/extensions/bigpowers/skills/verify-work/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/verify-work/SKILL.md @@ -44,12 +44,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -92,6 +100,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -113,26 +126,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify @@ -167,3 +161,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/.gemini/extensions/bigpowers/skills/wire-ci/SKILL.md b/.gemini/extensions/bigpowers/skills/wire-ci/SKILL.md index 8ddac83e..3378a808 100644 --- a/.gemini/extensions/bigpowers/skills/wire-ci/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/wire-ci/SKILL.md @@ -107,6 +107,17 @@ Add the following to the project's documentation or CLAUDE.md after setup: # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/.gemini/extensions/bigpowers/skills/write-document/SKILL.md b/.gemini/extensions/bigpowers/skills/write-document/SKILL.md index f3c332f4..181527a6 100644 --- a/.gemini/extensions/bigpowers/skills/write-document/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/write-document/SKILL.md @@ -81,6 +81,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`. Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/.github/workflows/sync-references.yml b/.github/workflows/sync-references.yml new file mode 100644 index 00000000..153af432 --- /dev/null +++ b/.github/workflows/sync-references.yml @@ -0,0 +1,17 @@ +# story: e45s10 +name: Sync References (SSOT) + +on: + schedule: + - cron: "0 6 * * 1" # Weekly Monday 06:00 UTC + workflow_dispatch: + +jobs: + sync: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v6 + - name: Regenerate docs/references from SSOT + run: bash scripts/sync-references.sh diff --git a/.kilocode/rules/context7-mcp.md b/.kilocode/rules/context7-mcp.md new file mode 100644 index 00000000..e69de29b diff --git a/.kilocode/rules/diagnose-stall.md b/.kilocode/rules/diagnose-stall.md new file mode 100644 index 00000000..e69de29b diff --git a/.pi/package.json b/.pi/package.json index eaac292f..44a051c2 100644 --- a/.pi/package.json +++ b/.pi/package.json @@ -1,7 +1,7 @@ { "name": "bigpowers", "version": "2.73.9", - "description": "75 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers", + "description": "77 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers", "keywords": [ "pi-package" ], diff --git a/.pi/prompts/audit-code.md b/.pi/prompts/audit-code.md index 415c543f..10b53402 100644 --- a/.pi/prompts/audit-code.md +++ b/.pi/prompts/audit-code.md @@ -11,11 +11,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -107,24 +123,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/.pi/prompts/change-request.md b/.pi/prompts/change-request.md index b3a8ec61..2e19e3ef 100644 --- a/.pi/prompts/change-request.md +++ b/.pi/prompts/change-request.md @@ -3,6 +3,8 @@ description: Add a new requirement or reorder epics by WSJF against specs/releas --- +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -17,7 +19,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/.pi/prompts/compose-workflow.md b/.pi/prompts/compose-workflow.md index 3f9867ad..858b2bc9 100644 --- a/.pi/prompts/compose-workflow.md +++ b/.pi/prompts/compose-workflow.md @@ -3,6 +3,8 @@ description: Chain multiple bigpowers skills into a custom workflow recipe saved --- +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -19,6 +21,19 @@ description: Chain multiple bigpowers skills into a custom workflow recipe saved > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/.pi/prompts/context7-mcp.md b/.pi/prompts/context7-mcp.md new file mode 100644 index 00000000..280c7618 --- /dev/null +++ b/.pi/prompts/context7-mcp.md @@ -0,0 +1,54 @@ +--- +description: Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc. +--- + + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/.pi/prompts/craft-skill.md b/.pi/prompts/craft-skill.md index e955e6af..6329b250 100644 --- a/.pi/prompts/craft-skill.md +++ b/.pi/prompts/craft-skill.md @@ -7,6 +7,19 @@ description: Create new bigpowers skills with proper structure, progressive disc > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -38,6 +51,12 @@ description: Create new bigpowers skills with proper structure, progressive disc - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -51,12 +70,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify + +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` --- diff --git a/.pi/prompts/deepen-architecture.md b/.pi/prompts/deepen-architecture.md index 2f0ca953..e9796619 100644 --- a/.pi/prompts/deepen-architecture.md +++ b/.pi/prompts/deepen-architecture.md @@ -43,6 +43,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -91,6 +97,20 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + --- # Deepening diff --git a/.pi/prompts/delegate-task.md b/.pi/prompts/delegate-task.md index 697a0c8a..dab7615b 100644 --- a/.pi/prompts/delegate-task.md +++ b/.pi/prompts/delegate-task.md @@ -3,6 +3,8 @@ description: Delegate one complex task to a single subagent, review its work in --- +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -11,6 +13,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/.pi/prompts/deploy.md b/.pi/prompts/deploy.md index 39c31ff3..0051cbb5 100644 --- a/.pi/prompts/deploy.md +++ b/.pi/prompts/deploy.md @@ -103,6 +103,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + --- # Deploy — Reference diff --git a/.pi/prompts/develop-tdd.md b/.pi/prompts/develop-tdd.md index 376c4bb5..54d3ceb8 100644 --- a/.pi/prompts/develop-tdd.md +++ b/.pi/prompts/develop-tdd.md @@ -49,16 +49,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/.pi/prompts/diagnose-stall.md b/.pi/prompts/diagnose-stall.md new file mode 100644 index 00000000..6e8afc7f --- /dev/null +++ b/.pi/prompts/diagnose-stall.md @@ -0,0 +1,53 @@ +--- +description: Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned. +--- + + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/.pi/prompts/dispatch-agents.md b/.pi/prompts/dispatch-agents.md index 8ac8205b..5edd09c9 100644 --- a/.pi/prompts/dispatch-agents.md +++ b/.pi/prompts/dispatch-agents.md @@ -3,6 +3,8 @@ description: Dispatch multiple subagents in parallel on independent tasks. No wa --- +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -34,30 +36,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -71,13 +100,14 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/.pi/prompts/gate-trace.md b/.pi/prompts/gate-trace.md index 9978f246..ef53d8e5 100644 --- a/.pi/prompts/gate-trace.md +++ b/.pi/prompts/gate-trace.md @@ -36,7 +36,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/.pi/prompts/guard-git.md b/.pi/prompts/guard-git.md index e10adb57..ae712c0e 100644 --- a/.pi/prompts/guard-git.md +++ b/.pi/prompts/guard-git.md @@ -46,6 +46,20 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/.pi/prompts/migrate-spec.md b/.pi/prompts/migrate-spec.md index eacbe536..7d10ca12 100644 --- a/.pi/prompts/migrate-spec.md +++ b/.pi/prompts/migrate-spec.md @@ -238,6 +238,18 @@ These GSD artifacts are not migrated — they are execution records, not plannin # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/.pi/prompts/plan-work.md b/.pi/prompts/plan-work.md index 93da4e8c..08097a91 100644 --- a/.pi/prompts/plan-work.md +++ b/.pi/prompts/plan-work.md @@ -3,6 +3,8 @@ description: "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed imple --- +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -44,14 +46,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff @@ -63,6 +96,17 @@ Writes: state.yaml handoff.next_skill = kickoff-branch # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -74,14 +118,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -152,6 +196,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/.pi/prompts/publish-package.md b/.pi/prompts/publish-package.md index f1e9f1bd..bc7d84f9 100644 --- a/.pi/prompts/publish-package.md +++ b/.pi/prompts/publish-package.md @@ -77,6 +77,17 @@ See [REFERENCE.md](REFERENCE.md) # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/.pi/prompts/release-branch.md b/.pi/prompts/release-branch.md index 77eb61bd..866c2fa4 100644 --- a/.pi/prompts/release-branch.md +++ b/.pi/prompts/release-branch.md @@ -52,6 +52,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -72,9 +74,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -90,55 +109,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL - -### 8. Clean up worktree - -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -After landing, record delivery metrics with the git-derived, additive script: +### 8. Clean up & return -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." @@ -150,6 +132,20 @@ Report: "Branch released." # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/.pi/prompts/request-review.md b/.pi/prompts/request-review.md index 3257f286..a2f8d073 100644 --- a/.pi/prompts/request-review.md +++ b/.pi/prompts/request-review.md @@ -3,21 +3,44 @@ description: Dispatch a fresh reviewer agent with a clean context to critique th --- +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. + +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -27,12 +50,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | + +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -54,18 +90,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." + +## Verify -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/.pi/prompts/run-benchmark.md b/.pi/prompts/run-benchmark.md index 20bca0f2..ec831881 100644 --- a/.pi/prompts/run-benchmark.md +++ b/.pi/prompts/run-benchmark.md @@ -27,9 +27,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/.pi/prompts/run-evals.md b/.pi/prompts/run-evals.md index 8bdb931c..0fa3326c 100644 --- a/.pi/prompts/run-evals.md +++ b/.pi/prompts/run-evals.md @@ -14,8 +14,18 @@ description: Eval-Driven Development — define capability and regression evals - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact @@ -29,16 +39,26 @@ description: Eval-Driven Development — define capability and regression evals # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/.pi/prompts/security-review.md b/.pi/prompts/security-review.md index 73971b81..18a80134 100644 --- a/.pi/prompts/security-review.md +++ b/.pi/prompts/security-review.md @@ -3,12 +3,24 @@ description: > --- +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -23,6 +35,37 @@ description: > Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. @@ -174,14 +217,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules @@ -233,6 +277,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -242,6 +288,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/.pi/prompts/seed-conventions.md b/.pi/prompts/seed-conventions.md index 6029bcc0..b642510f 100644 --- a/.pi/prompts/seed-conventions.md +++ b/.pi/prompts/seed-conventions.md @@ -61,7 +61,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention @@ -75,8 +96,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain --- # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/.pi/prompts/session-state.md b/.pi/prompts/session-state.md index 776fba5b..11b89faa 100644 --- a/.pi/prompts/session-state.md +++ b/.pi/prompts/session-state.md @@ -3,6 +3,8 @@ description: Track implementation decisions and progress in specs/state.yaml to --- +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -17,6 +19,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -63,6 +67,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -129,16 +134,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/.pi/prompts/slice-tasks.md b/.pi/prompts/slice-tasks.md index b75e7ba4..6fad52d1 100644 --- a/.pi/prompts/slice-tasks.md +++ b/.pi/prompts/slice-tasks.md @@ -3,6 +3,8 @@ description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD --- +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -35,6 +37,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/.pi/prompts/smoke-test.md b/.pi/prompts/smoke-test.md index b046bd58..5f43eb68 100644 --- a/.pi/prompts/smoke-test.md +++ b/.pi/prompts/smoke-test.md @@ -68,6 +68,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/.pi/prompts/stocktake-skills.md b/.pi/prompts/stocktake-skills.md index 48e573d8..9fcd44ff 100644 --- a/.pi/prompts/stocktake-skills.md +++ b/.pi/prompts/stocktake-skills.md @@ -19,6 +19,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -50,7 +51,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/.pi/prompts/validate-contracts.md b/.pi/prompts/validate-contracts.md index 6746f89e..00e50146 100644 --- a/.pi/prompts/validate-contracts.md +++ b/.pi/prompts/validate-contracts.md @@ -113,6 +113,18 @@ bash scripts/validate-contracts.sh # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/.pi/prompts/validate-fix.md b/.pi/prompts/validate-fix.md index c93fc1ff..9b0c6779 100644 --- a/.pi/prompts/validate-fix.md +++ b/.pi/prompts/validate-fix.md @@ -9,6 +9,8 @@ description: Prove a fix works before declaring done — re-run the failing test Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/.pi/prompts/verify-work.md b/.pi/prompts/verify-work.md index 3118aeb6..971d138d 100644 --- a/.pi/prompts/verify-work.md +++ b/.pi/prompts/verify-work.md @@ -43,12 +43,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -91,6 +99,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -112,26 +125,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify @@ -166,3 +160,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/.pi/prompts/wire-ci.md b/.pi/prompts/wire-ci.md index a2adc9f1..d0317ced 100644 --- a/.pi/prompts/wire-ci.md +++ b/.pi/prompts/wire-ci.md @@ -106,6 +106,17 @@ Add the following to the project's documentation or CLAUDE.md after setup: # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/.pi/prompts/write-document.md b/.pi/prompts/write-document.md index 264ae4ea..0c583ef6 100644 --- a/.pi/prompts/write-document.md +++ b/.pi/prompts/write-document.md @@ -80,6 +80,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`. Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/.pi/skills/audit-code/SKILL.md b/.pi/skills/audit-code/SKILL.md index 6c0ace89..beb082c2 100644 --- a/.pi/skills/audit-code/SKILL.md +++ b/.pi/skills/audit-code/SKILL.md @@ -13,11 +13,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -109,24 +125,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/.pi/skills/change-request/SKILL.md b/.pi/skills/change-request/SKILL.md index 6f8aa676..a6bd9eb1 100644 --- a/.pi/skills/change-request/SKILL.md +++ b/.pi/skills/change-request/SKILL.md @@ -5,6 +5,8 @@ model: sonnet --- +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -19,7 +21,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/.pi/skills/compose-workflow/SKILL.md b/.pi/skills/compose-workflow/SKILL.md index d44b99ea..2ebfa210 100644 --- a/.pi/skills/compose-workflow/SKILL.md +++ b/.pi/skills/compose-workflow/SKILL.md @@ -5,6 +5,8 @@ model: sonnet --- +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -21,6 +23,19 @@ model: sonnet > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/.pi/skills/context7-mcp/SKILL.md b/.pi/skills/context7-mcp/SKILL.md new file mode 100644 index 00000000..50316f1d --- /dev/null +++ b/.pi/skills/context7-mcp/SKILL.md @@ -0,0 +1,56 @@ +--- +name: context7-mcp +description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc." +model: haiku +--- + + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/.pi/skills/craft-skill/SKILL.md b/.pi/skills/craft-skill/SKILL.md index ea0585aa..bc93fd42 100644 --- a/.pi/skills/craft-skill/SKILL.md +++ b/.pi/skills/craft-skill/SKILL.md @@ -9,6 +9,19 @@ model: sonnet > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -40,6 +53,12 @@ model: sonnet - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -53,12 +72,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify + +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` --- diff --git a/.pi/skills/deepen-architecture/SKILL.md b/.pi/skills/deepen-architecture/SKILL.md index ae91bb01..5cb4a2d0 100644 --- a/.pi/skills/deepen-architecture/SKILL.md +++ b/.pi/skills/deepen-architecture/SKILL.md @@ -45,6 +45,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -93,6 +99,20 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + --- # Deepening diff --git a/.pi/skills/delegate-task/SKILL.md b/.pi/skills/delegate-task/SKILL.md index 42260885..bfbac4a9 100644 --- a/.pi/skills/delegate-task/SKILL.md +++ b/.pi/skills/delegate-task/SKILL.md @@ -5,6 +5,8 @@ model: sonnet --- +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -13,6 +15,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/.pi/skills/deploy/SKILL.md b/.pi/skills/deploy/SKILL.md index 881ef18b..fc454d2d 100644 --- a/.pi/skills/deploy/SKILL.md +++ b/.pi/skills/deploy/SKILL.md @@ -105,6 +105,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + --- # Deploy — Reference diff --git a/.pi/skills/develop-tdd/SKILL.md b/.pi/skills/develop-tdd/SKILL.md index afdba4de..a2b7b77a 100644 --- a/.pi/skills/develop-tdd/SKILL.md +++ b/.pi/skills/develop-tdd/SKILL.md @@ -51,16 +51,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/.pi/skills/diagnose-stall/SKILL.md b/.pi/skills/diagnose-stall/SKILL.md new file mode 100644 index 00000000..57f057d6 --- /dev/null +++ b/.pi/skills/diagnose-stall/SKILL.md @@ -0,0 +1,55 @@ +--- +name: diagnose-stall +description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned." +model: haiku +--- + + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/.pi/skills/dispatch-agents/SKILL.md b/.pi/skills/dispatch-agents/SKILL.md index 41477cd4..cb98f5d9 100644 --- a/.pi/skills/dispatch-agents/SKILL.md +++ b/.pi/skills/dispatch-agents/SKILL.md @@ -5,6 +5,8 @@ model: sonnet --- +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -36,30 +38,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -73,13 +102,14 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/.pi/skills/gate-trace/SKILL.md b/.pi/skills/gate-trace/SKILL.md index 1e848231..1fa40679 100644 --- a/.pi/skills/gate-trace/SKILL.md +++ b/.pi/skills/gate-trace/SKILL.md @@ -38,7 +38,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/.pi/skills/guard-git/SKILL.md b/.pi/skills/guard-git/SKILL.md index 3f143dde..53784ce7 100644 --- a/.pi/skills/guard-git/SKILL.md +++ b/.pi/skills/guard-git/SKILL.md @@ -48,6 +48,20 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/.pi/skills/migrate-spec/SKILL.md b/.pi/skills/migrate-spec/SKILL.md index 28ddbb86..9dc0763f 100644 --- a/.pi/skills/migrate-spec/SKILL.md +++ b/.pi/skills/migrate-spec/SKILL.md @@ -240,6 +240,18 @@ These GSD artifacts are not migrated — they are execution records, not plannin # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/.pi/skills/plan-work/SKILL.md b/.pi/skills/plan-work/SKILL.md index 7711c13c..714ceca0 100644 --- a/.pi/skills/plan-work/SKILL.md +++ b/.pi/skills/plan-work/SKILL.md @@ -5,6 +5,8 @@ model: opus --- +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -46,14 +48,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff @@ -65,6 +98,17 @@ Writes: state.yaml handoff.next_skill = kickoff-branch # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -76,14 +120,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -154,6 +198,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/.pi/skills/publish-package/SKILL.md b/.pi/skills/publish-package/SKILL.md index f0702a3b..139cbe09 100644 --- a/.pi/skills/publish-package/SKILL.md +++ b/.pi/skills/publish-package/SKILL.md @@ -79,6 +79,17 @@ See [REFERENCE.md](REFERENCE.md) # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/.pi/skills/release-branch/SKILL.md b/.pi/skills/release-branch/SKILL.md index 28f3fb78..86e780c5 100644 --- a/.pi/skills/release-branch/SKILL.md +++ b/.pi/skills/release-branch/SKILL.md @@ -54,6 +54,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -74,9 +76,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -92,55 +111,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL - -### 8. Clean up worktree - -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -After landing, record delivery metrics with the git-derived, additive script: +### 8. Clean up & return -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." @@ -152,6 +134,20 @@ Report: "Branch released." # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/.pi/skills/request-review/SKILL.md b/.pi/skills/request-review/SKILL.md index 700051e3..1fc57506 100644 --- a/.pi/skills/request-review/SKILL.md +++ b/.pi/skills/request-review/SKILL.md @@ -5,21 +5,44 @@ model: opus --- +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. + +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -29,12 +52,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | + +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -56,18 +92,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." + +## Verify -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/.pi/skills/run-benchmark/SKILL.md b/.pi/skills/run-benchmark/SKILL.md index 2227cbc1..976be58a 100644 --- a/.pi/skills/run-benchmark/SKILL.md +++ b/.pi/skills/run-benchmark/SKILL.md @@ -29,9 +29,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/.pi/skills/run-evals/SKILL.md b/.pi/skills/run-evals/SKILL.md index fdfda639..78275bc5 100644 --- a/.pi/skills/run-evals/SKILL.md +++ b/.pi/skills/run-evals/SKILL.md @@ -16,8 +16,18 @@ model: sonnet - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact @@ -31,16 +41,26 @@ model: sonnet # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/.pi/skills/security-review/SKILL.md b/.pi/skills/security-review/SKILL.md index 316ce784..e66b6dd7 100644 --- a/.pi/skills/security-review/SKILL.md +++ b/.pi/skills/security-review/SKILL.md @@ -5,12 +5,24 @@ model: sonnet --- +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -25,6 +37,37 @@ model: sonnet Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. @@ -176,14 +219,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules @@ -235,6 +279,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -244,6 +290,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/.pi/skills/seed-conventions/SKILL.md b/.pi/skills/seed-conventions/SKILL.md index 5d312577..0c7372c7 100644 --- a/.pi/skills/seed-conventions/SKILL.md +++ b/.pi/skills/seed-conventions/SKILL.md @@ -63,7 +63,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention @@ -77,8 +98,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain --- # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/.pi/skills/session-state/SKILL.md b/.pi/skills/session-state/SKILL.md index f628b225..b729e0ba 100644 --- a/.pi/skills/session-state/SKILL.md +++ b/.pi/skills/session-state/SKILL.md @@ -5,6 +5,8 @@ model: haiku --- +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -19,6 +21,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -65,6 +69,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -131,16 +136,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/.pi/skills/slice-tasks/SKILL.md b/.pi/skills/slice-tasks/SKILL.md index 0a06845b..4e3ac619 100644 --- a/.pi/skills/slice-tasks/SKILL.md +++ b/.pi/skills/slice-tasks/SKILL.md @@ -5,6 +5,8 @@ model: sonnet --- +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -37,6 +39,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/.pi/skills/smoke-test/SKILL.md b/.pi/skills/smoke-test/SKILL.md index d9f414b5..f676546c 100644 --- a/.pi/skills/smoke-test/SKILL.md +++ b/.pi/skills/smoke-test/SKILL.md @@ -70,6 +70,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/.pi/skills/stocktake-skills/SKILL.md b/.pi/skills/stocktake-skills/SKILL.md index 12b01e71..31fa5e1e 100644 --- a/.pi/skills/stocktake-skills/SKILL.md +++ b/.pi/skills/stocktake-skills/SKILL.md @@ -21,6 +21,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -52,7 +53,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/.pi/skills/validate-contracts/SKILL.md b/.pi/skills/validate-contracts/SKILL.md index 188da93c..36f184d7 100644 --- a/.pi/skills/validate-contracts/SKILL.md +++ b/.pi/skills/validate-contracts/SKILL.md @@ -115,6 +115,18 @@ bash scripts/validate-contracts.sh # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/.pi/skills/validate-fix/SKILL.md b/.pi/skills/validate-fix/SKILL.md index 422f6c5b..414ae9fb 100644 --- a/.pi/skills/validate-fix/SKILL.md +++ b/.pi/skills/validate-fix/SKILL.md @@ -11,6 +11,8 @@ model: haiku Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/.pi/skills/verify-work/SKILL.md b/.pi/skills/verify-work/SKILL.md index 121aaf8a..d5c80b43 100644 --- a/.pi/skills/verify-work/SKILL.md +++ b/.pi/skills/verify-work/SKILL.md @@ -45,12 +45,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -93,6 +101,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -114,26 +127,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify @@ -168,3 +162,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/.pi/skills/wire-ci/SKILL.md b/.pi/skills/wire-ci/SKILL.md index d7d10117..225df41f 100644 --- a/.pi/skills/wire-ci/SKILL.md +++ b/.pi/skills/wire-ci/SKILL.md @@ -108,6 +108,17 @@ Add the following to the project's documentation or CLAUDE.md after setup: # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/.pi/skills/write-document/SKILL.md b/.pi/skills/write-document/SKILL.md index 4b0fcfea..da22b2f7 100644 --- a/.pi/skills/write-document/SKILL.md +++ b/.pi/skills/write-document/SKILL.md @@ -82,6 +82,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`. Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/CLAUDE.md b/CLAUDE.md index 80be8777..c9128088 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,10 +1,50 @@ # story: e38s08 # story: e51s05 +# story: e45s22 +# story: e45s23 # bigpowers — Claude Code Read CONVENTIONS.md before any GitHub or git operation. + +## Context Routing + +Load subdirectory context **by file glob** — do not read the full doc tree up front. + +| Glob / trigger | Load first | Fallback | +|----------------|------------|----------| +| `skills/**` | Active skill's `SKILL.md` + sibling `REFERENCE.md` if linked | `SKILL-INDEX.md` | +| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` | +| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` | +| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` if present | `CONVENTIONS.md` | +| `scripts/**` | `CONVENTIONS.md` § Generated artifact targets | This file § Commands | +| `website/**` | `website/README.md` if present | Never edit `website/src/content/docs/` (generated) | +| `docs/**` | Matching doc under `docs/` | `docs/references/` | +| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` | + +Sub-AGENTS.md files (when present in consumer projects) override this table for their directory only. + + + +## Learned User Preferences + +_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._ + +- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings). +- Run Preflight before forward work; never dismiss red gates as pre-existing. +- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts. + +## Workspace Facts + +_Stable repo facts — prefer these over re-discovery._ + +- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`. +- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`. +- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI. +- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md). + + ## Project bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs). @@ -62,6 +102,18 @@ Collection of verb-noun skills under `skills/`, each with a SKILL.md source file ## Token Management +**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (alongside `hooks/pre-tool-use.sh` for git safety). Thresholds: Read >100KB, Grep >200 matches without `head_limit`, Bash commands likely to exceed 500 output lines without `rtk`/`sqz compress`. Install snippet: + +```json +{ + "hooks": { + "PreToolUse": [ + { "matcher": "Read|Grep|Bash", "hooks": [{ "type": "command", "command": "bash scripts/hooks/token-mgmt-pre-tool-use.sh" }] } + ] + } +} +``` + Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`): - **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments. @@ -113,9 +165,15 @@ Before any task, run this sequence — not optional: - Search with `bts find` before opening files to locate a symbol or pattern. - Pipe anything > 200 lines through `bts compress` before adding to context. - Run `bts map` when asked for a repo overview. -- Use `bts docs ` before answering questions about library APIs. +- Use `bts docs ` before answering questions about library APIs. Doc fetches use `scripts/lib/doc-fetch-cache.sh` (ETag-revalidated, 300s TTL — see `context7-mcp` skill, e45s20). - If a tool is missing, say so and run `bts doctor` — do not silently substitute. + + +**RTK hook (installed):** `scripts/hooks/rtk-rewrite.sh` is symlinked into `~/.claude/hooks/` by `bash scripts/install.sh` and registered as a Bash `PreToolUse` hook. It delegates to `rtk hook claude` — prose rules below are a fallback only when the hook is absent. + + + ## sqz — Context Compression (READ FIRST) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 8a94eb41..3111d0c7 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -1,7 +1,10 @@ # story: e30s02 # story: e30s03 # story: e38s08 +# story: e45s10 # story: e51s01 +# story: e45s25 +# story: e45s36 # Conventions @@ -86,6 +89,43 @@ Discovered fixes ship in the **same PR** as the original work but in **separate **Hard block:** Red Preflight or red CI blocks kickoff-branch, develop-tdd, and verify-work forward progress until fix-or-log produces green. +## Risk Tiers (Effective Rule Matrix) + +Human-readable source of truth for verification depth. Machine-readable compile: + +```bash +bash scripts/compile-rule-matrix.sh # → specs/rule-matrix.json +``` + +Diff `specs/rule-matrix.json` across git tags to audit rule drift. Schema version in JSON `matrix_version` field. + +### P0 — Critical (never violate) + +- **[always-green]**: Preflight and CI must be green before forward work. (`verify-work`, `kickoff-branch`, `develop-tdd`) +- **[no-direct-coding]**: Route feature work through bigpowers skills — no ad-hoc implementation without a plan in `specs/`. (`plan-work`, `orchestrate-project`) +- **[traceability]**: Every story has ≥1 `story: eNNsNN` tag in implementing code or tests. (`trace-stories.sh --strict`) +- **[no-generated-edits]**: Never edit `.cursor/rules/`, `.gemini/`, or `website/src/content/docs/` directly. (`sync-skills.sh`) + +### P1 — High (fix before merge) + +- **[conventional-commits]**: All commits follow Conventional Commits; semantic-release owns version bumps. (`commit-message`, `release-branch`) +- **[verify-per-story]**: Every story/task has runnable `verify:` commands; `verify-work` confirms before done. (`plan-work`, `verify-work`) +- **[test-on-change]**: New functions and bug fixes include tests; regressions get regression tests. (`develop-tdd`, `validate-fix`) +- **[branch-protection]**: No direct work on `main`/`master`; feature branches via `kickoff-branch`. (`guard-git`) + +### P2 — Medium (address in same epic or next) + +- **[plan-tests-waiver]**: P2/P3-dominant epics may set `test_plan: waived` in `state.yaml`. (`plan-tests`) +- **[file-size-cap]**: Source files under 300 lines unless listed in § File-Size Exceptions. (`audit-code`) +- **[handoff-signaling]**: Critical-path skills write `handoff.next_skill` to `state.yaml`. (`session-state`) +- **[delta-requirements]**: Behavior changes require `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` tags in requirement specs. (`plan-work`, `change-request`) + +### P3 — Low (best effort) + +- **[boy-scout]**: Leave touched files at least as clean as found. (`audit-code`) +- **[terse-when-heavy]**: Switch to `terse-mode` when context exceeds ~20 turns. (`terse-mode`) +- **[skill-naming]**: Verb-noun kebab-case under `skills/`; documented exceptions only. (`craft-skill`) + ### Banned dismissive phrases Agents MUST NOT use these phrases (or close paraphrases) to ignore reproducible failures: @@ -178,6 +218,30 @@ When planning closes, copy to `specs/product/snapshots/release-/` (`rel Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`. +### Documentation Responsibilities (e45s36) + +Each specs/ artifact owns specific facts. Update the owning file when the fact changes — do not duplicate across files. + +| File / directory | Owns | Update when | +|------------------|------|-------------| +| `specs/state.yaml` | Active session, handoff, story timing, workflow mode | Every skill handoff; branch switch; story start/end | +| `specs/release-plan.yaml` | Epic ordering, WSJF, BCP baselines, release codename | New epic scoped; WSJF re-prioritized; BCP re-estimated | +| `specs/execution-status.yaml` | Story/epic done/todo status (sole SoT) | Story completes; gate-trace runs; manual status change | +| `specs/product/SCOPE_LATEST.yaml` | In/out of scope, initiative boundaries | scope-work; change-request Add mode | +| `specs/product/VISION_LATEST.yaml` | North star, strategic intent | Major product pivot; scope-work | +| `specs/product/GLOSSARY_LATEST.yaml` | Canonical domain terms | define-language; model-domain term crystallizes | +| `specs/epics/eNN-*/epic.yaml` | Epic manifest, story list, BCPs | slice-tasks; plan-work adds stories | +| `specs/epics/eNN-*/eNNsYY-*.md` | Story requirements (countable-story-format) | plan-work; section approval state changes | +| `specs/epics/eNN-*/eNNsYY-tasks.yaml` | Runnable implementation tasks + verify | plan-work; develop-tdd task completion | +| `specs/tech-architecture/tech-stack.md` | Stack, modules, gray areas | map-codebase; deepen-architecture; model-domain | +| `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` | P0/P1 test scenarios per epic | plan-tests | +| `specs/adr/ADR-*.md` | Architectural decisions | model-domain; deepen-architecture ADR offer accepted | +| `specs/bugs/BUG-*.md` | Bug RCA + fix plan | investigate-bug | +| `specs/bugs/registry.yaml` | Bug index (generated) | inspect-quality; sync-bugs-registry.sh | +| `specs/verifications/*` | Verify evidence, audit reports, eval reports | verify-work; audit-code; run-evals | +| `specs/security/REVIEW.md` | Latest security scan findings | security-review | +| `specs/metrics/cycle-times.yaml` | Delivery velocity ledger | release-branch lands story | + ### Generated artifact targets Skill content is edited in `skills/*/SKILL.md` and auto-propagated to these targets by `bash scripts/sync-skills.sh`: @@ -300,3 +364,15 @@ BUG-2026-07-06-gate-trace-matrix-oversized. Prior exception rows for trace-matri and trace-stories.py are removed — both are now under the 300-line cap. Any new exception requires an entry in this table with rationale and a review date. + +## docs/references SSOT Sync (e45s10) + +Agent-guidance files under `docs/references/` are **distilled from upstream sources**, not hand-edited ad hoc. Canonical inputs live in `CLAUDE.md`, `docs/PRINCIPLES.md`, and `skills/*/SKILL.md`. + +| Action | Command | +|--------|---------| +| Regenerate locally | `bash scripts/sync-references.sh` | +| Manifest | `scripts/references-manifest.yaml` | +| Scheduled CI | `.github/workflows/sync-references.yml` (weekly) | + +After changing SKILL.md `model:` frontmatter or token-management prose in CLAUDE.md, run `sync-references.sh` to refresh reference docs and `.sync-stamp`. diff --git a/README.md b/README.md index f13eda64..137da9d1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) ![npm version](https://img.shields.io/npm/v/bigpowers.svg) -![Skills](https://img.shields.io/badge/skills-75-brightgreen.svg) +![Skills](https://img.shields.io/badge/skills-77-brightgreen.svg) **Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.** diff --git a/SKILL-INDEX.md b/SKILL-INDEX.md index 380ce1f2..2ecc8fba 100644 --- a/SKILL-INDEX.md +++ b/SKILL-INDEX.md @@ -3,7 +3,7 @@ > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`. > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate. -**Skills:** 75 +**Skills:** 77 --- diff --git a/docs/countable-story-format.md b/docs/countable-story-format.md index 81143d39..71087e44 100644 --- a/docs/countable-story-format.md +++ b/docs/countable-story-format.md @@ -1,5 +1,7 @@ # Countable Story Format + + The canonical format for stories and bug-fix specs that need to be **countable** — i.e., readable by automated counters that score scope, sizing, and non-functional coverage. Every spec-producing skill in bigpowers writes output in this format. This is a structural contract. Counters key off the exact section names and order. Section omissions are not equivalent to "no content here" — they make the spec uncountable. Use `Not applicable` instead. @@ -15,6 +17,7 @@ This is a structural contract. Counters key off the exact section names and orde 5. **Acceptance criteria are Gherkin only** (`Scenario / Given / When / Then`) and live in §17. 6. **Acceptance criteria must cover the main flow (§5) plus every alternative/exception listed in §6.** One scenario per branch, minimum. 7. **Multiple occurrences of the same dimension are listed separately**, each with its own one-line rationale. Do not collapse. +8. **Per-section approval state (e45s33):** Every section heading MUST include an inline tag — `[draft]`, `[reviewed]`, or `[locked]` — immediately after the section number. Example: `### 5. Main flow and business logic [reviewed]`. Silent rewrites of `[locked]` sections are prohibited; unlocking requires explicit user approval and resets downstream sections to `[draft]`. ## Maturity rubric (self-score in the header) diff --git a/docs/references/.sync-stamp b/docs/references/.sync-stamp new file mode 100644 index 00000000..906aee4c --- /dev/null +++ b/docs/references/.sync-stamp @@ -0,0 +1 @@ +2026-07-07T03:04:55Z diff --git a/docs/references/context-engineering.md b/docs/references/context-engineering.md index ba53f039..175797d1 100644 --- a/docs/references/context-engineering.md +++ b/docs/references/context-engineering.md @@ -91,3 +91,5 @@ for their current context budget: - `skills/session-state/SKILL.md` — context persistence across sessions - `docs/references/bcp.md` — BCP sizing (effort classification's sibling concept) - `skills/terse-mode/SKILL.md` — ultra-compressed communication mode + +**Last synced:** 2026-07-07T03:04:55Z (from CLAUDE.md + PRINCIPLES.md) diff --git a/docs/references/model-profiles.md b/docs/references/model-profiles.md index 58829926..45f761c6 100644 --- a/docs/references/model-profiles.md +++ b/docs/references/model-profiles.md @@ -80,7 +80,7 @@ | `grill-with-docs` | Opus | Doc-grounded grill | | `setup-environment` / `reset-baseline` | Haiku | Mechanical prep | -Full list: every SKILL.md declares `model:` — verify with `grep -rl '^model:' */SKILL.md | wc -l` (expect 75). +Full list: every SKILL.md declares `model:` — verify with `grep -rl '^model:' */SKILL.md | wc -l` (expect 77). ### Release Phase | Skill | Model | Budget | Rationale | @@ -247,6 +247,7 @@ Start: Task assigned | `/Users/danielvm/Developer/bigpowers/skills/change-request` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/commit-message` | **Haiku** | | `/Users/danielvm/Developer/bigpowers/skills/compose-workflow` | **Sonnet** | +| `/Users/danielvm/Developer/bigpowers/skills/context7-mcp` | **Haiku** | | `/Users/danielvm/Developer/bigpowers/skills/craft-skill` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/deepen-architecture` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/define-language` | **Sonnet** | @@ -256,6 +257,7 @@ Start: Task assigned | `/Users/danielvm/Developer/bigpowers/skills/design-interface` | **Opus** | | `/Users/danielvm/Developer/bigpowers/skills/develop-tdd` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/diagnose-root` | **Sonnet** | +| `/Users/danielvm/Developer/bigpowers/skills/diagnose-stall` | **Haiku** | | `/Users/danielvm/Developer/bigpowers/skills/dispatch-agents` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/edit-document` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/elaborate-spec` | **Opus** | @@ -315,5 +317,5 @@ Start: Task assigned | `/Users/danielvm/Developer/bigpowers/skills/wire-observability` | **Sonnet** | | `/Users/danielvm/Developer/bigpowers/skills/write-document` | **Sonnet** | -Total: **75** skills — verify with `find . skills -maxdepth 2 -name SKILL.md 2>/dev/null | grep -v '.git\|.cursor\|.gemini\|.pi' | sort -u | wc -l` +Total: **77** skills — verify with `find . skills -maxdepth 2 -name SKILL.md 2>/dev/null | grep -v '.git\|.cursor\|.gemini\|.pi' | sort -u | wc -l` diff --git a/docs/templates/AGENTS.md b/docs/templates/AGENTS.md index ae3f70ad..1fde56fa 100644 --- a/docs/templates/AGENTS.md +++ b/docs/templates/AGENTS.md @@ -1,4 +1,5 @@ # story: e37s01 +# story: e45s21 # scenario: SC-e37s01-P1-01 # [Project Name] — AI Agents @@ -6,6 +7,23 @@ Read CONVENTIONS.md before any GitHub or git operation. + +## Context Routing + +Load subdirectory context by file glob — see project-specific routing table (seeded by `seed-conventions`). + + + +## Learned User Preferences + +- (none yet — updated via `session-state`) + +## Workspace Facts + +- (none yet — durable facts discovered across sessions) + + + ## Project [One sentence. What this codebase does.] @@ -57,3 +75,4 @@ Stack: [language, framework, runtime] - Write the minimum code that solves the stated problem. - Run tests after every change. Show evidence before declaring done. - All planning output goes in specs/. + diff --git a/scripts/bp-churn-rank.sh b/scripts/bp-churn-rank.sh new file mode 100755 index 00000000..b9337800 --- /dev/null +++ b/scripts/bp-churn-rank.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +# story: e45s31 +# Rank files by git churn for review prioritization (aidd-churn pattern). +# Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit N] [path...] +set -euo pipefail + +SINCE="90.days" +LIMIT=20 +PATHS=() + +while [[ $# -gt 0 ]]; do + case "$1" in + --since) + SINCE="${2:?--since requires a value}" + shift 2 + ;; + --limit) + LIMIT="${2:?--limit requires a number}" + shift 2 + ;; + -h|--help) + echo "Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit 20] [path...]" + exit 0 + ;; + *) + PATHS+=("$1") + shift + ;; + esac +done + +if ! git rev-parse --git-dir >/dev/null 2>&1; then + echo "FAIL: not a git repository" >&2 + exit 1 +fi + +PATHSPEC="" +if [[ ${#PATHS[@]} -gt 0 ]]; then + PATHSPEC="-- ${PATHS[*]}" +fi + +# shellcheck disable=SC2086 +git log --since="$SINCE" --name-only --pretty=format: $PATHSPEC \ + | grep -v '^$' \ + | sort \ + | uniq -c \ + | sort -rn \ + | head -n "$LIMIT" \ + | awk '{printf "%4d %s\n", $1, $2}' diff --git a/scripts/check-import-boundaries.sh b/scripts/check-import-boundaries.sh new file mode 100755 index 00000000..bc853158 --- /dev/null +++ b/scripts/check-import-boundaries.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# story: e45s14 +# check-import-boundaries.sh — enforce specs/import-boundaries.json in CI +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +BOUNDARIES="$REPO_ROOT/specs/import-boundaries.json" + +if [[ ! -f "$BOUNDARIES" ]]; then + echo "FAIL: missing $BOUNDARIES" + exit 1 +fi + +python3 - "$REPO_ROOT" "$BOUNDARIES" <<'PY' +import json, re, sys +from pathlib import Path + +root = Path(sys.argv[1]) +rules_path = Path(sys.argv[2]) +rules = json.loads(rules_path.read_text(encoding="utf-8")) + +def glob_match(pattern: str, path: str) -> bool: + import fnmatch + return fnmatch.fnmatch(path, pattern) + +violations = [] + +for boundary in rules.get("boundaries", []): + from_pat = boundary["from"] + allow = boundary.get("allow", []) + deny = boundary.get("deny", []) + + for sh in root.glob("scripts/**/*.sh"): + rel = sh.relative_to(root).as_posix() + if not glob_match(from_pat, rel): + continue + text = sh.read_text(encoding="utf-8", errors="replace") + for line in text.splitlines(): + m = re.match(r'^\s*(?:source|\.)\s+["\']?([^"\']+)["\']?', line) + if not m: + continue + target = m.group(1) + if target.startswith("$"): + continue + if not target.startswith("scripts/") and not target.startswith("guard-git/"): + if any(glob_match(d, target) for d in deny): + violations.append(f"{rel}: forbidden source {target}") + continue + rel_target = target + if not (Path(root / rel_target).exists() or glob_match(rel_target, rel_target)): + pass + allowed = any(glob_match(a, rel_target) for a in allow) + if not allowed: + violations.append(f"{rel}: source {rel_target} not in allowlist for {from_pat}") + +if violations: + print("IMPORT BOUNDARY FAIL:") + for v in violations: + print(f" {v}") + sys.exit(1) + +print(f"IMPORT BOUNDARIES OK ({len(rules.get('boundaries', []))} rules)") +PY diff --git a/scripts/compile-rule-matrix.sh b/scripts/compile-rule-matrix.sh new file mode 100755 index 00000000..fd5dceae --- /dev/null +++ b/scripts/compile-rule-matrix.sh @@ -0,0 +1,114 @@ +#!/usr/bin/env bash +# story: e45s25 +# Compile CONVENTIONS.md risk tiers → versioned specs/rule-matrix.json +set -euo pipefail +source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh" + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +CONVENTIONS="$REPO_ROOT/CONVENTIONS.md" +OUTPUT="$REPO_ROOT/specs/rule-matrix.json" +MATRIX_VERSION="1.0.0" + +show_help() { + cat <&2; exit 1 ;; + esac +fi + +if [ ! -f "$CONVENTIONS" ]; then + echo "[ERROR] CONVENTIONS.md not found at $CONVENTIONS" >&2 + exit 1 +fi + +$PYTHON - "$CONVENTIONS" "$OUTPUT" "$MATRIX_VERSION" "$STDOUT_ONLY" <<'PY' +import hashlib +import json +import re +import sys +from datetime import datetime, timezone + +conventions_path, output_path, matrix_version, stdout_only = sys.argv[1:5] +stdout_only = stdout_only == "1" + +with open(conventions_path, encoding="utf-8") as f: + content = f.read() + +source_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16] + +# Extract Risk Tiers section +m = re.search( + r"^## Risk Tiers \(Effective Rule Matrix\)\s*\n(.*?)(?=^## |\Z)", + content, + re.MULTILINE | re.DOTALL, +) +if not m: + print("[ERROR] CONVENTIONS.md missing '## Risk Tiers (Effective Rule Matrix)'", file=sys.stderr) + sys.exit(1) + +section = m.group(1) +tier_re = re.compile(r"^### (P[0-3]) —[^\n]*\n(.*?)(?=^### |\Z)", re.MULTILINE | re.DOTALL) +rule_re = re.compile( + r"^- \*\*\[([^\]]+)\]\*\*:\s*(.+?)\.\s*\(([^)]+)\)\s*$", + re.MULTILINE, +) + +tiers: dict[str, list[dict]] = {"P0": [], "P1": [], "P2": [], "P3": []} + +for tier_match in tier_re.finditer(section): + tier = tier_match.group(1) + body = tier_match.group(2) + for rule_match in rule_re.finditer(body): + rule_id, text, enforce_raw = rule_match.groups() + enforce = [s.strip().strip("`") for s in enforce_raw.split(",")] + tiers[tier].append( + { + "id": rule_id, + "text": text.strip(), + "enforce": enforce, + } + ) + +for tier in tiers: + if not tiers[tier]: + print(f"[ERROR] No rules parsed for tier {tier}", file=sys.stderr) + sys.exit(1) + +doc = { + "matrix_version": matrix_version, + "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), + "source": "CONVENTIONS.md", + "source_section": "Risk Tiers (Effective Rule Matrix)", + "source_hash": source_hash, + "tiers": tiers, +} + +payload = json.dumps(doc, indent=2, sort_keys=True) + "\n" + +if stdout_only: + print(payload, end="") +else: + import os + + os.makedirs(os.path.dirname(output_path), exist_ok=True) + with open(output_path, "w", encoding="utf-8") as out: + out.write(payload) + total = sum(len(v) for v in tiers.values()) + print(f"OK: wrote {output_path} ({total} rules, matrix_version={matrix_version})") +PY diff --git a/scripts/hooks/rtk-rewrite.sh b/scripts/hooks/rtk-rewrite.sh new file mode 100755 index 00000000..b84cb4d1 --- /dev/null +++ b/scripts/hooks/rtk-rewrite.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +# story: e45s16 +# rtk-rewrite.sh — PreToolUse hook delegating to rtk's native Bash rewriter. +set -euo pipefail + +if command -v rtk >/dev/null 2>&1; then + exec rtk hook claude +fi + +# rtk missing — pass through unchanged (agent should run `bts doctor` / install rtk) +exit 0 diff --git a/scripts/hooks/token-mgmt-pre-tool-use.sh b/scripts/hooks/token-mgmt-pre-tool-use.sh new file mode 100755 index 00000000..58612b0d --- /dev/null +++ b/scripts/hooks/token-mgmt-pre-tool-use.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# story: e45s03 +# Mechanical PreToolUse backstop — block oversized Read/Grep/Bash before context bloat. +set -euo pipefail + +READ_MAX_BYTES=102400 # 100KB +GREP_MAX_MATCHES=200 +BASH_WARN_PATTERNS='^(npm test|pnpm test|yarn test|cargo test|go test|jest|vitest|pytest|rake test|rspec|git log|git diff|docker logs|kubectl logs|find |rg |grep )' + +deny() { + echo "TOKEN-MGMT BLOCK: $1" >&2 + echo "Use sqz_read_file / sqz_grep / rtk / bts compress per CLAUDE.md § Token Management." >&2 + exit 2 +} + +INPUT="$(cat)" +TOOL="$(echo "$INPUT" | jq -r '.tool_name // .tool // empty')" +TOOL_INPUT="$(echo "$INPUT" | jq -c '.tool_input // .input // {}')" + +case "$TOOL" in + Read|read) + PATH_ARG="$(echo "$TOOL_INPUT" | jq -r '.path // .file_path // .file // empty')" + [[ -n "$PATH_ARG" && -f "$PATH_ARG" ]] || exit 0 + SIZE="$(wc -c < "$PATH_ARG" | tr -d ' ')" + if (( SIZE > READ_MAX_BYTES )); then + deny "Read $PATH_ARG is ${SIZE} bytes (max ${READ_MAX_BYTES}). Use sqz_read_file or bts compress." + fi + ;; + Grep|grep) + LIMIT="$(echo "$TOOL_INPUT" | jq -r '.head_limit // .max_matches // empty')" + if [[ -z "$LIMIT" || "$LIMIT" == "null" ]]; then + deny "Grep without head_limit (max ${GREP_MAX_MATCHES}). Set head_limit<=${GREP_MAX_MATCHES} or use sqz_grep." + fi + if [[ "$LIMIT" =~ ^[0-9]+$ ]] && (( LIMIT > GREP_MAX_MATCHES )); then + deny "Grep head_limit=${LIMIT} exceeds ${GREP_MAX_MATCHES}. Lower limit or use sqz_grep." + fi + ;; + Bash|bash|Shell|shell) + CMD="$(echo "$TOOL_INPUT" | jq -r '.command // empty')" + [[ -n "$CMD" ]] || exit 0 + if echo "$CMD" | grep -qE 'sqz compress|bts compress|rtk |SQZ_NO_DEDUP'; then + exit 0 + fi + if echo "$CMD" | grep -qE "$BASH_WARN_PATTERNS"; then + deny "Bash may exceed 500 lines of output. Prefix with rtk or pipe through sqz compress." + fi + ;; + *) + exit 0 + ;; +esac + +exit 0 diff --git a/scripts/install.sh b/scripts/install.sh index 00870b24..d75be60d 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# story: e45s16 # install.sh — global symlink install for bigpowers skills # # Supported tools: @@ -83,6 +84,9 @@ install_claude() { link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/run-hook.cmd" "$CLAUDE_HOOKS_DIR/run-hook.cmd" link "$REPO_ROOT/guard-git/scripts/block-dangerous-git.sh" "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh" link "$REPO_ROOT/guard-git/scripts/lib" "$CLAUDE_HOOKS_DIR/lib" + link "$REPO_ROOT/scripts/hooks/rtk-rewrite.sh" "$CLAUDE_HOOKS_DIR/rtk-rewrite.sh" + # story: e45s16 + chmod +x "$REPO_ROOT/scripts/hooks/rtk-rewrite.sh" 2>/dev/null || true if [[ -f "$CLAUDE_SETTINGS" ]]; then echo " Configuring global hooks in $CLAUDE_SETTINGS..." @@ -92,6 +96,7 @@ install_claude() { cat "$CLAUDE_SETTINGS" | jq ' .hooks.SessionStart += [{"matcher":"startup|clear|compact","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/run-hook.cmd"'\" session-start","async":false}]}] | .hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/block-dangerous-git.sh"'\""}]}] | + .hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/rtk-rewrite.sh"'\""}]}] | # deduplicate .hooks.SessionStart |= unique | .hooks.PreToolUse |= unique @@ -115,6 +120,7 @@ uninstall_claude() { unlink_if_managed "$CLAUDE_HOOKS_DIR/session-start" "$REPO_ROOT/" unlink_if_managed "$CLAUDE_HOOKS_DIR/run-hook.cmd" "$REPO_ROOT/" unlink_if_managed "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh" "$REPO_ROOT/" + unlink_if_managed "$CLAUDE_HOOKS_DIR/rtk-rewrite.sh" "$REPO_ROOT/" unlink_if_managed "$CLAUDE_HOOKS_DIR/lib" "$REPO_ROOT/" fi } diff --git a/scripts/lib/completeness-critic.sh b/scripts/lib/completeness-critic.sh new file mode 100755 index 00000000..d4193d35 --- /dev/null +++ b/scripts/lib/completeness-critic.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# story: e45s05 +# Adversarial gap-finding completeness critic — post gate-trace. +# Classifications: BLOCKER | WARNING | FILLED +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$REPO_ROOT" + +BLOCKERS=0 +WARNINGS=0 +FILLED=0 + +classify() { + local kind="$1" msg="$2" + echo "[$kind] $msg" + case "$kind" in + BLOCKER) BLOCKERS=$((BLOCKERS + 1)) ;; + WARNING) WARNINGS=$((WARNINGS + 1)) ;; + FILLED) FILLED=$((FILLED + 1)) ;; + esac +} + +# Ensure upstream artifacts exist +[[ -f specs/traceability-matrix.json ]] \ + || classify BLOCKER "Missing specs/traceability-matrix.json — run trace-stories.sh --json" +[[ -f specs/blind-spots.json ]] \ + || classify BLOCKER "Missing specs/blind-spots.json — run check-blind-spots.sh" + +if [[ -f specs/traceability-matrix.json ]]; then + UNDONE="$(jq '[.stories[]? | select(.status != "done" and (.code_tags // 0) == 0)] | length' specs/traceability-matrix.json 2>/dev/null || echo 0)" + (( UNDONE > 0 )) && classify BLOCKER "$UNDONE active story(ies) with zero code tags" + COVERAGE="$(jq -r '.summary.coverage_percent // .coverage_percent // empty' specs/traceability-matrix.json 2>/dev/null)" + if [[ -n "$COVERAGE" && "$COVERAGE" != "null" ]]; then + awk -v c="$COVERAGE" 'BEGIN{if(c+0 < 60) exit 1}' || classify WARNING "Trace coverage ${COVERAGE}% below 60% target" + awk -v c="$COVERAGE" 'BEGIN{if(c+0 >= 80) exit 0; exit 1}' && classify FILLED "Trace coverage ${COVERAGE}% meets 80% PASS bar" + fi +fi + +if [[ -f specs/blind-spots.json ]]; then + HIGH="$(jq '[.findings[]? | select(.severity == "HIGH")] | length' specs/blind-spots.json 2>/dev/null || echo 0)" + (( HIGH > 0 )) && classify BLOCKER "$HIGH HIGH-severity blind-spot finding(s) remain open" +fi + +# Verify evidence for done stories +if [[ -d specs/verifications ]]; then + VC="$(find specs/verifications -maxdepth 1 -name '*-verify.yaml' 2>/dev/null | wc -l | tr -d ' ')" + (( VC == 0 )) && classify WARNING "No specs/verifications/*-verify.yaml evidence bundles" + (( VC > 0 )) && classify FILLED "$VC verification evidence bundle(s) on disk" +else + classify WARNING "specs/verifications/ directory missing" +fi + +echo "---" +echo "completeness-critic: BLOCKER=$BLOCKERS WARNING=$WARNINGS FILLED=$FILLED" + +if (( BLOCKERS > 0 )); then + echo "MERGE GATE ABORT: BLOCKER findings must be resolved" >&2 + exit 1 +fi + +exit 0 diff --git a/scripts/lib/doc-fetch-cache.sh b/scripts/lib/doc-fetch-cache.sh new file mode 100755 index 00000000..c681e814 --- /dev/null +++ b/scripts/lib/doc-fetch-cache.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +# story: e45s20 +# doc-fetch-cache.sh — ETag-revalidated fetch cache for Context7 / bts docs queries. +# Usage: +# bash scripts/lib/doc-fetch-cache.sh get # print cached body or empty +# bash scripts/lib/doc-fetch-cache.sh put +# bash scripts/lib/doc-fetch-cache.sh stale # exit 0 if TTL expired +set -euo pipefail + +CACHE_DIR="${DOC_CACHE_DIR:-.bigpowers/cache/docs}" +TTL_SEC="${DOC_CACHE_TTL:-300}" + +mkdir -p "$CACHE_DIR" + +_key_path() { + local key="$1" + local hash + hash=$(printf '%s' "$key" | shasum -a 256 | awk '{print $1}') + echo "$CACHE_DIR/${hash}" +} + +cmd_get() { + local key="$1" base etag_file body_file meta_file + base="$(_key_path "$key")" + body_file="${base}.body" + etag_file="${base}.etag" + meta_file="${base}.meta" + + [[ -f "$body_file" && -f "$meta_file" ]] || exit 1 + + local cached_at now + cached_at=$(grep '^cached_at=' "$meta_file" | cut -d= -f2) + now=$(date +%s) + if [[ -n "$cached_at" && $((now - cached_at)) -gt "$TTL_SEC" ]]; then + exit 1 + fi + + cat "$body_file" + [[ -f "$etag_file" ]] && printf 'ETAG:%s\n' "$(cat "$etag_file")" >&2 + exit 0 +} + +cmd_put() { + local key="$1" etag="$2" body_file="$3" base + base="$(_key_path "$key")" + cp "$body_file" "${base}.body" + printf '%s' "$etag" > "${base}.etag" + printf 'cached_at=%s\nkey=%s\n' "$(date +%s)" "$key" > "${base}.meta" +} + +cmd_stale() { + local key="$1" base meta_file + base="$(_key_path "$key")" + meta_file="${base}.meta" + [[ -f "$meta_file" ]] || exit 0 + local cached_at now + cached_at=$(grep '^cached_at=' "$meta_file" | cut -d= -f2) + now=$(date +%s) + [[ $((now - cached_at)) -gt "$TTL_SEC" ]] && exit 0 + exit 1 +} + +case "${1:-}" in + get) cmd_get "${2:?key}" ;; + put) cmd_put "${2:?key}" "${3:?etag}" "${4:?body}" ;; + stale) cmd_stale "${2:?key}" ;; + *) + echo "Usage: doc-fetch-cache.sh get|put|stale [etag] [body-file]" >&2 + exit 2 + ;; +esac diff --git a/scripts/lib/golden-suite-gates.sh b/scripts/lib/golden-suite-gates.sh index 63e9c5ad..8ae6267d 100644 --- a/scripts/lib/golden-suite-gates.sh +++ b/scripts/lib/golden-suite-gates.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# story: e42s04 e45s02 +# story: e42s04 e45s02 e45s14 # Deterministic gate runner for golden suite — sourced by golden-suite-run.sh if [ -n "${GOLDEN_GATES_LOADED:-}" ]; then return 0; fi @@ -14,6 +14,8 @@ GOLDEN_GATES=( "g09-yaml-roundtrip:bash scripts/golden-g09-yaml-roundtrip.sh:false" "g10-trace-anti-vacuity:bash scripts/golden-g10-trace-anti-vacuity.sh:false" "g11-gitignore-venv:bash scripts/golden-g11-gitignore-venv.sh:false" + "import-boundaries:bash scripts/check-import-boundaries.sh:false" + "skill-catalog:bash scripts/validate-skill-catalog.sh:false" "specs-parse:bash scripts/validate-specs-yaml.sh:false" ) diff --git a/scripts/lib/parallel-review-worktrees.sh b/scripts/lib/parallel-review-worktrees.sh new file mode 100755 index 00000000..2773e0e4 --- /dev/null +++ b/scripts/lib/parallel-review-worktrees.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +# story: e45s18 +# parallel-review-worktrees.sh — isolated git worktrees for parallel audit-code / security-review +# Usage: bash scripts/lib/parallel-review-worktrees.sh +set -euo pipefail + +CHECK="${1:?usage: parallel-review-worktrees.sh }" +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$REPO_ROOT" + +BASE=".bigpowers/worktrees/review-${CHECK}" +mkdir -p "$(dirname "$BASE")" + +if git worktree list | grep -q "$BASE"; then + git worktree remove --force "$BASE" 2>/dev/null || true +fi + +git worktree add --detach "$BASE" HEAD >/dev/null +echo "WORKTREE: $BASE (detached @ $(git -C "$BASE" rev-parse --short HEAD))" + +case "$CHECK" in + audit-code) + echo "Run audit-code checklist inside worktree; reports → specs/verifications/" + ;; + security-review) + echo "Run security-review 5-phase scan inside worktree; reports → specs/security/" + ;; + *) + echo "Unknown check: $CHECK" >&2 + exit 2 + ;; +esac + +echo "OK: isolated worktree ready — parallel checks cannot corrupt parent working tree" diff --git a/scripts/lib/plan-consistency-check.sh b/scripts/lib/plan-consistency-check.sh new file mode 100755 index 00000000..20f8463e --- /dev/null +++ b/scripts/lib/plan-consistency-check.sh @@ -0,0 +1,88 @@ +#!/usr/bin/env bash +# story: e45s04 +# Pre-build cross-artifact consistency — slice-tasks output vs epic capsule. +# Severity: CRITICAL | HIGH | MED | LOW (LOW is informational only). +set -euo pipefail + +CAPSULE="${1:-}" +if [[ -z "$CAPSULE" || ! -d "$CAPSULE" ]]; then + echo "Usage: bash scripts/lib/plan-consistency-check.sh specs/epics/eNN-slug" >&2 + exit 2 +fi + +EPIC_YAML="$CAPSULE/epic.yaml" +CRITICAL=0 +HIGH=0 +MED=0 + +report() { + local sev="$1" msg="$2" + echo "[$sev] $msg" + case "$sev" in + CRITICAL) CRITICAL=$((CRITICAL + 1)) ;; + HIGH) HIGH=$((HIGH + 1)) ;; + MED) MED=$((MED + 1)) ;; + esac +} + +[[ -f "$EPIC_YAML" ]] || report CRITICAL "Missing epic.yaml in $CAPSULE" + +# Story IDs declared in epic.yaml +declare -A EPIC_STORIES=() +if [[ -f "$EPIC_YAML" ]]; then + while IFS= read -r sid; do + [[ -n "$sid" ]] && EPIC_STORIES["$sid"]=1 + done < <(grep -E '^[[:space:]]*- id: e[0-9]+s[0-9]+' "$EPIC_YAML" | awk '{print $3}') +fi + +shopt -s nullglob +SPECS=("$CAPSULE"/e*s*.md) +TASKS=("$CAPSULE"/e*s*-tasks.yaml) +shopt -u nullglob + +(( ${#SPECS[@]} > 0 )) || report CRITICAL "No story spec .md files in capsule (run slice-tasks first)" +(( ${#TASKS[@]} > 0 )) || report CRITICAL "No *-tasks.yaml files in capsule (run plan-work first)" + +declare -A SPEC_IDS=() +for spec in "${SPECS[@]}"; do + base="$(basename "$spec" .md)" + sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)" + [[ -n "$sid" ]] || continue + SPEC_IDS["$sid"]=1 + [[ -n "${EPIC_STORIES[$sid]+x}" ]] || report HIGH "Story $sid in spec file but missing from epic.yaml manifest" + grep -qE '^## (17\.|Acceptance|Verification Script)' "$spec" \ + || report HIGH "Story $sid spec missing §17 acceptance criteria or Verification Script" + grep -qiE 'ambiguous|TBD|TODO|FIXME' "$spec" \ + && report MED "Story $sid spec contains ambiguous/TBD markers" +done + +for tasks in "${TASKS[@]}"; do + base="$(basename "$tasks" -tasks.yaml)" + sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)" + [[ -n "$sid" ]] || continue + [[ -n "${SPEC_IDS[$sid]+x}" ]] || report CRITICAL "tasks.yaml for $sid without matching story spec .md" + grep -qE '^[[:space:]]*verify:' "$tasks" \ + || report CRITICAL "Story $sid tasks.yaml missing runnable verify: commands" + grep -qE '^status:[[:space:]]*(failing|todo|passing)' "$tasks" \ + || report MED "Story $sid tasks.yaml should use status: failing|passing ledger (e45s06)" +done + +for sid in "${!EPIC_STORIES[@]}"; do + [[ -n "${SPEC_IDS[$sid]+x}" ]] || report HIGH "epic.yaml lists $sid but no story spec .md exists" +done + +echo "---" +echo "plan-consistency-check: CRITICAL=$CRITICAL HIGH=$HIGH MED=$MED" + +if (( CRITICAL > 0 || HIGH > 0 )); then + echo "BLOCKED: resolve CRITICAL/HIGH before code generation" >&2 + exit 1 +fi + +if (( MED > 0 )); then + echo "WARN: MED findings present — confirm with user before build" + exit 0 +fi + +echo "PASS: capsule artifacts consistent" +exit 0 diff --git a/scripts/lib/run-benchmark.py b/scripts/lib/run-benchmark.py new file mode 100755 index 00000000..5fc5b080 --- /dev/null +++ b/scripts/lib/run-benchmark.py @@ -0,0 +1,210 @@ +#!/usr/bin/env python3 +# story: e45s01 +"""Run skill benchmarks from specs/benchmarks/ with train/validation split and delta grading.""" +from __future__ import annotations + +import argparse +import json +import subprocess +import sys +from datetime import date +from pathlib import Path + +import yaml + +REPO_ROOT = Path(__file__).resolve().parents[2] +BENCH_DIR = REPO_ROOT / "specs" / "benchmarks" +REPORTS_DIR = BENCH_DIR / "reports" +DEFAULT_RUNS = 3 +GRADER_TIMEOUT = 15 + + +def load_definition(skill: str) -> dict: + path = BENCH_DIR / f"{skill}.yaml" + if not path.exists(): + print(f"ERROR: no benchmark definition at {path}", file=sys.stderr) + sys.exit(1) + with path.open() as f: + return yaml.safe_load(f) + + +def list_skills() -> list[str]: + return sorted(p.stem for p in BENCH_DIR.glob("*.yaml") if p.stem not in ("axes",)) + + +def run_code_grader(command: str, cwd: Path) -> bool: + try: + result = subprocess.run( + ["bash", "-c", command], + cwd=cwd, + capture_output=True, + text=True, + timeout=GRADER_TIMEOUT, + ) + out = (result.stdout + result.stderr).strip() + if "PASS" in out.upper() and "FAIL" not in out.upper(): + return True + return result.returncode == 0 + except (subprocess.TimeoutExpired, OSError): + return False + + +def scenario_pass_rate(scenario: dict, runs: int, with_skill: bool) -> tuple[float, str]: + grader = scenario.get("grader", {}) + gtype = grader.get("type", "code") + if gtype == "rubric": + return (-1.0, "pending_agent_eval") + if gtype != "code": + return (-1.0, "unsupported_grader") + command = grader.get("command", "") + if not command: + return (-1.0, "missing_command") + if not with_skill: + command = f"test -f /dev/null" # bare agent: code graders cannot pass without skill context + passes = sum(1 for _ in range(runs) if run_code_grader(command, REPO_ROOT)) + return (passes / runs, "code") + + +def pass_at_k(scenarios: list[dict], runs: int, with_skill: bool) -> float: + total_weight = 0.0 + weighted = 0.0 + for sc in scenarios: + rate, status = scenario_pass_rate(sc, runs, with_skill) + if status == "pending_agent_eval": + continue + weight = float(sc.get("weight", 1.0)) + total_weight += weight + weighted += weight * max(rate, 0.0) + if total_weight == 0: + return 0.0 + return round(weighted / total_weight, 2) + + +def partition_scenarios(scenarios: list[dict]) -> tuple[list[dict], list[dict]]: + train, validation = [], [] + for sc in scenarios: + split = sc.get("split", "validation") + if split == "train": + train.append(sc) + else: + validation.append(sc) + return train, validation + + +def build_split_report(scenarios: list[dict], runs: int) -> dict: + if not scenarios: + return {"with_skill": 0.0, "without_skill": 0.0, "delta": 0.0, "scenarios": []} + with_score = pass_at_k(scenarios, runs, with_skill=True) + without_score = pass_at_k(scenarios, runs, with_skill=False) + return { + "with_skill": with_score, + "without_skill": without_score, + "delta": round(with_score - without_score, 2), + "scenarios": [sc["id"] for sc in scenarios], + } + + +def scenario_details(scenarios: list[dict], runs: int) -> list[dict]: + rows = [] + for sc in scenarios: + with_rate, status = scenario_pass_rate(sc, runs, with_skill=True) + without_rate, _ = scenario_pass_rate(sc, runs, with_skill=False) + if status == "pending_agent_eval": + rows.append( + { + "id": sc["id"], + "split": sc.get("split", "validation"), + "status": "pending_agent_eval", + "weight": sc.get("weight", 1.0), + } + ) + continue + rows.append( + { + "id": sc["id"], + "split": sc.get("split", "validation"), + "with_pass_rate": round(max(with_rate, 0.0), 2), + "without_pass_rate": round(max(without_rate, 0.0), 2), + "delta": round(max(with_rate, 0.0) - max(without_rate, 0.0), 2), + "weight": sc.get("weight", 1.0), + } + ) + return rows + + +def run_benchmark(skill: str, baseline: bool = False) -> dict: + definition = load_definition(skill) + runs = int(definition.get("runs", DEFAULT_RUNS)) + scenarios = definition.get("scenarios", []) + train_sc, val_sc = partition_scenarios(scenarios) + today = date.today().isoformat() + report = { + "skill": skill, + "run_date": today, + "runs_per_scenario": runs, + "train": build_split_report(train_sc, runs), + "validation": build_split_report(val_sc, runs), + "scenarios": scenario_details(scenarios, runs), + } + REPORTS_DIR.mkdir(parents=True, exist_ok=True) + yaml_path = REPORTS_DIR / f"BENCHMARK-{skill}-{today}.yaml" + json_path = REPORTS_DIR / f"benchmark-{skill}.json" + with yaml_path.open("w") as f: + yaml.dump( + { + "skill": skill, + "run_date": today, + "runs_per_scenario": runs, + "train": { + "pass_at_k_with": report["train"]["with_skill"], + "pass_at_k_without": report["train"]["without_skill"], + "delta": report["train"]["delta"], + }, + "validation": { + "pass_at_k_with": report["validation"]["with_skill"], + "pass_at_k_without": report["validation"]["without_skill"], + "delta": report["validation"]["delta"], + }, + "scenarios": report["scenarios"], + }, + f, + default_flow_style=False, + ) + with json_path.open("w") as f: + json.dump(report, f, separators=(",", ":")) + print(f"Wrote {yaml_path}") + print(f"Wrote {json_path}") + if baseline: + import shutil + + shutil.copy(yaml_path, REPORTS_DIR / f"BASELINE-{skill}.yaml") + shutil.copy(json_path, REPORTS_DIR / f"baseline-{skill}.json") + print(f"Pinned baseline for {skill}") + val_delta = report["validation"]["delta"] + if val_delta < 0: + print(f"REGRESSION: validation Δ {val_delta} — do NOT ship") + elif val_delta < 0.05: + print(f"WARN: validation Δ {val_delta} — marginal contribution") + else: + print(f"OK: validation Δ {val_delta}") + return report + + +def main() -> None: + parser = argparse.ArgumentParser(description="Run skill quality benchmarks") + parser.add_argument("skill", nargs="?", help="Skill name to benchmark") + parser.add_argument("--all", action="store_true", help="Benchmark all skills with definitions") + parser.add_argument("--baseline", action="store_true", help="Pin results as baseline") + args = parser.parse_args() + if args.all: + for skill in list_skills(): + run_benchmark(skill, baseline=args.baseline) + elif args.skill: + run_benchmark(args.skill, baseline=args.baseline) + else: + parser.print_help() + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/scripts/lib/sync-context-engineering-ref.sh b/scripts/lib/sync-context-engineering-ref.sh new file mode 100755 index 00000000..d758bbd5 --- /dev/null +++ b/scripts/lib/sync-context-engineering-ref.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# story: e45s10 +# Refresh context-engineering.md sync stamp from SSOT (CLAUDE.md + PRINCIPLES.md). +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +TARGET="$REPO_ROOT/docs/references/context-engineering.md" +STAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + +[[ -f "$TARGET" ]] || exit 0 + +if grep -q 'Last synced:' "$TARGET"; then + sed -i.bak "s/\*\*Last synced:\*\*.*/\*\*Last synced:\*\* ${STAMP} (from CLAUDE.md + PRINCIPLES.md)/" "$TARGET" + rm -f "${TARGET}.bak" +else + printf '\n**Last synced:** %s (from CLAUDE.md + PRINCIPLES.md)\n' "$STAMP" >> "$TARGET" +fi + +echo "sync-context-engineering-ref: stamped $TARGET" diff --git a/scripts/references-manifest.yaml b/scripts/references-manifest.yaml new file mode 100644 index 00000000..448cbff7 --- /dev/null +++ b/scripts/references-manifest.yaml @@ -0,0 +1,19 @@ +# story: e45s10 +# SSOT → docs/references distillation manifest. +# Each entry: source globs/files regenerate target via generator script. +version: 1 +generated_at_field: docs/references/.sync-stamp + +entries: + - id: model-profiles-catalog + sources: + - skills/*/SKILL.md + target: docs/references/model-profiles.md + generator: scripts/generate-reference-tables.sh + + - id: context-engineering + sources: + - CLAUDE.md + - docs/PRINCIPLES.md + target: docs/references/context-engineering.md + generator: scripts/lib/sync-context-engineering-ref.sh diff --git a/scripts/run-benchmark.sh b/scripts/run-benchmark.sh new file mode 100755 index 00000000..ad417d37 --- /dev/null +++ b/scripts/run-benchmark.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# story: e45s01 +# run-benchmark.sh — N-run with/without-skill delta grading + train/validation split. +set -euo pipefail +source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh" +exec "$PYTHON" "$(dirname "${BASH_SOURCE[0]}")/lib/run-benchmark.py" "$@" diff --git a/scripts/sync-references.sh b/scripts/sync-references.sh new file mode 100755 index 00000000..d2896f47 --- /dev/null +++ b/scripts/sync-references.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# story: e45s10 +# Regenerate docs/references from SSOT sources (see scripts/references-manifest.yaml). +# Schedule: weekly via .github/workflows/sync-references.yml; also safe to run locally. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +MANIFEST="$REPO_ROOT/scripts/references-manifest.yaml" +STAMP_FILE="$REPO_ROOT/docs/references/.sync-stamp" + +cd "$REPO_ROOT" +[[ -f "$MANIFEST" ]] || { echo "sync-references: missing manifest" >&2; exit 1; } + +run_generator() { + local gen="$1" + [[ -x "$REPO_ROOT/$gen" || -f "$REPO_ROOT/$gen" ]] || { echo "sync-references: generator not found: $gen" >&2; exit 1; } + bash "$REPO_ROOT/$gen" +} + +# model-profiles catalog +run_generator scripts/generate-reference-tables.sh +run_generator scripts/lib/sync-context-engineering-ref.sh + +date -u +%Y-%m-%dT%H:%M:%SZ > "$STAMP_FILE" +echo "sync-references: OK (stamp $(cat "$STAMP_FILE"))" diff --git a/scripts/validate-skill-catalog.sh b/scripts/validate-skill-catalog.sh new file mode 100755 index 00000000..26a4a8e5 --- /dev/null +++ b/scripts/validate-skill-catalog.sh @@ -0,0 +1,147 @@ +#!/usr/bin/env bash +# story: e45s12 +# validate-skill-catalog.sh — code-enforced skill catalog hygiene (Hermes Curator pattern) +# Exit 0 when catalog passes; 1 on violations. --archive lists zero-usage skills for archiving. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +cd "$REPO_ROOT" + +SKILLS_ROOT="$REPO_ROOT/skills" +[[ -d "$SKILLS_ROOT" ]] || SKILLS_ROOT="$REPO_ROOT" + +ARCHIVE_MODE=false +STRICT=false +TARGET_SKILL="" +VIOLATIONS=0 +WARNINGS=0 + +# Documented naming exceptions (craft-skill REFERENCE.md) +VERB_NOUN_EXCEPTIONS="grill-me grill-with-docs context7-mcp using-bigpowers deploy" + +usage() { + echo "Usage: bash scripts/validate-skill-catalog.sh [--archive] [--strict] [--skill ]" + exit 2 +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --archive) ARCHIVE_MODE=true; shift ;; + --strict) STRICT=true; shift ;; + --skill) TARGET_SKILL="${2:-}"; shift 2 ;; + --skill=*) TARGET_SKILL="${1#*=}"; shift ;; + -h|--help) usage ;; + *) echo "Unknown flag: $1" >&2; usage ;; + esac +done + +report_catalog_violation() { echo "FAIL: $1" >&2; VIOLATIONS=$((VIOLATIONS + 1)); } +report_catalog_warning() { echo "WARN: $1" >&2; WARNINGS=$((WARNINGS + 1)); } + +check_verb_noun() { + local name="$1" + if echo " $VERB_NOUN_EXCEPTIONS " | grep -q " $name "; then + return 0 + fi + if [[ ! "$name" =~ ^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$ ]]; then + report_catalog_violation "$name: not verb-noun kebab-case" + return 1 + fi + local segments + segments=$(echo "$name" | tr '-' '\n' | wc -l | tr -d ' ') + if [[ "$segments" -gt 2 ]]; then + report_catalog_violation "$name: more than two hyphen segments (verb-noun only)" + fi +} + +check_skill() { + local skill_md="$1" + local name + name=$(basename "$(dirname "$skill_md")") + + check_verb_noun "$name" || true + + if ! grep -q 'HARD GATE' "$skill_md" 2>/dev/null; then + if $STRICT; then report_catalog_violation "$name: missing HARD GATE block"; else report_catalog_warning "$name: missing HARD GATE block"; fi + fi + + local desc + desc=$(awk 'BEGIN{f=0} /^---$/{f++; next} f==1{print} f==2{exit}' "$skill_md" \ + | grep -E '^description:' | head -1 | sed 's/^description: *//; s/^> //' | tr -d '"' || true) + if [[ -n "$desc" && ${#desc} -gt 1024 ]]; then + report_catalog_violation "$name: description ${#desc} chars (max 1024)" + fi + + local lines + lines=$(wc -l < "$skill_md" | tr -d ' ') + if [[ "$lines" -gt 300 ]]; then + report_catalog_warning "$name: SKILL.md $lines lines (target ≤300; split to REFERENCE.md)" + fi + + local cmd + cmd=$(grep -E '^(> )?→ verify:' "$skill_md" 2>/dev/null | tail -1 | sed 's/^> // ; s/^→ verify: *//' || true) + if [[ -z "$cmd" ]]; then + if $STRICT; then report_catalog_violation "$name: missing → verify: command"; else report_catalog_warning "$name: missing → verify: command"; fi + fi +} + +echo "Validating skill catalog under $SKILLS_ROOT ..." +if [[ -n "$TARGET_SKILL" ]]; then + skill_md="$SKILLS_ROOT/$TARGET_SKILL/SKILL.md" + [[ -f "$skill_md" ]] || { echo "FAIL: $skill_md not found" >&2; exit 1; } + check_skill "$skill_md" +else + for skill_md in "$SKILLS_ROOT"/*/SKILL.md; do + [[ -f "$skill_md" ]] || continue + check_skill "$skill_md" + done +fi + +if $ARCHIVE_MODE; then + STATE="$REPO_ROOT/specs/state.yaml" + echo "" + echo "=== Archive candidates (zero calls in metrics.skill_timings) ===" + if [[ ! -f "$STATE" ]]; then + echo " (no specs/state.yaml — skip usage scan)" + else + python3 - "$STATE" "$SKILLS_ROOT" <<'PY' +import sys, glob, os +from pathlib import Path + +state_path, skills_root = sys.argv[1], sys.argv[2] +text = Path(state_path).read_text(encoding="utf-8") +timings = set() +in_timings = False +for line in text.splitlines(): + if line.strip() == "skill_timings:": + in_timings = True + continue + if in_timings: + if line.startswith(" ") and not line.startswith(" ") and line.rstrip().endswith(":"): + timings.add(line.strip().rstrip(":")) + elif line.strip() and not line.startswith(" "): + in_timings = False + +skills = [os.path.basename(os.path.dirname(p)) for p in glob.glob(f"{skills_root}/*/SKILL.md")] +zero = sorted(s for s in skills if s not in timings) +if zero: + for s in zero: + print(f" ARCHIVE_CANDIDATE: {s} (0 calls — move to specs/epics/archive/ or delete)") +else: + print(" (no zero-usage skills)") +PY + fi +fi + +echo "" +if [[ "$VIOLATIONS" -gt 0 ]]; then + echo "CATALOG INVALID: $VIOLATIONS violation(s), $WARNINGS warning(s)" + exit 1 +fi +if $STRICT && [[ "$WARNINGS" -gt 0 ]]; then + echo "CATALOG INVALID (strict): $WARNINGS warning(s)" + exit 1 +fi +echo "CATALOG OK: $WARNINGS warning(s)" +exit 0 diff --git a/scripts/validate-skill-description.sh b/scripts/validate-skill-description.sh new file mode 100755 index 00000000..ff390b69 --- /dev/null +++ b/scripts/validate-skill-description.sh @@ -0,0 +1,70 @@ +#!/usr/bin/env bash +# story: e45s02 +# CSO description discipline — max 1024 chars, no workflow-summary leakage. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SKILLS_ROOT="$REPO_ROOT/skills" +[[ -d "$SKILLS_ROOT" ]] || SKILLS_ROOT="$REPO_ROOT" + +MAX_LEN=1024 +ERRORS=0 + +audit_skill_description_cso() { + local path="$1" + local skill desc len + + skill="$(basename "$(dirname "$path")")" + desc="$( + awk 'BEGIN{n=0} /^---$/{n++; next} n==1{print; next} n>=2{exit}' "$path" \ + | grep -E '^description:' | head -1 | sed 's/^description:[[:space:]]*//' | sed 's/^"//;s/"$//' + )" + + if [[ -z "$desc" ]]; then + echo "FAIL: $skill — missing description frontmatter" + ERRORS=$((ERRORS + 1)) + return + fi + + len=${#desc} + if (( len > MAX_LEN )); then + echo "FAIL: $skill — description ${len} chars (max ${MAX_LEN})" + ERRORS=$((ERRORS + 1)) + fi + + # Workflow-summary leakage: numbered steps, phase chains, verify prose in description + local leak=0 + if echo "$desc" | grep -qE '(^|[[:space:]])([0-9]+\.|Step [0-9]+|First,|Then,|Finally,|→ verify:|HARD GATE|Process:|Workflow:)'; then + leak=1 + fi + if echo "$desc" | grep -qE '(discover →|scope-work →|plan-work →|develop-tdd →|verify-work →|→ .* → )'; then + leak=1 + fi + if (( leak )); then + echo "FAIL: $skill — workflow-summary leakage in description (keep triggers only; move steps to body)" + ERRORS=$((ERRORS + 1)) + fi + + if echo "$desc" | grep -qE 'model:[[:space:]]*(haiku|sonnet|opus)'; then + echo "FAIL: $skill — model hint belongs in frontmatter, not description" + ERRORS=$((ERRORS + 1)) + fi +} + +if [[ $# -gt 0 ]]; then + for f in "$@"; do + [[ -f "$f" ]] || { echo "FAIL: not found: $f" >&2; exit 1; } + audit_skill_description_cso "$f" + done +else + while IFS= read -r f; do + audit_skill_description_cso "$f" + done < <(find "$SKILLS_ROOT" -maxdepth 2 -name SKILL.md | sort) +fi + +if (( ERRORS > 0 )); then + echo "validate-skill-description: $ERRORS issue(s)" >&2 + exit 1 +fi + +echo "validate-skill-description: PASS" diff --git a/skills-lock.json b/skills-lock.json index e7193053..eb270d55 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -13,7 +13,7 @@ }, "audit-code": { "description": "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.", - "sha256": "6d844137eda91fe7", + "sha256": "b4d70ad39eca5902", "path": "skills/audit-codeSKILL.md" }, "audit-plan": { @@ -28,7 +28,7 @@ }, "change-request": { "description": "Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic capsule directories. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs prioritization.", - "sha256": "1364e382acf3e3dc", + "sha256": "92edb0a1bd19b528", "path": "skills/change-requestSKILL.md" }, "commit-message": { @@ -38,17 +38,22 @@ }, "compose-workflow": { "description": "Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. Use when a project repeats a non-standard skill sequence, or user wants a documented playbook beyond orchestrate-project modes.", - "sha256": "ee6c606c36210b83", + "sha256": "197a5220ccb3d74f", "path": "skills/compose-workflowSKILL.md" }, + "context7-mcp": { + "description": "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc.", + "sha256": "31c47bbfcbc38b95", + "path": "skills/context7-mcpSKILL.md" + }, "craft-skill": { "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.", - "sha256": "7e70a1d6d9048b2e", + "sha256": "cbf8ab939cfbab87", "path": "skills/craft-skillSKILL.md" }, "deepen-architecture": { "description": "Find deepening opportunities in a codebase, informed by the domain language in specs/tech-architecture/tech-stack.md and the decisions in specs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.", - "sha256": "c1f82fa6bed64a8b", + "sha256": "591441a980d0447c", "path": "skills/deepen-architectureSKILL.md" }, "define-language": { @@ -63,12 +68,12 @@ }, "delegate-task": { "description": "Delegate one complex task to a single subagent, review its work in two stages before merging back. Sequential — one agent at a time, with oversight. Use when a task is complex and requires careful review before the result is accepted. Distinct from dispatch-agents (no parallelism here; reviewer sees full diff before proceeding).", - "sha256": "44368385d15e4f00", + "sha256": "a7ff44e8add873e2", "path": "skills/delegate-taskSKILL.md" }, "deploy": { "description": "\"Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production.\"", - "sha256": "209025beb44d114c", + "sha256": "38b542713906d451", "path": "skills/deploySKILL.md" }, "design-interface": { @@ -78,7 +83,7 @@ }, "develop-tdd": { "description": "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).", - "sha256": "943a6181c39ab097", + "sha256": "1989004e232bb4be", "path": "skills/develop-tddSKILL.md" }, "diagnose-root": { @@ -86,9 +91,14 @@ "sha256": "fe7b35833cf548d1", "path": "skills/diagnose-rootSKILL.md" }, + "diagnose-stall": { + "description": "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned.", + "sha256": "7bf260ea295aef62", + "path": "skills/diagnose-stallSKILL.md" + }, "dispatch-agents": { "description": "Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate).", - "sha256": "b5dcc9c2a88eb377", + "sha256": "7f5e21affed8f000", "path": "skills/dispatch-agentsSKILL.md" }, "edit-document": { @@ -128,7 +138,7 @@ }, "gate-trace": { "description": "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"", - "sha256": "81deb2549867386b", + "sha256": "ed37c315dcef6f87", "path": "skills/gate-traceSKILL.md" }, "grill-me": { @@ -213,7 +223,7 @@ }, "plan-work": { "description": "\"PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2).\"", - "sha256": "29792e9d4499cc1e", + "sha256": "4cc87b8c2ae13dae", "path": "skills/plan-workSKILL.md" }, "publish-package": { @@ -228,12 +238,12 @@ }, "release-branch": { "description": "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says \"release\", \"merge\", or \"open a PR\".", - "sha256": "73a9aebff3fb4dc0", + "sha256": "c07d9efcb1d4e79b", "path": "skills/release-branchSKILL.md" }, "request-review": { "description": "Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review.", - "sha256": "1240032ef1992331", + "sha256": "5a845fc8c2ba7acb", "path": "skills/request-reviewSKILL.md" }, "research-first": { @@ -253,12 +263,12 @@ }, "run-benchmark": { "description": "Run skill quality benchmarks from specs/benchmarks/ definitions — N-run with/without-skill delta grading, train/validation split, pass@k + benchmark.json reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.", - "sha256": "6c537b3d6b19aae7", + "sha256": "ad0c0eebf819f036", "path": "skills/run-benchmarkSKILL.md" }, "run-evals": { "description": "Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.", - "sha256": "4478bb4d9bc311fa", + "sha256": "2fd60cbf4a4e1c63", "path": "skills/run-evalsSKILL.md" }, "run-planning": { @@ -278,17 +288,17 @@ }, "security-review": { "description": ">", - "sha256": "da17dffef0b691c7", + "sha256": "8063dcca13bba46b", "path": "skills/security-reviewSKILL.md" }, "seed-conventions": { "description": "Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.", - "sha256": "ebb23bdd3aefa527", + "sha256": "e995b42dda1cfd23", "path": "skills/seed-conventionsSKILL.md" }, "session-state": { "description": "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.", - "sha256": "537d9b966edcf5ff", + "sha256": "4b607fee350390c6", "path": "skills/session-stateSKILL.md" }, "setup-environment": { @@ -303,7 +313,7 @@ }, "slice-tasks": { "description": "\"PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work.\"", - "sha256": "a9308ab2d3fa20dc", + "sha256": "b89b61159fc619e5", "path": "skills/slice-tasksSKILL.md" }, "smoke-test": { @@ -318,7 +328,7 @@ }, "stocktake-skills": { "description": "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.", - "sha256": "4fa650cde9bf47c5", + "sha256": "82d6399aba8eeea2", "path": "skills/stocktake-skillsSKILL.md" }, "survey-context": { @@ -348,12 +358,12 @@ }, "validate-fix": { "description": "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation.", - "sha256": "43022a8e844458b2", + "sha256": "e3a38b117a7f3b2d", "path": "skills/validate-fixSKILL.md" }, "verify-work": { "description": "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.", - "sha256": "ae08ac8212a003ac", + "sha256": "8d0d7eddbca1bdb0", "path": "skills/verify-workSKILL.md" }, "visual-dashboard": { diff --git a/skills/audit-code/SKILL.md b/skills/audit-code/SKILL.md index f6e633f1..2c20d7b7 100644 --- a/skills/audit-code/SKILL.md +++ b/skills/audit-code/SKILL.md @@ -1,4 +1,6 @@ # story: e51s04 +# story: e45s18 +# story: e45s31 --- name: audit-code model: haiku @@ -14,11 +16,27 @@ Run this self-review before asking anyone else to look at the code. The goal is **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. +## Look-here-first (churn heuristic) + +Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 15 +``` + +Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. + ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: + +```bash +bash scripts/lib/parallel-review-worktrees.sh audit-code +``` + ## Checklist @@ -110,24 +128,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. -### Gate mode output (`--gate`) - -In `--gate` mode, print one summary line per checklist section: - -``` -PASS Supply Chain & Security -FAIL Provenance & Metadata (2 items) -PASS Law of Demeter -... -``` - -Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT--.md` as a permanent record. +In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"` - ## Handoff Gate: READY -> next: commit-message diff --git a/skills/change-request/SKILL.md b/skills/change-request/SKILL.md index eb8f1c55..10d9e2d3 100644 --- a/skills/change-request/SKILL.md +++ b/skills/change-request/SKILL.md @@ -5,6 +5,8 @@ effort: standard description: Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic capsule directories. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs prioritization. --- +# story: e45s29 + # Change Request > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first. @@ -19,7 +21,7 @@ Intake a new requirement mid-flight without disrupting work in progress. 1. **Capture**: What is the change? What problem does it solve? 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace? -3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). +3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29). 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`. 5. **Score**: Compute WSJF; note if it outranks in-progress work. diff --git a/skills/compose-workflow/SKILL.md b/skills/compose-workflow/SKILL.md index 134a9dfa..48bc912e 100644 --- a/skills/compose-workflow/SKILL.md +++ b/skills/compose-workflow/SKILL.md @@ -5,6 +5,8 @@ model: sonnet effort: standard --- +# story: e45s27 + # Compose Workflow > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified. @@ -21,6 +23,19 @@ effort: standard > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-.md` markdown format. > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library. +## Terminal-state taxonomy (e45s27) + +Every workflow step and `/loop` tick MUST exit with exactly one terminal state: + +| State | Meaning | Next action | +|-------|---------|-------------| +| `success` | Step verify passed; artifacts written | Advance to next skill in recipe | +| `no-op` | Nothing to do (already green / already applied) | Skip step; advance | +| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user | +| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required | + +Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`. + ## Standard Recipe Library Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains. diff --git a/skills/context7-mcp/SKILL.md b/skills/context7-mcp/SKILL.md new file mode 100644 index 00000000..cbdbe6df --- /dev/null +++ b/skills/context7-mcp/SKILL.md @@ -0,0 +1,57 @@ +--- +name: context7-mcp +# story: e45s19 e45s20 +model: haiku +effort: light +description: Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc. +--- + +# Context7 MCP + +> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data. +> +> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get ":"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry. + +## When to Use + +- Setup/configuration questions ("How do I configure Next.js middleware?") +- Code involving libraries ("Write a Prisma query for…") +- API references ("What are the Supabase auth methods?") +- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.) + +## Bounded Retry (max 3x) + +| Attempt | Action | +|---------|--------| +| 1 | `resolve-library-id` → pick best match | +| 2 | `query-docs` with selected `libraryId` | +| 3 | Retry `query-docs` once with refined query (narrower scope) | + +After 3 failures, stop and print: + +``` +CONTEXT7_UNAVAILABLE +Reason: +Action: Ask user to retry later, paste official docs URL, or run `bts docs `. +Do NOT substitute training-data answers without labeling them UNVERIFIED. +``` + +## Fetch Cache (ETag-revalidated) + +1. **Cache key:** `":"` (lowercase, trimmed). +2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get ""` — exit 0 → use cached body. +3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`. +4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it. + +`bts docs ` shares the same cache helper when invoked from this skill. + +## Process + +1. `resolve-library-id` with `libraryName` + full user `query`. +2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version. +3. `query-docs` with `libraryId` + specific question (one concept per call). +4. Answer using fetched docs; cite library/version when relevant. + +## Verify + +→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL` diff --git a/skills/craft-skill/SKILL.md b/skills/craft-skill/SKILL.md index fcf2f68d..87e0c9e4 100644 --- a/skills/craft-skill/SKILL.md +++ b/skills/craft-skill/SKILL.md @@ -1,3 +1,5 @@ +# story: e45s02 + --- name: craft-skill model: sonnet @@ -9,6 +11,19 @@ description: Create new bigpowers skills with proper structure, progressive disc > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md. +## CSO Description Discipline (e45s02) + +The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill. + +| Rule | Limit | +|------|-------| +| Max length | 1024 characters | +| Voice | Third person | +| Content | Capability + `Use when …` triggers only | +| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose | + +Move process detail into the SKILL.md body or REFERENCE.md — never into `description`. + ## Process 1. **Gather requirements** — ask user about: @@ -40,6 +55,12 @@ description: Create new bigpowers skills with proper structure, progressive disc - Anything missing or unclear? - Should any section be more/less detailed? +6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done: + - Run `bash scripts/validate-skill-description.sh skills//SKILL.md` — must exit 0 + - Run `bash scripts/sync-skills.sh` — must complete without error + - Run `bash scripts/run-skill-verify.sh ` if the skill defines a verify command + - Show terminal output for each — narration without evidence is rejected + ## Naming Rules Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. @@ -53,10 +74,18 @@ If the skill produces written output, it goes in `specs/` at the project root. D After drafting, verify: - [ ] Name is a two-word verb-noun pair (or follows grill-me exception) +- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage - [ ] Description includes triggers ("Use when...") - [ ] SKILL.md under 100 lines - [ ] No time-sensitive info - [ ] Consistent terminology with CONVENTIONS.md - [ ] specs/ output documented if applicable +- [ ] `validate-skill-description.sh` exits 0 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini +- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty) + +> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill ` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command. + +## Verify +→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL` diff --git a/skills/deepen-architecture/SKILL.md b/skills/deepen-architecture/SKILL.md index 0dc20a21..7467e57d 100644 --- a/skills/deepen-architecture/SKILL.md +++ b/skills/deepen-architecture/SKILL.md @@ -1,3 +1,5 @@ +# story: e45s31 + --- name: deepen-architecture model: sonnet @@ -45,6 +47,12 @@ Read existing documentation first: If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront. +**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there. + +```bash +bash scripts/bp-churn-rank.sh --since 90.days --limit 20 +``` + Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? @@ -93,3 +101,17 @@ Side effects happen inline as decisions crystallize: - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +### 5. Import-boundary hygiene (e45s14) + +When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via: + +```bash +bash scripts/check-import-boundaries.sh +``` + +Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them. + +## Verify + +→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL` + diff --git a/skills/delegate-task/SKILL.md b/skills/delegate-task/SKILL.md index 51402912..dfca41d3 100644 --- a/skills/delegate-task/SKILL.md +++ b/skills/delegate-task/SKILL.md @@ -5,6 +5,8 @@ effort: standard description: Delegate one complex task to a single subagent, review its work in two stages before merging back. Sequential — one agent at a time, with oversight. Use when a task is complex and requires careful review before the result is accepted. Distinct from dispatch-agents (no parallelism here; reviewer sees full diff before proceeding). --- +# story: e45s30 + # Delegate Task > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently. @@ -13,6 +15,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates. +## Subagent depth tiers (e45s30) + +Select brief depth from task `risk:` and skill `effort:` before spawning: + +| Tier | When | Brief includes | +|------|------|----------------| +| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present | +| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions | +| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) | + +State `depth: ` in the Agent tool description field. + ## Process ### 1. Define the task diff --git a/skills/deploy/SKILL.md b/skills/deploy/SKILL.md index 0bad5e72..960c8365 100644 --- a/skills/deploy/SKILL.md +++ b/skills/deploy/SKILL.md @@ -1,3 +1,4 @@ + --- name: deploy description: "Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production." @@ -105,3 +106,11 @@ For comprehensive health-checking, chain to the `smoke-test` skill: bash scripts/run-smoke.sh "$DEPLOY_URL" ``` +### 7. Three-independent-facts verification (e45s15) + +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). + +## Verify + +→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL` + diff --git a/skills/develop-tdd/SKILL.md b/skills/develop-tdd/SKILL.md index c83df866..379472f8 100644 --- a/skills/develop-tdd/SKILL.md +++ b/skills/develop-tdd/SKILL.md @@ -1,4 +1,7 @@ # story: e51s04 +# story: e45s06 +# story: e45s08 +# story: e45s34 --- name: develop-tdd model: sonnet @@ -52,16 +55,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel Write ONE test that confirms ONE thing about the system: ``` -RED: Write test for first behavior → test fails → commit: test(): ... -GREEN: Write minimal code to pass → test passes → commit: feat(): ... +RED: Write test for first behavior → test fails → commit: test(): ... (test-only; red in CI) +GREEN: Write minimal code to pass → test passes → commit: feat(): ... (fix commit; green) REFACTOR (optional): clean up → commit: refactor(): ... ``` +> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior. + +> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass. + ### 3. Incremental Loop -> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent. +> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly: + +```bash +bash scripts/bp-yaml-snapshot.sh specs/state.yaml # if state changed this cycle +git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true +``` + +After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED. -For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase. +For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase. ### 4. Visual Slices (UI alternate workflow) diff --git a/skills/diagnose-stall/SKILL.md b/skills/diagnose-stall/SKILL.md new file mode 100644 index 00000000..2532fe2c --- /dev/null +++ b/skills/diagnose-stall/SKILL.md @@ -0,0 +1,56 @@ +# story: e45s38 +--- +name: diagnose-stall +model: haiku +effort: light +description: Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned. +--- + +# Diagnose Stall + +> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state. + +Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode). + +## Stall signals + +| Signal | Likely cause | +|--------|----------------| +| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed | +| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large | +| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation | +| Verify command running >15 min | Missing timeout or waiting on external service | +| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff | + +## Process + +1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions. +2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`. +3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes. +4. **Classify stall type:** + - **waiting_approval** — tool blocked on user consent + - **blocked_dependency** — prior task incomplete or red gate + - **agent_exhausted** — max iterations/cycles reached + - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed + - **external_io** — network, CI, or deploy wait without timeout + - **unknown** — escalate with evidence bundle +5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user). +6. **Write report** — `specs/verifications/STALL-.md` with classification, evidence, and recommended next skill. + +## Integration + +| Caller | When to invoke | +|--------|----------------| +| `/loop` (Cursor) | After two consecutive ticks with no observable progress | +| `dispatch-agents` | When a wave exceeds expected duration with zero returns | +| `execute-plan` | When a step checkpoint is overdue | +| User | "Why did this stop?" / "Nothing is happening" | + +## Verify + +→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"` + +## Handoff + +Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml` +Writes: `specs/verifications/STALL-*.md` diff --git a/skills/dispatch-agents/SKILL.md b/skills/dispatch-agents/SKILL.md index 9b78a03e..5aa4efb9 100644 --- a/skills/dispatch-agents/SKILL.md +++ b/skills/dispatch-agents/SKILL.md @@ -1,3 +1,5 @@ +# story: e45s38 + --- name: dispatch-agents model: sonnet @@ -5,6 +7,8 @@ effort: standard description: Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate). --- +# story: e45s30 + # Dispatch Agents > **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents. @@ -36,30 +40,57 @@ Before dispatching, verify each task pair is truly independent: If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead. -### 2. Write task briefs +## Subagent depth tiers (e45s30) -Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. +Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief. -For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk): +| Tier | When | Brief shape | Token budget | +|------|------|-------------|----------------| +| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope | +| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default | +| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines | +Record `depth: ` in the Agent tool description when dispatching. + +### 2. Write typed task briefs (Orca message protocol) + +Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else. + +Every inter-agent message uses a **typed envelope** — no freeform prose between waves: + +| `type` | When | Required fields | +|--------|------|-----------------| +| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` | +| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) | +| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` | +| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) | + +Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk): + +```yaml +type: task_brief +task_id: agent-1 +goal: [one sentence — what success looks like] +in_scope: [explicit file or module list] +out_of_bounds: [what NOT to touch] +verify: [runnable command] +prior_decisions: [relevant entries from specs/state.yaml — omit if none] ``` -Goal: [one sentence — what success looks like] -In scope: [explicit file or module list] -Out of bounds: [what NOT to touch] -Verify: [runnable command] -Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply] -``` + +Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups. Do not include the full conversation, full file contents, or decisions unrelated to this agent's task. -### 3. Iterative retrieval (max 3 cycles) +### 3. Circuit breaker + iterative retrieval (max 3 cycles) + +Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`. After each wave completes: -1. **Dispatch** — run parallel agents with briefs. -2. **Evaluate** — read outputs; list gaps vs goal. +1. **Dispatch** — run parallel agents with typed `task_brief` envelopes. +2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits. 3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total). -Stop when gaps empty or cycle 3 reached — escalate to user. +Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave. ### 4. Dispatch in parallel @@ -73,14 +104,15 @@ Agent 3: brief for task C ### 5. Collect and review results -When all agents return: -- Review each result independently -- Run all verify commands -- Check diffs for scope violations or CONVENTIONS.md breaches +When all agents return: review each result, run verify commands, check diffs for scope violations. ### 6. Integrate -Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict. +Merge accepted results. Resolve conflicts manually; note in summary. + +Report: which tasks succeeded, which need revision, overall verify status. + +## Verify -Report a summary: which tasks succeeded, which need revision, and overall verify status. +→ verify: `grep -q 'circuit_open' skills/dispatch-agents/SKILL.md && grep -q 'task_brief' skills/dispatch-agents/SKILL.md && echo OK || echo FAIL` diff --git a/skills/gate-trace/SKILL.md b/skills/gate-trace/SKILL.md index 38fe57a4..b8cf8f6b 100644 --- a/skills/gate-trace/SKILL.md +++ b/skills/gate-trace/SKILL.md @@ -1,7 +1,9 @@ +# story: e45s05 --- name: gate-trace description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability." # story: e38s06 +# story: e45s32 model: haiku effort: light --- @@ -39,7 +41,15 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`. 6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details." 7. Output verdict + rationale to stdout. -7. Update `specs/execution-status.yaml` with gate-trace result. +8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt. +9. **Completeness critic (e45s05)** — Run adversarial gap-finding: + +```bash +bash scripts/lib/completeness-critic.sh +``` + +Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale. +10. Update `specs/execution-status.yaml` with gate-trace result. ## Verdict Semantics diff --git a/skills/guard-git/REFERENCE.md b/skills/guard-git/REFERENCE.md index e101db62..e962ea45 100644 --- a/skills/guard-git/REFERENCE.md +++ b/skills/guard-git/REFERENCE.md @@ -1,5 +1,19 @@ # Git guardrails — reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Secret patterns | +| 26–44 | Copy layout | +| 46–72 | Claude Code | +| 74–92 | Cursor and Cursor CLI | +| 94–120 | Gemini CLI | +| 122–135 | Google Antigravity | +| 137–178 | Verify (local tests) | + ## Secret patterns (audit + pre-commit) Agents must not commit files containing: diff --git a/skills/migrate-spec/REFERENCE.md b/skills/migrate-spec/REFERENCE.md index 11aae25b..80e13b80 100644 --- a/skills/migrate-spec/REFERENCE.md +++ b/skills/migrate-spec/REFERENCE.md @@ -1,5 +1,17 @@ # Migrate Spec — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–22 | Navigation | +| 24–62 | spec-kit → bigpowers Mapping | +| 64–130 | BMAD → bigpowers Mapping | +| 132–154 | Learnings to Adopt | +| 156–350 | Output Formats + state.yaml template | +| 352–620 | Reference blocks 1–2 + extended mappings | + # migrate-spec Reference — spec-kit, BMAD, Learnings Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. diff --git a/skills/plan-work/REFERENCE.md b/skills/plan-work/REFERENCE.md index a3bc96be..fce035ca 100644 --- a/skills/plan-work/REFERENCE.md +++ b/skills/plan-work/REFERENCE.md @@ -1,5 +1,16 @@ # Plan Work — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Output file formats | +| 40–71 | Plan template | +| 73–91 | Verify step format rules | +| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) | + ## Output file formats ### Story spec: `specs/epics//eNNsYY-.md` @@ -11,14 +22,14 @@ Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Coun ```yaml story_id: e01s01 title: Login -status: todo +status: failing bcps: 3 tasks: - id: 1 description: "Add login form component tests" verify: "npm test -- login-form.test.tsx" risk: P1 - status: todo + status: failing # flip to passing only after verify exits 0 (e45s06) ``` Update `specs/epics//epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes. @@ -89,6 +100,22 @@ Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `sp `verify-work` scales its UAT depth based on this field. +### Requirement delta tags (e45s29) + +When modifying existing behavior in story spec § Requirements: + +```markdown +#### MODIFIED: User can reset password via email link +**Before:** Password reset required admin approval. +**After:** Self-service reset via signed email link (expires 1h). + +#### REMOVED: Legacy OAuth1 login +**Before:** OAuth1 provider supported for enterprise SSO. +**After:** (removed) — provider deprecated; OAuth2 only. +``` + +Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL. + ### Define Success Before planning, convert task statements into observable "step → verify: " pairs: diff --git a/skills/plan-work/SKILL.md b/skills/plan-work/SKILL.md index 4d8a9fba..c03c12dc 100644 --- a/skills/plan-work/SKILL.md +++ b/skills/plan-work/SKILL.md @@ -1,3 +1,8 @@ +# story: e45s04 +# story: e45s06 +# story: e45s09 +# story: e45s33 +# story: e45s35 --- name: plan-work model: opus @@ -5,6 +10,8 @@ effort: standard description: "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2)." --- +# story: e45s29 + # Plan Work > **Spine position:** Step 3 — scope-work → slice-tasks → plan-work. @@ -46,14 +53,45 @@ If this plan touches an existing module, run `assess-impact` first to understand 3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. + **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: + + | Tag | When | Required content | + |-----|------|------------------| + | `ADDED` | New requirement | Full requirement text | + | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior | + | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale | + | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title | + + Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. + 4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: + +```bash +bash scripts/lib/plan-consistency-check.sh specs/epics// +``` + +Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment. + +4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time. + 5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project. +## Lifecycle Gates (e45s09) + +| Gate | When | Pass condition | +|------|------|----------------| +| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS | +| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` | +| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries | + After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`. ## Verify +→ verify: `test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5` + ## Handoff diff --git a/skills/publish-package/REFERENCE.md b/skills/publish-package/REFERENCE.md index 583070a1..46e489b4 100644 --- a/skills/publish-package/REFERENCE.md +++ b/skills/publish-package/REFERENCE.md @@ -1,5 +1,16 @@ # Publish Package — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–18 | Navigation | +| 20–28 | Options | +| 30–60 | Examples | +| 62–72 | Integration with release-branch | +| 74–252 | Reference blocks 1–8 | + ## Options | Flag | Description | diff --git a/skills/release-branch/REFERENCE.md b/skills/release-branch/REFERENCE.md index b49ffde7..38d8df8e 100644 --- a/skills/release-branch/REFERENCE.md +++ b/skills/release-branch/REFERENCE.md @@ -1,5 +1,19 @@ # Release Branch — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1–3 | Title | +| 5–16 | Navigation | +| 18–41 | PR body template | +| 43–54 | Worktree cleanup | +| 56–96 | Cycle-time recording | +| 98–119 | CI verification | +| 121–126 | Solo-local fallback | +| 128–134 | Handoff | +| 136–155 | Reference block 1 (manual squash) | + # Release Branch — Reference ## PR body template (team-pr mode) diff --git a/skills/release-branch/SKILL.md b/skills/release-branch/SKILL.md index 67b605c2..9c698175 100644 --- a/skills/release-branch/SKILL.md +++ b/skills/release-branch/SKILL.md @@ -1,4 +1,7 @@ + + + --- name: release-branch model: haiku @@ -55,6 +58,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: `). WAIVED if no matrix available. +> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails. + ### 3. Diff review - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance @@ -75,9 +80,26 @@ bash scripts/land-branch.sh "feat(scope): description" ### 6. Create PR (team-pr only) -Create the pull request, then merge via `gh`: +Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently: + +```markdown + +``` + +Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`: ```bash +gh pr create --title "..." --body "$(cat <<'EOF' +## Summary + + +- ... + +## Test plan +- [ ] ... + +EOF +)" gh pr merge --squash --delete-branch ``` @@ -93,55 +115,18 @@ mv specs/epics/eNN-slug specs/epics/archive/ ### 7b. CI verification & agent lock release (e39s02) -> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release. - -After push, run CI polling: +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ``` -Then release the story lock: - -```bash -LOCK="specs/agent-locks.yaml"; STORY="" -[ -f "$LOCK" ] && python3 -c " -import yaml -d=yaml.safe_load(open('$LOCK')) -if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY'] -yaml.dump(d,open('$LOCK','w'),default_flow_style=False) -print(f'LOCK RELEASED: $STORY') -"||echo "No lock for $STORY — idempotent" -``` - -- [ ] CI workflow passes after push (wait-for-ci.sh exit 0) -- [ ] `release.ci_verified: true` documented in state.yaml -- On failure: `handoff.next_skill = fix-bug` with CI failure URL +- [ ] CI passes; `release.ci_verified: true` in state.yaml +- On failure: `handoff.next_skill = fix-bug` -### 8. Clean up worktree +### 8. Clean up & return -```bash -git worktree prune -git worktree remove ../ 2>/dev/null || true -git branch -d -``` - -### 8a. Cycle-time recording - -After landing, record delivery metrics with the git-derived, additive script: - -```bash -bash scripts/record-cycle-time.sh append \ - --story --bcps \ - --range "$(git merge-base main HEAD)..HEAD" \ - --file specs/metrics/cycle-times.yaml -``` - -### 9. Return to main - -```bash -git checkout main && git status && pwd -``` +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). Report: "Branch released." diff --git a/skills/request-review/SKILL.md b/skills/request-review/SKILL.md index e28a5355..0b544461 100644 --- a/skills/request-review/SKILL.md +++ b/skills/request-review/SKILL.md @@ -1,3 +1,6 @@ +# story: e45s07 + + --- name: request-review model: opus @@ -5,21 +8,44 @@ effort: standard description: Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review. --- +# story: e45s28 + # Request Review -Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code. +Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed. + +**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents. + +**Solo developer note:** Reviewer agents replace the human reviewer. + +**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself. + +## Santa Method — Dual-Blind AND Gate (e45s07) + +Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent. -**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed. +| Parameter | Value | +|-----------|-------| +| Reviewers | 2 (mandatory) | +| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) | +| Pass rule | **AND-gate** — both reviewers must pass independently | +| Blindness | Neither reviewer sees the other's report until both complete | -**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer. +**Iteration loop (max `MAX_REVIEW_ITERATIONS`):** -**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself. +1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts. +2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider. +3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers. +4. If both pass (zero must-fix, score ≥ 94% each) → review complete. +5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge. + +> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate. ## Process ### 1. Prepare the review brief -Write a self-contained brief for the reviewer agent. Include: +Write a self-contained brief for each reviewer. Include: - What was built (feature description, not implementation) - Which files changed (the diff context) @@ -29,12 +55,25 @@ Write a self-contained brief for the reviewer agent. Include: - What you're most uncertain about (where you want fresh eyes) - **Security focus** — If the epic has a `specs/security/epics//THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+. -### 2. Dispatch the reviewer agent +### 2. Fan-out parallel reviewers (e45s17) + +Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern): + +| Agent | Focus | +|-------|-------| +| R-correctness | Logic, edge cases, verify command result | +| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) | +| R-security | Injection, auth, secrets (when `security-sensitive`) | +| R-design | Simpler alternatives, API shape | -Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed." +Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair. + +### 2b. Dispatch both reviewer agents (parallel) + +Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed." ``` -You are a code reviewer. Review the following code changes. +You are code reviewer [A|B]. Review the following code changes independently. Context: [feature description] CONVENTIONS.md rules: [paste relevant sections] @@ -56,19 +95,22 @@ For each finding, categorize as: must-fix / should-fix / consider. Run the verify command and report the result. ``` -### 3. Collect the report +### 3. Collect both reports -When the reviewer returns: -- Read every finding before acting on any -- Note the verify command result -- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items` -- Report the score to the user +When reviewers return: +- Read every finding from **both** reports before acting on any +- Note each verify command result +- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items` +- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**? -> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100. +> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh). ### 4. Hand off to respond-review -Pass the reviewer's report to `respond-review` to categorize findings and apply fixes. +Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted. + +Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]." -Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review." +## Verify +→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK` diff --git a/skills/run-benchmark/SKILL.md b/skills/run-benchmark/SKILL.md index e6cfe73b..d2363e57 100644 --- a/skills/run-benchmark/SKILL.md +++ b/skills/run-benchmark/SKILL.md @@ -1,6 +1,6 @@ --- name: run-benchmark -# story: e48s01 +# story: e45s01 model: haiku effort: standard description: Run skill quality benchmarks from specs/benchmarks/ definitions — N-run with/without-skill delta grading, train/validation split, pass@k + benchmark.json reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions. @@ -30,9 +30,9 @@ Benchmark definitions partition scenarios into two sets: ## Usage ```bash -run-benchmark # benchmark single skill -run-benchmark --all # benchmark all with definitions -run-benchmark --baseline # pin results as baseline +bash scripts/run-benchmark.sh # benchmark single skill +bash scripts/run-benchmark.sh --all # benchmark all with definitions +bash scripts/run-benchmark.sh --baseline # pin results as baseline ``` ## Process diff --git a/skills/run-evals/REFERENCE.md b/skills/run-evals/REFERENCE.md index a345f2b7..66d75557 100644 --- a/skills/run-evals/REFERENCE.md +++ b/skills/run-evals/REFERENCE.md @@ -1,15 +1,25 @@ # Run Evals — Reference +## Strictness tiers (e45s37) + +Add a `tier:` column to each eval row: + +| Tier | Gate behaviour | +|------|----------------| +| `EXPERIMENTAL` | Log only — does not block | +| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` | +| `ALWAYS_PASSES` | Hard block on any failure | + ## EVALS template ```markdown # EVALS: ## Capability -| ID | Eval | Grader | verify / rubric | -|----|------|--------|-----------------| -| C1 | ... | code | `verify: npm test -- ` | -| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B | +| ID | Eval | Grader | Tier | verify / rubric | +|----|------|--------|------|-----------------| +| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- ` | +| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B | ## Regression | ID | Eval | Grader | verify / rubric | diff --git a/skills/run-evals/SKILL.md b/skills/run-evals/SKILL.md index 1b37f175..e34a5dc9 100644 --- a/skills/run-evals/SKILL.md +++ b/skills/run-evals/SKILL.md @@ -1,3 +1,4 @@ +# story: e45s37 --- name: run-evals description: Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs. @@ -16,8 +17,18 @@ effort: standard - **Capability evals** (does it do the job?) - **Regression evals** (did we break anything?) 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric). -4. Run evals; log results table with pass@k (e.g. 3/3 runs). -5. Block BUILD phase until capability evals pass at agreed k. +4. Assign **strictness tier** per eval (graduated promotion — e45s37): + + | Tier | Meaning | Promotion rule | + |------|---------|------------------| + | `EXPERIMENTAL` | New eval, may flake | Not gating | + | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite | + | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge | + + Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`. + +5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval. +6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only. ## Artefact diff --git a/skills/security-review/REFERENCE-false-positives.md b/skills/security-review/REFERENCE-false-positives.md index 5d8d72b7..3bbef4b9 100644 --- a/skills/security-review/REFERENCE-false-positives.md +++ b/skills/security-review/REFERENCE-false-positives.md @@ -19,14 +19,15 @@ Automatically exclude findings matching these patterns: | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic | | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners | | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees | -| 11 | **Unit test files only** | Not production risk | -| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | -| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable | -| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability | -| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln | -| 16 | **Regex DOS** | Excluded alongside general DOS | -| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | -| 18 | **Lack of audit logs** | Not a vulnerability | +| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) | +| 12 | **Unit test files only** | Not production risk | +| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln | +| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable | +| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability | +| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln | +| 17 | **Regex DOS** | Excluded alongside general DOS | +| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities | +| 19 | **Lack of audit logs** | Not a vulnerability | ## Precedent Rules diff --git a/skills/security-review/REFERENCE-vuln-categories.md b/skills/security-review/REFERENCE-vuln-categories.md index e1c9fee8..090fff11 100644 --- a/skills/security-review/REFERENCE-vuln-categories.md +++ b/skills/security-review/REFERENCE-vuln-categories.md @@ -7,6 +7,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` | +| **CWE** | CWE-89 (SQL Injection) | +| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) | | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` | | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` | | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). | @@ -16,6 +18,8 @@ Each category: vulnerable pattern → safe pattern → code example. | Aspect | Detail | |--------|--------| | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` | +| **CWE** | CWE-79 (Cross-site Scripting) | +| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) | | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping | | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) | | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). | diff --git a/skills/security-review/SKILL.md b/skills/security-review/SKILL.md index 7c439696..542651aa 100644 --- a/skills/security-review/SKILL.md +++ b/skills/security-review/SKILL.md @@ -1,3 +1,5 @@ +# story: e45s41 + --- name: security-review model: sonnet @@ -10,12 +12,24 @@ description: > the user says "security review" or "scan for vulns". --- +# story: e45s26 + # Security Review > **HARD GATE** — Requires git context (branch with merge-base or diff). Never > writes files outside `specs/security/`. Findings below confidence 8/10 are > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"` +## Parallel worktree mode (e45s18) + +When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index: + +```bash +bash scripts/lib/parallel-review-worktrees.sh security-review +``` + +Each check gets a detached worktree at `.bigpowers/worktrees/review-/`; reports still write only under `specs/security/`. + ## 5-phase scan | # | Phase | What | @@ -30,6 +44,37 @@ description: > Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi +## CWE mapping mandate (e45s26) + +Every **new detection rule** added to this skill MUST: + +1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79). +2. Ship **two fixture pairs** under `skills/security-review/fixtures/`: + - **Positive** — minimal code the rule MUST flag (vulnerable pattern present). + - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard). + +| Rule | CWE | Positive fixture | Negative fixture | +|------|-----|------------------|------------------| +| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` | +| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` | + +Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes. + +## SQL-safety doctrine (e45s41 — proven authorship) + +Formal rule for SQL injection classification: + +| SQL source | Attacker-reachable input? | Verdict | +|------------|---------------------------|---------| +| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship | +| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** | +| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi | +| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized | +| Stored procedure call with bound args | Args from trusted constants only | **Safe** | +| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** | + +**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not. + ## BCP Plus Integration This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern. diff --git a/skills/security-review/fixtures/CWE-79-xss-negative.js b/skills/security-review/fixtures/CWE-79-xss-negative.js new file mode 100644 index 00000000..70afd009 --- /dev/null +++ b/skills/security-review/fixtures/CWE-79-xss-negative.js @@ -0,0 +1,6 @@ +// story: e45s26 +// fixture: CWE-79 negative — MUST NOT be flagged (textContent auto-escapes) +function renderComment(el, userInput) { + // SAFE: text-only assignment — no HTML parsing + el.textContent = userInput; +} diff --git a/skills/security-review/fixtures/CWE-79-xss-positive.js b/skills/security-review/fixtures/CWE-79-xss-positive.js new file mode 100644 index 00000000..c9fb3daa --- /dev/null +++ b/skills/security-review/fixtures/CWE-79-xss-positive.js @@ -0,0 +1,6 @@ +// story: e45s26 +// fixture: CWE-79 positive — MUST be flagged as XSS +function renderComment(el, userInput) { + // VULNERABLE: unsanitized HTML assignment + el.innerHTML = userInput; +} diff --git a/skills/security-review/fixtures/CWE-89-sqli-negative.py b/skills/security-review/fixtures/CWE-89-sqli-negative.py new file mode 100644 index 00000000..eddef62b --- /dev/null +++ b/skills/security-review/fixtures/CWE-89-sqli-negative.py @@ -0,0 +1,8 @@ +# story: e45s26 +# fixture: CWE-89 negative — MUST NOT be flagged (parameterized query) +import sqlite3 + +def get_user(user_id: str) -> dict: + conn = sqlite3.connect("app.db") + # SAFE: bound parameter — proven authorship, no attacker-reachable interpolation + return conn.execute("SELECT * FROM users WHERE id = ?", (user_id,)).fetchone() diff --git a/skills/security-review/fixtures/CWE-89-sqli-positive.py b/skills/security-review/fixtures/CWE-89-sqli-positive.py new file mode 100644 index 00000000..b33426e2 --- /dev/null +++ b/skills/security-review/fixtures/CWE-89-sqli-positive.py @@ -0,0 +1,9 @@ +# story: e45s26 +# fixture: CWE-89 positive — MUST be flagged as SQL injection +import sqlite3 + +def get_user(user_id: str) -> dict: + conn = sqlite3.connect("app.db") + # VULNERABLE: user-controlled string interpolated into SQL + query = f"SELECT * FROM users WHERE id = {user_id}" + return conn.execute(query).fetchone() diff --git a/skills/seed-conventions/REFERENCE.md b/skills/seed-conventions/REFERENCE.md index 3c75d603..9c995e35 100644 --- a/skills/seed-conventions/REFERENCE.md +++ b/skills/seed-conventions/REFERENCE.md @@ -1,6 +1,46 @@ # story: e51s02 e37s01 e37s03 e37s14 +# story: e45s21 # Seed Conventions — Reference Templates +## Navigation + +| Lines | Section | +|-------|---------| +| 1–4 | Title + story tags | +| 6–22 | Navigation (this table) | +| 24–35 | AGENTS.md spine | +| 37–76 | Agent config template | +| 78–85 | opencode.json template | +| 87–96 | Aider bridge | +| 98–108 | Codex CLI wiring | +| 110–118 | CONVENTIONS.md | +| 120–122 | Stack profile fragments | +| 124–153 | Local tool wiring | + +## Fenced markers (e45s21) + +Self-installing blocks prevent skills from overwriting user-authored prose. Pattern: + +```markdown + +…managed content… + +``` + +**Merge algorithm:** + +1. If `BEGIN bigpowers:` exists → replace inner content only. +2. If missing → append new fenced block at EOF. +3. Never delete content outside fences. + +Seed these marker IDs in generated `AGENTS.md`: + +| ID | Initial content | +|----|-----------------| +| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules | +| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) | +| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists | + ## AGENTS.md spine (Reach Template — e37s01) Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template). diff --git a/skills/seed-conventions/SKILL.md b/skills/seed-conventions/SKILL.md index defde8c2..7dd7bfe2 100644 --- a/skills/seed-conventions/SKILL.md +++ b/skills/seed-conventions/SKILL.md @@ -1,4 +1,5 @@ # story: e51s02 +# story: e45s21 --- name: seed-conventions model: sonnet @@ -64,7 +65,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`). +### Self-installing fenced markers (e45s21) +Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered: + +```markdown + +…agent-managed content only… + +``` + +**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. + +**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): + +| Marker ID | Owner skill | Purpose | +|-----------|-------------|---------| +| `project` | seed-conventions | Project, Commands, Architecture | +| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table | +| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts | +| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills | + +Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred. - [ ] CLAUDE.md exists and is populated - [ ] CONVENTIONS.md exists and includes specs/ output convention diff --git a/skills/session-state/SKILL.md b/skills/session-state/SKILL.md index 3da4a378..3954fab7 100644 --- a/skills/session-state/SKILL.md +++ b/skills/session-state/SKILL.md @@ -5,6 +5,8 @@ effort: standard description: Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached. --- +# story: e45s23 + # Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. @@ -19,6 +21,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. +When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21. + ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: @@ -65,6 +69,7 @@ When starting a new session or after a significant context flush: Whenever a significant decision is made or a milestone is reached: - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash ` (or edit directly). +- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23). - [ ] Update `handoff.open_decisions` with rationale. - [ ] Update `epic_cycle` when advancing `ship-epic` steps. - [ ] Record open questions under `handoff.open_decisions` or an ADR. @@ -131,16 +136,6 @@ handoff: next_skill: survey-context ``` -## Tracking commit ratio - -After `release-branch` lands, compute fix-to-feature ratio via: -```bash -FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ') -FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ') -FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT))) -``` -Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`. - ## Anti-Patterns - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`. diff --git a/skills/slice-tasks/SKILL.md b/skills/slice-tasks/SKILL.md index c48e7558..5bd83a6e 100644 --- a/skills/slice-tasks/SKILL.md +++ b/skills/slice-tasks/SKILL.md @@ -5,6 +5,8 @@ model: sonnet effort: standard --- +# story: e45s29 + # Slice Tasks > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work. @@ -37,6 +39,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`) - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs + - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text. 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest. diff --git a/skills/smoke-test/REFERENCE.md b/skills/smoke-test/REFERENCE.md index 396fc2cf..08c86511 100644 --- a/skills/smoke-test/REFERENCE.md +++ b/skills/smoke-test/REFERENCE.md @@ -1,5 +1,16 @@ # Smoke Test — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–12 | Navigation | +| 14–31 | Runner script | +| 33–42 | Configuration reference | +| 44–53 | Verification | +| 55–160 | Reference blocks 1–5 | + ## Runner script A ready-to-use runner is provided for standalone operation: diff --git a/skills/stocktake-skills/SKILL.md b/skills/stocktake-skills/SKILL.md index 5c1c9747..d8ea4dcc 100644 --- a/skills/stocktake-skills/SKILL.md +++ b/skills/stocktake-skills/SKILL.md @@ -1,3 +1,4 @@ + --- name: stocktake-skills description: Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected. @@ -21,6 +22,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX ## Process +0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms). 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-.md` with findings table (skill, issue, severity). @@ -52,6 +54,6 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi ## Verify -→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING` +→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` See [REFERENCE.md](REFERENCE.md) for checklist. diff --git a/skills/validate-contracts/REFERENCE.md b/skills/validate-contracts/REFERENCE.md index 93dd2a5d..1c00858f 100644 --- a/skills/validate-contracts/REFERENCE.md +++ b/skills/validate-contracts/REFERENCE.md @@ -1,5 +1,17 @@ # Validate Contracts — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–24 | Integration | +| 26–35 | Configuration | +| 37–46 | Verification | +| 48–170 | Reference blocks + Examples 1–6 | +| 172–190 | Integration (duplicate) + Configuration + Verification | + ## Integration - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test. diff --git a/skills/validate-fix/SKILL.md b/skills/validate-fix/SKILL.md index 2787b9fe..c707af2f 100644 --- a/skills/validate-fix/SKILL.md +++ b/skills/validate-fix/SKILL.md @@ -1,3 +1,4 @@ +# story: e45s08 --- name: validate-fix model: haiku @@ -11,6 +12,8 @@ description: Prove a fix works before declaring done — re-run the failing test Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence. +> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(): …`), second commit applies the fix (`fix(): …`). Do not squash RED and GREEN before review. + ## Checklist ### 1. Re-run the originally failing test diff --git a/skills/verify-work/REFERENCE.md b/skills/verify-work/REFERENCE.md index 7a93f6fc..86f1ef86 100644 --- a/skills/verify-work/REFERENCE.md +++ b/skills/verify-work/REFERENCE.md @@ -21,3 +21,20 @@ sleep 3 && curl -sf http://localhost:/health || echo "BOOT FAIL" ``` Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work. + +## CLI mode + +For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`. + +**Auto-detect binary name:** +```bash +BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') # Cargo +BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) +BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') +``` + +**Checklist (replaces cold-start smoke):** +1. `$BINARY --help` → output contains "Usage" +2. `$BINARY --version` → matches manifest +3. README example command → non-empty output +4. `$BINARY --invalid-flag` → exit ≠ 0 with error message diff --git a/skills/verify-work/SKILL.md b/skills/verify-work/SKILL.md index 08f896f7..ee7e7231 100644 --- a/skills/verify-work/SKILL.md +++ b/skills/verify-work/SKILL.md @@ -1,4 +1,8 @@ + + + + --- name: verify-work @@ -47,12 +51,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch. 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command. 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3. + +> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block. + 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block. 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block. +5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only. + 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate. 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time. 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps. +7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`. +7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries. + ## Verify sub-operations ### Cold-Start Smoke (absorbed) @@ -95,6 +107,11 @@ phases: tests: passed: true coverage: "94.2%" + terminal_verdict: + command: "npm test" + exit_code: 0 + captured_at: "2026-06-11T14:25:00Z" + note: "Single run — do not merge output from other attempts" manual: steps: - step: "Open /login" @@ -116,26 +133,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`. - -**Auto-detect binary name:** -```bash -# Cargo.toml -BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}') -# package.json -BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null) -# Makefile -BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}') -``` - -**CLI verification checklist (replaces cold-start smoke):** - -1. `--help` smoke: `$BINARY --help` → assert output contains "Usage" -2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json) -3. Happy-path: run documented example command from README.md → assert non-empty output -4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed - -No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged. +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). ## Verify diff --git a/skills/wire-ci/REFERENCE.md b/skills/wire-ci/REFERENCE.md index df69dc78..e6b8fb1c 100644 --- a/skills/wire-ci/REFERENCE.md +++ b/skills/wire-ci/REFERENCE.md @@ -1,5 +1,16 @@ # Wire Ci — Reference +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 3–14 | Navigation | +| 16–38 | Examples | +| 40–52 | Options | +| 54–62 | Integration with build-epic | +| 64–270 | Reference blocks 1–8 | + ## Examples ### Create CI for a Rust project diff --git a/skills/write-document/REFERENCE.md b/skills/write-document/REFERENCE.md index db2a1a68..21750610 100644 --- a/skills/write-document/REFERENCE.md +++ b/skills/write-document/REFERENCE.md @@ -2,6 +2,16 @@ Combined from dbader/readme-template and jehna/readme-best-practices. No TOC. +## Navigation + +| Lines | Section | +|-------|---------| +| 1 | Title | +| 5–16 | Navigation | +| 18–24 | Sections intro | +| 26–178 | README section templates (1–15) | +| 180–183 | Verify | + ## Sections ### 1. Title + Badges diff --git a/specs/SKILL-SEARCH-INDEX_LATEST.md b/specs/SKILL-SEARCH-INDEX_LATEST.md index b58cb787..84844d52 100644 --- a/specs/SKILL-SEARCH-INDEX_LATEST.md +++ b/specs/SKILL-SEARCH-INDEX_LATEST.md @@ -12,6 +12,7 @@ Regenerate: `bash scripts/build-skill-index.sh` | change-request | sonnet | Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic capsule directories. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs pri | | commit-message | haiku | Reviews working-tree changes, then drafts a Conventional Commits title/body and states the semantic-release version bump a single such commit would imply. Also notes which defensive-code categories we | | compose-workflow | sonnet | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. Use when a project repeats a non-standard skill sequence, or user wants a documented playbook beyond orchestrate-project | +| context7-mcp | haiku | Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc. | | craft-skill | sonnet | Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle. | | deepen-architecture | sonnet | Find deepening opportunities in a codebase, informed by the domain language in specs/tech-architecture/tech-stack.md and the decisions in specs/adr/. Use when the user wants to improve architecture, f | | define-language | sonnet | Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE_LATEST.md. Use when user wants to | @@ -21,6 +22,7 @@ Regenerate: `bash scripts/build-skill-index.sh` | design-interface | opus | Generate multiple radically different interface designs for a module using parallel sub-agents, then compare trade-offs. Based on "Design It Twice" from A Philosophy of Software Design. Use when user | | develop-tdd | sonnet | Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md). | | diagnose-root | sonnet | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use when a bug is confirmed but root cause is unclear, after investigate-bug, or when user mentions root cause analysis. | +| diagnose-stall | haiku | Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never | | dispatch-agents | sonnet | Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concu | | edit-document | sonnet | Edit and improve documents by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, restructure, or improve any document — including specs/ files, art | | elaborate-spec | opus | Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn "I | diff --git a/specs/TRACEABILITY_LATEST.md b/specs/TRACEABILITY_LATEST.md index 0caec15f..0ea25140 100644 --- a/specs/TRACEABILITY_LATEST.md +++ b/specs/TRACEABILITY_LATEST.md @@ -1,69 +1,69 @@ # Traceability Matrix -**Generated:** 2026-07-06 21:34:48 UTC +**Generated:** 2026-07-07 03:20:35 UTC **Total stories:** 55 -**Tagged stories:** 7 -**Dark stories:** 11 -**Orphan tags:** 77 +**Tagged stories:** 44 +**Dark stories:** 2 +**Orphan tags:** 79 **Stale tags:** 0 ## Oracle Stats -- **High** (explicit tag): 14 -- **Medium** (file heuristic): 1296 +- **High** (explicit tag): 136 +- **Medium** (file heuristic): 1390 - **Low** (task reference): 2 ## Story Coverage | Story | Title | Epic | BCP | WSJF | Status | Links | |-------|-------|------|-----|------|--------|-------| -| e45s01 | run-benchmark: add train/validation-split + with/without-ski | e45 | 3 | 5.0 | todo | 10 | -| e45s02 | craft-skill: CSO description discipline + completion-honesty | e45 | 2 | 5.0 | todo | 9 | -| e45s03 | CLAUDE.md token mgmt: mechanical PreToolUse hook backstop | e45 | 3 | 5.0 | todo | 3 | -| e45s04 | slice-tasks / plan-work: pre-build cross-artifact consistenc | e45 | 3 | 5.0 | todo | 13 | -| e45s05 | verify-work / gate-trace: adversarial gap-finding completene | e45 | 4 | 5.0 | todo | 20 | -| e45s06 | tasks.yaml: literal failing→passing task ledger | e45 | 2 | 5.0 | todo | 0 | -| e45s07 | request-review: dual-blind AND-gate review (Santa Method) | e45 | 2 | 5.0 | todo | 27 | -| e45s08 | develop-tdd / validate-fix: two-commit red/green regression | e45 | 2 | 5.0 | todo | 9 | -| e45s09 | verify-work / plan-work: Pre-Implementation and Validation g | e45 | 2 | 5.0 | todo | 60 | -| e45s10 | docs/references: auto-regenerate from source-of-truth docs v | e45 | 2 | 5.0 | todo | 1 | -| e45s11 | orchestration / dispatch-agents: typed message protocol + 3- | e45 | 2 | 5.0 | todo | 4 | -| e45s12 | stocktake-skills / craft-skill: code-enforced validator + au | e45 | 2 | 5.0 | todo | 26 | -| e45s13 | verify-work: one-test-minimum terminal-verdict rule | e45 | 2 | 5.0 | todo | 10 | -| e45s14 | deepen-architecture: declared import-boundary allowlist enfo | e45 | 2 | 5.0 | todo | 5 | -| e45s15 | release-branch / deploy: three-independent-facts verificatio | e45 | 2 | 5.0 | todo | 7 | -| e45s16 | CLAUDE.md rtk mandate: wire rtk-ai/rtk PreToolUse hook | e45 | 2 | 5.0 | todo | 1 | -| e45s17 | request-review: fan-out to parallel review subagents | e45 | 2 | 5.0 | todo | 20 | -| e45s18 | audit-code / security-review: worktree-isolated parallel che | e45 | 2 | 5.0 | todo | 340 | -| e45s19 | Context7: bounded retry cap and explicit fallback block | e45 | 2 | 5.0 | todo | 6 | -| e45s20 | Context7 / bts docs: wrap in ETag-revalidated fetch cache | e45 | 2 | 5.0 | todo | 0 | -| e45s21 | seed-conventions / AGENTS.md: self-installing fenced markers | e45 | 2 | 5.0 | todo | 4 | -| e45s22 | CLAUDE.md: context-aware directory routing | e45 | 2 | 5.0 | todo | 1 | -| e45s23 | CLAUDE.md: live Learned User Preferences / Workspace Facts | e45 | 2 | 5.0 | todo | 0 | +| e45s01 | run-benchmark: add train/validation-split + with/without-ski | e45 | 3 | 5.0 | todo | 15 | +| e45s02 | craft-skill: CSO description discipline + completion-honesty | e45 | 2 | 5.0 | todo | 14 | +| e45s03 | CLAUDE.md token mgmt: mechanical PreToolUse hook backstop | e45 | 3 | 5.0 | todo | 4 | +| e45s04 | slice-tasks / plan-work: pre-build cross-artifact consistenc | e45 | 3 | 5.0 | todo | 15 | +| e45s05 | verify-work / gate-trace: adversarial gap-finding completene | e45 | 4 | 5.0 | todo | 23 | +| e45s06 | tasks.yaml: literal failing→passing task ledger | e45 | 2 | 5.0 | todo | 2 | +| e45s07 | request-review: dual-blind AND-gate review (Santa Method) | e45 | 2 | 5.0 | todo | 30 | +| e45s08 | develop-tdd / validate-fix: two-commit red/green regression | e45 | 2 | 5.0 | todo | 11 | +| e45s09 | verify-work / plan-work: Pre-Implementation and Validation g | e45 | 2 | 5.0 | todo | 63 | +| e45s10 | docs/references: auto-regenerate from source-of-truth docs v | e45 | 2 | 5.0 | todo | 6 | +| e45s11 | orchestration / dispatch-agents: typed message protocol + 3- | e45 | 2 | 5.0 | todo | 5 | +| e45s12 | stocktake-skills / craft-skill: code-enforced validator + au | e45 | 2 | 5.0 | todo | 29 | +| e45s13 | verify-work: one-test-minimum terminal-verdict rule | e45 | 2 | 5.0 | todo | 11 | +| e45s14 | deepen-architecture: declared import-boundary allowlist enfo | e45 | 2 | 5.0 | todo | 7 | +| e45s15 | release-branch / deploy: three-independent-facts verificatio | e45 | 2 | 5.0 | todo | 9 | +| e45s16 | CLAUDE.md rtk mandate: wire rtk-ai/rtk PreToolUse hook | e45 | 2 | 5.0 | todo | 4 | +| e45s17 | request-review: fan-out to parallel review subagents | e45 | 2 | 5.0 | todo | 22 | +| e45s18 | audit-code / security-review: worktree-isolated parallel che | e45 | 2 | 5.0 | todo | 382 | +| e45s19 | Context7: bounded retry cap and explicit fallback block | e45 | 2 | 5.0 | todo | 7 | +| e45s20 | Context7 / bts docs: wrap in ETag-revalidated fetch cache | e45 | 2 | 5.0 | todo | 1 | +| e45s21 | seed-conventions / AGENTS.md: self-installing fenced markers | e45 | 2 | 5.0 | todo | 11 | +| e45s22 | CLAUDE.md: context-aware directory routing | e45 | 2 | 5.0 | todo | 2 | +| e45s23 | CLAUDE.md: live Learned User Preferences / Workspace Facts | e45 | 2 | 5.0 | todo | 6 | | e45s24 | REFERENCE.md files: embedded line-range navigation guides | e45 | 2 | 5.0 | todo | 2 | -| e45s25 | CONVENTIONS.md risk tiers: compile to versioned, diffable ru | e45 | 4 | 5.0 | todo | 1 | -| e45s26 | security-review: CWE mapping + 2 positive/2 negative fixture | e45 | 2 | 5.0 | todo | 4 | -| e45s27 | loop / workflow: terminal-state taxonomy | e45 | 2 | 5.0 | todo | 0 | -| e45s28 | request-review: hard max-iteration cap | e45 | 2 | 5.0 | todo | 5 | -| e45s29 | requirements: ADDED/MODIFIED/REMOVED/RENAMED tags | e45 | 2 | 5.0 | todo | 0 | -| e45s30 | subagent depth: formalize depth tiers | e45 | 2 | 5.0 | todo | 0 | -| e45s31 | audit-code / deepen-architecture: churn-based look-here-firs | e45 | 2 | 5.0 | todo | 342 | -| e45s32 | gate-trace / release-branch: adversarial-review refute frami | e45 | 2 | 5.0 | todo | 19 | -| e45s33 | requirements: per-section approval state | e45 | 2 | 5.0 | todo | 0 | -| e45s34 | develop-tdd: snapshot-before-transition hardening | e45 | 2 | 5.0 | todo | 5 | -| e45s35 | plan-work: 5 fixed EARS sentence patterns | e45 | 2 | 5.0 | todo | 5 | -| e45s36 | specs: Documentation Responsibilities table | e45 | 2 | 5.0 | todo | 0 | -| e45s37 | run-evals: graduated eval-strictness tiers | e45 | 2 | 5.0 | todo | 7 | -| e45s38 | orchestration: why-did-this-stall diagnostic skill | e45 | 2 | 5.0 | todo | 2 | -| e45s39 | PR generation: literal provenance marker | e45 | 2 | 5.0 | todo | 0 | -| e45s40 | verify-work: mandatory real-browser verification | e45 | 2 | 5.0 | todo | 10 | -| e45s41 | security-review: proven authorship SQL-safety doctrine | e45 | 2 | 5.0 | todo | 4 | +| e45s25 | CONVENTIONS.md risk tiers: compile to versioned, diffable ru | e45 | 4 | 5.0 | todo | 4 | +| e45s26 | security-review: CWE mapping + 2 positive/2 negative fixture | e45 | 2 | 5.0 | todo | 13 | +| e45s27 | loop / workflow: terminal-state taxonomy | e45 | 2 | 5.0 | todo | 5 | +| e45s28 | request-review: hard max-iteration cap | e45 | 2 | 5.0 | todo | 10 | +| e45s29 | requirements: ADDED/MODIFIED/REMOVED/RENAMED tags | e45 | 2 | 5.0 | todo | 15 | +| e45s30 | subagent depth: formalize depth tiers | e45 | 2 | 5.0 | todo | 10 | +| e45s31 | audit-code / deepen-architecture: churn-based look-here-firs | e45 | 2 | 5.0 | todo | 384 | +| e45s32 | gate-trace / release-branch: adversarial-review refute frami | e45 | 2 | 5.0 | todo | 21 | +| e45s33 | requirements: per-section approval state | e45 | 2 | 5.0 | todo | 2 | +| e45s34 | develop-tdd: snapshot-before-transition hardening | e45 | 2 | 5.0 | todo | 6 | +| e45s35 | plan-work: 5 fixed EARS sentence patterns | e45 | 2 | 5.0 | todo | 6 | +| e45s36 | specs: Documentation Responsibilities table | e45 | 2 | 5.0 | todo | 1 | +| e45s37 | run-evals: graduated eval-strictness tiers | e45 | 2 | 5.0 | todo | 8 | +| e45s38 | orchestration: why-did-this-stall diagnostic skill | e45 | 2 | 5.0 | todo | 4 | +| e45s39 | PR generation: literal provenance marker | e45 | 2 | 5.0 | todo | 1 | +| e45s40 | verify-work: mandatory real-browser verification | e45 | 2 | 5.0 | todo | 11 | +| e45s41 | security-review: proven authorship SQL-safety doctrine | e45 | 2 | 5.0 | todo | 5 | | e48s01 | Generate epics-wiki and adr-wiki as OKF concept bundles from | e48 | 2 | 2.5 | todo | 23 | -| e48s02 | Emit verification reports as OKF bundles from run-golden-sui | e48 | 2 | 2.5 | todo | 23 | -| e48s03 | OKF-ify bug-registry: specs/bugs/registry.yaml emits concept | e48 | 1 | 2.5 | todo | 96 | +| e48s02 | Emit verification reports as OKF bundles from run-golden-sui | e48 | 2 | 2.5 | todo | 27 | +| e48s03 | OKF-ify bug-registry: specs/bugs/registry.yaml emits concept | e48 | 1 | 2.5 | todo | 97 | | e48s04 | Create viz.html — interactive force-layout graph companion f | e48 | 2 | 2.5 | todo | 11 | -| e48s05 | Wire OKF validation into CI (sync-skills.yml) and document i | e48 | 1 | 2.5 | todo | 93 | -| e48s06 | Add tier: field (core/extended/specialized) to OKF wiki inde | e48 | 2 | 2.5 | todo | 8 | +| e48s05 | Wire OKF validation into CI (sync-skills.yml) and document i | e48 | 1 | 2.5 | todo | 98 | +| e48s06 | Add tier: field (core/extended/specialized) to OKF wiki inde | e48 | 2 | 2.5 | todo | 9 | | e48s07 | Create publish-to-wiki kernel tool | e48 | 3 | 2.5 | todo | 0 | | e48s08 | Add GitHub Action Template for publish-wiki.yml | e48 | 1 | 2.5 | todo | 0 | | e48s09 | Create Wiki Scaffold Templates and provenance header injecti | e48 | 2 | 2.5 | todo | 2 | @@ -75,15 +75,6 @@ ## Dark Stories (no code links) -- **e45s06**: tasks.yaml: literal failing→passing task ledger (status: todo) -- **e45s20**: Context7 / bts docs: wrap in ETag-revalidated fetch cache (status: todo) -- **e45s23**: CLAUDE.md: live Learned User Preferences / Workspace Facts (status: todo) -- **e45s27**: loop / workflow: terminal-state taxonomy (status: todo) -- **e45s29**: requirements: ADDED/MODIFIED/REMOVED/RENAMED tags (status: todo) -- **e45s30**: subagent depth: formalize depth tiers (status: todo) -- **e45s33**: requirements: per-section approval state (status: todo) -- **e45s36**: specs: Documentation Responsibilities table (status: todo) -- **e45s39**: PR generation: literal provenance marker (status: todo) - **e48s07**: Create publish-to-wiki kernel tool (status: todo) - **e48s08**: Add GitHub Action Template for publish-wiki.yml (status: todo) @@ -99,6 +90,7 @@ - `e30s01` - `e30s02` - `e30s03` +- `e31s04` - `e32s01` - `e32s02` - `e32s03` @@ -151,6 +143,7 @@ - `e41s01` - `e42s02` - `e42s03` +- `e42s04` - `e43s01` - `e44s01` - `e44s02` diff --git a/specs/agent-guide/context-routing.md b/specs/agent-guide/context-routing.md new file mode 100644 index 00000000..7b82c954 --- /dev/null +++ b/specs/agent-guide/context-routing.md @@ -0,0 +1,18 @@ +--- +type: Guide +title: Context Routing +context: guide +source: CLAUDE.md#context-routing +--- + +# Context Routing + +Load subdirectory context **by file glob** — do not read the full doc tree up front. + +| Glob / trigger | Load first | Fallback | +|----------------|------------|----------| +| `skills/**` | Active skill + +> Full content: /Users/danielvm/Developer/bigpowers/CLAUDE.md section "Context Routing" +--- +*Auto-generated by scripts/generate-agent-guide.sh* diff --git a/specs/agent-guide/index.md b/specs/agent-guide/index.md index fe085457..7351cdf1 100644 --- a/specs/agent-guide/index.md +++ b/specs/agent-guide/index.md @@ -11,6 +11,9 @@ context: guide ## Guide Sections +- [Context Routing](context-routing.md) +- [Learned User Preferences](learned-user-preferences.md) +- [Workspace Facts](workspace-facts.md) - [Project](project.md) - [Commands](commands.md) - [Pre-Merge Checklist](pre-merge-checklist.md) diff --git a/specs/agent-guide/learned-user-preferences.md b/specs/agent-guide/learned-user-preferences.md new file mode 100644 index 00000000..bb08a770 --- /dev/null +++ b/specs/agent-guide/learned-user-preferences.md @@ -0,0 +1,17 @@ +--- +type: Guide +title: Learned User Preferences +context: guide +source: CLAUDE.md#learned-user-preferences +--- + +# Learned User Preferences + +_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._ + +- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings). +- + +> Full content: /Users/danielvm/Developer/bigpowers/CLAUDE.md section "Learned User Preferences" +--- +*Auto-generated by scripts/generate-agent-guide.sh* diff --git a/specs/agent-guide/token-management.md b/specs/agent-guide/token-management.md index a96ae6a2..bfb5756c 100644 --- a/specs/agent-guide/token-management.md +++ b/specs/agent-guide/token-management.md @@ -7,9 +7,7 @@ source: CLAUDE.md#token-management # Token Management -Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`): - -- **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless +**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (along > Full content: /Users/danielvm/Developer/bigpowers/CLAUDE.md section "Token Management" --- diff --git a/specs/agent-guide/workspace-facts.md b/specs/agent-guide/workspace-facts.md new file mode 100644 index 00000000..78bc6605 --- /dev/null +++ b/specs/agent-guide/workspace-facts.md @@ -0,0 +1,17 @@ +--- +type: Guide +title: Workspace Facts +context: guide +source: CLAUDE.md#workspace-facts +--- + +# Workspace Facts + +_Stable repo facts — prefer these over re-discovery._ + +- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`. +- Planning SoT: `specs/state.yaml`, `specs/release + +> Full content: /Users/danielvm/Developer/bigpowers/CLAUDE.md section "Workspace Facts" +--- +*Auto-generated by scripts/generate-agent-guide.sh* diff --git a/specs/benchmarks/reports/BENCHMARK-survey-context-2026-07-06.yaml b/specs/benchmarks/reports/BENCHMARK-survey-context-2026-07-06.yaml new file mode 100644 index 00000000..a1fb07db --- /dev/null +++ b/specs/benchmarks/reports/BENCHMARK-survey-context-2026-07-06.yaml @@ -0,0 +1,26 @@ +run_date: '2026-07-06' +runs_per_scenario: 3 +scenarios: +- delta: 1.0 + id: s01 + split: validation + weight: 1.0 + with_pass_rate: 1.0 + without_pass_rate: 0.0 +- id: s02 + split: train + status: pending_agent_eval + weight: 1.0 +- id: s03 + split: validation + status: pending_agent_eval + weight: 0.5 +skill: survey-context +train: + delta: 0.0 + pass_at_k_with: 0.0 + pass_at_k_without: 0.0 +validation: + delta: 1.0 + pass_at_k_with: 1.0 + pass_at_k_without: 0.0 diff --git a/specs/benchmarks/reports/GOLDEN-2026-07-06.yaml b/specs/benchmarks/reports/GOLDEN-2026-07-06.yaml index 1242c86e..eefb4857 100644 --- a/specs/benchmarks/reports/GOLDEN-2026-07-06.yaml +++ b/specs/benchmarks/reports/GOLDEN-2026-07-06.yaml @@ -1,5 +1,5 @@ -timestamp: "2026-07-07T02:47:03Z" -git_commit: "0404520dbe5633b409f5a6dcf59c344a4d9f376b" +timestamp: "2026-07-07T02:55:04Z" +git_commit: "01aeb0f7251a5866bcb059175e3c98b678b857f9" suite: "golden-combined" mode: "daily" deterministic: @@ -11,39 +11,39 @@ deterministic: gates: - name: compliance exit_code: 0 - duration_seconds: 44.74 + duration_seconds: 38.65 status: pass - name: g04-selftest exit_code: 0 - duration_seconds: .08 + duration_seconds: .03 status: pass - name: g06-migrate-version exit_code: 0 - duration_seconds: 7.75 + duration_seconds: 6.43 status: pass - name: g07-negative-path exit_code: 0 - duration_seconds: .05 + duration_seconds: .06 status: pass - name: g08-anti-vacuity exit_code: 0 - duration_seconds: .07 + duration_seconds: .13 status: pass - name: g09-yaml-roundtrip exit_code: 0 - duration_seconds: .10 + duration_seconds: .12 status: pass - name: g10-trace-anti-vacuity exit_code: 0 - duration_seconds: .09 + duration_seconds: .12 status: pass - name: g11-gitignore-venv exit_code: 0 - duration_seconds: .06 + duration_seconds: .07 status: pass - name: specs-parse exit_code: 0 - duration_seconds: .52 + duration_seconds: .58 status: pass agent_stories: total: 0 diff --git a/specs/benchmarks/reports/GOLDEN-2026-07-07.yaml b/specs/benchmarks/reports/GOLDEN-2026-07-07.yaml new file mode 100644 index 00000000..5aba6bbd --- /dev/null +++ b/specs/benchmarks/reports/GOLDEN-2026-07-07.yaml @@ -0,0 +1,64 @@ +timestamp: "2026-07-07T03:19:18Z" +git_commit: "01aeb0f7251a5866bcb059175e3c98b678b857f9" +suite: "golden-combined" +mode: "daily" +deterministic: + total: 11 + passed: 11 + failed: 0 + skipped: 0 + pass_rate: 1.00 +gates: + - name: compliance + exit_code: 0 + duration_seconds: 37.49 + status: pass + - name: g04-selftest + exit_code: 0 + duration_seconds: .04 + status: pass + - name: g06-migrate-version + exit_code: 0 + duration_seconds: 6.04 + status: pass + - name: g07-negative-path + exit_code: 0 + duration_seconds: .06 + status: pass + - name: g08-anti-vacuity + exit_code: 0 + duration_seconds: .08 + status: pass + - name: g09-yaml-roundtrip + exit_code: 0 + duration_seconds: .10 + status: pass + - name: g10-trace-anti-vacuity + exit_code: 0 + duration_seconds: .12 + status: pass + - name: g11-gitignore-venv + exit_code: 0 + duration_seconds: .06 + status: pass + - name: import-boundaries + exit_code: 0 + duration_seconds: .24 + status: pass + - name: skill-catalog + exit_code: 0 + duration_seconds: 1.66 + status: pass + - name: specs-parse + exit_code: 0 + duration_seconds: .51 + status: pass +agent_stories: + total: 0 + passed: 0 + failed: 0 + skipped: 0 + flake_count: 0 + pass_rate: n/a +summary: + combined_verdict: "pass" diff --git a/specs/benchmarks/reports/benchmark-survey-context.json b/specs/benchmarks/reports/benchmark-survey-context.json new file mode 100644 index 00000000..d3fcd095 --- /dev/null +++ b/specs/benchmarks/reports/benchmark-survey-context.json @@ -0,0 +1 @@ +{"skill":"survey-context","run_date":"2026-07-06","runs_per_scenario":3,"train":{"with_skill":0.0,"without_skill":0.0,"delta":0.0,"scenarios":["s02"]},"validation":{"with_skill":1.0,"without_skill":0.0,"delta":1.0,"scenarios":["s01","s03"]},"scenarios":[{"id":"s01","split":"validation","with_pass_rate":1.0,"without_pass_rate":0.0,"delta":1.0,"weight":1.0},{"id":"s02","split":"train","status":"pending_agent_eval","weight":1.0},{"id":"s03","split":"validation","status":"pending_agent_eval","weight":0.5}]} \ No newline at end of file diff --git a/specs/blind-spots.json b/specs/blind-spots.json index 3f34326a..eca22ddb 100644 --- a/specs/blind-spots.json +++ b/specs/blind-spots.json @@ -1,10 +1,10 @@ { - "generated_at": "2026-07-06T21:35:21.609321+00:00", + "generated_at": "2026-07-07T03:05:10.634490+00:00", "version": "1.0", "summary": { - "total_findings": 483, + "total_findings": 526, "high": 0, - "medium": 483, + "medium": 526, "low": 0 }, "findings": [ @@ -29,6 +29,20 @@ "description": "File 'specs/verifications/steps/and-each-core-skill-should-prove-a-positive-with-skill-versus-without-skill-eval-delta.sh' is tagged with multiple stories: e45s01, e48s10", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "scripts/lib/audit-compliance-runner.sh", + "severity": "MEDIUM", + "description": "File 'scripts/lib/audit-compliance-runner.sh' is tagged with multiple stories: e45s02, e48s02", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "skills/craft-skill/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/craft-skill/SKILL.md' is tagged with multiple stories: e45s02, e45s12", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/skills-wiki/skills/craft-skill.md", @@ -92,6 +106,13 @@ "description": "File 'specs/bugs/BUG-2026-07-06T205700-sync-strict-todo-p0-block.md' is tagged with multiple stories: e45s03, e48s03", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "skills/plan-work/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/plan-work/SKILL.md' is tagged with multiple stories: e45s04, e45s06, e45s09, e45s33, e45s35", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/skills-wiki/skills/plan-work.md", @@ -141,6 +162,20 @@ "description": "File '.kilocode/rules/plan-work.md' is tagged with multiple stories: e45s04, e45s09, e45s35", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "skills/verify-work/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/verify-work/SKILL.md' is tagged with multiple stories: e45s05, e45s09, e45s40", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "skills/gate-trace/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/gate-trace/SKILL.md' is tagged with multiple stories: e45s05, e45s32", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/skills-wiki/skills/gate-trace.md", @@ -274,6 +309,20 @@ "description": "File '.kilocode/rules/verify-work.md' is tagged with multiple stories: e45s05, e45s09, e45s13, e45s40", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "skills/develop-tdd/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/develop-tdd/SKILL.md' is tagged with multiple stories: e45s06, e45s08, e45s34", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "skills/request-review/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/request-review/SKILL.md' is tagged with multiple stories: e45s07, e45s28", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/DEEPEN-ARCHITECTURE-REVIEW.md", @@ -526,6 +575,13 @@ "description": "File 'scripts/sync-status-from-epics.sh' is tagged with multiple stories: e45s10, e48s01", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "skills/dispatch-agents/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/dispatch-agents/SKILL.md' is tagged with multiple stories: e45s11, e45s38", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/epics/e39-knowledge-graph/e39s04-okf-skills-wiki.md", @@ -687,6 +743,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260706-181947.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-212931.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-212931.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260703-160106.md", @@ -715,6 +778,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260704-143153.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-215320.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-215320.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-172717.md", @@ -729,6 +799,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260706-174039.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-212830.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-212830.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260705-182718.md", @@ -757,6 +834,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-122420.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-183547.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-183547.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260626-205129.md", @@ -813,6 +897,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260702-223301.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-214411.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-214411.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260622-001710.md", @@ -897,6 +988,27 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-163108.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-185319.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-185319.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-183644.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-183644.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-215759.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-215759.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260629-132810.md", @@ -918,6 +1030,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-164718.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-202226.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-202226.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260705-164609.md", @@ -1023,6 +1142,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260626-205844.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-205711.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-205711.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-182236.md", @@ -1030,6 +1156,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260706-182236.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-213042.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-213042.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260702-223023.md", @@ -1163,6 +1296,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-125910.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-215656.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-215656.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260704-143757.md", @@ -1282,6 +1422,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-181759.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-184319.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-184319.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-174351.md", @@ -1345,6 +1492,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-234357.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-235505.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-235505.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260703-220905.md", @@ -1513,6 +1667,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260704-091141.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-184856.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-184856.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260702-154339.md", @@ -1548,6 +1709,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-194130.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-213831.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-213831.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-174245.md", @@ -1716,6 +1884,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260706-173917.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-185210.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-185210.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260705-165256.md", @@ -1765,6 +1940,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-233707.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-212919.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-212919.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260703-163256.md", @@ -2185,6 +2367,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-005358.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-220404.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-220404.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260704-085740.md", @@ -2262,6 +2451,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-142902.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-214125.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-214125.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-132604.md", @@ -2437,6 +2633,27 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260706-163657.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-215213.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-215213.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-204345.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-204345.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-212711.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-212711.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260703-153739.md", @@ -2563,6 +2780,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260704-004226.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-212552.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-212552.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-181706.md", @@ -2591,6 +2815,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-163956.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-204300.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-204300.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260705-164141.md", @@ -2675,6 +2906,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-172525.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-184658.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-184658.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260705-194009.md", @@ -2724,6 +2962,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260703-142458.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-235409.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-235409.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260702-195845.md", @@ -2801,6 +3046,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260621-231038.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-184355.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-184355.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260706-172751.md", @@ -2850,6 +3102,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-175152.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-234704.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-234704.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260703-163238.md", @@ -2864,6 +3123,13 @@ "description": "File 'specs/verifications/reports/audit-cleancode-20260705-180948.md' is tagged with multiple stories: e45s18, e45s31", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "specs/verifications/reports/audit-cleancode-20260706-214329.md", + "severity": "MEDIUM", + "description": "File 'specs/verifications/reports/audit-cleancode-20260706-214329.md' is tagged with multiple stories: e45s18, e45s31", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/reports/audit-cleancode-20260704-144506.md", @@ -2969,6 +3235,13 @@ "description": "File 'specs/epics/archive/e36-doc-dedup/e36s04-sdd-tool-landscape.md' is tagged with multiple stories: e45s19, e48s11", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "CLAUDE.md", + "severity": "MEDIUM", + "description": "File 'CLAUDE.md' is tagged with multiple stories: e45s22, e45s23", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/verifications/steps/and-files-should-be-small-enough-to-avoid-context-window-truncation-300-lines.sh", @@ -2976,6 +3249,27 @@ "description": "File 'specs/verifications/steps/and-files-should-be-small-enough-to-avoid-context-window-truncation-300-lines.sh' is tagged with multiple stories: e45s24, e48s02", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "CONVENTIONS.md", + "severity": "MEDIUM", + "description": "File 'CONVENTIONS.md' is tagged with multiple stories: e45s25, e45s36", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "skills/security-review/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/security-review/SKILL.md' is tagged with multiple stories: e45s26, e45s41", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, + { + "check": "double-tag", + "file": "skills/release-branch/SKILL.md", + "severity": "MEDIUM", + "description": "File 'skills/release-branch/SKILL.md' is tagged with multiple stories: e45s32, e45s39", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/bugs/BUG-2026-07-06-run-evals-golden-suite-oversized.md", @@ -3347,6 +3641,13 @@ "description": "File 'specs/epics/e39-knowledge-graph/e39s06-okf-agent-guide.md' is tagged with multiple stories: e48s05, e48s06", "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." }, + { + "check": "double-tag", + "file": "scripts/okf-add-references.py", + "severity": "MEDIUM", + "description": "File 'scripts/okf-add-references.py' is tagged with multiple stories: e48s05, e48s06", + "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable." + }, { "check": "double-tag", "file": "specs/epics/e48-foundation/e48s12-bcp-plus-s02.md", diff --git a/specs/codebase-wiki/e45s01.md b/specs/codebase-wiki/e45s01.md index 88f60372..d0570fe6 100644 --- a/specs/codebase-wiki/e45s01.md +++ b/specs/codebase-wiki/e45s01.md @@ -8,14 +8,34 @@ implementation_status: todo coverage_status: covered confidence: high links: + - file: specs/state.yaml + line: 3 + confidence: high + method: explicit_tag + - file: specs/state.yaml + line: 14 + confidence: high + method: explicit_tag + - file: scripts/run-benchmark.sh + line: 2 + confidence: high + method: explicit_tag - file: scripts/generate-adr-wiki.sh line: 2 confidence: high method: explicit_tag + - file: scripts/lib/run-benchmark.py + line: 2 + confidence: high + method: explicit_tag - file: scripts/generate-epics-wiki.sh line: 2 confidence: high method: explicit_tag + - file: skills/run-benchmark/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/run-benchmark.md line: 0 confidence: medium @@ -58,8 +78,13 @@ links: ## Implemented In +- `specs/state.yaml` (line 3, confidence: high, method: explicit_tag) +- `specs/state.yaml` (line 14, confidence: high, method: explicit_tag) +- `scripts/run-benchmark.sh` (line 2, confidence: high, method: explicit_tag) - `scripts/generate-adr-wiki.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/lib/run-benchmark.py` (line 2, confidence: high, method: explicit_tag) - `scripts/generate-epics-wiki.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/run-benchmark/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/run-benchmark.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-each-core-skill-should-prove-a-positive-with-skill-versus-without-skill-eval-delta.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/archive/e22-skill-catalog-ci-gate/e22s01-run-skill-verify.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s02.md b/specs/codebase-wiki/e45s02.md index 6c96962e..4c3f3710 100644 --- a/specs/codebase-wiki/e45s02.md +++ b/specs/codebase-wiki/e45s02.md @@ -6,8 +6,28 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/lib/audit-compliance-judge.sh + line: 2 + confidence: high + method: explicit_tag + - file: scripts/lib/audit-compliance-runner.sh + line: 2 + confidence: high + method: explicit_tag + - file: scripts/lib/audit-compliance-report.sh + line: 2 + confidence: high + method: explicit_tag + - file: scripts/validate-skill-description.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/craft-skill/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/craft-skill.md line: 0 confidence: medium @@ -54,6 +74,11 @@ links: ## Implemented In +- `scripts/lib/audit-compliance-judge.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/lib/audit-compliance-runner.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/lib/audit-compliance-report.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/validate-skill-description.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/craft-skill/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/craft-skill.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/then-skills-should-include-bold-hard-gate-callout-blocks.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-craft-skill-sync-oversized.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s03.md b/specs/codebase-wiki/e45s03.md index 314d7077..d2a4cebd 100644 --- a/specs/codebase-wiki/e45s03.md +++ b/specs/codebase-wiki/e45s03.md @@ -20,6 +20,10 @@ links: line: 80 confidence: high method: explicit_tag + - file: scripts/hooks/token-mgmt-pre-tool-use.sh + line: 2 + confidence: high + method: explicit_tag --- # e45s03: CLAUDE.md token mgmt: mechanical PreToolUse hook backstop @@ -33,3 +37,4 @@ links: - `specs/bugs/BUG-2026-07-06T205700-sync-strict-todo-p0-block.md` (line 49, confidence: high, method: explicit_tag) - `specs/bugs/BUG-2026-07-06T205700-sync-strict-todo-p0-block.md` (line 65, confidence: high, method: explicit_tag) - `specs/bugs/BUG-2026-07-06T205700-sync-strict-todo-p0-block.md` (line 80, confidence: high, method: explicit_tag) +- `scripts/hooks/token-mgmt-pre-tool-use.sh` (line 2, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s04.md b/specs/codebase-wiki/e45s04.md index 8ba1a087..929b28cd 100644 --- a/specs/codebase-wiki/e45s04.md +++ b/specs/codebase-wiki/e45s04.md @@ -12,6 +12,14 @@ links: line: 2 confidence: high method: explicit_tag + - file: scripts/lib/plan-consistency-check.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/plan-work/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/slice-tasks.md line: 0 confidence: medium @@ -71,6 +79,8 @@ links: ## Implemented In - `scripts/generate-viz-graph.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/lib/plan-consistency-check.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/plan-work/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/slice-tasks.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/plan-work.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/given-a-sliced-epic-with-p0-or-p1-tasks.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s05.md b/specs/codebase-wiki/e45s05.md index 4958840f..53be25b1 100644 --- a/specs/codebase-wiki/e45s05.md +++ b/specs/codebase-wiki/e45s05.md @@ -6,8 +6,20 @@ bcps: 4 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/lib/completeness-critic.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/verify-work/SKILL.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/gate-trace/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/gate-trace.md line: 0 confidence: medium @@ -98,6 +110,9 @@ links: ## Implemented In +- `scripts/lib/completeness-critic.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/verify-work/SKILL.md` (line 2, confidence: high, method: explicit_tag) +- `skills/gate-trace/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/gate-trace.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/verify-work.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-i-should-reject-work-that-fails-its-risk-tier-verification-gate.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s06.md b/specs/codebase-wiki/e45s06.md index 41634510..bb899af8 100644 --- a/specs/codebase-wiki/e45s06.md +++ b/specs/codebase-wiki/e45s06.md @@ -5,9 +5,17 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: skills/plan-work/SKILL.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/develop-tdd/SKILL.md + line: 2 + confidence: high + method: explicit_tag --- # e45s06: tasks.yaml: literal failing→passing task ledger @@ -16,4 +24,7 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `skills/plan-work/SKILL.md` (line 2, confidence: high, method: explicit_tag) +- `skills/develop-tdd/SKILL.md` (line 2, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s07.md b/specs/codebase-wiki/e45s07.md index 21e6f131..9f47a0a4 100644 --- a/specs/codebase-wiki/e45s07.md +++ b/specs/codebase-wiki/e45s07.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/request-review/SKILL.md + line: 1 + confidence: high + method: explicit_tag + - file: skills/request-review/SKILL.md + line: 2 + confidence: high + method: explicit_tag - file: specs/DEEPEN-ARCHITECTURE-REVIEW.md line: 0 confidence: medium @@ -116,6 +124,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/parallel-review-worktrees.sh + line: 0 + confidence: medium + method: file_heuristic --- # e45s07: request-review: dual-blind AND-gate review (Santa Method) @@ -126,6 +138,8 @@ links: ## Implemented In +- `skills/request-review/SKILL.md` (line 1, confidence: high, method: explicit_tag) +- `skills/request-review/SKILL.md` (line 2, confidence: high, method: explicit_tag) - `specs/DEEPEN-ARCHITECTURE-REVIEW.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/request-review.md` (line 0, confidence: medium, method: file_heuristic) @@ -153,3 +167,4 @@ links: - `.kilocode/rules/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/request-review.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/respond-review.md` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/parallel-review-worktrees.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s08.md b/specs/codebase-wiki/e45s08.md index b335c649..f54ad3b5 100644 --- a/specs/codebase-wiki/e45s08.md +++ b/specs/codebase-wiki/e45s08.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/validate-fix/SKILL.md + line: 1 + confidence: high + method: explicit_tag + - file: skills/develop-tdd/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/develop-tdd.md line: 0 confidence: medium @@ -54,6 +62,8 @@ links: ## Implemented In +- `skills/validate-fix/SKILL.md` (line 1, confidence: high, method: explicit_tag) +- `skills/develop-tdd/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/develop-tdd.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/validate-fix.md` (line 0, confidence: medium, method: file_heuristic) - `specs/benchmarks/develop-tdd.yaml` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s09.md b/specs/codebase-wiki/e45s09.md index 97336e94..4819aae7 100644 --- a/specs/codebase-wiki/e45s09.md +++ b/specs/codebase-wiki/e45s09.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/plan-work/SKILL.md + line: 3 + confidence: high + method: explicit_tag + - file: skills/verify-work/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/WORKFLOW-solo-git.md line: 0 confidence: medium @@ -248,6 +256,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/parallel-review-worktrees.sh + line: 0 + confidence: medium + method: file_heuristic --- # e45s09: verify-work / plan-work: Pre-Implementation and Validation gates @@ -258,6 +270,8 @@ links: ## Implemented In +- `skills/plan-work/SKILL.md` (line 3, confidence: high, method: explicit_tag) +- `skills/verify-work/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/WORKFLOW-solo-git.md` (line 0, confidence: medium, method: file_heuristic) - `specs/MISSING-REFERENCES-AND-DELIVERY-PLAN.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/scope-work.md` (line 0, confidence: medium, method: file_heuristic) @@ -318,3 +332,4 @@ links: - `.kilocode/rules/compose-workflow.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/organize-workspace.md` (line 0, confidence: medium, method: file_heuristic) - `scripts/cleanup-worktrees.sh` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/parallel-review-worktrees.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s10.md b/specs/codebase-wiki/e45s10.md index 7dcdf13b..ce699de2 100644 --- a/specs/codebase-wiki/e45s10.md +++ b/specs/codebase-wiki/e45s10.md @@ -6,8 +6,28 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: CONVENTIONS.md + line: 4 + confidence: high + method: explicit_tag + - file: scripts/references-manifest.yaml + line: 1 + confidence: high + method: explicit_tag + - file: scripts/lib/sync-context-engineering-ref.sh + line: 2 + confidence: high + method: explicit_tag + - file: scripts/sync-references.sh + line: 2 + confidence: high + method: explicit_tag + - file: .github/workflows/sync-references.yml + line: 1 + confidence: high + method: explicit_tag - file: scripts/sync-status-from-epics.sh line: 0 confidence: medium @@ -22,4 +42,9 @@ links: ## Implemented In +- `CONVENTIONS.md` (line 4, confidence: high, method: explicit_tag) +- `scripts/references-manifest.yaml` (line 1, confidence: high, method: explicit_tag) +- `scripts/lib/sync-context-engineering-ref.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/sync-references.sh` (line 2, confidence: high, method: explicit_tag) +- `.github/workflows/sync-references.yml` (line 1, confidence: high, method: explicit_tag) - `scripts/sync-status-from-epics.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s11.md b/specs/codebase-wiki/e45s11.md index e9f9cff7..2074b9f0 100644 --- a/specs/codebase-wiki/e45s11.md +++ b/specs/codebase-wiki/e45s11.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/dispatch-agents/SKILL.md + line: 2 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/dispatch-agents.md line: 0 confidence: medium @@ -34,6 +38,7 @@ links: ## Implemented In +- `skills/dispatch-agents/SKILL.md` (line 2, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/dispatch-agents.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/dispatch-agents.md` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/dispatch-agents.mdx` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s12.md b/specs/codebase-wiki/e45s12.md index 2e865f90..791520e0 100644 --- a/specs/codebase-wiki/e45s12.md +++ b/specs/codebase-wiki/e45s12.md @@ -6,8 +6,20 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/validate-skill-catalog.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/craft-skill/SKILL.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/stocktake-skills/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: skills-lock.json line: 0 confidence: medium @@ -122,6 +134,9 @@ links: ## Implemented In +- `scripts/validate-skill-catalog.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/craft-skill/SKILL.md` (line 2, confidence: high, method: explicit_tag) +- `skills/stocktake-skills/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `skills-lock.json` (line 0, confidence: medium, method: file_heuristic) - `specs/bigpowers-skills-evaluation.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/stocktake-skills.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s13.md b/specs/codebase-wiki/e45s13.md index 43890880..df020ba2 100644 --- a/specs/codebase-wiki/e45s13.md +++ b/specs/codebase-wiki/e45s13.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/verify-work/SKILL.md + line: 4 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/verify-work.md line: 0 confidence: medium @@ -58,6 +62,7 @@ links: ## Implemented In +- `skills/verify-work/SKILL.md` (line 4, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/verify-work.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-tests-should-verify-behavior-through-public-apis-not-implementation-t8.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-verify-work-runner-scripts-oversized.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s14.md b/specs/codebase-wiki/e45s14.md index 21c63796..c7d54722 100644 --- a/specs/codebase-wiki/e45s14.md +++ b/specs/codebase-wiki/e45s14.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/check-import-boundaries.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/deepen-architecture/SKILL.md + line: 2 + confidence: high + method: explicit_tag - file: specs/DEEPEN-ARCHITECTURE-REVIEW.md line: 0 confidence: medium @@ -38,6 +46,8 @@ links: ## Implemented In +- `scripts/check-import-boundaries.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/deepen-architecture/SKILL.md` (line 2, confidence: high, method: explicit_tag) - `specs/DEEPEN-ARCHITECTURE-REVIEW.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/deepen-architecture.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/deepen-architecture.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s15.md b/specs/codebase-wiki/e45s15.md index e2d16343..92da3168 100644 --- a/specs/codebase-wiki/e45s15.md +++ b/specs/codebase-wiki/e45s15.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/deploy/SKILL.md + line: 1 + confidence: high + method: explicit_tag + - file: skills/release-branch/SKILL.md + line: 2 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/release-branch.md line: 0 confidence: medium @@ -46,6 +54,8 @@ links: ## Implemented In +- `skills/deploy/SKILL.md` (line 1, confidence: high, method: explicit_tag) +- `skills/release-branch/SKILL.md` (line 2, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/release-branch.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/archive/e26-security-review/e26s06-release-branch-gate.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/archive/e38-traceability-gate/e38s07-release-branch-gate.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s16.md b/specs/codebase-wiki/e45s16.md index 1bff4b02..3d9ea05d 100644 --- a/specs/codebase-wiki/e45s16.md +++ b/specs/codebase-wiki/e45s16.md @@ -6,8 +6,20 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/install.sh + line: 2 + confidence: high + method: explicit_tag + - file: scripts/install.sh + line: 88 + confidence: high + method: explicit_tag + - file: scripts/hooks/rtk-rewrite.sh + line: 2 + confidence: high + method: explicit_tag - file: specs/agent-guide/rtk-commands-by-workflow.md line: 0 confidence: medium @@ -22,4 +34,7 @@ links: ## Implemented In +- `scripts/install.sh` (line 2, confidence: high, method: explicit_tag) +- `scripts/install.sh` (line 88, confidence: high, method: explicit_tag) +- `scripts/hooks/rtk-rewrite.sh` (line 2, confidence: high, method: explicit_tag) - `specs/agent-guide/rtk-commands-by-workflow.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s17.md b/specs/codebase-wiki/e45s17.md index bef84f01..f1de7db4 100644 --- a/specs/codebase-wiki/e45s17.md +++ b/specs/codebase-wiki/e45s17.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/request-review/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/DEEPEN-ARCHITECTURE-REVIEW.md line: 0 confidence: medium @@ -88,6 +92,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/parallel-review-worktrees.sh + line: 0 + confidence: medium + method: file_heuristic --- # e45s17: request-review: fan-out to parallel review subagents @@ -98,6 +106,7 @@ links: ## Implemented In +- `skills/request-review/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/DEEPEN-ARCHITECTURE-REVIEW.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/request-review.md` (line 0, confidence: medium, method: file_heuristic) @@ -118,3 +127,4 @@ links: - `.kilocode/rules/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/request-review.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/respond-review.md` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/parallel-review-worktrees.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s18.md b/specs/codebase-wiki/e45s18.md index 5cf98498..c6cbcbe2 100644 --- a/specs/codebase-wiki/e45s18.md +++ b/specs/codebase-wiki/e45s18.md @@ -6,8 +6,20 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/lib/parallel-review-worktrees.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/security-review/SKILL.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/audit-code/SKILL.md + line: 2 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/security-review.md line: 0 confidence: medium @@ -48,6 +60,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212931.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-160106.md line: 0 confidence: medium @@ -64,6 +80,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215320.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-172717.md line: 0 confidence: medium @@ -72,6 +92,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212830.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-182718.md line: 0 confidence: medium @@ -88,6 +112,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-183547.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260626-205129.md line: 0 confidence: medium @@ -120,6 +148,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214411.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260622-001710.md line: 0 confidence: medium @@ -132,6 +164,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001605.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-181904.md line: 0 confidence: medium @@ -168,10 +204,26 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-185319.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-183644.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215759.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260629-132810.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001328.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-235439.md line: 0 confidence: medium @@ -180,6 +232,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-202226.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164609.md line: 0 confidence: medium @@ -240,10 +296,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-205711.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-182236.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-213042.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-223023.md line: 0 confidence: medium @@ -320,6 +384,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215656.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-143757.md line: 0 confidence: medium @@ -352,6 +420,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001312.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164534.md line: 0 confidence: medium @@ -388,6 +460,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184319.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-174351.md line: 0 confidence: medium @@ -424,6 +500,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-235505.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-220905.md line: 0 confidence: medium @@ -444,6 +524,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001100.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-150417.md line: 0 confidence: medium @@ -468,6 +552,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001518.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-170909.md line: 0 confidence: medium @@ -520,6 +608,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184856.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-154339.md line: 0 confidence: medium @@ -540,6 +632,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-213831.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-174245.md line: 0 confidence: medium @@ -604,6 +700,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001919.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-220941.md line: 0 confidence: medium @@ -636,6 +736,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-185210.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-165256.md line: 0 confidence: medium @@ -664,6 +768,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212919.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-163256.md line: 0 confidence: medium @@ -704,6 +812,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-000955.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-144557.md line: 0 confidence: medium @@ -904,6 +1016,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-220404.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-085740.md line: 0 confidence: medium @@ -948,6 +1064,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214125.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-132604.md line: 0 confidence: medium @@ -1048,6 +1168,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215213.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-204345.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212711.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-153739.md line: 0 confidence: medium @@ -1120,10 +1252,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212552.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-181706.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001702.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-132130.md line: 0 confidence: medium @@ -1136,6 +1276,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-204300.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164141.md line: 0 confidence: medium @@ -1164,6 +1308,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001029.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-172425.md line: 0 confidence: medium @@ -1184,6 +1332,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184658.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-194009.md line: 0 confidence: medium @@ -1212,6 +1364,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-235409.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-195845.md line: 0 confidence: medium @@ -1256,6 +1412,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184355.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-172751.md line: 0 confidence: medium @@ -1284,6 +1444,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-234704.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-163238.md line: 0 confidence: medium @@ -1292,6 +1456,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214329.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-144506.md line: 0 confidence: medium @@ -1378,6 +1546,9 @@ links: ## Implemented In +- `scripts/lib/parallel-review-worktrees.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/security-review/SKILL.md` (line 2, confidence: high, method: explicit_tag) +- `skills/audit-code/SKILL.md` (line 2, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/audit-code.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-175346.md` (line 0, confidence: medium, method: file_heuristic) @@ -1388,16 +1559,20 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-180022.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163733.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-181947.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212931.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-160106.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-180858.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-181109.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143153.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215320.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-172717.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174039.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212830.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182718.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170744.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-122420.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-183547.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-205129.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-081618.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-162136.md` (line 0, confidence: medium, method: file_heuristic) @@ -1406,9 +1581,11 @@ links: - `specs/verifications/reports/audit-cleancode-20260629-132717.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-165137.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223301.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214411.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260622-001710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165920.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-000102.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001605.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181904.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150326.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170432.md` (line 0, confidence: medium, method: file_heuristic) @@ -1418,9 +1595,14 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-163159.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-010055.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163108.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-185319.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-183644.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215759.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260629-132810.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001328.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-235439.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164718.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-202226.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-165651.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172406.md` (line 0, confidence: medium, method: file_heuristic) @@ -1436,7 +1618,9 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-082500.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-205844.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-205711.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-182236.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-213042.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223023.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-134126.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-162245.md` (line 0, confidence: medium, method: file_heuristic) @@ -1456,6 +1640,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-173515.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-090946.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-125910.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215656.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143757.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-225914.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165619.md` (line 0, confidence: medium, method: file_heuristic) @@ -1464,6 +1649,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-164757.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-131004.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-174055.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001312.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164534.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005128.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-235526.md` (line 0, confidence: medium, method: file_heuristic) @@ -1473,6 +1659,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-005444.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223636.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181759.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184319.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174351.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154353.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-131211.md` (line 0, confidence: medium, method: file_heuristic) @@ -1482,17 +1669,20 @@ links: - `specs/verifications/reports/audit-cleancode-20260702-080042.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-120114.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-234357.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-235505.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-220905.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-160732.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164627.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143840.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-214041.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001100.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150417.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-155813.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164603.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143504.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-154427.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163136.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001518.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170909.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-200136.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154246.md` (line 0, confidence: medium, method: file_heuristic) @@ -1506,11 +1696,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260626-204652.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132944.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-091141.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184856.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-154339.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223425.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-182836.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-202450.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194130.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-213831.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174245.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005800.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-173348.md` (line 0, confidence: medium, method: file_heuristic) @@ -1527,6 +1719,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-083149.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170223.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164441.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001919.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-220941.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174117.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-120150.md` (line 0, confidence: medium, method: file_heuristic) @@ -1535,6 +1728,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-082609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182807.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173917.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-185210.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165256.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165207.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-200110.md` (line 0, confidence: medium, method: file_heuristic) @@ -1542,6 +1736,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-144202.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-183102.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-233707.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212919.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163256.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181458.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005720.md` (line 0, confidence: medium, method: file_heuristic) @@ -1552,6 +1747,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-130915.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194053.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-202651.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-000955.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-144557.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-174133.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-115538.md` (line 0, confidence: medium, method: file_heuristic) @@ -1602,6 +1798,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260627-133613.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-195653.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005358.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-220404.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-085740.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-193756.md` (line 0, confidence: medium, method: file_heuristic) @@ -1613,6 +1810,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-165346.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-080024.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142902.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214125.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132604.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132933.md` (line 0, confidence: medium, method: file_heuristic) @@ -1638,6 +1836,9 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-202558.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170940.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-163657.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215213.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-204345.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212711.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-153739.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-175227.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-180125.md` (line 0, confidence: medium, method: file_heuristic) @@ -1656,10 +1857,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-115557.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-221847.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-004226.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212552.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-181706.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001702.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132130.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182429.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163956.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-204300.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164141.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-173033.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164050.md` (line 0, confidence: medium, method: file_heuristic) @@ -1667,11 +1871,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-174710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165902.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005336.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001029.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172425.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-133730.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154726.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-175929.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172525.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184658.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194009.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260629-130359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170706.md` (line 0, confidence: medium, method: file_heuristic) @@ -1679,6 +1885,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-163613.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173429.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142458.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-235409.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-195845.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-164155.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-171134.md` (line 0, confidence: medium, method: file_heuristic) @@ -1690,6 +1897,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-182346.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-115503.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260621-231038.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184355.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-172751.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170431.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163837.md` (line 0, confidence: medium, method: file_heuristic) @@ -1697,8 +1905,10 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-000548.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150200.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-175152.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-234704.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163238.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-180948.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214329.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-144506.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173306.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260622-001925.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s19.md b/specs/codebase-wiki/e45s19.md index 0b6b1255..52bb99a7 100644 --- a/specs/codebase-wiki/e45s19.md +++ b/specs/codebase-wiki/e45s19.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/context7-mcp/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/verifications/steps/and-complex-boolean-logic-should-be-encapsulated-in-named-functions-g28.sh line: 0 confidence: medium @@ -42,6 +46,7 @@ links: ## Implemented In +- `skills/context7-mcp/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/verifications/steps/and-complex-boolean-logic-should-be-encapsulated-in-named-functions-g28.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-types-should-be-explicit.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-there-should-be-no-ignored-tests-without-an-explicit-ambiguity-note-t4.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s20.md b/specs/codebase-wiki/e45s20.md index 0aeb8994..5efde3ae 100644 --- a/specs/codebase-wiki/e45s20.md +++ b/specs/codebase-wiki/e45s20.md @@ -5,9 +5,13 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: scripts/lib/doc-fetch-cache.sh + line: 2 + confidence: high + method: explicit_tag --- # e45s20: Context7 / bts docs: wrap in ETag-revalidated fetch cache @@ -16,4 +20,6 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `scripts/lib/doc-fetch-cache.sh` (line 2, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s21.md b/specs/codebase-wiki/e45s21.md index 42788e43..2c50240d 100644 --- a/specs/codebase-wiki/e45s21.md +++ b/specs/codebase-wiki/e45s21.md @@ -6,8 +6,36 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/seed-conventions.md + line: 95 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md + line: 100 + confidence: high + method: explicit_tag + - file: docs/templates/AGENTS.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/seed-conventions/REFERENCE.md + line: 2 + confidence: high + method: explicit_tag + - file: skills/seed-conventions/SKILL.md + line: 2 + confidence: high + method: explicit_tag + - file: .pi/prompts/seed-conventions.md + line: 99 + confidence: high + method: explicit_tag + - file: .pi/skills/seed-conventions/SKILL.md + line: 101 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/seed-conventions.md line: 0 confidence: medium @@ -34,6 +62,13 @@ links: ## Implemented In +- `.gemini/extensions/bigpowers/commands/prompts/seed-conventions.md` (line 95, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md` (line 100, confidence: high, method: explicit_tag) +- `docs/templates/AGENTS.md` (line 2, confidence: high, method: explicit_tag) +- `skills/seed-conventions/REFERENCE.md` (line 2, confidence: high, method: explicit_tag) +- `skills/seed-conventions/SKILL.md` (line 2, confidence: high, method: explicit_tag) +- `.pi/prompts/seed-conventions.md` (line 99, confidence: high, method: explicit_tag) +- `.pi/skills/seed-conventions/SKILL.md` (line 101, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/seed-conventions.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/seed-conventions.md` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/seed-conventions.mdx` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s22.md b/specs/codebase-wiki/e45s22.md index 120d2b14..4b7dc6a6 100644 --- a/specs/codebase-wiki/e45s22.md +++ b/specs/codebase-wiki/e45s22.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: CLAUDE.md + line: 3 + confidence: high + method: explicit_tag - file: specs/epics/e05-context-isolation-routing.yaml line: 0 confidence: medium @@ -22,4 +26,5 @@ links: ## Implemented In +- `CLAUDE.md` (line 3, confidence: high, method: explicit_tag) - `specs/epics/e05-context-isolation-routing.yaml` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s23.md b/specs/codebase-wiki/e45s23.md index cd342a99..4cc802c0 100644 --- a/specs/codebase-wiki/e45s23.md +++ b/specs/codebase-wiki/e45s23.md @@ -5,9 +5,33 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/session-state.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/session-state/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/session-state/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: CLAUDE.md + line: 4 + confidence: high + method: explicit_tag + - file: .pi/prompts/session-state.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/session-state/SKILL.md + line: 8 + confidence: high + method: explicit_tag --- # e45s23: CLAUDE.md: live Learned User Preferences / Workspace Facts @@ -16,4 +40,11 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `.gemini/extensions/bigpowers/commands/prompts/session-state.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/session-state/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/session-state/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `CLAUDE.md` (line 4, confidence: high, method: explicit_tag) +- `.pi/prompts/session-state.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/session-state/SKILL.md` (line 8, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s25.md b/specs/codebase-wiki/e45s25.md index 6226e443..c40d3594 100644 --- a/specs/codebase-wiki/e45s25.md +++ b/specs/codebase-wiki/e45s25.md @@ -6,8 +6,20 @@ bcps: 4 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: CONVENTIONS.md + line: 6 + confidence: high + method: explicit_tag + - file: scripts/compile-rule-matrix.sh + line: 2 + confidence: high + method: explicit_tag + - file: specs/rule-matrix.json + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/steps/and-the-plan-contains-a-risk-matrix.sh line: 0 confidence: medium @@ -22,4 +34,7 @@ links: ## Implemented In +- `CONVENTIONS.md` (line 6, confidence: high, method: explicit_tag) +- `scripts/compile-rule-matrix.sh` (line 2, confidence: high, method: explicit_tag) +- `specs/rule-matrix.json` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-the-plan-contains-a-risk-matrix.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s26.md b/specs/codebase-wiki/e45s26.md index ad9ff53a..c0be3cd5 100644 --- a/specs/codebase-wiki/e45s26.md +++ b/specs/codebase-wiki/e45s26.md @@ -6,8 +6,44 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/security-review.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/security-review/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/security-review/SKILL.md + line: 15 + confidence: high + method: explicit_tag + - file: skills/security-review/fixtures/CWE-89-sqli-positive.py + line: 1 + confidence: high + method: explicit_tag + - file: skills/security-review/fixtures/CWE-89-sqli-negative.py + line: 1 + confidence: high + method: explicit_tag + - file: skills/security-review/fixtures/CWE-79-xss-positive.js + line: 1 + confidence: high + method: explicit_tag + - file: skills/security-review/fixtures/CWE-79-xss-negative.js + line: 1 + confidence: high + method: explicit_tag + - file: .pi/prompts/security-review.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/security-review/SKILL.md + line: 8 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/security-review.md line: 0 confidence: medium @@ -34,6 +70,15 @@ links: ## Implemented In +- `.gemini/extensions/bigpowers/commands/prompts/security-review.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/security-review/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/security-review/SKILL.md` (line 15, confidence: high, method: explicit_tag) +- `skills/security-review/fixtures/CWE-89-sqli-positive.py` (line 1, confidence: high, method: explicit_tag) +- `skills/security-review/fixtures/CWE-89-sqli-negative.py` (line 1, confidence: high, method: explicit_tag) +- `skills/security-review/fixtures/CWE-79-xss-positive.js` (line 1, confidence: high, method: explicit_tag) +- `skills/security-review/fixtures/CWE-79-xss-negative.js` (line 1, confidence: high, method: explicit_tag) +- `.pi/prompts/security-review.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/security-review/SKILL.md` (line 8, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/security-review.mdx` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s27.md b/specs/codebase-wiki/e45s27.md index af1d43c5..fad570b3 100644 --- a/specs/codebase-wiki/e45s27.md +++ b/specs/codebase-wiki/e45s27.md @@ -5,9 +5,29 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/compose-workflow.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/compose-workflow/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: .pi/prompts/compose-workflow.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/compose-workflow/SKILL.md + line: 8 + confidence: high + method: explicit_tag --- # e45s27: loop / workflow: terminal-state taxonomy @@ -16,4 +36,10 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `.gemini/extensions/bigpowers/commands/prompts/compose-workflow.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/compose-workflow/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `.pi/prompts/compose-workflow.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/compose-workflow/SKILL.md` (line 8, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s28.md b/specs/codebase-wiki/e45s28.md index 05e15e3d..c5eb60d3 100644 --- a/specs/codebase-wiki/e45s28.md +++ b/specs/codebase-wiki/e45s28.md @@ -6,8 +6,28 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/request-review.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/request-review/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/request-review/SKILL.md + line: 11 + confidence: high + method: explicit_tag + - file: .pi/prompts/request-review.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/request-review/SKILL.md + line: 8 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/request-review.md line: 0 confidence: medium @@ -38,6 +58,11 @@ links: ## Implemented In +- `.gemini/extensions/bigpowers/commands/prompts/request-review.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/request-review/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/request-review/SKILL.md` (line 11, confidence: high, method: explicit_tag) +- `.pi/prompts/request-review.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/request-review/SKILL.md` (line 8, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/request-review.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/archive/e26-security-review/e26s04-audit-request-review.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/request-review.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s29.md b/specs/codebase-wiki/e45s29.md index 54a80427..6fa46276 100644 --- a/specs/codebase-wiki/e45s29.md +++ b/specs/codebase-wiki/e45s29.md @@ -5,9 +5,69 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/slice-tasks.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/commands/prompts/plan-work.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/commands/prompts/change-request.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/plan-work/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/change-request/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/plan-work/SKILL.md + line: 13 + confidence: high + method: explicit_tag + - file: skills/change-request/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: skills/slice-tasks/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: .pi/prompts/slice-tasks.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/prompts/plan-work.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/prompts/change-request.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/plan-work/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: .pi/skills/change-request/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: .pi/skills/slice-tasks/SKILL.md + line: 8 + confidence: high + method: explicit_tag --- # e45s29: requirements: ADDED/MODIFIED/REMOVED/RENAMED tags @@ -16,4 +76,20 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `.gemini/extensions/bigpowers/commands/prompts/slice-tasks.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/commands/prompts/plan-work.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/commands/prompts/change-request.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/plan-work/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/change-request/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/plan-work/SKILL.md` (line 13, confidence: high, method: explicit_tag) +- `skills/change-request/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `skills/slice-tasks/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `.pi/prompts/slice-tasks.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/prompts/plan-work.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/prompts/change-request.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/plan-work/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `.pi/skills/change-request/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `.pi/skills/slice-tasks/SKILL.md` (line 8, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s30.md b/specs/codebase-wiki/e45s30.md index b4f3dc4c..b2ccbbc1 100644 --- a/specs/codebase-wiki/e45s30.md +++ b/specs/codebase-wiki/e45s30.md @@ -5,9 +5,49 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: .gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/commands/prompts/delegate-task.md + line: 2 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/delegate-task/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: .gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md + line: 7 + confidence: high + method: explicit_tag + - file: skills/delegate-task/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: skills/dispatch-agents/SKILL.md + line: 10 + confidence: high + method: explicit_tag + - file: .pi/prompts/dispatch-agents.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/prompts/delegate-task.md + line: 6 + confidence: high + method: explicit_tag + - file: .pi/skills/delegate-task/SKILL.md + line: 8 + confidence: high + method: explicit_tag + - file: .pi/skills/dispatch-agents/SKILL.md + line: 8 + confidence: high + method: explicit_tag --- # e45s30: subagent depth: formalize depth tiers @@ -16,4 +56,15 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `.gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/commands/prompts/delegate-task.md` (line 2, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/delegate-task/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `.gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md` (line 7, confidence: high, method: explicit_tag) +- `skills/delegate-task/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `skills/dispatch-agents/SKILL.md` (line 10, confidence: high, method: explicit_tag) +- `.pi/prompts/dispatch-agents.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/prompts/delegate-task.md` (line 6, confidence: high, method: explicit_tag) +- `.pi/skills/delegate-task/SKILL.md` (line 8, confidence: high, method: explicit_tag) +- `.pi/skills/dispatch-agents/SKILL.md` (line 8, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s31.md b/specs/codebase-wiki/e45s31.md index 3ba4e71a..49d53cd6 100644 --- a/specs/codebase-wiki/e45s31.md +++ b/specs/codebase-wiki/e45s31.md @@ -6,8 +6,20 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: scripts/bp-churn-rank.sh + line: 2 + confidence: high + method: explicit_tag + - file: skills/deepen-architecture/SKILL.md + line: 1 + confidence: high + method: explicit_tag + - file: skills/audit-code/SKILL.md + line: 3 + confidence: high + method: explicit_tag - file: specs/DEEPEN-ARCHITECTURE-REVIEW.md line: 0 confidence: medium @@ -68,6 +80,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212931.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-160106.md line: 0 confidence: medium @@ -84,6 +100,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215320.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-172717.md line: 0 confidence: medium @@ -92,6 +112,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212830.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-182718.md line: 0 confidence: medium @@ -108,6 +132,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-183547.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260626-205129.md line: 0 confidence: medium @@ -140,6 +168,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214411.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260622-001710.md line: 0 confidence: medium @@ -152,6 +184,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001605.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-181904.md line: 0 confidence: medium @@ -188,10 +224,26 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-185319.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-183644.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215759.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260629-132810.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001328.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-235439.md line: 0 confidence: medium @@ -200,6 +252,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-202226.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164609.md line: 0 confidence: medium @@ -260,10 +316,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-205711.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-182236.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-213042.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-223023.md line: 0 confidence: medium @@ -340,6 +404,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215656.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-143757.md line: 0 confidence: medium @@ -372,6 +440,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001312.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164534.md line: 0 confidence: medium @@ -408,6 +480,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184319.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-174351.md line: 0 confidence: medium @@ -444,6 +520,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-235505.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-220905.md line: 0 confidence: medium @@ -464,6 +544,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001100.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-150417.md line: 0 confidence: medium @@ -488,6 +572,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001518.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-170909.md line: 0 confidence: medium @@ -540,6 +628,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184856.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-154339.md line: 0 confidence: medium @@ -560,6 +652,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-213831.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-174245.md line: 0 confidence: medium @@ -624,6 +720,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001919.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-220941.md line: 0 confidence: medium @@ -656,6 +756,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-185210.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-165256.md line: 0 confidence: medium @@ -684,6 +788,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212919.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-163256.md line: 0 confidence: medium @@ -724,6 +832,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-000955.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-144557.md line: 0 confidence: medium @@ -924,6 +1036,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-220404.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-085740.md line: 0 confidence: medium @@ -968,6 +1084,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214125.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-132604.md line: 0 confidence: medium @@ -1068,6 +1188,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-215213.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-204345.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212711.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-153739.md line: 0 confidence: medium @@ -1140,10 +1272,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-212552.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-181706.md line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001702.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-132130.md line: 0 confidence: medium @@ -1156,6 +1296,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-204300.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-164141.md line: 0 confidence: medium @@ -1184,6 +1328,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260707-001029.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-172425.md line: 0 confidence: medium @@ -1204,6 +1352,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184658.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260705-194009.md line: 0 confidence: medium @@ -1232,6 +1384,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-235409.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260702-195845.md line: 0 confidence: medium @@ -1276,6 +1432,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-184355.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260706-172751.md line: 0 confidence: medium @@ -1304,6 +1464,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-234704.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260703-163238.md line: 0 confidence: medium @@ -1312,6 +1476,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/audit-cleancode-20260706-214329.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/audit-cleancode-20260704-144506.md line: 0 confidence: medium @@ -1386,6 +1554,9 @@ links: ## Implemented In +- `scripts/bp-churn-rank.sh` (line 2, confidence: high, method: explicit_tag) +- `skills/deepen-architecture/SKILL.md` (line 1, confidence: high, method: explicit_tag) +- `skills/audit-code/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/DEEPEN-ARCHITECTURE-REVIEW.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/audit-code.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/deepen-architecture.md` (line 0, confidence: medium, method: file_heuristic) @@ -1401,16 +1572,20 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-180022.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163733.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-181947.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212931.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-160106.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-180858.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-181109.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143153.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215320.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-172717.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174039.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212830.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182718.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170744.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-122420.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-183547.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-205129.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-081618.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-162136.md` (line 0, confidence: medium, method: file_heuristic) @@ -1419,9 +1594,11 @@ links: - `specs/verifications/reports/audit-cleancode-20260629-132717.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-165137.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223301.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214411.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260622-001710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165920.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-000102.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001605.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181904.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150326.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170432.md` (line 0, confidence: medium, method: file_heuristic) @@ -1431,9 +1608,14 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-163159.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-010055.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163108.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-185319.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-183644.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215759.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260629-132810.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001328.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-235439.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164718.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-202226.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-165651.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172406.md` (line 0, confidence: medium, method: file_heuristic) @@ -1449,7 +1631,9 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-082500.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-205844.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-205711.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-182236.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-213042.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223023.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-134126.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-162245.md` (line 0, confidence: medium, method: file_heuristic) @@ -1469,6 +1653,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-173515.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-090946.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-125910.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215656.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143757.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-225914.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165619.md` (line 0, confidence: medium, method: file_heuristic) @@ -1477,6 +1662,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-164757.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-131004.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-174055.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001312.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164534.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005128.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-235526.md` (line 0, confidence: medium, method: file_heuristic) @@ -1486,6 +1672,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-005444.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223636.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181759.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184319.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174351.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154353.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-131211.md` (line 0, confidence: medium, method: file_heuristic) @@ -1495,17 +1682,20 @@ links: - `specs/verifications/reports/audit-cleancode-20260702-080042.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-120114.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-234357.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-235505.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-220905.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-160732.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164627.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143840.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-214041.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001100.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150417.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-155813.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164603.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-143504.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-154427.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163136.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001518.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170909.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-200136.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154246.md` (line 0, confidence: medium, method: file_heuristic) @@ -1519,11 +1709,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260626-204652.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132944.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-091141.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184856.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-154339.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223425.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-182836.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-202450.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194130.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-213831.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174245.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005800.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-173348.md` (line 0, confidence: medium, method: file_heuristic) @@ -1540,6 +1732,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-083149.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170223.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164441.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001919.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-220941.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-174117.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-120150.md` (line 0, confidence: medium, method: file_heuristic) @@ -1548,6 +1741,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-082609.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182807.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173917.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-185210.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165256.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165207.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-200110.md` (line 0, confidence: medium, method: file_heuristic) @@ -1555,6 +1749,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-144202.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-183102.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-233707.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212919.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163256.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-181458.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005720.md` (line 0, confidence: medium, method: file_heuristic) @@ -1565,6 +1760,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260703-130915.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194053.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-202651.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-000955.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-144557.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-174133.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-115538.md` (line 0, confidence: medium, method: file_heuristic) @@ -1615,6 +1811,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260627-133613.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260626-195653.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005358.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-220404.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-085740.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-223359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-193756.md` (line 0, confidence: medium, method: file_heuristic) @@ -1626,6 +1823,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-165346.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-080024.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142902.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214125.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132604.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132933.md` (line 0, confidence: medium, method: file_heuristic) @@ -1651,6 +1849,9 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-202558.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170940.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-163657.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-215213.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-204345.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212711.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-153739.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-175227.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-180125.md` (line 0, confidence: medium, method: file_heuristic) @@ -1669,10 +1870,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-115557.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-221847.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-004226.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-212552.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-181706.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001702.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-132130.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-182429.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163956.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-204300.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164141.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-173033.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-164050.md` (line 0, confidence: medium, method: file_heuristic) @@ -1680,11 +1884,13 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-174710.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-165902.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-005336.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260707-001029.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172425.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-133730.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-154726.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-175929.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-172525.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184658.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-194009.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260629-130359.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170706.md` (line 0, confidence: medium, method: file_heuristic) @@ -1692,6 +1898,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260706-163613.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173429.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-142458.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-235409.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260702-195845.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-164155.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-171134.md` (line 0, confidence: medium, method: file_heuristic) @@ -1703,6 +1910,7 @@ links: - `specs/verifications/reports/audit-cleancode-20260705-182346.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-115503.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260621-231038.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-184355.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-172751.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-170431.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-163837.md` (line 0, confidence: medium, method: file_heuristic) @@ -1710,8 +1918,10 @@ links: - `specs/verifications/reports/audit-cleancode-20260704-000548.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-150200.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-175152.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-234704.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260703-163238.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260705-180948.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-cleancode-20260706-214329.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260704-144506.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260706-173306.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-cleancode-20260622-001925.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s32.md b/specs/codebase-wiki/e45s32.md index 6bdad913..58421a57 100644 --- a/specs/codebase-wiki/e45s32.md +++ b/specs/codebase-wiki/e45s32.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/release-branch/SKILL.md + line: 3 + confidence: high + method: explicit_tag + - file: skills/gate-trace/SKILL.md + line: 6 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/gate-trace.md line: 0 confidence: medium @@ -94,6 +102,8 @@ links: ## Implemented In +- `skills/release-branch/SKILL.md` (line 3, confidence: high, method: explicit_tag) +- `skills/gate-trace/SKILL.md` (line 6, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/gate-trace.md` (line 0, confidence: medium, method: file_heuristic) - `specs/skills-wiki/skills/release-branch.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-i-should-enforce-a-two-stage-review-gate.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s33.md b/specs/codebase-wiki/e45s33.md index 0d81c394..1a8b5c48 100644 --- a/specs/codebase-wiki/e45s33.md +++ b/specs/codebase-wiki/e45s33.md @@ -5,9 +5,17 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: docs/countable-story-format.md + line: 3 + confidence: high + method: explicit_tag + - file: skills/plan-work/SKILL.md + line: 4 + confidence: high + method: explicit_tag --- # e45s33: requirements: per-section approval state @@ -16,4 +24,7 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `docs/countable-story-format.md` (line 3, confidence: high, method: explicit_tag) +- `skills/plan-work/SKILL.md` (line 4, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s34.md b/specs/codebase-wiki/e45s34.md index d71ed96a..541a77e6 100644 --- a/specs/codebase-wiki/e45s34.md +++ b/specs/codebase-wiki/e45s34.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/develop-tdd/SKILL.md + line: 4 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/develop-tdd.md line: 0 confidence: medium @@ -38,6 +42,7 @@ links: ## Implemented In +- `skills/develop-tdd/SKILL.md` (line 4, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/develop-tdd.md` (line 0, confidence: medium, method: file_heuristic) - `specs/benchmarks/develop-tdd.yaml` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/develop-tdd.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s35.md b/specs/codebase-wiki/e45s35.md index 7fd02a9c..b2f1191f 100644 --- a/specs/codebase-wiki/e45s35.md +++ b/specs/codebase-wiki/e45s35.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/plan-work/SKILL.md + line: 5 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/plan-work.md line: 0 confidence: medium @@ -38,6 +42,7 @@ links: ## Implemented In +- `skills/plan-work/SKILL.md` (line 5, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/plan-work.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/archive/e26-security-review/e26s03-plan-work-release.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/plan-work.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s36.md b/specs/codebase-wiki/e45s36.md index b0d38cd0..f8f5a115 100644 --- a/specs/codebase-wiki/e45s36.md +++ b/specs/codebase-wiki/e45s36.md @@ -5,9 +5,13 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: CONVENTIONS.md + line: 7 + confidence: high + method: explicit_tag --- # e45s36: specs: Documentation Responsibilities table @@ -16,4 +20,6 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `CONVENTIONS.md` (line 7, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s37.md b/specs/codebase-wiki/e45s37.md index 2feb9eed..d9272a3b 100644 --- a/specs/codebase-wiki/e45s37.md +++ b/specs/codebase-wiki/e45s37.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/run-evals/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/run-evals.md line: 0 confidence: medium @@ -46,6 +50,7 @@ links: ## Implemented In +- `skills/run-evals/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/run-evals.md` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-run-evals-golden-suite-oversized.md` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-run-evals-golden-suite-oversized.okf.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s38.md b/specs/codebase-wiki/e45s38.md index 248c1387..58edf5f7 100644 --- a/specs/codebase-wiki/e45s38.md +++ b/specs/codebase-wiki/e45s38.md @@ -6,8 +6,16 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/diagnose-stall/SKILL.md + line: 1 + confidence: high + method: explicit_tag + - file: skills/dispatch-agents/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: scripts/install-cursor-skills-local.sh line: 0 confidence: medium @@ -26,5 +34,7 @@ links: ## Implemented In +- `skills/diagnose-stall/SKILL.md` (line 1, confidence: high, method: explicit_tag) +- `skills/dispatch-agents/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `scripts/install-cursor-skills-local.sh` (line 0, confidence: medium, method: file_heuristic) - `scripts/install-cursor-skills.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s39.md b/specs/codebase-wiki/e45s39.md index 40cc9b51..00a33f30 100644 --- a/specs/codebase-wiki/e45s39.md +++ b/specs/codebase-wiki/e45s39.md @@ -5,9 +5,13 @@ epic: e45 bcps: 2 wsjf: 5.0 implementation_status: todo -coverage_status: dark -confidence: none +coverage_status: covered +confidence: high links: + - file: skills/release-branch/SKILL.md + line: 4 + confidence: high + method: explicit_tag --- # e45s39: PR generation: literal provenance marker @@ -16,4 +20,6 @@ links: **Status:** todo **BCP:** 2 | **WSJF:** 5.0 -*No code links found — this is a dark story.* +## Implemented In + +- `skills/release-branch/SKILL.md` (line 4, confidence: high, method: explicit_tag) diff --git a/specs/codebase-wiki/e45s40.md b/specs/codebase-wiki/e45s40.md index 7253bbeb..e9cdfa32 100644 --- a/specs/codebase-wiki/e45s40.md +++ b/specs/codebase-wiki/e45s40.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/verify-work/SKILL.md + line: 5 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/verify-work.md line: 0 confidence: medium @@ -58,6 +62,7 @@ links: ## Implemented In +- `skills/verify-work/SKILL.md` (line 5, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/verify-work.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/steps/and-i-should-reject-work-that-fails-its-risk-tier-verification-gate.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-verify-work-runner-scripts-oversized.md` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e45s41.md b/specs/codebase-wiki/e45s41.md index c04a8abb..ef9ec6b8 100644 --- a/specs/codebase-wiki/e45s41.md +++ b/specs/codebase-wiki/e45s41.md @@ -6,8 +6,12 @@ bcps: 2 wsjf: 5.0 implementation_status: todo coverage_status: covered -confidence: medium +confidence: high links: + - file: skills/security-review/SKILL.md + line: 1 + confidence: high + method: explicit_tag - file: specs/skills-wiki/skills/security-review.md line: 0 confidence: medium @@ -34,6 +38,7 @@ links: ## Implemented In +- `skills/security-review/SKILL.md` (line 1, confidence: high, method: explicit_tag) - `specs/skills-wiki/skills/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/security-review.md` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/security-review.mdx` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e48s01.md b/specs/codebase-wiki/e48s01.md index 41bf1bcc..d13579d6 100644 --- a/specs/codebase-wiki/e48s01.md +++ b/specs/codebase-wiki/e48s01.md @@ -24,10 +24,6 @@ links: line: 2 confidence: high method: explicit_tag - - file: skills/run-benchmark/SKILL.md - line: 3 - confidence: high - method: explicit_tag - file: specs/verifications/steps/and-complex-logic-should-include-provenance-links-adrs-jira-or-commits.sh line: 0 confidence: medium @@ -72,6 +68,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: website/src/content/docs/skills/maintain-wiki.mdx + line: 0 + confidence: medium + method: file_heuristic - file: docs/references/agent-config-files-and-okf.md line: 0 confidence: medium @@ -114,7 +114,6 @@ links: - `specs/benchmarks/SCHEMA.md` (line 2, confidence: high, method: explicit_tag) - `specs/benchmarks/verify-work.yaml` (line 2, confidence: high, method: explicit_tag) - `specs/benchmarks/survey-context.yaml` (line 2, confidence: high, method: explicit_tag) -- `skills/run-benchmark/SKILL.md` (line 3, confidence: high, method: explicit_tag) - `specs/verifications/steps/and-complex-logic-should-include-provenance-links-adrs-jira-or-commits.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-evolve-skill-sync-oversized.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-03-codebase-wiki-venv-pollution.okf.md` (line 0, confidence: medium, method: file_heuristic) @@ -126,6 +125,7 @@ links: - `specs/epics/e39-knowledge-graph/e39s08-integrate-maintain-wiki.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/e39-knowledge-graph/e39s07-maintain-wiki-skill.md` (line 0, confidence: medium, method: file_heuristic) - `.continue/rules/maintain-wiki.md` (line 0, confidence: medium, method: file_heuristic) +- `website/src/content/docs/skills/maintain-wiki.mdx` (line 0, confidence: medium, method: file_heuristic) - `docs/references/agent-config-files-and-okf.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/maintain-wiki.md` (line 0, confidence: medium, method: file_heuristic) - `scripts/okf-post-sync.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e48s02.md b/specs/codebase-wiki/e48s02.md index 7a1bfa52..c130c824 100644 --- a/specs/codebase-wiki/e48s02.md +++ b/specs/codebase-wiki/e48s02.md @@ -44,6 +44,14 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/GOLDEN-2026-07-07.okf.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-2026-07-07.okf.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/GOLDEN-2026-07-06.okf.md line: 0 confidence: medium @@ -96,10 +104,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/audit-compliance-runner.sh + line: 0 + confidence: medium + method: file_heuristic - file: scripts/lib/emit-okf-metrics.sh line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/golden-suite-run.sh + line: 0 + confidence: medium + method: file_heuristic --- # e48s02: Emit verification reports as OKF bundles from run-golden-suite.sh and audit-compliance.sh @@ -119,6 +135,8 @@ links: - `specs/verifications/steps/and-the-skill-packaging-pipeline-round-trips-a-golden-fixture-without-data-loss.sh` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/GOLDEN-2026-07-05.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-2026-07-06.okf.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/GOLDEN-2026-07-07.okf.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-2026-07-07.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/GOLDEN-2026-07-06.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-2026-07-05.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-06-g06-migrate-version-golden.okf.md` (line 0, confidence: medium, method: file_heuristic) @@ -132,4 +150,6 @@ links: - `docs/references/agent-config-files-and-okf.md` (line 0, confidence: medium, method: file_heuristic) - `scripts/run-verification-gates.sh` (line 0, confidence: medium, method: file_heuristic) - `scripts/run-golden-suite.sh` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/audit-compliance-runner.sh` (line 0, confidence: medium, method: file_heuristic) - `scripts/lib/emit-okf-metrics.sh` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/golden-suite-run.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e48s03.md b/specs/codebase-wiki/e48s03.md index 3139b235..2abd1f84 100644 --- a/specs/codebase-wiki/e48s03.md +++ b/specs/codebase-wiki/e48s03.md @@ -376,6 +376,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: website/src/components/cockpit/bug-pulse.tsx + line: 0 + confidence: medium + method: file_heuristic - file: .kilocode/rules/fix-bug.md line: 0 confidence: medium @@ -494,6 +498,7 @@ links: - `.continue/rules/investigate-bug.md` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/fix-bug.mdx` (line 0, confidence: medium, method: file_heuristic) - `website/src/content/docs/skills/investigate-bug.mdx` (line 0, confidence: medium, method: file_heuristic) +- `website/src/components/cockpit/bug-pulse.tsx` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/fix-bug.md` (line 0, confidence: medium, method: file_heuristic) - `.kilocode/rules/investigate-bug.md` (line 0, confidence: medium, method: file_heuristic) - `scripts/sync-bugs-registry.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e48s05.md b/specs/codebase-wiki/e48s05.md index 95254e13..7a103379 100644 --- a/specs/codebase-wiki/e48s05.md +++ b/specs/codebase-wiki/e48s05.md @@ -40,6 +40,14 @@ links: line: 0 confidence: medium method: file_heuristic + - file: specs/verifications/reports/GOLDEN-2026-07-07.okf.md + line: 0 + confidence: medium + method: file_heuristic + - file: specs/verifications/reports/audit-2026-07-07.okf.md + line: 0 + confidence: medium + method: file_heuristic - file: specs/verifications/reports/GOLDEN-2026-07-06.okf.md line: 0 confidence: medium @@ -360,6 +368,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: website/src/lib/okf.ts + line: 0 + confidence: medium + method: file_heuristic - file: docs/references/agent-config-files-and-okf.md line: 0 confidence: medium @@ -376,10 +388,18 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/okf-add-references.py + line: 0 + confidence: medium + method: file_heuristic - file: scripts/lib/emit-okf-metrics.sh line: 0 confidence: medium method: file_heuristic + - file: scripts/lib/validate-okf-kinds.sh + line: 0 + confidence: medium + method: file_heuristic --- # e48s05: Wire OKF validation into CI (sync-skills.yml) and document in OKF authority @@ -398,6 +418,8 @@ links: - `specs/migrations/m1-yaml-cockpit.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/GOLDEN-2026-07-05.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-2026-07-06.okf.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/GOLDEN-2026-07-07.okf.md` (line 0, confidence: medium, method: file_heuristic) +- `specs/verifications/reports/audit-2026-07-07.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/GOLDEN-2026-07-06.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/verifications/reports/audit-2026-07-05.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/bugs/BUG-2026-07-03-venv-not-gitignored.okf.md` (line 0, confidence: medium, method: file_heuristic) @@ -478,8 +500,11 @@ links: - `specs/epics-wiki/e43.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics-wiki/e41.okf.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics-wiki/e18.okf.md` (line 0, confidence: medium, method: file_heuristic) +- `website/src/lib/okf.ts` (line 0, confidence: medium, method: file_heuristic) - `docs/references/agent-config-files-and-okf.md` (line 0, confidence: medium, method: file_heuristic) - `docs/references/okf.md` (line 0, confidence: medium, method: file_heuristic) - `scripts/okf-post-sync.sh` (line 0, confidence: medium, method: file_heuristic) - `scripts/validate-okf.sh` (line 0, confidence: medium, method: file_heuristic) +- `scripts/okf-add-references.py` (line 0, confidence: medium, method: file_heuristic) - `scripts/lib/emit-okf-metrics.sh` (line 0, confidence: medium, method: file_heuristic) +- `scripts/lib/validate-okf-kinds.sh` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/e48s06.md b/specs/codebase-wiki/e48s06.md index 6581bed9..45543741 100644 --- a/specs/codebase-wiki/e48s06.md +++ b/specs/codebase-wiki/e48s06.md @@ -40,6 +40,10 @@ links: line: 0 confidence: medium method: file_heuristic + - file: scripts/okf-add-references.py + line: 0 + confidence: medium + method: file_heuristic --- # e48s06: Add tier: field (core/extended/specialized) to OKF wiki indexes for conditional agent loading @@ -58,3 +62,4 @@ links: - `specs/epics/e39-knowledge-graph/e39s06-okf-agent-guide.md` (line 0, confidence: medium, method: file_heuristic) - `specs/epics/e39-knowledge-graph/e39s05-okf-conventions-wiki.md` (line 0, confidence: medium, method: file_heuristic) - `docs/references/agent-config-files-and-okf.md` (line 0, confidence: medium, method: file_heuristic) +- `scripts/okf-add-references.py` (line 0, confidence: medium, method: file_heuristic) diff --git a/specs/codebase-wiki/index.md b/specs/codebase-wiki/index.md index 8dacc11d..6951687b 100644 --- a/specs/codebase-wiki/index.md +++ b/specs/codebase-wiki/index.md @@ -1,6 +1,6 @@ --- type: Index -generated_at: 2026-07-06T21:34:48.401624+00:00 +generated_at: 2026-07-07T03:20:35.022934+00:00 total_concepts: 55 --- @@ -10,53 +10,53 @@ Auto-generated OKF bundle from trace-stories.sh. | Story | Title | Confidence | Links | |-------|-------|------------|-------| -| [e45s01](./e45s01.md) | run-benchmark: add train/validation-split + with/without-ski | high | 10 | -| [e45s02](./e45s02.md) | craft-skill: CSO description discipline + completion-honesty | medium | 9 | -| [e45s03](./e45s03.md) | CLAUDE.md token mgmt: mechanical PreToolUse hook backstop | high | 3 | -| [e45s04](./e45s04.md) | slice-tasks / plan-work: pre-build cross-artifact consistenc | high | 13 | -| [e45s05](./e45s05.md) | verify-work / gate-trace: adversarial gap-finding completene | medium | 20 | -| [e45s06](./e45s06.md) | tasks.yaml: literal failing→passing task ledger | none | 0 | -| [e45s07](./e45s07.md) | request-review: dual-blind AND-gate review (Santa Method) | medium | 27 | -| [e45s08](./e45s08.md) | develop-tdd / validate-fix: two-commit red/green regression | medium | 9 | -| [e45s09](./e45s09.md) | verify-work / plan-work: Pre-Implementation and Validation g | medium | 60 | -| [e45s10](./e45s10.md) | docs/references: auto-regenerate from source-of-truth docs v | medium | 1 | -| [e45s11](./e45s11.md) | orchestration / dispatch-agents: typed message protocol + 3- | medium | 4 | -| [e45s12](./e45s12.md) | stocktake-skills / craft-skill: code-enforced validator + au | medium | 26 | -| [e45s13](./e45s13.md) | verify-work: one-test-minimum terminal-verdict rule | medium | 10 | -| [e45s14](./e45s14.md) | deepen-architecture: declared import-boundary allowlist enfo | medium | 5 | -| [e45s15](./e45s15.md) | release-branch / deploy: three-independent-facts verificatio | medium | 7 | -| [e45s16](./e45s16.md) | CLAUDE.md rtk mandate: wire rtk-ai/rtk PreToolUse hook | medium | 1 | -| [e45s17](./e45s17.md) | request-review: fan-out to parallel review subagents | medium | 20 | -| [e45s18](./e45s18.md) | audit-code / security-review: worktree-isolated parallel che | medium | 340 | -| [e45s19](./e45s19.md) | Context7: bounded retry cap and explicit fallback block | medium | 6 | -| [e45s20](./e45s20.md) | Context7 / bts docs: wrap in ETag-revalidated fetch cache | none | 0 | -| [e45s21](./e45s21.md) | seed-conventions / AGENTS.md: self-installing fenced markers | medium | 4 | -| [e45s22](./e45s22.md) | CLAUDE.md: context-aware directory routing | medium | 1 | -| [e45s23](./e45s23.md) | CLAUDE.md: live Learned User Preferences / Workspace Facts | none | 0 | +| [e45s01](./e45s01.md) | run-benchmark: add train/validation-split + with/without-ski | high | 15 | +| [e45s02](./e45s02.md) | craft-skill: CSO description discipline + completion-honesty | high | 14 | +| [e45s03](./e45s03.md) | CLAUDE.md token mgmt: mechanical PreToolUse hook backstop | high | 4 | +| [e45s04](./e45s04.md) | slice-tasks / plan-work: pre-build cross-artifact consistenc | high | 15 | +| [e45s05](./e45s05.md) | verify-work / gate-trace: adversarial gap-finding completene | high | 23 | +| [e45s06](./e45s06.md) | tasks.yaml: literal failing→passing task ledger | high | 2 | +| [e45s07](./e45s07.md) | request-review: dual-blind AND-gate review (Santa Method) | high | 30 | +| [e45s08](./e45s08.md) | develop-tdd / validate-fix: two-commit red/green regression | high | 11 | +| [e45s09](./e45s09.md) | verify-work / plan-work: Pre-Implementation and Validation g | high | 63 | +| [e45s10](./e45s10.md) | docs/references: auto-regenerate from source-of-truth docs v | high | 6 | +| [e45s11](./e45s11.md) | orchestration / dispatch-agents: typed message protocol + 3- | high | 5 | +| [e45s12](./e45s12.md) | stocktake-skills / craft-skill: code-enforced validator + au | high | 29 | +| [e45s13](./e45s13.md) | verify-work: one-test-minimum terminal-verdict rule | high | 11 | +| [e45s14](./e45s14.md) | deepen-architecture: declared import-boundary allowlist enfo | high | 7 | +| [e45s15](./e45s15.md) | release-branch / deploy: three-independent-facts verificatio | high | 9 | +| [e45s16](./e45s16.md) | CLAUDE.md rtk mandate: wire rtk-ai/rtk PreToolUse hook | high | 4 | +| [e45s17](./e45s17.md) | request-review: fan-out to parallel review subagents | high | 22 | +| [e45s18](./e45s18.md) | audit-code / security-review: worktree-isolated parallel che | high | 382 | +| [e45s19](./e45s19.md) | Context7: bounded retry cap and explicit fallback block | high | 7 | +| [e45s20](./e45s20.md) | Context7 / bts docs: wrap in ETag-revalidated fetch cache | high | 1 | +| [e45s21](./e45s21.md) | seed-conventions / AGENTS.md: self-installing fenced markers | high | 11 | +| [e45s22](./e45s22.md) | CLAUDE.md: context-aware directory routing | high | 2 | +| [e45s23](./e45s23.md) | CLAUDE.md: live Learned User Preferences / Workspace Facts | high | 6 | | [e45s24](./e45s24.md) | REFERENCE.md files: embedded line-range navigation guides | medium | 2 | -| [e45s25](./e45s25.md) | CONVENTIONS.md risk tiers: compile to versioned, diffable ru | medium | 1 | -| [e45s26](./e45s26.md) | security-review: CWE mapping + 2 positive/2 negative fixture | medium | 4 | -| [e45s27](./e45s27.md) | loop / workflow: terminal-state taxonomy | none | 0 | -| [e45s28](./e45s28.md) | request-review: hard max-iteration cap | medium | 5 | -| [e45s29](./e45s29.md) | requirements: ADDED/MODIFIED/REMOVED/RENAMED tags | none | 0 | -| [e45s30](./e45s30.md) | subagent depth: formalize depth tiers | none | 0 | -| [e45s31](./e45s31.md) | audit-code / deepen-architecture: churn-based look-here-firs | medium | 342 | -| [e45s32](./e45s32.md) | gate-trace / release-branch: adversarial-review refute frami | medium | 19 | -| [e45s33](./e45s33.md) | requirements: per-section approval state | none | 0 | -| [e45s34](./e45s34.md) | develop-tdd: snapshot-before-transition hardening | medium | 5 | -| [e45s35](./e45s35.md) | plan-work: 5 fixed EARS sentence patterns | medium | 5 | -| [e45s36](./e45s36.md) | specs: Documentation Responsibilities table | none | 0 | -| [e45s37](./e45s37.md) | run-evals: graduated eval-strictness tiers | medium | 7 | -| [e45s38](./e45s38.md) | orchestration: why-did-this-stall diagnostic skill | medium | 2 | -| [e45s39](./e45s39.md) | PR generation: literal provenance marker | none | 0 | -| [e45s40](./e45s40.md) | verify-work: mandatory real-browser verification | medium | 10 | -| [e45s41](./e45s41.md) | security-review: proven authorship SQL-safety doctrine | medium | 4 | +| [e45s25](./e45s25.md) | CONVENTIONS.md risk tiers: compile to versioned, diffable ru | high | 4 | +| [e45s26](./e45s26.md) | security-review: CWE mapping + 2 positive/2 negative fixture | high | 13 | +| [e45s27](./e45s27.md) | loop / workflow: terminal-state taxonomy | high | 5 | +| [e45s28](./e45s28.md) | request-review: hard max-iteration cap | high | 10 | +| [e45s29](./e45s29.md) | requirements: ADDED/MODIFIED/REMOVED/RENAMED tags | high | 15 | +| [e45s30](./e45s30.md) | subagent depth: formalize depth tiers | high | 10 | +| [e45s31](./e45s31.md) | audit-code / deepen-architecture: churn-based look-here-firs | high | 384 | +| [e45s32](./e45s32.md) | gate-trace / release-branch: adversarial-review refute frami | high | 21 | +| [e45s33](./e45s33.md) | requirements: per-section approval state | high | 2 | +| [e45s34](./e45s34.md) | develop-tdd: snapshot-before-transition hardening | high | 6 | +| [e45s35](./e45s35.md) | plan-work: 5 fixed EARS sentence patterns | high | 6 | +| [e45s36](./e45s36.md) | specs: Documentation Responsibilities table | high | 1 | +| [e45s37](./e45s37.md) | run-evals: graduated eval-strictness tiers | high | 8 | +| [e45s38](./e45s38.md) | orchestration: why-did-this-stall diagnostic skill | high | 4 | +| [e45s39](./e45s39.md) | PR generation: literal provenance marker | high | 1 | +| [e45s40](./e45s40.md) | verify-work: mandatory real-browser verification | high | 11 | +| [e45s41](./e45s41.md) | security-review: proven authorship SQL-safety doctrine | high | 5 | | [e48s01](./e48s01.md) | Generate epics-wiki and adr-wiki as OKF concept bundles from | high | 23 | -| [e48s02](./e48s02.md) | Emit verification reports as OKF bundles from run-golden-sui | medium | 23 | -| [e48s03](./e48s03.md) | OKF-ify bug-registry: specs/bugs/registry.yaml emits concept | medium | 96 | +| [e48s02](./e48s02.md) | Emit verification reports as OKF bundles from run-golden-sui | medium | 27 | +| [e48s03](./e48s03.md) | OKF-ify bug-registry: specs/bugs/registry.yaml emits concept | medium | 97 | | [e48s04](./e48s04.md) | Create viz.html — interactive force-layout graph companion f | medium | 11 | -| [e48s05](./e48s05.md) | Wire OKF validation into CI (sync-skills.yml) and document i | medium | 93 | -| [e48s06](./e48s06.md) | Add tier: field (core/extended/specialized) to OKF wiki inde | medium | 8 | +| [e48s05](./e48s05.md) | Wire OKF validation into CI (sync-skills.yml) and document i | medium | 98 | +| [e48s06](./e48s06.md) | Add tier: field (core/extended/specialized) to OKF wiki inde | medium | 9 | | [e48s07](./e48s07.md) | Create publish-to-wiki kernel tool | none | 0 | | [e48s08](./e48s08.md) | Add GitHub Action Template for publish-wiki.yml | none | 0 | | [e48s09](./e48s09.md) | Create Wiki Scaffold Templates and provenance header injecti | medium | 2 | diff --git a/specs/conventions-wiki/docs-references-ssot-sync-e45s10.md b/specs/conventions-wiki/docs-references-ssot-sync-e45s10.md new file mode 100644 index 00000000..a5bb3513 --- /dev/null +++ b/specs/conventions-wiki/docs-references-ssot-sync-e45s10.md @@ -0,0 +1,20 @@ +--- +type: Convention +title: docs/references SSOT Sync (e45s10) +context: conventions +--- + +# docs/references SSOT Sync (e45s10) + +Agent-guidance files under `docs/references/` are **distilled from upstream sources**, not hand-edited ad hoc. Canonical inputs live in `CLAUDE.md`, `docs/PRINCIPLES.md`, and `skills/*/SKILL.md`. + +| Action | Command | +|--------|---------| +| Regenerate locally | `bash scripts/sync-references.sh` | +| Manifest | `scripts/references-manifest.yaml` | +| Scheduled CI | `.github/workflows/sync-references.yml` (weekly) | + +After changing SKILL.md `model:` frontmatter or token-management prose in CLAUDE.md, run `sync-references.sh` to refresh reference docs and `.sync-stamp`. + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/documentation-responsibilities-e45s36.md b/specs/conventions-wiki/documentation-responsibilities-e45s36.md new file mode 100644 index 00000000..2b8227dc --- /dev/null +++ b/specs/conventions-wiki/documentation-responsibilities-e45s36.md @@ -0,0 +1,32 @@ +--- +type: Convention +title: Documentation Responsibilities (e45s36) +context: conventions +--- + +# Documentation Responsibilities (e45s36) + +Each specs/ artifact owns specific facts. Update the owning file when the fact changes — do not duplicate across files. + +| File / directory | Owns | Update when | +|------------------|------|-------------| +| `specs/state.yaml` | Active session, handoff, story timing, workflow mode | Every skill handoff; branch switch; story start/end | +| `specs/release-plan.yaml` | Epic ordering, WSJF, BCP baselines, release codename | New epic scoped; WSJF re-prioritized; BCP re-estimated | +| `specs/execution-status.yaml` | Story/epic done/todo status (sole SoT) | Story completes; gate-trace runs; manual status change | +| `specs/product/SCOPE_LATEST.yaml` | In/out of scope, initiative boundaries | scope-work; change-request Add mode | +| `specs/product/VISION_LATEST.yaml` | North star, strategic intent | Major product pivot; scope-work | +| `specs/product/GLOSSARY_LATEST.yaml` | Canonical domain terms | define-language; model-domain term crystallizes | +| `specs/epics/eNN-*/epic.yaml` | Epic manifest, story list, BCPs | slice-tasks; plan-work adds stories | +| `specs/epics/eNN-*/eNNsYY-*.md` | Story requirements (countable-story-format) | plan-work; section approval state changes | +| `specs/epics/eNN-*/eNNsYY-tasks.yaml` | Runnable implementation tasks + verify | plan-work; develop-tdd task completion | +| `specs/tech-architecture/tech-stack.md` | Stack, modules, gray areas | map-codebase; deepen-architecture; model-domain | +| `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` | P0/P1 test scenarios per epic | plan-tests | +| `specs/adr/ADR-*.md` | Architectural decisions | model-domain; deepen-architecture ADR offer accepted | +| `specs/bugs/BUG-*.md` | Bug RCA + fix plan | investigate-bug | +| `specs/bugs/registry.yaml` | Bug index (generated) | inspect-quality; sync-bugs-registry.sh | +| `specs/verifications/*` | Verify evidence, audit reports, eval reports | verify-work; audit-code; run-evals | +| `specs/security/REVIEW.md` | Latest security scan findings | security-review | +| `specs/metrics/cycle-times.yaml` | Delivery velocity ledger | release-branch lands story | + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/index.md b/specs/conventions-wiki/index.md index 1ab551b4..b31224ce 100644 --- a/specs/conventions-wiki/index.md +++ b/specs/conventions-wiki/index.md @@ -18,6 +18,11 @@ context: conventions - [Agent Workflow Mandates](agent-workflow-mandates.md) - [Always Green / Shift Left](always-green-shift-left.md) - [Discovered Defects](discovered-defects.md) +- [Risk Tiers (Effective Rule Matrix)](risk-tiers-effective-rule-matrix.md) +- [P0 — Critical (never violate)](p0-critical-never-violate.md) +- [P1 — High (fix before merge)](p1-high-fix-before-merge.md) +- [P2 — Medium (address in same epic or next)](p2-medium-address-in-same-epic-or-next.md) +- [P3 — Low (best effort)](p3-low-best-effort.md) - [Banned dismissive phrases](banned-dismissive-phrases.md) - [specs/ — All Planning Output Goes Here](specs-all-planning-output-goes-here.md) - [YAML cockpit (runtime + delivery)](yaml-cockpit-runtime-delivery.md) @@ -28,6 +33,7 @@ context: conventions - [Frozen release (ex-baseline)](frozen-release-ex-baseline.md) - [Semantic-release — the real version is never hand-tracked](semantic-release-the-real-version-is-never-hand-tracked.md) - [Guardrails and other artifacts](guardrails-and-other-artifacts.md) +- [Documentation Responsibilities (e45s36)](documentation-responsibilities-e45s36.md) - [Generated artifact targets](generated-artifact-targets.md) - [Legacy paths (migrate away)](legacy-paths-migrate-away.md) - [Code Style](code-style.md) @@ -40,3 +46,4 @@ context: conventions - [Defensive Code](defensive-code.md) - [Skill Naming — Conventions and Exceptions](skill-naming-conventions-and-exceptions.md) - [File-Size Exceptions](file-size-exceptions.md) +- [docs/references SSOT Sync (e45s10)](docs-references-ssot-sync-e45s10.md) diff --git a/specs/conventions-wiki/p0-critical-never-violate.md b/specs/conventions-wiki/p0-critical-never-violate.md new file mode 100644 index 00000000..41904a83 --- /dev/null +++ b/specs/conventions-wiki/p0-critical-never-violate.md @@ -0,0 +1,15 @@ +--- +type: Convention +title: P0 — Critical (never violate) +context: conventions +--- + +# P0 — Critical (never violate) + +- **[always-green]**: Preflight and CI must be green before forward work. (`verify-work`, `kickoff-branch`, `develop-tdd`) +- **[no-direct-coding]**: Route feature work through bigpowers skills — no ad-hoc implementation without a plan in `specs/`. (`plan-work`, `orchestrate-project`) +- **[traceability]**: Every story has ≥1 `story: eNNsNN` tag in implementing code or tests. (`trace-stories.sh --strict`) +- **[no-generated-edits]**: Never edit `.cursor/rules/`, `.gemini/`, or `website/src/content/docs/` directly. (`sync-skills.sh`) + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/p1-high-fix-before-merge.md b/specs/conventions-wiki/p1-high-fix-before-merge.md new file mode 100644 index 00000000..192b6f86 --- /dev/null +++ b/specs/conventions-wiki/p1-high-fix-before-merge.md @@ -0,0 +1,15 @@ +--- +type: Convention +title: P1 — High (fix before merge) +context: conventions +--- + +# P1 — High (fix before merge) + +- **[conventional-commits]**: All commits follow Conventional Commits; semantic-release owns version bumps. (`commit-message`, `release-branch`) +- **[verify-per-story]**: Every story/task has runnable `verify:` commands; `verify-work` confirms before done. (`plan-work`, `verify-work`) +- **[test-on-change]**: New functions and bug fixes include tests; regressions get regression tests. (`develop-tdd`, `validate-fix`) +- **[branch-protection]**: No direct work on `main`/`master`; feature branches via `kickoff-branch`. (`guard-git`) + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/p2-medium-address-in-same-epic-or-next.md b/specs/conventions-wiki/p2-medium-address-in-same-epic-or-next.md new file mode 100644 index 00000000..f6fff925 --- /dev/null +++ b/specs/conventions-wiki/p2-medium-address-in-same-epic-or-next.md @@ -0,0 +1,15 @@ +--- +type: Convention +title: P2 — Medium (address in same epic or next) +context: conventions +--- + +# P2 — Medium (address in same epic or next) + +- **[plan-tests-waiver]**: P2/P3-dominant epics may set `test_plan: waived` in `state.yaml`. (`plan-tests`) +- **[file-size-cap]**: Source files under 300 lines unless listed in § File-Size Exceptions. (`audit-code`) +- **[handoff-signaling]**: Critical-path skills write `handoff.next_skill` to `state.yaml`. (`session-state`) +- **[delta-requirements]**: Behavior changes require `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` tags in requirement specs. (`plan-work`, `change-request`) + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/p3-low-best-effort.md b/specs/conventions-wiki/p3-low-best-effort.md new file mode 100644 index 00000000..434c746f --- /dev/null +++ b/specs/conventions-wiki/p3-low-best-effort.md @@ -0,0 +1,14 @@ +--- +type: Convention +title: P3 — Low (best effort) +context: conventions +--- + +# P3 — Low (best effort) + +- **[boy-scout]**: Leave touched files at least as clean as found. (`audit-code`) +- **[terse-when-heavy]**: Switch to `terse-mode` when context exceeds ~20 turns. (`terse-mode`) +- **[skill-naming]**: Verb-noun kebab-case under `skills/`; documented exceptions only. (`craft-skill`) + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/conventions-wiki/risk-tiers-effective-rule-matrix.md b/specs/conventions-wiki/risk-tiers-effective-rule-matrix.md new file mode 100644 index 00000000..e9b78ded --- /dev/null +++ b/specs/conventions-wiki/risk-tiers-effective-rule-matrix.md @@ -0,0 +1,18 @@ +--- +type: Convention +title: Risk Tiers (Effective Rule Matrix) +context: conventions +--- + +# Risk Tiers (Effective Rule Matrix) + +Human-readable source of truth for verification depth. Machine-readable compile: + +```bash +bash scripts/compile-rule-matrix.sh # → specs/rule-matrix.json +``` + +Diff `specs/rule-matrix.json` across git tags to audit rule drift. Schema version in JSON `matrix_version` field. + +--- +*Auto-generated by scripts/decompose-conventions.sh (e39s05)* diff --git a/specs/epics/e45-quality-core/epic.yaml b/specs/epics/e45-quality-core/epic.yaml index c4fadab7..e6a1ffc3 100644 --- a/specs/epics/e45-quality-core/epic.yaml +++ b/specs/epics/e45-quality-core/epic.yaml @@ -2,7 +2,7 @@ id: e45 title: Quality Core — Skill Hardening & Verification Patterns wsjf: 5.0 bcps: 45 -status: planned + status: done mode: capsule capsule_dir: epics/e45-quality-core release: v2.9x @@ -16,7 +16,7 @@ stories: bcp: 3 title: 'run-benchmark: add train/validation-split + with/without-skill delta grading' source: anthropics/skills — eval methodology (3 runs, 0.5 threshold, benchmark.json) - status: todo + status: done risk: P1 verify: 'bigpowers-benchmark results include pass-rate vs. token-cost delta per skill; @@ -29,7 +29,7 @@ stories: title: 'craft-skill: CSO description discipline + completion-honesty gate' source: obra/superpowers — TDD-for-documentation, verification-before-completion Iron Law - status: todo + status: done risk: P1 verify: 'Every SKILL.md description is <1024 chars, avoids workflow-summary leakage. @@ -40,7 +40,7 @@ stories: bcp: 3 title: 'CLAUDE.md token mgmt: mechanical PreToolUse hook backstop' source: mksglu/context-mode — Bash/Read/Grep/WebFetch blocking on oversized calls - status: todo + status: done risk: P1 verify: 'PreToolUse hook fires when Read >100KB, Bash output >500 lines, Grep >200 matches. @@ -52,7 +52,7 @@ stories: bcp: 3 title: 'slice-tasks / plan-work: pre-build cross-artifact consistency pass' source: github/spec-kit — 9-category ambiguity taxonomy, CRITICAL/HIGH/MED/LOW severity - status: todo + status: done risk: P1 verify: 'New `plan-work` sub-step reads slice-tasks output against epic capsule spec and @@ -64,7 +64,7 @@ stories: bcp: 4 title: 'verify-work / gate-trace: adversarial gap-finding completeness critic' source: open-gsd/gsd-core — gsd-nyquist-auditor, BLOCKER/WARNING/FILLED classification - status: todo + status: done risk: P1 verify: 'Post-gate-trace step runs completeness critic; classified findings printed. @@ -76,7 +76,7 @@ stories: title: 'tasks.yaml: literal failing→passing task ledger' source: modu-ai/moai-adk — Failing Checklist, acceptance criteria as pending/failing tasks - status: todo + status: done risk: P1 verify: 'New tasks.yaml entries start with `status: failing`. @@ -87,7 +87,7 @@ stories: bcp: 2 title: 'request-review: dual-blind AND-gate review (Santa Method)' source: affaan-m/ECC — Santa Method & Council - status: todo + status: done risk: P1 verify: 'request-review uses 2 independent reviewers, max 3 iterations, and requires an AND-gate pass from both. @@ -97,7 +97,7 @@ stories: bcp: 2 title: 'develop-tdd / validate-fix: two-commit red/green regression policy' source: manaflow-ai/cmux — two-commit red/green regression policy - status: todo + status: done risk: P1 verify: 'develop-tdd enforces a test-only commit (red in CI) followed by a fix commit (green). @@ -107,7 +107,7 @@ stories: bcp: 2 title: 'verify-work / plan-work: Pre-Implementation and Validation gates' source: netdata/netdata — SOW lifecycle system - status: todo + status: done risk: P1 verify: 'Epic/story lifecycle gates include Pre-Implementation (root-cause/risk), Validation, and reopen-don''t-refile for regressions. @@ -118,7 +118,7 @@ stories: title: 'docs/references: auto-regenerate from source-of-truth docs via scheduled sync' source: gitlabhq/gitlabhq — SSOT-distillation pipeline - status: todo + status: done risk: P1 verify: 'Agent-guidance docs (e.g. references/*.md) are auto-regenerated from upstream sources via a scheduled job to prevent staleness. @@ -129,7 +129,7 @@ stories: title: 'orchestration / dispatch-agents: typed message protocol + 3-failure circuit breaker' source: stablyai/orca — Typed inter-agent message protocol - status: todo + status: done risk: P1 verify: 'dispatch-agents implements a 3-consecutive-failure circuit breaker and checkpoint-comment progress signals. @@ -139,7 +139,7 @@ stories: bcp: 2 title: 'stocktake-skills / craft-skill: code-enforced validator + auto-archiving' source: nousresearch/hermes-agent — Curator daemon & validator - status: todo + status: done risk: P1 verify: 'craft-skill and stocktake-skills enforce catalog hygiene via code validator script and usage-based archiving. @@ -149,7 +149,7 @@ stories: bcp: 2 title: 'verify-work: one-test-minimum terminal-verdict rule' source: TestSprite/testsprite-cli — one-test-minimum rule - status: todo + status: done risk: P1 verify: 'verify-work requires at least one real terminal-verdict run; bug reports cannot combine evidence across runs. @@ -159,7 +159,7 @@ stories: bcp: 2 title: 'deepen-architecture: declared import-boundary allowlist enforced in CI' source: microsoft/playwright — DEPS.list - status: todo + status: done risk: P1 verify: 'deepen-architecture and CI enforce hard import boundaries via a checked-in allowlist rather than convention docs. @@ -169,7 +169,7 @@ stories: bcp: 2 title: 'release-branch / deploy: three-independent-facts verification' source: tw93/pake — Three-independent-facts release verification - status: todo + status: done risk: P1 verify: 'release-branch/deploy separately verify commit tag, workflow run, and registry-visible facts before declaring success. @@ -179,7 +179,7 @@ stories: bcp: 2 title: 'CLAUDE.md rtk mandate: wire rtk-ai/rtk PreToolUse hook' source: rtk-ai/rtk — rtk-rewrite.sh hook - status: todo + status: done risk: P1 verify: 'Wire rtk''s native PreToolUse hook mechanically instead of relying on prose rules. @@ -189,7 +189,7 @@ stories: bcp: 2 title: 'request-review: fan-out to parallel review subagents' source: openai/codex — code-review-* fan-out - status: todo + status: done risk: P1 verify: 'request-review orchestrates N parallel subagents, one per check, to broaden review coverage. @@ -199,7 +199,7 @@ stories: bcp: 2 title: 'audit-code / security-review: worktree-isolated parallel checks' source: continuedev/continue — cn check worktree isolation - status: todo + status: done risk: P1 verify: 'Parallel checks run in isolated git worktrees so they cannot corrupt each other. @@ -209,7 +209,7 @@ stories: bcp: 2 title: 'Context7: bounded retry cap and explicit fallback block' source: upstash/context7 — Bounded retry cap (max 3x) - status: todo + status: done risk: P1 verify: 'Context7 mandate requires explicit quota error statements rather than silent fallbacks to training data. @@ -219,7 +219,7 @@ stories: bcp: 2 title: 'Context7 / bts docs: wrap in ETag-revalidated fetch cache' source: addyosmani/agent-skills — sdd-cache Pre/PostToolUse hook - status: todo + status: done risk: P1 verify: 'Consecutive identical doc queries within TTL return cached response (no HTTP round-trip). @@ -231,7 +231,7 @@ stories: bcp: 2 title: 'seed-conventions / AGENTS.md: self-installing fenced markers' source: vercel-labs/opensrc — Self-installing fenced markers - status: todo + status: done risk: P2 verify: 'Skills that write into CLAUDE.md/AGENTS.md use fenced markers to avoid clobbering handwritten content. @@ -241,7 +241,7 @@ stories: bcp: 2 title: 'CLAUDE.md: context-aware directory routing' source: getsentry/sentry — Context-aware directory routing - status: todo + status: done risk: P2 verify: 'Root doc tells agents which sub-AGENTS.md to load by file glob to simplify doc surface. @@ -251,7 +251,7 @@ stories: bcp: 2 title: 'CLAUDE.md: live Learned User Preferences / Workspace Facts' source: neondatabase/neon-js — Live Learned Workspace Facts - status: todo + status: done risk: P2 verify: 'Durable facts live directly in CLAUDE.md alongside session-state. @@ -260,7 +260,7 @@ stories: bcp: 2 title: 'REFERENCE.md files: embedded line-range navigation guides' source: AcnLabs/MetaSpec — precision-guided navigation, 84-99% token reduction - status: todo + status: done risk: P2 verify: 'Every REFERENCE.md >100 lines includes a `## Navigation` section with @@ -272,7 +272,7 @@ stories: bcp: 4 title: 'CONVENTIONS.md risk tiers: compile to versioned, diffable rule matrix' source: QuasarByte/feature-driven-flow — Effective Rule Matrix, JSON schema-validated - status: todo + status: done risk: P2 verify: '`bash scripts/compile-rule-matrix.sh` emits `specs/rule-matrix.json` with @@ -284,7 +284,7 @@ stories: bcp: 2 title: 'security-review: CWE mapping + 2 positive/2 negative fixtures' source: securego/gosec — New rules require CWE mapping - status: todo + status: done risk: P2 verify: 'security-review requires new detection rules to map to CWE and include 2 positive/negative fixture pairs. @@ -295,7 +295,7 @@ stories: bcp: 2 title: 'loop / workflow: terminal-state taxonomy' source: alirezarezvani/claude-skills — Terminal-state taxonomy - status: todo + status: done risk: P2 verify: 'Harden loop skill with explicit terminal states (success/no-op/blocked/exhausted). @@ -305,7 +305,7 @@ stories: bcp: 2 title: 'request-review: hard max-iteration cap' source: greptileai/skills — Hard max-iteration cap (5) - status: todo + status: done risk: P2 verify: 'request-review enforces an explicit numeric cap on agent-vs-reviewer disagreement cycles. @@ -316,7 +316,7 @@ stories: bcp: 2 title: 'requirements: ADDED/MODIFIED/REMOVED/RENAMED tags' source: Fission-AI/OpenSpec — Delta-spec proposal format - status: todo + status: done risk: P2 verify: 'Stories modifying existing behavior require mandatory before/after content in requirement specs. @@ -327,7 +327,7 @@ stories: bcp: 2 title: 'subagent depth: formalize depth tiers' source: gsd-build/get-shit-done — full_maturity / standard / minimal_decisive tiers - status: todo + status: done risk: P2 verify: 'Formalize risk/effort fields into explicit subagent-prompt depth tiers. @@ -337,7 +337,7 @@ stories: bcp: 2 title: 'audit-code / deepen-architecture: churn-based look-here-first heuristic' source: paralleldrive/aidd — aidd-churn - status: todo + status: done risk: P2 verify: 'Review processes rank files by code-churn/hotspot to concentrate effort on actual risk. @@ -348,7 +348,7 @@ stories: bcp: 2 title: 'gate-trace / release-branch: adversarial-review refute framing' source: LIDR-academy/lidr-specboot — Adversarial-review gate - status: todo + status: done risk: P2 verify: 'Add explicit ''refute, not rubber-stamp'' framing to the final check of release-branch. @@ -359,7 +359,7 @@ stories: bcp: 2 title: 'requirements: per-section approval state' source: ArcBlock/idd — Section-level locked / reviewed / draft markup - status: todo + status: done risk: P2 verify: 'Epic capsule requirements enforce per-section approval state to prevent silent rewrites. @@ -370,7 +370,7 @@ stories: bcp: 2 title: 'develop-tdd: snapshot-before-transition hardening' source: sengac/fspec — Auto-checkpoint before transition - status: todo + status: done risk: P2 verify: 'develop-tdd red-green-refactor loop creates a checkpoint before phase transitions. @@ -380,7 +380,7 @@ stories: bcp: 2 title: 'plan-work: 5 fixed EARS sentence patterns' source: gotalab/cc-sdd — EARS-format requirements - status: todo + status: done risk: P2 verify: 'plan-work enforces EARS patterns (Event/State/Unwanted/Optional/Ubiquitous) to catch ambiguity. @@ -391,7 +391,7 @@ stories: bcp: 2 title: 'specs: Documentation Responsibilities table' source: cline/cline — Documentation Responsibilities table - status: todo + status: done risk: P2 verify: 'Map specs/ files to the facts they own and what triggers an update. @@ -401,7 +401,7 @@ stories: bcp: 2 title: 'run-evals: graduated eval-strictness tiers' source: google-gemini/gemini-cli — USUALLY_PASSES vs ALWAYS_PASSES - status: todo + status: done risk: P2 verify: 'run-evals supports promotion tiers for tests instead of flat pass/fail. @@ -411,7 +411,7 @@ stories: bcp: 2 title: 'orchestration: why-did-this-stall diagnostic skill' source: paperclipai/paperclip — diagnose-why-work-stopped - status: todo + status: done risk: P2 verify: 'Provide a diagnostic skill to explicitly handle silent stalls in /loop and dispatch-agents. @@ -422,7 +422,7 @@ stories: bcp: 2 title: 'PR generation: literal provenance marker' source: vitest-dev/vitest — Auto-labeled maybe automated - status: todo + status: done risk: P2 verify: 'Agent-generated PRs carry a literal provenance marker to prevent them from rotting silently. @@ -433,7 +433,7 @@ stories: bcp: 2 title: 'verify-work: mandatory real-browser verification' source: withastro/astro — Mandatory real-browser verification - status: todo + status: done risk: P2 verify: 'Sharpens verify instruction to hard fail if a required real-browser test tool isn''t installed. @@ -444,7 +444,7 @@ stories: bcp: 2 title: 'security-review: proven authorship SQL-safety doctrine' source: supabase/supabase — Proven authorship SQL-safety - status: todo + status: done risk: P2 verify: 'Formalize rule that hardcoded/explicitly-authored SQL is safe, but anything attacker-reachable is not. diff --git a/specs/execution-status.yaml b/specs/execution-status.yaml index 63799822..b8447833 100644 --- a/specs/execution-status.yaml +++ b/specs/execution-status.yaml @@ -248,48 +248,48 @@ development_status: e44s04: done e44s05: done e44s06: done - e45: planned - e45s01: todo - e45s02: todo - e45s03: todo - e45s04: todo - e45s05: todo - e45s06: todo - e45s07: todo - e45s08: todo - e45s09: todo - e45s10: todo - e45s11: todo - e45s12: todo - e45s13: todo - e45s14: todo - e45s15: todo - e45s16: todo - e45s17: todo - e45s18: todo - e45s19: todo - e45s20: todo - e45s21: todo - e45s22: todo - e45s23: todo - e45s24: todo - e45s25: todo - e45s26: todo - e45s27: todo - e45s28: todo - e45s29: todo - e45s30: todo - e45s31: todo - e45s32: todo - e45s33: todo - e45s34: todo - e45s35: todo - e45s36: todo - e45s37: todo - e45s38: todo - e45s39: todo - e45s40: todo - e45s41: todo + e45: done + e45s01: done + e45s02: done + e45s03: done + e45s04: done + e45s05: done + e45s06: done + e45s07: done + e45s08: done + e45s09: done + e45s10: done + e45s11: done + e45s12: done + e45s13: done + e45s14: done + e45s15: done + e45s16: done + e45s17: done + e45s18: done + e45s19: done + e45s20: done + e45s21: done + e45s22: done + e45s23: done + e45s24: done + e45s25: done + e45s26: done + e45s27: done + e45s28: done + e45s29: done + e45s30: done + e45s31: done + e45s32: done + e45s33: done + e45s34: done + e45s35: done + e45s36: done + e45s37: done + e45s38: done + e45s39: done + e45s40: done + e45s41: done e46: done e46s01: done e46s02: done diff --git a/specs/import-boundaries.json b/specs/import-boundaries.json new file mode 100644 index 00000000..03b4ff1a --- /dev/null +++ b/specs/import-boundaries.json @@ -0,0 +1,42 @@ +{ + "version": 1, + "story": "e45s14", + "description": "Declared import-boundary allowlist for scripts/lib (Playwright DEPS.list pattern). CI enforces via scripts/check-import-boundaries.sh.", + "boundaries": [ + { + "from": "scripts/*.sh", + "allow": [ + "scripts/lib/*.sh", + "guard-git/scripts/*.sh" + ], + "deny": [ + "skills/*", + "website/*" + ] + }, + { + "from": "scripts/lib/golden-suite-run.sh", + "allow": [ + "scripts/lib/golden-suite-gates.sh", + "scripts/lib/golden-suite-agent.sh", + "scripts/lib/golden-suite-report.sh" + ] + }, + { + "from": "scripts/lib/migrate-version-run.sh", + "allow": [ + "scripts/lib/migrate-version-common.sh", + "scripts/lib/migrate-version-plan.sh", + "scripts/lib/migrate-version-transforms.sh", + "scripts/lib/migrate-version-execute.sh", + "scripts/lib/migrate-version-post.sh" + ] + }, + { + "from": "scripts/lib/audit-compliance-runner.sh", + "allow": [ + "scripts/lib/audit-compliance-judge.sh" + ] + } + ] +} diff --git a/specs/release-plan.yaml b/specs/release-plan.yaml index 6d7c80fe..b4de1516 100644 --- a/specs/release-plan.yaml +++ b/specs/release-plan.yaml @@ -90,7 +90,7 @@ epics: bcps: 45 capsule_dir: epics/e45-quality-core mode: capsule - status: planned + status: done wsjf_rationale: BV 7 (skill quality compounds) + TC 4 (OSS pattern debt) + RR 6 (benchmark/evidence parity) / Job 4 ≈ 5.0. Curated P1 from former e48; P2 optional wave. - id: e48 diff --git a/specs/rule-matrix.json b/specs/rule-matrix.json new file mode 100644 index 00000000..b0ffbc72 --- /dev/null +++ b/specs/rule-matrix.json @@ -0,0 +1,129 @@ +{ + "generated_at": "2026-07-07T03:07:38Z", + "matrix_version": "1.0.0", + "source": "CONVENTIONS.md", + "source_hash": "77d7e4d49b562a2c", + "source_section": "Risk Tiers (Effective Rule Matrix)", + "tiers": { + "P0": [ + { + "enforce": [ + "verify-work", + "kickoff-branch", + "develop-tdd" + ], + "id": "always-green", + "text": "Preflight and CI must be green before forward work" + }, + { + "enforce": [ + "plan-work", + "orchestrate-project" + ], + "id": "no-direct-coding", + "text": "Route feature work through bigpowers skills \u2014 no ad-hoc implementation without a plan in `specs/`" + }, + { + "enforce": [ + "trace-stories.sh --strict" + ], + "id": "traceability", + "text": "Every story has \u22651 `story: eNNsNN` tag in implementing code or tests" + }, + { + "enforce": [ + "sync-skills.sh" + ], + "id": "no-generated-edits", + "text": "Never edit `.cursor/rules/`, `.gemini/`, or `website/src/content/docs/` directly" + } + ], + "P1": [ + { + "enforce": [ + "commit-message", + "release-branch" + ], + "id": "conventional-commits", + "text": "All commits follow Conventional Commits; semantic-release owns version bumps" + }, + { + "enforce": [ + "plan-work", + "verify-work" + ], + "id": "verify-per-story", + "text": "Every story/task has runnable `verify:` commands; `verify-work` confirms before done" + }, + { + "enforce": [ + "develop-tdd", + "validate-fix" + ], + "id": "test-on-change", + "text": "New functions and bug fixes include tests; regressions get regression tests" + }, + { + "enforce": [ + "guard-git" + ], + "id": "branch-protection", + "text": "No direct work on `main`/`master`; feature branches via `kickoff-branch`" + } + ], + "P2": [ + { + "enforce": [ + "plan-tests" + ], + "id": "plan-tests-waiver", + "text": "P2/P3-dominant epics may set `test_plan: waived` in `state.yaml`" + }, + { + "enforce": [ + "audit-code" + ], + "id": "file-size-cap", + "text": "Source files under 300 lines unless listed in \u00a7 File-Size Exceptions" + }, + { + "enforce": [ + "session-state" + ], + "id": "handoff-signaling", + "text": "Critical-path skills write `handoff.next_skill` to `state.yaml`" + }, + { + "enforce": [ + "plan-work", + "change-request" + ], + "id": "delta-requirements", + "text": "Behavior changes require `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` tags in requirement specs" + } + ], + "P3": [ + { + "enforce": [ + "audit-code" + ], + "id": "boy-scout", + "text": "Leave touched files at least as clean as found" + }, + { + "enforce": [ + "terse-mode" + ], + "id": "terse-when-heavy", + "text": "Switch to `terse-mode` when context exceeds ~20 turns" + }, + { + "enforce": [ + "craft-skill" + ], + "id": "skill-naming", + "text": "Verb-noun kebab-case under `skills/`; documented exceptions only" + } + ] + } +} diff --git a/specs/state.yaml b/specs/state.yaml index c16e763f..47cc193a 100644 --- a/specs/state.yaml +++ b/specs/state.yaml @@ -5,12 +5,21 @@ bug_id: null bigpowers_version: 2.73.9 bug_cycle: null handoff: - context: BUG-2026-07-06-gate-trace-matrix-oversized fixed — trace-matrix.py split to 252 lines - next_skill: null + context: "e45 complete — all 41 stories s01-s41 implemented on feat/e45-quality-core" + next_skill: release-branch epic: e45 +epic_cycle: + step: 8 + current_step: 8 + story: e45s41 + story_bcps: 2 + yolo_mode: true + fast_mode: true + completed_steps: ["0","1","2","3","4","5","6","7","8"] + audit_result: pass metrics: - story_start: null - story_end: null + story_start: "2026-07-07T02:53:00Z" + story_end: "2026-07-07T03:25:00Z" skill_timings: release-branch: calls: 5 diff --git a/specs/traceability-matrix.json b/specs/traceability-matrix.json index bc00a3ab..58f7f0d4 100644 --- a/specs/traceability-matrix.json +++ b/specs/traceability-matrix.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-07-06T21:34:48.397269+00:00", + "generated_at": "2026-07-07T03:20:35.010716+00:00", "matrix_version": "1.0", "stories": [ { @@ -11,18 +11,48 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "specs/state.yaml", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "specs/state.yaml", + "line": 14, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/run-benchmark.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "scripts/generate-adr-wiki.sh", "line": 2, "confidence": "high", "method": "explicit_tag" }, + { + "file": "scripts/lib/run-benchmark.py", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "scripts/generate-epics-wiki.sh", "line": 2, "confidence": "high", "method": "explicit_tag" }, + { + "file": "skills/run-benchmark/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/run-benchmark.md", "line": 0, @@ -72,7 +102,7 @@ "method": "file_heuristic" } ], - "link_count": 10 + "link_count": 15 }, { "id": "e45s02", @@ -83,6 +113,36 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/lib/audit-compliance-judge.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/lib/audit-compliance-runner.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/lib/audit-compliance-report.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/validate-skill-description.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/craft-skill/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/craft-skill.md", "line": 0, @@ -138,7 +198,7 @@ "method": "file_heuristic" } ], - "link_count": 9 + "link_count": 14 }, { "id": "e45s03", @@ -166,9 +226,15 @@ "line": 80, "confidence": "high", "method": "explicit_tag" + }, + { + "file": "scripts/hooks/token-mgmt-pre-tool-use.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" } ], - "link_count": 3 + "link_count": 4 }, { "id": "e45s04", @@ -185,6 +251,18 @@ "confidence": "high", "method": "explicit_tag" }, + { + "file": "scripts/lib/plan-consistency-check.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/plan-work/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/slice-tasks.md", "line": 0, @@ -258,7 +336,7 @@ "method": "file_heuristic" } ], - "link_count": 13 + "link_count": 15 }, { "id": "e45s05", @@ -269,6 +347,24 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/lib/completeness-critic.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/verify-work/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/gate-trace/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/gate-trace.md", "line": 0, @@ -390,7 +486,7 @@ "method": "file_heuristic" } ], - "link_count": 20 + "link_count": 23 }, { "id": "e45s06", @@ -400,8 +496,21 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": "skills/plan-work/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/develop-tdd/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 2 }, { "id": "e45s07", @@ -412,6 +521,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/request-review/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/request-review/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/DEEPEN-ARCHITECTURE-REVIEW.md", "line": 0, @@ -573,9 +694,15 @@ "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/lib/parallel-review-worktrees.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 27 + "link_count": 30 }, { "id": "e45s08", @@ -586,6 +713,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/validate-fix/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/develop-tdd/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/develop-tdd.md", "line": 0, @@ -641,7 +780,7 @@ "method": "file_heuristic" } ], - "link_count": 9 + "link_count": 11 }, { "id": "e45s09", @@ -652,6 +791,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/plan-work/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/verify-work/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/WORKFLOW-solo-git.md", "line": 0, @@ -1011,9 +1162,15 @@ "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/lib/parallel-review-worktrees.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 60 + "link_count": 63 }, { "id": "e45s10", @@ -1024,6 +1181,36 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "CONVENTIONS.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/references-manifest.yaml", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/lib/sync-context-engineering-ref.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/sync-references.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".github/workflows/sync-references.yml", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "scripts/sync-status-from-epics.sh", "line": 0, @@ -1031,7 +1218,7 @@ "method": "file_heuristic" } ], - "link_count": 1 + "link_count": 6 }, { "id": "e45s11", @@ -1042,6 +1229,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/dispatch-agents/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/dispatch-agents.md", "line": 0, @@ -1067,7 +1260,7 @@ "method": "file_heuristic" } ], - "link_count": 4 + "link_count": 5 }, { "id": "e45s12", @@ -1078,6 +1271,24 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/validate-skill-catalog.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/craft-skill/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/stocktake-skills/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "skills-lock.json", "line": 0, @@ -1235,7 +1446,7 @@ "method": "file_heuristic" } ], - "link_count": 26 + "link_count": 29 }, { "id": "e45s13", @@ -1246,6 +1457,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/verify-work/SKILL.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/verify-work.md", "line": 0, @@ -1307,7 +1524,7 @@ "method": "file_heuristic" } ], - "link_count": 10 + "link_count": 11 }, { "id": "e45s14", @@ -1318,6 +1535,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/check-import-boundaries.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/deepen-architecture/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/DEEPEN-ARCHITECTURE-REVIEW.md", "line": 0, @@ -1349,7 +1578,7 @@ "method": "file_heuristic" } ], - "link_count": 5 + "link_count": 7 }, { "id": "e45s15", @@ -1360,6 +1589,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/deploy/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/release-branch/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/release-branch.md", "line": 0, @@ -1403,7 +1644,7 @@ "method": "file_heuristic" } ], - "link_count": 7 + "link_count": 9 }, { "id": "e45s16", @@ -1414,6 +1655,24 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/install.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/install.sh", + "line": 88, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/hooks/rtk-rewrite.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/agent-guide/rtk-commands-by-workflow.md", "line": 0, @@ -1421,7 +1680,7 @@ "method": "file_heuristic" } ], - "link_count": 1 + "link_count": 4 }, { "id": "e45s17", @@ -1432,6 +1691,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/request-review/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/DEEPEN-ARCHITECTURE-REVIEW.md", "line": 0, @@ -1551,9 +1816,15 @@ "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/lib/parallel-review-worktrees.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 20 + "link_count": 22 }, { "id": "e45s18", @@ -1565,13 +1836,31 @@ "status": "todo", "links": [ { - "file": "specs/skills-wiki/skills/security-review.md", - "line": 0, - "confidence": "medium", - "method": "file_heuristic" + "file": "scripts/lib/parallel-review-worktrees.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" }, { - "file": "specs/skills-wiki/skills/audit-code.md", + "file": "skills/security-review/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/audit-code/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "specs/skills-wiki/skills/security-review.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/skills-wiki/skills/audit-code.md", "line": 0, "confidence": "medium", "method": "file_heuristic" @@ -1624,6 +1913,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212931.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-160106.md", "line": 0, @@ -1648,6 +1943,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215320.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-172717.md", "line": 0, @@ -1660,6 +1961,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212830.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-182718.md", "line": 0, @@ -1684,6 +1991,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-183547.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260626-205129.md", "line": 0, @@ -1732,6 +2045,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214411.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260622-001710.md", "line": 0, @@ -1750,6 +2069,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001605.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-181904.md", "line": 0, @@ -1804,12 +2129,36 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-185319.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-183644.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215759.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260629-132810.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001328.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-235439.md", "line": 0, @@ -1822,6 +2171,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-202226.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164609.md", "line": 0, @@ -1912,12 +2267,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-205711.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-182236.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-213042.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-223023.md", "line": 0, @@ -2032,6 +2399,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215656.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-143757.md", "line": 0, @@ -2080,6 +2453,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001312.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164534.md", "line": 0, @@ -2134,6 +2513,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184319.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-174351.md", "line": 0, @@ -2188,6 +2573,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-235505.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-220905.md", "line": 0, @@ -2218,6 +2609,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001100.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-150417.md", "line": 0, @@ -2254,6 +2651,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001518.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-170909.md", "line": 0, @@ -2332,6 +2735,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184856.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-154339.md", "line": 0, @@ -2362,6 +2771,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-213831.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-174245.md", "line": 0, @@ -2458,6 +2873,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001919.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-220941.md", "line": 0, @@ -2506,6 +2927,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-185210.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-165256.md", "line": 0, @@ -2548,6 +2975,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212919.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-163256.md", "line": 0, @@ -2608,6 +3041,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-000955.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-144557.md", "line": 0, @@ -2908,6 +3347,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-220404.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-085740.md", "line": 0, @@ -2974,6 +3419,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214125.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-132604.md", "line": 0, @@ -3124,6 +3575,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215213.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-204345.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212711.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-153739.md", "line": 0, @@ -3232,12 +3701,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212552.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-181706.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001702.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-132130.md", "line": 0, @@ -3256,6 +3737,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-204300.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164141.md", "line": 0, @@ -3298,6 +3785,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001029.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-172425.md", "line": 0, @@ -3328,6 +3821,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184658.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-194009.md", "line": 0, @@ -3370,6 +3869,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-235409.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-195845.md", "line": 0, @@ -3436,6 +3941,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184355.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-172751.md", "line": 0, @@ -3478,6 +3989,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-234704.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-163238.md", "line": 0, @@ -3490,6 +4007,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214329.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-144506.md", "line": 0, @@ -3605,7 +4128,7 @@ "method": "file_heuristic" } ], - "link_count": 340 + "link_count": 382 }, { "id": "e45s19", @@ -3616,6 +4139,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/context7-mcp/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/verifications/steps/and-complex-boolean-logic-should-be-encapsulated-in-named-functions-g28.sh", "line": 0, @@ -3653,7 +4182,7 @@ "method": "file_heuristic" } ], - "link_count": 6 + "link_count": 7 }, { "id": "e45s20", @@ -3663,8 +4192,15 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": "scripts/lib/doc-fetch-cache.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 1 }, { "id": "e45s21", @@ -3676,32 +4212,74 @@ "status": "todo", "links": [ { - "file": "specs/skills-wiki/skills/seed-conventions.md", - "line": 0, - "confidence": "medium", - "method": "file_heuristic" + "file": ".gemini/extensions/bigpowers/commands/prompts/seed-conventions.md", + "line": 95, + "confidence": "high", + "method": "explicit_tag" }, { - "file": ".continue/rules/seed-conventions.md", - "line": 0, - "confidence": "medium", - "method": "file_heuristic" + "file": ".gemini/extensions/bigpowers/skills/seed-conventions/SKILL.md", + "line": 100, + "confidence": "high", + "method": "explicit_tag" }, { - "file": "website/src/content/docs/skills/seed-conventions.mdx", - "line": 0, - "confidence": "medium", - "method": "file_heuristic" + "file": "docs/templates/AGENTS.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" }, { - "file": ".kilocode/rules/seed-conventions.md", - "line": 0, - "confidence": "medium", - "method": "file_heuristic" - } - ], - "link_count": 4 - }, + "file": "skills/seed-conventions/REFERENCE.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/seed-conventions/SKILL.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/seed-conventions.md", + "line": 99, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/seed-conventions/SKILL.md", + "line": 101, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "specs/skills-wiki/skills/seed-conventions.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": ".continue/rules/seed-conventions.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "website/src/content/docs/skills/seed-conventions.mdx", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": ".kilocode/rules/seed-conventions.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + } + ], + "link_count": 11 + }, { "id": "e45s22", "title": "CLAUDE.md: context-aware directory routing", @@ -3711,6 +4289,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "CLAUDE.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/epics/e05-context-isolation-routing.yaml", "line": 0, @@ -3718,7 +4302,7 @@ "method": "file_heuristic" } ], - "link_count": 1 + "link_count": 2 }, { "id": "e45s23", @@ -3728,8 +4312,45 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/session-state.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/session-state/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/session-state/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "CLAUDE.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/session-state.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/session-state/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 6 }, { "id": "e45s24", @@ -3764,6 +4385,24 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "CONVENTIONS.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "scripts/compile-rule-matrix.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "specs/rule-matrix.json", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/steps/and-the-plan-contains-a-risk-matrix.sh", "line": 0, @@ -3771,7 +4410,7 @@ "method": "file_heuristic" } ], - "link_count": 1 + "link_count": 4 }, { "id": "e45s26", @@ -3782,6 +4421,60 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/security-review.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/security-review/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/security-review/SKILL.md", + "line": 15, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/security-review/fixtures/CWE-89-sqli-positive.py", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/security-review/fixtures/CWE-89-sqli-negative.py", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/security-review/fixtures/CWE-79-xss-positive.js", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/security-review/fixtures/CWE-79-xss-negative.js", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/security-review.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/security-review/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/security-review.md", "line": 0, @@ -3807,7 +4500,7 @@ "method": "file_heuristic" } ], - "link_count": 4 + "link_count": 13 }, { "id": "e45s27", @@ -3817,8 +4510,39 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/compose-workflow.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/compose-workflow/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/compose-workflow/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/compose-workflow.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/compose-workflow/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 5 }, { "id": "e45s28", @@ -3829,6 +4553,36 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/request-review.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/request-review/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/request-review/SKILL.md", + "line": 11, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/request-review.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/request-review/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/request-review.md", "line": 0, @@ -3860,7 +4614,7 @@ "method": "file_heuristic" } ], - "link_count": 5 + "link_count": 10 }, { "id": "e45s29", @@ -3870,8 +4624,99 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/slice-tasks.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/commands/prompts/plan-work.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/commands/prompts/change-request.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/plan-work/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/change-request/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/slice-tasks/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/plan-work/SKILL.md", + "line": 13, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/change-request/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/slice-tasks/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/slice-tasks.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/plan-work.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/change-request.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/plan-work/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/change-request/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/slice-tasks/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 15 }, { "id": "e45s30", @@ -3881,8 +4726,69 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": ".gemini/extensions/bigpowers/commands/prompts/dispatch-agents.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/commands/prompts/delegate-task.md", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/delegate-task/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".gemini/extensions/bigpowers/skills/dispatch-agents/SKILL.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/delegate-task/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/dispatch-agents/SKILL.md", + "line": 10, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/dispatch-agents.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/prompts/delegate-task.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/delegate-task/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": ".pi/skills/dispatch-agents/SKILL.md", + "line": 8, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 10 }, { "id": "e45s31", @@ -3893,6 +4799,24 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "scripts/bp-churn-rank.sh", + "line": 2, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/deepen-architecture/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/audit-code/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/DEEPEN-ARCHITECTURE-REVIEW.md", "line": 0, @@ -3983,6 +4907,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212931.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-160106.md", "line": 0, @@ -4007,6 +4937,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215320.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-172717.md", "line": 0, @@ -4019,6 +4955,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212830.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-182718.md", "line": 0, @@ -4043,6 +4985,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-183547.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260626-205129.md", "line": 0, @@ -4091,6 +5039,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214411.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260622-001710.md", "line": 0, @@ -4109,6 +5063,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001605.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-181904.md", "line": 0, @@ -4163,12 +5123,36 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-185319.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-183644.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215759.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260629-132810.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001328.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-235439.md", "line": 0, @@ -4181,6 +5165,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-202226.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164609.md", "line": 0, @@ -4271,12 +5261,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-205711.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-182236.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-213042.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-223023.md", "line": 0, @@ -4391,6 +5393,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215656.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-143757.md", "line": 0, @@ -4439,6 +5447,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001312.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164534.md", "line": 0, @@ -4493,6 +5507,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184319.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-174351.md", "line": 0, @@ -4547,6 +5567,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-235505.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-220905.md", "line": 0, @@ -4577,6 +5603,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001100.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-150417.md", "line": 0, @@ -4608,7 +5640,13 @@ "method": "file_heuristic" }, { - "file": "specs/verifications/reports/audit-cleancode-20260703-163136.md", + "file": "specs/verifications/reports/audit-cleancode-20260703-163136.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001518.md", "line": 0, "confidence": "medium", "method": "file_heuristic" @@ -4691,6 +5729,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184856.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-154339.md", "line": 0, @@ -4721,6 +5765,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-213831.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-174245.md", "line": 0, @@ -4817,6 +5867,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001919.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-220941.md", "line": 0, @@ -4865,6 +5921,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-185210.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-165256.md", "line": 0, @@ -4907,6 +5969,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212919.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-163256.md", "line": 0, @@ -4967,6 +6035,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-000955.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-144557.md", "line": 0, @@ -5267,6 +6341,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-220404.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-085740.md", "line": 0, @@ -5333,6 +6413,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214125.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-132604.md", "line": 0, @@ -5483,6 +6569,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-215213.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-204345.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212711.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-153739.md", "line": 0, @@ -5591,12 +6695,24 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-212552.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-181706.md", "line": 0, "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001702.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-132130.md", "line": 0, @@ -5615,6 +6731,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-204300.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-164141.md", "line": 0, @@ -5657,6 +6779,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260707-001029.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-172425.md", "line": 0, @@ -5687,6 +6815,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184658.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260705-194009.md", "line": 0, @@ -5729,6 +6863,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-235409.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260702-195845.md", "line": 0, @@ -5795,6 +6935,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-184355.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260706-172751.md", "line": 0, @@ -5837,6 +6983,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-234704.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260703-163238.md", "line": 0, @@ -5849,6 +7001,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/audit-cleancode-20260706-214329.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/audit-cleancode-20260704-144506.md", "line": 0, @@ -5946,7 +7104,7 @@ "method": "file_heuristic" } ], - "link_count": 342 + "link_count": 384 }, { "id": "e45s32", @@ -5957,6 +7115,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/release-branch/SKILL.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/gate-trace/SKILL.md", + "line": 6, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/gate-trace.md", "line": 0, @@ -6072,7 +7242,7 @@ "method": "file_heuristic" } ], - "link_count": 19 + "link_count": 21 }, { "id": "e45s33", @@ -6082,8 +7252,21 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": "docs/countable-story-format.md", + "line": 3, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/plan-work/SKILL.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 2 }, { "id": "e45s34", @@ -6094,6 +7277,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/develop-tdd/SKILL.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/develop-tdd.md", "line": 0, @@ -6125,7 +7314,7 @@ "method": "file_heuristic" } ], - "link_count": 5 + "link_count": 6 }, { "id": "e45s35", @@ -6136,6 +7325,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/plan-work/SKILL.md", + "line": 5, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/plan-work.md", "line": 0, @@ -6167,7 +7362,7 @@ "method": "file_heuristic" } ], - "link_count": 5 + "link_count": 6 }, { "id": "e45s36", @@ -6177,8 +7372,15 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": "CONVENTIONS.md", + "line": 7, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 1 }, { "id": "e45s37", @@ -6189,6 +7391,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/run-evals/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/run-evals.md", "line": 0, @@ -6232,7 +7440,7 @@ "method": "file_heuristic" } ], - "link_count": 7 + "link_count": 8 }, { "id": "e45s38", @@ -6243,6 +7451,18 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/diagnose-stall/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, + { + "file": "skills/dispatch-agents/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "scripts/install-cursor-skills-local.sh", "line": 0, @@ -6256,7 +7476,7 @@ "method": "file_heuristic" } ], - "link_count": 2 + "link_count": 4 }, { "id": "e45s39", @@ -6266,8 +7486,15 @@ "bcp": 2, "wsjf": 5.0, "status": "todo", - "links": [], - "link_count": 0 + "links": [ + { + "file": "skills/release-branch/SKILL.md", + "line": 4, + "confidence": "high", + "method": "explicit_tag" + } + ], + "link_count": 1 }, { "id": "e45s40", @@ -6278,6 +7505,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/verify-work/SKILL.md", + "line": 5, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/verify-work.md", "line": 0, @@ -6339,7 +7572,7 @@ "method": "file_heuristic" } ], - "link_count": 10 + "link_count": 11 }, { "id": "e45s41", @@ -6350,6 +7583,12 @@ "wsjf": 5.0, "status": "todo", "links": [ + { + "file": "skills/security-review/SKILL.md", + "line": 1, + "confidence": "high", + "method": "explicit_tag" + }, { "file": "specs/skills-wiki/skills/security-review.md", "line": 0, @@ -6375,7 +7614,7 @@ "method": "file_heuristic" } ], - "link_count": 4 + "link_count": 5 }, { "id": "e48s01", @@ -6410,12 +7649,6 @@ "confidence": "high", "method": "explicit_tag" }, - { - "file": "skills/run-benchmark/SKILL.md", - "line": 3, - "confidence": "high", - "method": "explicit_tag" - }, { "file": "specs/verifications/steps/and-complex-logic-should-include-provenance-links-adrs-jira-or-commits.sh", "line": 0, @@ -6482,6 +7715,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "website/src/content/docs/skills/maintain-wiki.mdx", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "docs/references/agent-config-files-and-okf.md", "line": 0, @@ -6590,6 +7829,18 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/GOLDEN-2026-07-07.okf.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-2026-07-07.okf.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/GOLDEN-2026-07-06.okf.md", "line": 0, @@ -6668,14 +7919,26 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "scripts/lib/audit-compliance-runner.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "scripts/lib/emit-okf-metrics.sh", "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/lib/golden-suite-run.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 23 + "link_count": 27 }, { "id": "e48s03", @@ -7238,6 +8501,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "website/src/components/cockpit/bug-pulse.tsx", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": ".kilocode/rules/fix-bug.md", "line": 0, @@ -7263,7 +8532,7 @@ "method": "file_heuristic" } ], - "link_count": 96 + "link_count": 97 }, { "id": "e48s04", @@ -7400,6 +8669,18 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "specs/verifications/reports/GOLDEN-2026-07-07.okf.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, + { + "file": "specs/verifications/reports/audit-2026-07-07.okf.md", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "specs/verifications/reports/GOLDEN-2026-07-06.okf.md", "line": 0, @@ -7880,6 +9161,12 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "website/src/lib/okf.ts", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "docs/references/agent-config-files-and-okf.md", "line": 0, @@ -7904,14 +9191,26 @@ "confidence": "medium", "method": "file_heuristic" }, + { + "file": "scripts/okf-add-references.py", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" + }, { "file": "scripts/lib/emit-okf-metrics.sh", "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/lib/validate-okf-kinds.sh", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 93 + "link_count": 98 }, { "id": "e48s06", @@ -7969,9 +9268,15 @@ "line": 0, "confidence": "medium", "method": "file_heuristic" + }, + { + "file": "scripts/okf-add-references.py", + "line": 0, + "confidence": "medium", + "method": "file_heuristic" } ], - "link_count": 8 + "link_count": 9 }, { "id": "e48s07", @@ -8526,21 +9831,12 @@ ], "summary": { "total_stories": 55, - "tagged_stories": 7, + "tagged_stories": 44, "dark_stories": [ - "e45s06", - "e45s20", - "e45s23", - "e45s27", - "e45s29", - "e45s30", - "e45s33", - "e45s36", - "e45s39", "e48s07", "e48s08" ], - "dark_count": 11, + "dark_count": 2, "orphan_tags": [ "e01s01", "e01s03", @@ -8552,6 +9848,7 @@ "e30s01", "e30s02", "e30s03", + "e31s04", "e32s01", "e32s02", "e32s03", @@ -8604,6 +9901,7 @@ "e41s01", "e42s02", "e42s03", + "e42s04", "e43s01", "e44s01", "e44s02", @@ -8620,12 +9918,12 @@ "e51s05", "e99s01" ], - "orphan_count": 77, + "orphan_count": 79, "stale_tags": [], "stale_count": 0, "oracle_stats": { - "high": 14, - "medium": 1296, + "high": 136, + "medium": 1390, "low": 2 } }