@cbartens/bkit 6.0.0 → 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 +154 -151
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +17 -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 +108 -107
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +154 -151
- package/.bkit/core/.bkit/authoring.md +714 -84
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +281 -193
- package/.bkit/core/.bkit/comparison.md +43 -41
- package/.bkit/core/.bkit/install.md +154 -84
- package/.bkit/core/.bkit/jsonl.md +193 -130
- package/.bkit/core/.bkit/pipeline.md +114 -114
- package/.bkit/core/.bkit/prompts.md +272 -165
- package/.bkit/core/.bkit/providers.md +457 -271
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +529 -256
- package/.bkit/core/.bkit/trackers.md +80 -52
- package/.bkit/core/.bkit/workflows.md +589 -504
- 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 +5 -73
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
- package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
- package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
- package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
- package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
- package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
- package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
- package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
- package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
- package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
- package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
- package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
- package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
- package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
- package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
- package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
- package/.bkit/core/docs/templates/bkit-plan.md +138 -132
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
- package/.bkit/core/engine/checks/after/index.ts +12 -2
- package/.bkit/core/engine/checks/after/tools.ts +80 -33
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +1 -1
- package/.bkit/core/engine/checks/before/index.ts +7 -0
- package/.bkit/core/engine/checks/before/repo.ts +40 -0
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
- package/.bkit/core/engine/checks/tips/detect.ts +32 -0
- package/.bkit/core/engine/checks/tips/index.ts +47 -6
- package/.bkit/core/engine/cli.ts +238 -84
- package/.bkit/core/engine/commands/analysis.ts +128 -76
- 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/install/uninstall.ts +21 -27
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +126 -11
- package/.bkit/core/engine/commands/lib.ts +303 -6
- package/.bkit/core/engine/commands/registry.ts +6 -2
- package/.bkit/core/engine/commands/setup/setup.ts +1 -0
- package/.bkit/core/engine/commands/stats.ts +91 -35
- package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
- package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +433 -55
- package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
- package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
- package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
- package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
- package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
- package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
- package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
- package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +200 -17
- package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
- package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
- 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 +1285 -356
- package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
- package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
- 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 +60 -12
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -3
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +956 -52
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +16 -4
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +3 -2
- 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/status.ts +160 -9
- package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
- package/.bkit/core/engine/render/hosts.ts +114 -14
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +92 -17
- 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 +1 -1
- package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
- package/.bkit/core/engine/tools/instructions.ts +94 -43
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +53 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -4
- package/.bkit/core/hooks/guardrails-tiers.js +3 -3
- 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 +187 -116
- package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
- package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
- package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
- package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
- package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
- 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 +87 -50
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
- package/.bkit/core/prompts/bkit-design-generate.md +68 -52
- package/.bkit/core/prompts/bkit-design-organise.md +73 -35
- package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
- package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
- package/.bkit/core/prompts/bkit-design-spike.md +54 -47
- package/.bkit/core/prompts/bkit-design-update.md +42 -31
- package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
- package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
- package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
- package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
- package/.bkit/core/prompts/bkit-plan-update.md +70 -52
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
- package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
- package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
- package/.bkit/core/workflows/bkit-auto.md +53 -30
- package/.bkit/core/workflows/bkit-build.md +635 -304
- package/.bkit/core/workflows/bkit-debug.md +301 -148
- package/.bkit/core/workflows/bkit-design.md +167 -95
- package/.bkit/core/workflows/bkit-plan.md +172 -84
- package/.bkit/core/workflows/bkit-ship.md +299 -152
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +3 -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/.opencode/opencode.json +1 -1
- package/.bkit/shared/CLAUDE.md +5 -1
- package/.bkit/shared/GEMINI.md +4 -1
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +239 -166
- 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 +282 -176
- 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 +24 -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 +53 -50
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
- 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 +95 -35
- package/.bkit/templates/.prettierignore +6 -7
- 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 +9 -1
- 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 +119 -0
- package/README.md +250 -76
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +52 -2
- package/dist/checks/after/index.js +12 -4
- package/dist/checks/after/tools.js +73 -33
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +1 -1
- package/dist/checks/before/index.js +6 -2
- package/dist/checks/before/repo.js +35 -1
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +59 -17
- package/dist/checks/tips/detect.js +30 -0
- package/dist/checks/tips/index.js +48 -6
- package/dist/cli.js +222 -84
- package/dist/commands/analysis.js +77 -53
- 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/install/uninstall.js +23 -27
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +126 -10
- package/dist/commands/lib.js +244 -5
- package/dist/commands/registry.js +6 -2
- package/dist/commands/setup/setup.js +1 -0
- package/dist/commands/stats.js +69 -30
- package/dist/commands/workflow/branches.js +1232 -111
- package/dist/commands/workflow/challenge.js +90 -37
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +371 -51
- package/dist/commands/workflow/counters.js +206 -40
- package/dist/commands/workflow/decisions.js +60 -17
- package/dist/commands/workflow/disk.js +213 -55
- package/dist/commands/workflow/fids.js +18 -1
- package/dist/commands/workflow/issues.js +6 -0
- package/dist/commands/workflow/ledgers.js +372 -21
- package/dist/commands/workflow/locks.js +2 -0
- package/dist/commands/workflow/plan-blocks.js +78 -14
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +12 -3
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +50 -17
- package/dist/commands/workflow/run-facts.js +23 -28
- package/dist/commands/workflow/runs.js +530 -33
- package/dist/commands/workflow/runtime.js +3 -0
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +166 -19
- package/dist/commands/workflow/step-table.js +61 -29
- package/dist/commands/workflow/steps.js +542 -26
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +154 -41
- 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 +1013 -321
- package/dist/commands/workflow/workflows.js +191 -38
- package/dist/commands/workflow/worktrees.js +310 -42
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +57 -12
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +3 -3
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +851 -53
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +11 -5
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +3 -2
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/status.js +115 -5
- package/dist/ledgers/telemetry.js +121 -17
- package/dist/render/hosts.js +100 -14
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +1 -1
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +59 -10
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +1 -1
- package/dist/tools/instructions-sources.js +15 -16
- package/dist/tools/instructions.js +83 -39
- package/package.json +58 -42
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/workflow/workstreams.js +0 -149
- /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,171 +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
14
|
> - NEVER paste a secret or credential value into the report.
|
|
15
|
-
> -
|
|
15
|
+
> - Treat historical records (`docs/plans/**`, `docs/archive/**`, `docs/completed.md`) and existing ledger rows as citers only, and never edit them.
|
|
16
16
|
|
|
17
17
|
## Universal Instructions
|
|
18
18
|
|
|
19
19
|
### Context & Goals
|
|
20
20
|
|
|
21
|
-
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.
|
|
22
22
|
|
|
23
|
-
|
|
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.
|
|
24
24
|
|
|
25
|
-
**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".
|
|
26
26
|
|
|
27
|
-
**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).
|
|
28
28
|
|
|
29
29
|
**Anchor Standards:**
|
|
30
30
|
|
|
31
31
|
- Diátaxis (unversioned; record the date read).
|
|
32
|
-
- Docs-as-code prose linter and link checker (e.g
|
|
33
|
-
- Architecture decision records (e.g
|
|
34
|
-
- Runbook practice (e.g
|
|
35
|
-
- Source-host community health files (e.g
|
|
36
|
-
- API-doc validation for the language (e.g
|
|
37
|
-
- 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.
|
|
38
38
|
|
|
39
39
|
### Scope
|
|
40
40
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
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.
|
|
49
50
|
|
|
50
51
|
### Out of Scope
|
|
51
52
|
|
|
52
53
|
<!-- prettier-ignore -->
|
|
53
54
|
| Excluded item | Why | Where it belongs |
|
|
54
55
|
| --- | --- | --- |
|
|
55
|
-
| Whether a doc is in the right place |
|
|
56
|
-
| Stale pointers found only from the code side (route or file moved, no doc cites the old path) |
|
|
57
|
-
| Capability-register status (`one` / `bypassed` / `split` / `gap`) |
|
|
58
|
-
| Architecture graph diagram correctness |
|
|
59
|
-
| Turning a check into a CI gate |
|
|
60
|
-
| A stale fact inside a historical record |
|
|
61
|
-
| Instruction files each agent host loads; agent permissions, hooks, tool servers |
|
|
62
|
-
| 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 |
|
|
63
64
|
|
|
64
65
|
### Pre-Flight / Dependencies
|
|
65
66
|
|
|
66
67
|
#### Core
|
|
67
68
|
|
|
68
|
-
- [ ] **Permissions:** blocked
|
|
69
|
-
- [ ] **Repo Read:** Steps 2-13 — live docs, instruction files, manifests
|
|
70
|
-
- [ ] **Web:** Step 14 — fetch anchor standards. Fallback: versions
|
|
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.
|
|
71
72
|
|
|
72
73
|
#### Conditional
|
|
73
74
|
|
|
74
|
-
- [ ] **Prose and Format:** Step 4 — e.g
|
|
75
|
-
- [ ] **Managed-Block Check:** bkit project → Step 4 — e.g
|
|
76
|
-
- [ ] **Link Checker:** Step 4 — offline fragments plus cached external URLs
|
|
77
|
-
- [ ] **Diagram Renderer:**
|
|
78
|
-
- [ ] **API Doc Validator:**
|
|
79
|
-
- [ ] **Local Memory:**
|
|
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`.
|
|
80
81
|
|
|
81
82
|
### 🔒 Gate 1: Prerequisites Check
|
|
82
83
|
|
|
83
|
-
- [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
|
|
84
|
-
- [ ] **Gate 1 — Verified:**
|
|
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.
|
|
85
86
|
|
|
86
87
|
### Probe Steps
|
|
87
88
|
|
|
88
|
-
- [ ] **Step 1 — Previous Run:** **Done when:**
|
|
89
|
-
- [ ] **Step 2 — Scope:**
|
|
90
|
-
- [ ] **Step 3 — Catalogue:** `.agents/docs.md
|
|
91
|
-
- [ ] **Step 4 — Mechanical:** Run prose lint, format check
|
|
92
|
-
-
|
|
93
|
-
-
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
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.
|
|
97
99
|
|
|
98
|
-
|
|
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.
|
|
99
101
|
|
|
100
|
-
- [ ] **Step 5 — Ledgers:** Rows cited by `key` (`.bkit/jsonl.md` § Key & References). Resolve winning row
|
|
101
|
-
-
|
|
102
|
-
- `docs/completed.md` or plan → do not edit.
|
|
103
|
-
-
|
|
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.
|
|
104
106
|
|
|
105
|
-
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.
|
|
106
108
|
|
|
107
|
-
- [ ] **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.
|
|
108
110
|
|
|
109
111
|
<!-- prettier-ignore -->
|
|
110
112
|
| Claim type | Check against |
|
|
111
113
|
| --- | --- |
|
|
112
|
-
| 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 |
|
|
113
115
|
| What a script does | The script, end to end. Look hardest for anything that deletes |
|
|
114
116
|
| Which parts exist, on which platform | The code, on every platform the doc claims |
|
|
115
117
|
| `file:line` | Open the line. It must still say what the doc claims |
|
|
116
118
|
| Section links (`§ Heading`) | The heading exists, word for word |
|
|
117
119
|
| Counts and lists | Count them again |
|
|
118
120
|
|
|
119
|
-
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.
|
|
127
|
+
|
|
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.
|
|
129
|
+
|
|
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.
|
|
131
|
+
|
|
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.
|
|
120
133
|
|
|
121
|
-
|
|
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.
|
|
122
135
|
|
|
123
|
-
|
|
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.
|
|
124
144
|
|
|
125
|
-
|
|
145
|
+
**Done when:** `Memory` holds each hit, or the skip is recorded.
|
|
126
146
|
|
|
127
|
-
- [ ] **Step
|
|
128
|
-
- [ ] **Step
|
|
129
|
-
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
-
|
|
133
|
-
-
|
|
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.
|
|
134
157
|
|
|
135
|
-
**Done when:** `
|
|
158
|
+
**Done when:** `Topics` holds the duplicates, the quadrant labels, and any compress candidate.
|
|
136
159
|
|
|
137
|
-
- [ ] **Step
|
|
138
|
-
- [ ] **Step
|
|
139
|
-
- [ ] **Step
|
|
140
|
-
- [ ] **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.
|
|
141
|
-
- [ ] **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`.
|
|
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`.
|
|
142
163
|
|
|
143
164
|
### 🔒 Gate 2: Probes Check
|
|
144
165
|
|
|
145
|
-
- [ ] **Steps complete:** every step `[x]`, or
|
|
146
|
-
- [ ] **Evidence:** every finding cites
|
|
147
|
-
- [ ] **No secrets:** no secret or credential value anywhere in the report.
|
|
148
|
-
- [ ] **
|
|
149
|
-
- [ ] **
|
|
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.
|
|
150
173
|
|
|
151
174
|
## Findings
|
|
152
175
|
|
|
153
176
|
<!-- prettier-ignore -->
|
|
154
177
|
| Severity | Use |
|
|
155
178
|
| --- | --- |
|
|
156
|
-
| `CRITICAL` | Following the doc destroys data, skips a safety check, or blocks a fresh start with no workaround written
|
|
157
|
-
| `HIGH` |
|
|
158
|
-
| `MEDIUM` |
|
|
159
|
-
| `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. |
|
|
160
183
|
|
|
161
|
-
Within a severity
|
|
184
|
+
Within a severity, list destructive steps and contradictions first.
|
|
162
185
|
|
|
163
186
|
<!-- prettier-ignore -->
|
|
164
187
|
| ID | Severity | Location | Evidence | Expected |
|
|
165
188
|
| --- | --- | --- | --- | --- |
|
|
166
189
|
| PENDING | PENDING | PENDING | PENDING | PENDING |
|
|
167
190
|
|
|
168
|
-
|
|
191
|
+
**If** the run finds nothing → write one row: `None`.
|
|
169
192
|
|
|
170
193
|
## Report
|
|
171
194
|
|
|
@@ -254,13 +277,15 @@ PENDING
|
|
|
254
277
|
|
|
255
278
|
### 🔒 Gate 3: Report Check
|
|
256
279
|
|
|
257
|
-
- [ ] **No placeholders:** no `PENDING` left
|
|
258
|
-
- [ ] **Summary:**
|
|
259
|
-
- [ ] **Series:** load size, and setup-walk times when the walk ran, beside previous report's numbers, or
|
|
260
|
-
- [ ] **Writes:** only this report, template `Project Instructions
|
|
261
|
-
- [ ] **
|
|
262
|
-
- [ ] **
|
|
263
|
-
- [ ] **
|
|
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.
|
|
264
289
|
|
|
265
290
|
<!-- bkit:end -->
|
|
266
291
|
|