@cbartens/bkit 5.5.1 → 6.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +167 -154
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +18 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +112 -102
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +167 -154
- package/.bkit/core/.bkit/authoring.md +747 -0
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +283 -195
- package/.bkit/core/.bkit/comparison.md +45 -43
- package/.bkit/core/.bkit/install.md +166 -95
- package/.bkit/core/.bkit/jsonl.md +339 -196
- package/.bkit/core/.bkit/pipeline.md +142 -145
- package/.bkit/core/.bkit/prompts.md +295 -264
- package/.bkit/core/.bkit/providers.md +460 -277
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +530 -256
- package/.bkit/core/.bkit/trackers.md +116 -65
- package/.bkit/core/.bkit/workflows.md +742 -618
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +6 -80
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
- package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
- package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
- package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
- package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
- package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
- package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
- package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
- package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
- package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
- package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
- package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
- package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
- package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
- package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
- package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
- package/.bkit/core/docs/templates/bkit-plan.md +158 -281
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +21 -8
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +125 -123
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +3 -3
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +25 -1
- package/.bkit/core/engine/checks/before/repo.ts +208 -2
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
- package/.bkit/core/engine/checks/tips/detect.ts +66 -0
- package/.bkit/core/engine/checks/tips/index.ts +52 -11
- package/.bkit/core/engine/cli.ts +251 -130
- package/.bkit/core/engine/commands/analysis.ts +282 -199
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +139 -18
- package/.bkit/core/engine/commands/lib.ts +381 -22
- package/.bkit/core/engine/commands/registry.ts +10 -2
- package/.bkit/core/engine/commands/setup/setup.ts +8 -7
- package/.bkit/core/engine/commands/stats.ts +260 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
- package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
- package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
- package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
- package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
- package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
- package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
- package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
- package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +329 -33
- package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
- package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +67 -17
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +24 -16
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +1196 -45
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +18 -6
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +9 -4
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +249 -21
- package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
- package/.bkit/core/engine/render/hosts.ts +118 -14
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +8 -1
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +243 -31
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
- package/.bkit/core/engine/tools/instructions.ts +1802 -0
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +54 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -5
- package/.bkit/core/hooks/guardrails-tiers.js +10 -4
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
- package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
- package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
- package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
- package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
- package/.bkit/core/prompts/bkit-design-generate.md +80 -46
- package/.bkit/core/prompts/bkit-design-organise.md +83 -32
- package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
- package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
- package/.bkit/core/prompts/bkit-design-spike.md +64 -40
- package/.bkit/core/prompts/bkit-design-update.md +53 -28
- package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
- package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
- package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
- package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
- package/.bkit/core/prompts/bkit-plan-update.md +86 -31
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
- package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
- package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
- package/.bkit/core/workflows/bkit-auto.md +89 -58
- package/.bkit/core/workflows/bkit-build.md +967 -517
- package/.bkit/core/workflows/bkit-debug.md +555 -387
- package/.bkit/core/workflows/bkit-design.md +319 -283
- package/.bkit/core/workflows/bkit-plan.md +319 -342
- package/.bkit/core/workflows/bkit-ship.md +525 -328
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +14 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +12 -1
- package/.bkit/shared/CLAUDE.md +6 -2
- package/.bkit/shared/GEMINI.md +5 -2
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +241 -168
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +289 -174
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +96 -36
- package/.bkit/templates/.prettierignore +6 -0
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +231 -0
- package/README.md +278 -89
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +91 -30
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +22 -11
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +111 -114
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +3 -3
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +20 -3
- package/dist/checks/before/repo.js +197 -2
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +70 -19
- package/dist/checks/tips/detect.js +62 -0
- package/dist/checks/tips/index.js +51 -9
- package/dist/cli.js +234 -124
- package/dist/commands/analysis.js +174 -141
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +82 -55
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +137 -17
- package/dist/commands/lib.js +295 -21
- package/dist/commands/registry.js +10 -2
- package/dist/commands/setup/setup.js +8 -7
- package/dist/commands/stats.js +175 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +1873 -152
- package/dist/commands/workflow/challenge.js +609 -0
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +1045 -46
- package/dist/commands/workflow/counters.js +385 -86
- package/dist/commands/workflow/decisions.js +484 -0
- package/dist/commands/workflow/disk.js +214 -56
- package/dist/commands/workflow/fids.js +706 -33
- package/dist/commands/workflow/issues.js +349 -59
- package/dist/commands/workflow/ledgers.js +1123 -37
- package/dist/commands/workflow/locks.js +26 -2
- package/dist/commands/workflow/plan-blocks.js +501 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +154 -35
- package/dist/commands/workflow/repo.js +58 -8
- package/dist/commands/workflow/roadmap.js +58 -23
- package/dist/commands/workflow/run-facts.js +421 -0
- package/dist/commands/workflow/runs.js +670 -72
- package/dist/commands/workflow/runtime.js +15 -1
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +282 -34
- package/dist/commands/workflow/step-table.js +308 -0
- package/dist/commands/workflow/steps.js +703 -96
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +388 -0
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1695 -305
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +1014 -222
- package/dist/commands/workflow/worktrees.js +432 -26
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +64 -17
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +25 -16
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +1090 -48
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +13 -7
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +9 -4
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +176 -13
- package/dist/ledgers/telemetry.js +1010 -125
- package/dist/render/hosts.js +104 -14
- package/dist/render/models.js +12 -0
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/branches.js +3 -1
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +8 -1
- package/dist/shared/json.js +20 -7
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +181 -24
- package/dist/shared/text.js +333 -0
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +720 -0
- package/dist/tools/instructions.js +1623 -0
- package/package.json +156 -51
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/harvest.js +0 -353
- package/dist/commands/workflow/workstreams.js +0 -143
- package/dist/tools/wording.js +0 -680
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -1,191 +1,194 @@
|
|
|
1
|
-
<!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
|
|
2
|
-
|
|
3
1
|
<!-- bkit:start -->
|
|
4
2
|
|
|
5
3
|
{{BKIT_MANAGED_MARKER}}
|
|
6
4
|
|
|
5
|
+
<!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. -->
|
|
6
|
+
|
|
7
7
|
# Documentation Audit
|
|
8
8
|
|
|
9
9
|
> [!CAUTION]
|
|
10
|
-
> **Purpose:**
|
|
10
|
+
> **Purpose:** Whether the docs are still true: each claim matches the code, each pointer lands, and each fact agents rely on is written down.
|
|
11
11
|
>
|
|
12
12
|
> **Rules:**
|
|
13
13
|
>
|
|
14
|
-
> - Read-only audit; never edit code, config, or data.
|
|
15
|
-
> - `Universal Instructions` apply to all projects; `Project Instructions` apply only to this project.
|
|
16
|
-
> - Local audit instructions / overrides → `Project Instructions` below the bkit-managed block; universal instructions stay in-block.
|
|
17
|
-
> - Any tools mentioned in `Universal Instructions` are examples only; swap for actual tools in final output; drop inapplicable.
|
|
18
|
-
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
19
|
-
> - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
|
|
20
|
-
> - Every claim cites this run's evidence (`file:line`, or command / query and its output) and tool behind it; a previous report's figure, list, or status is a lead, not evidence.
|
|
21
|
-
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
22
14
|
> - NEVER paste a secret or credential value into the report.
|
|
23
|
-
> -
|
|
15
|
+
> - Treat historical records (`docs/plans/**`, `docs/archive/**`, `docs/completed.md`) and existing ledger rows as citers only, and never edit them.
|
|
24
16
|
|
|
25
17
|
## Universal Instructions
|
|
26
18
|
|
|
27
19
|
### Context & Goals
|
|
28
20
|
|
|
29
|
-
Docs are the record agents work from: memory points at them, plans
|
|
21
|
+
Docs are the record agents work from: memory points at them, and plans and code comments cite them. A wrong doc is worse than a missing one, because agents follow it. Prose lint checks style, the formatter checks shape, and the managed-block check covers managed blocks only. None of them reads the docs against the code. The doc update on each ship sees only the files that ship changed, so drift across ships belongs to nobody.
|
|
30
22
|
|
|
31
|
-
|
|
23
|
+
The failure this audit targets is a claim the code has left behind. Examples: a default the doc states that the deployed environment does not use; a script phase the doc leaves out (look hardest for anything that deletes); a pointer that leads nowhere; and a fact the running code relies on that exists only in memory, or was dropped from a ledger.
|
|
32
24
|
|
|
33
|
-
**Applies when:** project has live docs
|
|
25
|
+
**Applies when:** the project has live docs: prose under `docs/` or `.agents/`, or a root `README.md` that agents treat as the entry point. **If** it has none → write one `N/A` row with its evidence, and never report the surface as "clean".
|
|
34
26
|
|
|
35
|
-
**Cadence:**
|
|
27
|
+
**Cadence:** Run once a month. Run an extra pass after a ledger migration, a `bkit upgrade`, or a toolchain change (runtime, package manager, SDK, or a new required tool or hook).
|
|
36
28
|
|
|
37
|
-
**Anchor Standards:**
|
|
29
|
+
**Anchor Standards:**
|
|
38
30
|
|
|
39
31
|
- Diátaxis (unversioned; record the date read).
|
|
40
|
-
- Docs-as-code prose linter and link checker (e.g
|
|
41
|
-
- Architecture decision records (e.g
|
|
42
|
-
- Runbook practice (e.g
|
|
43
|
-
- Source-host community health files (e.g
|
|
44
|
-
- API-doc validation for the language (e.g
|
|
45
|
-
- HTTP API specification when the project serves HTTP (e.g
|
|
32
|
+
- Docs-as-code prose linter and link checker (e.g., Vale, lychee); record versions.
|
|
33
|
+
- Architecture decision records (e.g., ADR form).
|
|
34
|
+
- Runbook practice (e.g., Google SRE Workbook, "On-Call").
|
|
35
|
+
- Source-host community health files (e.g., GitHub `README`, `CONTRIBUTING`, `SECURITY.md`).
|
|
36
|
+
- API-doc validation for the language (e.g., TypeDoc validation, TSDoc); record version.
|
|
37
|
+
- HTTP API specification when the project serves HTTP (e.g., OpenAPI); record version.
|
|
46
38
|
|
|
47
39
|
### Scope
|
|
48
40
|
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
41
|
+
- Check every live doc on every run.
|
|
42
|
+
- Check the catalogue: `.agents/docs.md` rows against the files on disk, and the root entry point.
|
|
43
|
+
- Run the mechanical checks: prose, format, managed-block drift, backticked paths, links and anchors, commands, and diagrams.
|
|
44
|
+
- Check that each ledger citation resolves to one winning row, and that each significant choice has a `docs/decisions.jsonl` row.
|
|
45
|
+
- Check the claims in every live doc against the code.
|
|
46
|
+
- Check that the setup doc is enough to start, that the runbooks exist, and walk each one.
|
|
47
|
+
- Check the generated reference for HTTP APIs, background events and shared packages.
|
|
48
|
+
- Check auto-memory against the docs, and the instruction files against each other.
|
|
49
|
+
- Check that each topic has one doc, and label each live doc with its Diátaxis quadrant.
|
|
57
50
|
|
|
58
51
|
### Out of Scope
|
|
59
52
|
|
|
60
53
|
<!-- prettier-ignore -->
|
|
61
54
|
| Excluded item | Why | Where it belongs |
|
|
62
55
|
| --- | --- | --- |
|
|
63
|
-
| Whether a doc is in the right place |
|
|
64
|
-
| Stale pointers found only from the code side (route or file moved, no doc cites the old path) |
|
|
65
|
-
| Capability-register status (`one` / `bypassed` / `split` / `gap`) |
|
|
66
|
-
| Architecture graph diagram correctness |
|
|
67
|
-
| Turning a check into a CI gate |
|
|
68
|
-
| A stale fact inside a historical record |
|
|
69
|
-
| Instruction files each agent host loads; agent permissions, hooks, tool servers |
|
|
70
|
-
| Applying doc edits, appending ledger rows, editing memory |
|
|
56
|
+
| Whether a doc is in the right place | The repo sweep covers placement | `bkit-audit-repo` |
|
|
57
|
+
| Stale pointers found only from the code side (route or file moved, no doc cites the old path) | The code-side sweep covers it | `bkit-audit-dead-code` |
|
|
58
|
+
| Capability-register status (`one` / `bypassed` / `split` / `gap`) | The duplication sweep covers it | `bkit-audit-duplication` |
|
|
59
|
+
| Architecture graph diagram correctness | The architecture sweep covers it | `bkit-audit-architecture` |
|
|
60
|
+
| Turning a check into a CI gate | It is a gate design | `bkit-audit-gates` |
|
|
61
|
+
| A stale fact inside a historical record | It is history, not a defect | Citers only; fix a dead pointer at the target |
|
|
62
|
+
| Instruction files each agent host loads; agent permissions, hooks, tool servers | The agent config sweep covers it | `bkit-audit-agents` |
|
|
63
|
+
| Applying doc edits, appending ledger rows, editing memory | The audit only reports | A plan made from this report |
|
|
71
64
|
|
|
72
65
|
### Pre-Flight / Dependencies
|
|
73
66
|
|
|
74
|
-
**Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
|
|
75
|
-
|
|
76
|
-
**Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
|
|
77
|
-
|
|
78
67
|
#### Core
|
|
79
68
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
- [ ] **
|
|
83
|
-
- [ ] **Repo Read:** Steps 2–13 — live docs, instruction files, manifests, CI workflow. Fallback: none; unreadable tree = finding.
|
|
84
|
-
- [ ] **Web:** Step 14 — fetch anchor standards. Fallback: versions recorded as unread.
|
|
69
|
+
- [ ] **Permissions:** every blocked call is recorded.
|
|
70
|
+
- [ ] **Repo Read:** Steps 2-13 — live docs, instruction files, manifests and the CI workflow. Fallback: none. An unreadable tree is a finding.
|
|
71
|
+
- [ ] **Web:** Step 14 — fetch the anchor standards. Fallback: record the versions as unread.
|
|
85
72
|
|
|
86
73
|
#### Conditional
|
|
87
74
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
- [ ] **
|
|
91
|
-
- [ ] **
|
|
92
|
-
- [ ] **
|
|
93
|
-
- [ ] **
|
|
94
|
-
- [ ] **API Doc Validator:** Shared packages or an HTTP API → Step 9 — e.g. TypeDoc `--validation`, `eslint-plugin-jsdoc`. Fallback: read exports; broken links `Not Checked`.
|
|
95
|
-
- [ ] **Local Memory:** Maintainer machine → Step 10 — IDE auto-memory directory. Fallback: cloud session skips; record in `Not Checked`.
|
|
75
|
+
- [ ] **Prose and Format:** Step 4 — e.g., Vale, Prettier. Fallback: skip that check, and name it in `Not Checked`.
|
|
76
|
+
- [ ] **Managed-Block Check:** **If** this is a bkit project → Step 4 — e.g., `bkit check`. Fallback: read the managed blocks, and mark drift `Not Checked`.
|
|
77
|
+
- [ ] **Link Checker:** Step 4 — offline fragments plus cached external URLs (e.g., lychee). Fallback: open relative links by hand, and mark external URLs `Not Checked`.
|
|
78
|
+
- [ ] **Diagram Renderer:** **If** docs have fenced diagrams → Step 4 — e.g., mermaid-cli, a headless browser. A cloud session may lack the browser. Fallback: skip the render, and mark it `Not Checked`.
|
|
79
|
+
- [ ] **API Doc Validator:** **If** the project has shared packages **or** an HTTP API → Step 9 — e.g., TypeDoc `--validation`, `eslint-plugin-jsdoc`. Fallback: read the exports, and mark broken links `Not Checked`.
|
|
80
|
+
- [ ] **Local Memory:** **If** the run is on a maintainer machine → Step 10 — the IDE auto-memory directory. Fallback: a cloud session skips it and records that in `Not Checked`.
|
|
96
81
|
|
|
97
82
|
### 🔒 Gate 1: Prerequisites Check
|
|
98
83
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
- [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
|
|
102
|
-
- [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
|
|
84
|
+
- [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
|
|
85
|
+
- [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
|
|
103
86
|
|
|
104
87
|
### Probe Steps
|
|
105
88
|
|
|
106
|
-
- [ ] **Step 1 — Previous Run:**
|
|
107
|
-
- [ ] **Step 2 — Scope:**
|
|
108
|
-
- [ ] **Step 3 — Catalogue:** `.agents/docs.md
|
|
109
|
-
- [ ] **Step 4 — Mechanical:** Run prose lint, format check
|
|
110
|
-
-
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
89
|
+
- [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
|
|
90
|
+
- [ ] **Step 2 — Scope:** **If** there are no live docs → write one `N/A` row with evidence, then **STOP**. Otherwise take every live doc, and rank them by drift: for each live doc, count the commits to the repo paths it cites since the doc last changed, and add a column for the cited paths that no longer resolve. Record the ranking. Start from an up-to-date default branch with a clean `git status`. Historical records are citers. A pointer in one that leads nowhere is a finding, fixed at the target. A stale fact inside one is history, not a defect. **Done when:** `Scope` holds every live doc and the drift ranking.
|
|
91
|
+
- [ ] **Step 3 — Catalogue:** Check `.agents/docs.md`. Every file on disk under `docs/`, outside `plans/`, `archive/` and `audits/`, has a row, and every row's file exists. No doc is listed twice. Two docs on one topic is a bug, and that includes one doc in both tables with different reading columns. Each row's one-line scope still matches the doc. The root `README.md` works as the entry point: it says what the project is, links the setup doc, the architecture doc and `.agents/docs.md`, and says how to report a security issue. A missing community-health file with no README substitute is a finding. **Done when:** `Catalogue` names every mismatch, and every clean check.
|
|
92
|
+
- [ ] **Step 4 — Mechanical:** Run prose lint, the format check and the managed-block check. Then:
|
|
93
|
+
- Check that every backticked repo path in a live doc exists, and that every `*.md` name in a live doc resolves, backticked or not. The output is candidates. A path named on purpose as removed is not a finding. A path that moved is a finding. Section anchors and `file:line` wait for `Claims`.
|
|
94
|
+
- Check relative links and heading anchors offline across every doc, plans and archive included, because they are citers. Then check external URLs in live docs, with a cache. The anchor builder must match the host (e.g., GitHub). Open a failed fragment before calling it broken. The path check cannot see Markdown links.
|
|
95
|
+
- Check that every package-manager script a live doc names is defined by some manifest, and that every script path a doc runs exists. Both lists are candidates, because a doc may name a removed script on purpose.
|
|
96
|
+
- Confirm that the prose-lint and format globs cover every live doc. A live doc outside them is a finding, because neither check ever reads it.
|
|
97
|
+
- Check that diagrams still parse (e.g., Mermaid). A syntax break renders as raw text with no CI signal, so render each live doc that has one.
|
|
98
|
+
- Check Markdown tables in live docs. Each carries `<!-- prettier-ignore -->` directly above its head, and each renders. No row has more cells than the separator, because GFM drops the overflow. The header and separator counts match, because a mismatch renders as raw text. Run the check read-only (e.g., `node scripts/prettier/bkit-insert-ignore.mjs --check`; the bkit package template is in `.bkit/templates/scripts/prettier/`, and it skips `docs/audits/` and `docs/plans/`). **If** there is no such check → `Process Improvements` proposes the template.
|
|
115
99
|
|
|
116
|
-
|
|
100
|
+
A path or link fix is a doc edit for `@bkit-utility-update-documentation`, as a sync pass only (no reorganising, compressing or cross-referencing), after the intentional hits are struck. **If** a pointer broke because a route or file moved → also name `bkit-audit-dead-code`. **If** a broken diagram is the architecture graph → also name `bkit-audit-architecture`. A check that could be a CI gate goes to `bkit-audit-gates`. **Done when:** `Mechanical` lists the broken paths, links, scripts, diagrams and tables, each with its destination, including the checks that came back clean.
|
|
117
101
|
|
|
118
|
-
- [ ] **Step 5 — Ledgers:** Rows cited by `key` (`.bkit/jsonl.md` § Key & References). Resolve winning row
|
|
119
|
-
-
|
|
120
|
-
- `docs/completed.md` or plan → do not edit.
|
|
121
|
-
-
|
|
102
|
+
- [ ] **Step 5 — Ledgers:** Rows are cited by `key` (`.bkit/jsonl.md` § Key & References). Resolve the winning row by folding on `key` and taking the highest `ts` (§ Updating a Row). Legacy counter ids (e.g., `KN-<n>`, `DE-<n>`) are leftovers. They are not unique, and they survive in `references`. New citations of them keep appearing, so this check runs every time. `references` may be a string or a list, so accept both; a reader that assumes a list silently skips string rows. Build three candidate lists: a cited legacy id that resolves to nothing; a cited legacy id that resolves to more than one row; and a `key` cited next to a ledger name that no row has. The third list also picks up job names, so open each one. Also flag rows whose `references` is null, because a citation to such a row cannot resolve. Rows that share a `key` are updates, not duplicates. A clash is only when different keys claim the same legacy id. For each real hit:
|
|
103
|
+
- **If** the hit is in a live doc or a code comment → the report names the citation change to the row's `key`. This run does not edit.
|
|
104
|
+
- **If** the hit is in `docs/completed.md` or a plan → do not edit. The report names the new version of the owning row to append, with the old id in `references`.
|
|
105
|
+
- **If** the fact is in no row → run `git log -S` on the old id. The report quotes the historical text to restore, or asks the maintainer. Never reconstruct rationale nobody wrote. Restoring is a same-`key` append in the next step. Never edit a line in place.
|
|
122
106
|
|
|
123
|
-
Then choices recorded at all. List each external service, major library
|
|
107
|
+
Then check that choices are recorded at all. List each external service, major library and data-model choice visible in the code, and find its `docs/decisions.jsonl` row. A missing row is a question for the maintainer, not rationale to write. A choice the code reversed needs a newer row with the same `key`, and the report names the row to append. **Done when:** `Ledgers` lists every unresolved citation and every choice without a row.
|
|
124
108
|
|
|
125
|
-
- [ ] **Step 6 — Claims:** For each live doc, list claims something depends on
|
|
109
|
+
- [ ] **Step 6 — Claims:** For each live doc, list the claims something depends on, and check each against the code. No tool does this.
|
|
126
110
|
|
|
127
111
|
<!-- prettier-ignore -->
|
|
128
112
|
| Claim type | Check against |
|
|
129
113
|
| --- | --- |
|
|
130
|
-
| Defaults and flags | Schema default and the env files that are actually deployed. A schema default (e.g
|
|
114
|
+
| Defaults and flags | Schema default and the env files that are actually deployed. A schema default (e.g., zod `.default()`) applies only when the variable is unset |
|
|
131
115
|
| What a script does | The script, end to end. Look hardest for anything that deletes |
|
|
132
116
|
| Which parts exist, on which platform | The code, on every platform the doc claims |
|
|
133
117
|
| `file:line` | Open the line. It must still say what the doc claims |
|
|
134
118
|
| Section links (`§ Heading`) | The heading exists, word for word |
|
|
135
119
|
| Counts and lists | Count them again |
|
|
136
120
|
|
|
137
|
-
Destinations:
|
|
121
|
+
Destinations:
|
|
122
|
+
- **If** the doc is wrong **and** the code is right → a doc edit.
|
|
123
|
+
- **If** the doc is right **and** the code is wrong → a `docs/failures.jsonl` row, which `@bkit-utility-update-failures` applies. Do not "fix" the doc to match the bug.
|
|
124
|
+
- **If** there is no recorded intent → a question for the maintainer.
|
|
125
|
+
- **If** it is a statement about the product's shape → proposed wording for the owner before it lands.
|
|
126
|
+
- **If** the drift is inside `bkit:start` / `bkit:end` → an upstream bkit fix. Do not edit there, because `bkit install` overwrites it.
|
|
138
127
|
|
|
139
|
-
-
|
|
128
|
+
Write the handoff for `@bkit-utility-update-documentation`; this run does not invoke it. Give it findings from this report only, known drift first (the `file:line` and the code that disproves it), no managed-block interiors, and no historical records or `*.jsonl`. Unscoped, it walks every indexed doc in several passes and stops partway. It cannot run commands, so give it script behaviour and deployed values from this list. A compress pass can delete a warning, so the next reader checks every removed "never", "always" or trap. For docs that other code reads, fix by hand, then run the tests that `Handoff` finds. Do not trust "synced"; re-grep every changed claim. **Done when:** `Claims` has a row per hit: `file:line` · what the doc said · what the code does · severity · destination.
|
|
140
129
|
|
|
141
|
-
|
|
130
|
+
- [ ] **Step 7 — Setup:** The setup doc is enough when a new developer, or an agent in a fresh session or worktree, gets from a clean clone to a running app and a passing local suite using only that doc. Run the cheap checks and the full walk on every run.
|
|
142
131
|
|
|
143
|
-
|
|
132
|
+
Cheap checks: the tool versions in the doc match the manifest and version files (e.g., `engines`, `packageManager`, `.nvmrc`, `.python-version`, `rust-toolchain.toml`). Every binary that a package script, git hook or local CI runner calls is listed; a hook dying on a missing binary is the usual first-day stop. Required and optional are still right: **if** nothing calls a tool, **or** its platform is retired → it is not required. Every command and path in the doc exists. Every variable the code reads is in the example env, or the doc says where to get it. Every example variable is still read, and the doc names the right example file and how it is loaded. The doc says what an agent needs that a person already has: env trust in a new worktree, language-server provisioning, and which steps a cloud session cannot run.
|
|
144
133
|
|
|
145
|
-
|
|
146
|
-
- [ ] **Step 9 — Reference:** HTTP routes external or native client calls → generated, current reference (e.g. OpenAPI), not prose. Each background-event name and payload schema → generated or code-adjacent reference matching what is sent. Shared packages → API-doc validation over each entry point (e.g. TSDoc: broken `{@link}` references, exported symbols with no docs). Gap = finding; fix = generated reference, next step. **Done when:** `Reference` row per surface: present or gap.
|
|
147
|
-
- [ ] **Step 10 — Memory:** Local session → auto-memory must point at docs, never copy them. Cloud session → skip and say so.
|
|
148
|
-
- Fact only in memory → doc or ledger row it should move to, and pointer to leave behind.
|
|
149
|
-
- Memory copying doc → cut to pointer (path, section, one-line hook).
|
|
150
|
-
- Pointer at section moved or gone → pointer fix, and whether `Mechanical` missed same move in docs.
|
|
151
|
-
- Memory and doc disagree → code decides. Report says which next step should fix.
|
|
134
|
+
Full walk: make a fresh clone into a temp directory, not a worktree of this checkout, because a worktree hides missing steps. Follow the doc literally, in order. Every time you need something the doc did not say is a finding. Reach these goal states in order, recording the time each takes: the install succeeds; the local app serves on the doc's port and sign-in works; the local static, unit and integration gate passes; local end-to-end passes; and, when the doc has a mobile section, the simulator and emulator run. Then take a new worktree of the existing checkout through to the first passing test, which is the agent path. Then record which goal states a cloud session can reach, and whether the doc says which it cannot. Secrets: the doc says where each one comes from, and whether that works without asking a person. Never paste a value. **Done when:** `Setup` has a row per cheap check, and, when the walk ran, the time per goal state and every point where the doc was not enough.
|
|
152
135
|
|
|
153
|
-
|
|
136
|
+
- [ ] **Step 8 — Runbooks:** Check that a procedure exists for each case below, named by doc and section: production rollback, per host (web deploy, plus native update and store build when those exist); database restore and point-in-time recovery; a migration that fails partway through a push; secret rotation, per provider; a failing or poisoned background-job queue; an outage at the primary dependency; and a user data export and a user data deletion request. Walk every procedure with the `Claims` checks: every command exists, every path is real, and every dashboard step still matches. A missing procedure is a finding. A procedure that says who to tell but not what to run is a finding. The destination is the doc and section to add, and also `bkit-audit-reliability`. **Done when:** `Runbooks` lists each procedure and its walk.
|
|
137
|
+
- [ ] **Step 9 — Reference:** **If** an external or native client calls HTTP routes → they need a generated, current reference (e.g., OpenAPI), not prose. Each background-event name and payload schema needs a generated or code-adjacent reference that matches what is sent. **If** the project has shared packages → run API-doc validation over each entry point (e.g., TSDoc: broken `{@link}` references, exported symbols with no docs). A gap is a finding, and the fix is a generated reference in the next step. **Done when:** `Reference` has a row per surface: present or gap.
|
|
138
|
+
- [ ] **Step 10 — Memory:** **If** the session is local → auto-memory must point at docs, never copy them. **If** the session is in the cloud → skip this step and say so.
|
|
139
|
+
- **If** a fact is only in memory → name the doc or ledger row it should move to, and the pointer to leave behind.
|
|
140
|
+
- **If** memory copies a doc → cut it to a pointer (path, section, one-line hook).
|
|
141
|
+
- Run the Step 4 path resolver over the memory files.
|
|
142
|
+
- **If** a pointer aims at a section that moved or is gone → name the pointer fix, and whether `Mechanical` missed the same move in the docs.
|
|
143
|
+
- **If** memory and a doc disagree → the code decides. The report says which next step should fix it.
|
|
154
144
|
|
|
155
|
-
|
|
156
|
-
- [ ] **Step 12 — Topics:** Two docs on one topic = bug (`.agents/docs.md`): pick home, delete copy, link to home. Look in order: same table or list in two docs; section in domain doc repeating ledger row; audit report still giving advice doc replaced. Label each live doc by Diátaxis quadrant (tutorial, how-to, reference, explanation). Doc mixing quadrants = finding for split. Topic agents need with no doc in right quadrant = finding for new one. Record labels so next run diffs them. `@bkit-utility-compress-markdown` overwrites one file per call; this run does not invoke it. Long prose doc may be named as candidate. Never a doc tests parse, never a ledger. **Done when:** `Topics` holds duplicates, quadrant labels, and any compress candidate.
|
|
157
|
-
- [ ] **Step 13 — Handoff:** This run does not edit docs. Read CI workflow for what docs-only push actually runs. Record recheck next step owes after edits this report names: prose lint, format check, managed-block check, `Mechanical` and `Ledgers` again (both should list nothing new), and every test that reads a doc the report says to touch. Find those tests (`git grep -l`), do not list from memory. Change to code comment, script, or migration = code change → normal lanes. **Done when:** `Handoff` names recheck commands and tests.
|
|
158
|
-
- [ ] **Step 14 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per Diátaxis quadrant, link, and anchor checking, decision records, runbooks, each community health file, and API or package reference → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
|
|
159
|
-
- [ ] **Step 15 — Anything Else:** (a) Everything changed since previous report's commit touching docs (new or renamed docs, `.agents/*.md` and other rule files, package scripts, env vars, routes, background events, new ledger rows, new external services) → one-line verdict each. (b) Bounded ~30 min pass: what senior technical writer flags that no step asks; read what happened since previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows, vendor status incidents) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
|
|
145
|
+
**Done when:** `Memory` holds each hit, or the skip is recorded.
|
|
160
146
|
|
|
161
|
-
|
|
147
|
+
- [ ] **Step 11 — Rules:** Read the instruction files the IDE loads side by side (`AGENTS.md`, `CLAUDE.md`, IDE rule files, `.agents/rules.md`, and any other). A directive that one file forbids, or two commands for the same task, is a finding. **If** it is inside `bkit:start` / `bkit:end` → it is an upstream bkit fix. The destination is proposed wording, so the owner can pick the rule that stands. Record the load size as a series: the byte size of the always-applied files, and about a quarter of that in tokens. Growth with no new rule means copying. **Done when:** `Rules` lists the contradictions and the load size.
|
|
148
|
+
- [ ] **Step 12 — Topics:** Two docs on one topic is a bug (`.agents/docs.md`).
|
|
149
|
+
- Look for duplicates in this order: the same table or list in two docs; a section in a domain doc that repeats a ledger row; and an audit report still giving advice that a doc replaced.
|
|
150
|
+
- For each duplicate, name the home, the copy to delete and the link to add, for the next step to apply.
|
|
151
|
+
- Label each live doc with its Diátaxis quadrant (tutorial, how-to, reference, explanation).
|
|
152
|
+
- Record the labels, so the next run can diff them.
|
|
153
|
+
- A doc that mixes quadrants is a finding for a split.
|
|
154
|
+
- A topic agents need with no doc in the right quadrant is a finding for a new one.
|
|
155
|
+
- A long prose doc may be named as a candidate for `@bkit-utility-compress-markdown`, which overwrites one file per call. This run does not invoke it.
|
|
156
|
+
- Never name a doc that tests parse, or a ledger, as a compress candidate.
|
|
157
|
+
|
|
158
|
+
**Done when:** `Topics` holds the duplicates, the quadrant labels, and any compress candidate.
|
|
159
|
+
|
|
160
|
+
- [ ] **Step 13 — Handoff:** This run does not edit docs. Read the CI workflow for what a docs-only push actually runs. Record the recheck the next step owes after the edits this report names: prose lint, the format check, the managed-block check, `Mechanical` and `Ledgers` again (both should list nothing new), and every test that reads a doc the report says to touch. Find those tests with `git grep -l`; do not list them from memory. A change to a code comment, a script or a migration is a code change, and takes the normal lanes. **Done when:** `Handoff` names the recheck commands and tests.
|
|
161
|
+
- [ ] **Step 14 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. In `Standards Coverage`, give one row per Diátaxis quadrant, plus one row each for link checking, anchor checking, decision records, runbooks, each community health file, and the API or package reference, marked checked (with the step), not applicable (saying why) or finding. Mark each recommended practice the project does not apply as adopt (with a proposed step), reject (saying why) or not applicable. **Done when:** no row is empty.
|
|
162
|
+
- [ ] **Step 15 — Anything Else:** (a) List everything changed since the previous report's commit that touches docs (new or renamed docs, `.agents/*.md` and other rule files, package scripts, env vars, routes, background events, new ledger rows and new external services), with a one-line verdict each. (b) In a bounded pass of about 30 minutes, note what a senior technical writer would flag that no step asks about. Read what happened since the previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows and vendor status incidents), and note what no step would catch. **Done when:** `Beyond the Steps` holds both passes, or says `none`. **If** one class of issue is seen on 2 runs → propose a step for it in `Process Improvements`.
|
|
162
163
|
|
|
163
|
-
|
|
164
|
+
### 🔒 Gate 2: Probes Check
|
|
164
165
|
|
|
165
|
-
- [ ] **Steps complete:** every step `[x]`, or
|
|
166
|
-
- [ ] **Evidence:** every finding cites
|
|
167
|
-
- [ ] **No secrets:** no secret or credential value anywhere in the report.
|
|
168
|
-
- [ ] **
|
|
169
|
-
- [ ] **
|
|
166
|
+
- [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
|
|
167
|
+
- [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
|
|
168
|
+
- [ ] **No secrets:** no secret or credential value appears anywhere in the report.
|
|
169
|
+
- [ ] **Docs untouched:** no live doc, memory file or instruction file changed, other than the template's `Project Instructions`.
|
|
170
|
+
- [ ] **Ledger rows untouched:** no existing ledger row changed.
|
|
171
|
+
- [ ] **Scratch in tmp:** scratch files are only under the repo-root `tmp/`.
|
|
172
|
+
- [ ] **Gate 2 — Verified:** every item above holds.
|
|
170
173
|
|
|
171
174
|
## Findings
|
|
172
175
|
|
|
173
176
|
<!-- prettier-ignore -->
|
|
174
177
|
| Severity | Use |
|
|
175
178
|
| --- | --- |
|
|
176
|
-
| `CRITICAL` | Following the doc destroys data, skips a safety check, or blocks a fresh start with no workaround written
|
|
177
|
-
| `HIGH` |
|
|
178
|
-
| `MEDIUM` |
|
|
179
|
-
| `LOW` |
|
|
179
|
+
| `CRITICAL` | Following the doc destroys data, skips a safety check, or blocks a fresh start with no workaround written. Instruction files contradict each other on a safety rule. |
|
|
180
|
+
| `HIGH` | The doc states the opposite of the code on a flag, a default or a platform shape. A pointer an agent follows leads nowhere. Running code depends on a fact that no ledger row holds. The setup doc has a gap with a known workaround. |
|
|
181
|
+
| `MEDIUM` | A `file:line`, count or list has drifted. A table renders as raw text or drops cells. A setup command is wrong but recoverable. A runbook is missing. A generated reference is missing. The same topic is in two docs. A doc mixes Diátaxis quadrants. A choice has no decision row. |
|
|
182
|
+
| `LOW` | A catalogue one-line scope is slightly off. Wording drift changes no instruction. A quadrant label needs no split. |
|
|
180
183
|
|
|
181
|
-
|
|
184
|
+
Within a severity, list destructive steps and contradictions first.
|
|
182
185
|
|
|
183
186
|
<!-- prettier-ignore -->
|
|
184
187
|
| ID | Severity | Location | Evidence | Expected |
|
|
185
188
|
| --- | --- | --- | --- | --- |
|
|
186
189
|
| PENDING | PENDING | PENDING | PENDING | PENDING |
|
|
187
190
|
|
|
188
|
-
|
|
191
|
+
**If** the run finds nothing → write one row: `None`.
|
|
189
192
|
|
|
190
193
|
## Report
|
|
191
194
|
|
|
@@ -274,17 +277,15 @@ PENDING
|
|
|
274
277
|
|
|
275
278
|
### 🔒 Gate 3: Report Check
|
|
276
279
|
|
|
277
|
-
**
|
|
278
|
-
|
|
279
|
-
- [ ] **
|
|
280
|
-
- [ ] **
|
|
281
|
-
- [ ] **
|
|
282
|
-
- [ ] **
|
|
283
|
-
- [ ] **
|
|
284
|
-
- [ ] **
|
|
285
|
-
- [ ] **Gate 3
|
|
286
|
-
|
|
287
|
-
> `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
|
|
280
|
+
- [ ] **No placeholders:** no `PENDING` is left.
|
|
281
|
+
- [ ] **Summary:** `Summary` gives the count per severity.
|
|
282
|
+
- [ ] **Series:** the report shows load size, and setup-walk times when the walk ran, beside the previous report's numbers, or marks the run as baseline.
|
|
283
|
+
- [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
|
|
284
|
+
- [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
|
|
285
|
+
- [ ] **Process Improvements:** `Universal` and `Project` are both filled.
|
|
286
|
+
- [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
|
|
287
|
+
- [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
|
|
288
|
+
- [ ] **Gate 3 — Verified:** every item above holds.
|
|
288
289
|
|
|
289
290
|
<!-- bkit:end -->
|
|
290
291
|
|