@cbartens/bkit 0.0.0-stage → 5.0.1
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 +417 -0
- package/.bkit/core/.agents/context.md +95 -0
- package/.bkit/core/.agents/docs.md +62 -0
- package/.bkit/core/.agents/rules.md +147 -0
- package/.bkit/core/.agents/skills.md +43 -0
- package/.bkit/core/.bkit/LICENSE.md +151 -0
- package/.bkit/core/.bkit/README.md +417 -0
- package/.bkit/core/.bkit/cloud.md +493 -0
- package/.bkit/core/.bkit/comparison.md +321 -0
- package/.bkit/core/.bkit/install.md +401 -0
- package/.bkit/core/.bkit/jsonl.md +497 -0
- package/.bkit/core/.bkit/prompts.md +474 -0
- package/.bkit/core/.bkit/providers.md +598 -0
- package/.bkit/core/.bkit/templates.md +470 -0
- package/.bkit/core/.bkit/trackers.md +95 -0
- package/.bkit/core/.bkit/workflows.md +1550 -0
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
- package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
- package/.bkit/core/AGENTS.md +77 -0
- package/.bkit/core/LICENSE.md +149 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
- package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
- package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
- package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
- package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
- package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
- package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
- package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
- package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
- package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
- package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
- package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
- package/.bkit/core/docs/templates/bkit-plan.md +476 -0
- package/.bkit/core/engine/checks/after/auth.ts +149 -0
- package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
- package/.bkit/core/engine/checks/after/github.ts +424 -0
- package/.bkit/core/engine/checks/after/index.ts +530 -0
- package/.bkit/core/engine/checks/after/managed.ts +217 -0
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/after/tools.ts +427 -0
- package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
- package/.bkit/core/engine/checks/before/env.ts +187 -0
- package/.bkit/core/engine/checks/before/files.ts +204 -0
- package/.bkit/core/engine/checks/before/index.ts +206 -0
- package/.bkit/core/engine/checks/before/mcp.ts +127 -0
- package/.bkit/core/engine/checks/before/repo.ts +77 -0
- package/.bkit/core/engine/checks/before/version.ts +67 -0
- package/.bkit/core/engine/checks/status-holes.ts +479 -0
- package/.bkit/core/engine/cli.ts +867 -0
- package/.bkit/core/engine/commands/analysis.ts +550 -0
- package/.bkit/core/engine/commands/ci/ci.ts +483 -0
- package/.bkit/core/engine/commands/comply.ts +415 -0
- package/.bkit/core/engine/commands/harvest.ts +459 -0
- package/.bkit/core/engine/commands/install/check.ts +70 -0
- package/.bkit/core/engine/commands/install/doctor.ts +254 -0
- package/.bkit/core/engine/commands/install/install.ts +550 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
- package/.bkit/core/engine/commands/launch.ts +139 -0
- package/.bkit/core/engine/commands/lib.ts +495 -0
- package/.bkit/core/engine/commands/registry.ts +53 -0
- package/.bkit/core/engine/commands/setup/setup.ts +184 -0
- package/.bkit/core/engine/commands/telemetry.ts +32 -0
- package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
- package/.bkit/core/engine/commands/workflow/context.ts +961 -0
- package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
- package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
- package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
- package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
- package/.bkit/core/engine/commands/workflow/status.ts +455 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
- package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
- package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
- package/.bkit/core/engine/install/cloud-env.ts +924 -0
- package/.bkit/core/engine/install/managed-block.ts +212 -0
- package/.bkit/core/engine/install/manifest.ts +448 -0
- package/.bkit/core/engine/install/modules/claude.ts +362 -0
- package/.bkit/core/engine/install/modules/cloud.ts +173 -0
- package/.bkit/core/engine/install/modules/codex.ts +219 -0
- package/.bkit/core/engine/install/modules/core.ts +620 -0
- package/.bkit/core/engine/install/modules/cursor.ts +231 -0
- package/.bkit/core/engine/install/modules/index.ts +242 -0
- package/.bkit/core/engine/install/modules/opencode.ts +573 -0
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/placeholders.ts +108 -0
- package/.bkit/core/engine/install/template-copies.ts +119 -0
- package/.bkit/core/engine/install/version-file.ts +284 -0
- package/.bkit/core/engine/install/write.ts +467 -0
- package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
- package/.bkit/core/engine/ledgers/status.ts +213 -0
- package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
- package/.bkit/core/engine/render/hosts.ts +372 -0
- package/.bkit/core/engine/render/models.ts +323 -0
- package/.bkit/core/engine/render/parts.ts +38 -0
- package/.bkit/core/engine/render/trackers.ts +170 -0
- package/.bkit/core/engine/shared/egress.ts +345 -0
- package/.bkit/core/engine/shared/json.ts +16 -0
- package/.bkit/core/engine/shared/log-prefix.ts +9 -0
- package/.bkit/core/engine/shared/package-json.ts +29 -0
- package/.bkit/core/engine/shared/package-manager.ts +38 -0
- package/.bkit/core/engine/shared/package-roots.ts +163 -0
- package/.bkit/core/engine/shared/protected-paths.ts +164 -0
- package/.bkit/core/engine/shared/settings.ts +72 -0
- package/.bkit/core/engine/shared/timeouts.ts +20 -0
- package/.bkit/core/engine/tools/wording.ts +748 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
- package/.bkit/core/hooks/gateguard-engine.js +193 -0
- package/.bkit/core/hooks/guardrails-shell.js +154 -0
- package/.bkit/core/hooks/guardrails-tiers.js +68 -0
- package/.bkit/core/hooks/preflight-linear.sh +73 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
- package/.bkit/core/prompts/bkit-build-summary.md +93 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
- package/.bkit/core/prompts/bkit-design-generate.md +110 -0
- package/.bkit/core/prompts/bkit-design-organise.md +85 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
- package/.bkit/core/prompts/bkit-design-spike.md +97 -0
- package/.bkit/core/prompts/bkit-design-summary.md +106 -0
- package/.bkit/core/prompts/bkit-design-update.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
- package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
- package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
- package/.bkit/core/prompts/bkit-plan-update.md +68 -0
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
- package/.bkit/core/workflows/bkit-auto.md +121 -0
- package/.bkit/core/workflows/bkit-build.md +802 -0
- package/.bkit/core/workflows/bkit-debug.md +649 -0
- package/.bkit/core/workflows/bkit-design.md +495 -0
- package/.bkit/core/workflows/bkit-plan.md +510 -0
- package/.bkit/core/workflows/bkit-ship.md +650 -0
- package/.bkit/shared/.bkit/.env.example +86 -0
- package/.bkit/shared/.claude/bkit-cloud.md +117 -0
- package/.bkit/shared/.claude/settings.json +88 -0
- package/.bkit/shared/.codex/hooks.json +26 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
- package/.bkit/shared/.cursor/hooks.json +26 -0
- package/.bkit/shared/.cursor/mcp.json +15 -0
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
- package/.bkit/shared/.gitattributes +37 -0
- package/.bkit/shared/.mcp.json +16 -0
- package/.bkit/shared/.opencode/opencode.json +62 -0
- package/.bkit/shared/CLAUDE.md +11 -0
- package/.bkit/shared/LICENSE.md +22 -0
- package/.bkit/shared/docs/architecture.md +19 -0
- package/.bkit/shared/docs/data-schema.md +19 -0
- package/.bkit/shared/docs/deployments.md +433 -0
- package/.bkit/shared/docs/design.md +39 -0
- package/.bkit/shared/docs/noise.md +19 -0
- package/.bkit/shared/docs/observability.md +25 -0
- package/.bkit/shared/docs/security.md +42 -0
- package/.bkit/shared/docs/setup.md +30 -0
- package/.bkit/shared/docs/technology.md +18 -0
- package/.bkit/shared/docs/testing.md +413 -0
- package/.bkit/shared/gitignore +97 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
- package/.bkit/templates/.cursor/Dockerfile +68 -0
- package/.bkit/templates/.cursor/environment.json +6 -0
- package/.bkit/templates/.cursor/settings.json +11 -0
- package/.bkit/templates/.envrc +7 -0
- package/.bkit/templates/.github/dependabot.yml +52 -0
- package/.bkit/templates/.github/renovate.json5 +224 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
- package/.bkit/templates/.graphifyignore +108 -0
- package/.bkit/templates/.husky/pre-commit +16 -0
- package/.bkit/templates/.husky/pre-push +91 -0
- package/.bkit/templates/.lintstagedrc.json +3 -0
- package/.bkit/templates/.prettierignore +41 -0
- package/.bkit/templates/.serena/project.yml +243 -0
- package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
- package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
- package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
- package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
- package/.bkit/templates/.vale.ini +67 -0
- package/.bkit/templates/LICENSE.md +22 -0
- package/.bkit/templates/context/bkit-cloudrun.md +84 -0
- package/.bkit/templates/context/bkit-expo.md +186 -0
- package/.bkit/templates/context/bkit-github.md +79 -0
- package/.bkit/templates/context/bkit-inngest.md +45 -0
- package/.bkit/templates/context/bkit-maestro.md +76 -0
- package/.bkit/templates/context/bkit-playwright.md +62 -0
- package/.bkit/templates/context/bkit-resend.md +36 -0
- package/.bkit/templates/context/bkit-sentry.md +65 -0
- package/.bkit/templates/context/bkit-serena.md +33 -0
- package/.bkit/templates/context/bkit-stripe.md +36 -0
- package/.bkit/templates/context/bkit-supabase.md +59 -0
- package/.bkit/templates/context/bkit-tavily.md +49 -0
- package/.bkit/templates/context/bkit-vercel.md +64 -0
- package/.bkit/templates/docs/capabilities.md +72 -0
- package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
- package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
- package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
- package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
- package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
- package/.bkit/templates/slop-scan.config.json +120 -0
- package/CHANGELOG.md +1503 -0
- package/LICENSE.md +161 -0
- package/README.md +184 -2
- package/dist/checks/after/auth.js +140 -0
- package/dist/checks/after/ci-yml.js +681 -0
- package/dist/checks/after/github.js +400 -0
- package/dist/checks/after/index.js +431 -0
- package/dist/checks/after/managed.js +187 -0
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/after/tools.js +351 -0
- package/dist/checks/before/context-fetch.js +426 -0
- package/dist/checks/before/env.js +163 -0
- package/dist/checks/before/files.js +187 -0
- package/dist/checks/before/index.js +162 -0
- package/dist/checks/before/mcp.js +111 -0
- package/dist/checks/before/repo.js +71 -0
- package/dist/checks/before/version.js +60 -0
- package/dist/checks/status-holes.js +393 -0
- package/dist/cli.js +688 -0
- package/dist/commands/analysis.js +325 -0
- package/dist/commands/ci/ci.js +438 -0
- package/dist/commands/comply.js +310 -0
- package/dist/commands/harvest.js +354 -0
- package/dist/commands/install/check.js +61 -0
- package/dist/commands/install/doctor.js +209 -0
- package/dist/commands/install/install.js +475 -0
- package/dist/commands/install/uninstall.js +839 -0
- package/dist/commands/install/upgrade.js +782 -0
- package/dist/commands/launch.js +118 -0
- package/dist/commands/lib.js +363 -0
- package/dist/commands/registry.js +50 -0
- package/dist/commands/setup/setup.js +158 -0
- package/dist/commands/telemetry.js +29 -0
- package/dist/commands/workflow/branches.js +1265 -0
- package/dist/commands/workflow/context.js +846 -0
- package/dist/commands/workflow/counters.js +227 -0
- package/dist/commands/workflow/fids.js +224 -0
- package/dist/commands/workflow/issues.js +585 -0
- package/dist/commands/workflow/ledgers.js +472 -0
- package/dist/commands/workflow/locks.js +364 -0
- package/dist/commands/workflow/prs.js +904 -0
- package/dist/commands/workflow/repo.js +199 -0
- package/dist/commands/workflow/roadmap.js +495 -0
- package/dist/commands/workflow/runs.js +1717 -0
- package/dist/commands/workflow/runtime.js +257 -0
- package/dist/commands/workflow/skills.js +110 -0
- package/dist/commands/workflow/status.js +392 -0
- package/dist/commands/workflow/steps.js +1093 -0
- package/dist/commands/workflow/tests.js +144 -0
- package/dist/commands/workflow/workflows.js +1342 -0
- package/dist/commands/workflow/workstreams.js +141 -0
- package/dist/commands/workflow/worktrees.js +473 -0
- package/dist/install/cloud-env.js +818 -0
- package/dist/install/managed-block.js +182 -0
- package/dist/install/manifest.js +376 -0
- package/dist/install/modules/claude.js +288 -0
- package/dist/install/modules/cloud.js +151 -0
- package/dist/install/modules/codex.js +193 -0
- package/dist/install/modules/core.js +531 -0
- package/dist/install/modules/cursor.js +186 -0
- package/dist/install/modules/index.js +152 -0
- package/dist/install/modules/opencode.js +504 -0
- package/dist/install/payload-links.js +119 -0
- package/dist/install/placeholders.js +87 -0
- package/dist/install/template-copies.js +106 -0
- package/dist/install/version-file.js +204 -0
- package/dist/install/write.js +342 -0
- package/dist/ledgers/clamp-log.js +27 -0
- package/dist/ledgers/status.js +156 -0
- package/dist/ledgers/telemetry.js +637 -0
- package/dist/render/hosts.js +339 -0
- package/dist/render/models.js +288 -0
- package/dist/render/parts.js +33 -0
- package/dist/render/trackers.js +135 -0
- package/dist/shared/egress.js +299 -0
- package/dist/shared/json.js +16 -0
- package/dist/shared/log-prefix.js +7 -0
- package/dist/shared/package-json.js +22 -0
- package/dist/shared/package-manager.js +32 -0
- package/dist/shared/package-roots.js +145 -0
- package/dist/shared/protected-paths.js +153 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +19 -0
- package/dist/tools/wording.js +680 -0
- package/package.json +101 -4
|
@@ -0,0 +1,222 @@
|
|
|
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. `@bkit-audit-generate` fills this template. -->
|
|
2
|
+
|
|
3
|
+
<!-- bkit:start -->
|
|
4
|
+
|
|
5
|
+
{{BKIT_MANAGED_MARKER}}
|
|
6
|
+
|
|
7
|
+
# Reliability Audit
|
|
8
|
+
|
|
9
|
+
> [!CAUTION]
|
|
10
|
+
> **Purpose:** What the product does when a dependency is slow, down, or delivered twice: dropped errors, missing timeouts, unsafe retries, races, unbounded work, and failure modes no alert reports.
|
|
11
|
+
>
|
|
12
|
+
> **Rules:**
|
|
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 evidence (`file:line`, or command / query and its output) and tool behind it.
|
|
21
|
+
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
22
|
+
> - never take a dependency down, inject a fault, or change an alert, monitor, or flag. A game day is a separate exercise; this run only records its date and outcome.
|
|
23
|
+
> - never run a replay, retry, send, charge, or restore. Read the procedure only.
|
|
24
|
+
|
|
25
|
+
## Universal Instructions
|
|
26
|
+
|
|
27
|
+
### Context & Goals
|
|
28
|
+
|
|
29
|
+
Failure paths are least-tested: happy path is tested; vendor outage stays unwalked until it happens. Target failure: **a dependency is slow, down, or delivered twice, and the call site answers with success** — e.g. write whose error is dropped, route returns success, no event fires, no dashboard sees it. Each new call site drifts that answer.
|
|
30
|
+
|
|
31
|
+
**Applies when:** outbound calls, webhook receivers, background jobs, or write paths. None → one `N/A` row with evidence, never "clean".
|
|
32
|
+
|
|
33
|
+
**Cadence:** quarterly. Extra pass when a new vendor, webhook, or background job lands. Game day in `Degradation` is separate, also quarterly, on its own date; each run records when it last happened.
|
|
34
|
+
|
|
35
|
+
**Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
|
|
36
|
+
|
|
37
|
+
- Google SRE Workbook (online edition): Implementing SLOs, Alerting on SLOs (multi-window, multi-burn-rate), Example error budget policy.
|
|
38
|
+
- Google SRE Book (online edition): Postmortem Culture.
|
|
39
|
+
- AWS Well-Architected Framework, Reliability Pillar: REL05 BP01–BP07 (graceful degradation, throttling, retries, fail fast, client timeouts, stateless, emergency levers), REL11 (static stability), REL13 (disaster recovery). Record the publication date read.
|
|
40
|
+
- Background-job flow-control docs (e.g. Inngest concurrency and `createFunction`, Temporal task queues).
|
|
41
|
+
|
|
42
|
+
### Scope
|
|
43
|
+
|
|
44
|
+
- Outbound calls, webhook receivers, background work, write paths. Hard vs soft, including transitive dependencies.
|
|
45
|
+
- Critical journeys, SLOs, error-budget policy.
|
|
46
|
+
- Dropped errors, timeouts, retries, idempotency, races, unbounded work.
|
|
47
|
+
- User-local time, where the product schedules.
|
|
48
|
+
- What the user sees when a dependency is down; every dependency walked on paper; last game day recorded, not run.
|
|
49
|
+
- Emergency levers, recovery targets, disaster paths.
|
|
50
|
+
- Deploys, old clients, alerts, runbooks, incident response.
|
|
51
|
+
|
|
52
|
+
### Out of Scope
|
|
53
|
+
|
|
54
|
+
<!-- prettier-ignore -->
|
|
55
|
+
| Excluded item | Why | Where it belongs |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| Errors that already reached a log | That sweep reads them; this sweep is failures that never reach a log | `bkit-audit-logs` |
|
|
58
|
+
| Grants, catalogue integrity, restore drill | Database sweep | `bkit-audit-database` |
|
|
59
|
+
| Query plans and database-side limits | Database sweep | `bkit-audit-database` |
|
|
60
|
+
| Live fault injection | Separate exercise, under that audit's rules | `bkit-audit-red-team` |
|
|
61
|
+
| Prompt bounds, call limits, evals | LLM sweep | `bkit-audit-llm` |
|
|
62
|
+
| Which model is called, deprecation, registry | Registry sweep | `bkit-audit-models` |
|
|
63
|
+
| Copied wrappers as duplication | Duplication sweep | `bkit-audit-duplication` |
|
|
64
|
+
| Adding a lint or test gate | Gates sweep | `bkit-audit-gates` |
|
|
65
|
+
| Rewriting a doc that omits a surface | Docs sweep | `bkit-audit-documentation` |
|
|
66
|
+
| Store-side version settings | Store sweep | `bkit-audit-app-store` |
|
|
67
|
+
| Whether an outside caller is allowed to trigger a replay | Security sweep; this audit still reads idempotency | `bkit-audit-security` |
|
|
68
|
+
| Changing code, alerts, or monitors | Audit reports only | Plan from this report |
|
|
69
|
+
|
|
70
|
+
### Pre-Flight / Dependencies
|
|
71
|
+
|
|
72
|
+
**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.
|
|
73
|
+
|
|
74
|
+
#### Core
|
|
75
|
+
|
|
76
|
+
Always verify.
|
|
77
|
+
|
|
78
|
+
- [ ] **Code Search:** Steps 2–12, 14, 16 — text search and language server for callers, e.g. ripgrep, Serena, `tsserver`. Language-server hits under-report; empty is inconclusive → corroborate with text search and name the tool. Fallback: text search only; name it per claim.
|
|
79
|
+
- [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
|
|
80
|
+
|
|
81
|
+
#### Conditional
|
|
82
|
+
|
|
83
|
+
Verify only when applicable.
|
|
84
|
+
|
|
85
|
+
- [ ] **Metrics:** Hosted traces, errors, or health endpoint → Steps 3, 13 — SLO queries and alert config, e.g. Sentry, Datadog, Better Stack. Fallback: repo config only; live measurements `Not Checked`.
|
|
86
|
+
- [ ] **Job Platform:** Background jobs → Steps 6, 7 — flow control and replay docs, read-only, e.g. Inngest, Temporal. Fallback: code only; live run history `Not Checked`.
|
|
87
|
+
- [ ] **Deploy Platform:** Hosted deploys → Step 12 — skew protection, rollout, rollback history, e.g. Vercel API, Cloud Run. Fallback: repo config only; dashboard settings `Not Checked`.
|
|
88
|
+
- [ ] **Vendor Status:** External dependencies → Step 13 — status feeds. Fallback: none; feeds `Not Checked`.
|
|
89
|
+
|
|
90
|
+
### 🔒 Gate 1: Prerequisites Check
|
|
91
|
+
|
|
92
|
+
**Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
|
|
93
|
+
|
|
94
|
+
- [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
|
|
95
|
+
- [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
|
|
96
|
+
|
|
97
|
+
### Probe Steps
|
|
98
|
+
|
|
99
|
+
- [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
|
|
100
|
+
- [ ] **Step 2 — Surfaces:** One table, kept run to run for diffs. Outbound calls (every SDK client and every `fetch` host); webhook receivers; background work (job functions and scheduled database jobs); write paths (routes and server actions that change data). Per dependency: hard (journey fails without it) or soft (degrades), and what it depends on in turn. Transitive counts (e.g. auth mail via mail vendor → mail outage is sign-in outage). Surface in code, not docs = finding; doc rewrite → `bkit-audit-documentation`. **Done when:** `Surfaces` lists every surface with hard/soft and transitive deps, or `N/A` and STOP.
|
|
101
|
+
- [ ] **Step 3 — Journeys:** Every user-reliant journey. Per journey: SLI as good/total ratio, SLO over rolling 28-day window, current measurement with query that produced it. Keep table run to run. No target, or target nobody measures = finding. Error-budget policy: what changes when budget spent (e.g. feature freeze, mandatory postmortem when one incident uses >20% of budget). Record whether policy triggered since previous run and whether obeyed. No policy = finding. **Done when:** `Journeys` row per journey: SLI · SLO · measurement and query · budget triggered · obeyed.
|
|
102
|
+
- [ ] **Step 4 — Dropped Errors:** Codebase-wide, not only errors that reached a log (`bkit-audit-logs` owns those). `catch` that neither rethrows, returns error, nor logs at `warn` or above; client calls whose error never read (e.g. Supabase `{ error }`, AWS SDK, Prisma); promises without `await` or `.catch`; broad catches turning every failure into one generic message so caller cannot tell timeout from bug. Dropped, never logged = invisible to user and operators; those first. Deliberate best-effort (telemetry, fire-and-forget notification) OK when code says so. Linter-catchable class (e.g. `@typescript-eslint/no-floating-promises`, unread client `error`) → name rule under `Process Improvements`; do not add it. Adding gate → `bkit-audit-gates`. **Done when:** every hit = finding with `file:line`.
|
|
103
|
+
- [ ] **Step 5 — Timeouts:** Per outbound call from `Surfaces`. Timeout (`fetch` none by default; SDK may or may not). No timeout holds function open until platform kills it. Each timeout × attempts + backoff fits inside calling function's duration limit; each inner timeout shorter than outer. Function killed at limit reports nothing; platform timeouts → `bkit-audit-logs`; this step owns budget. Bounded retries with backoff on worth-retrying errors (timeouts, 429, 5xx), never 4xx. Retries only on safe ops: retrying create, charge, or send without idempotency key does it twice. Background-job retry setting (e.g. Inngest `retries`) and re-run behavior per step. Model call has fallback model/provider list or degraded path without model. Models listed → `bkit-audit-models`. Token caps and evals → `bkit-audit-llm`. Credit-limit vs rate-limit responses distinct, not one generic retry: credit limit does not succeed on retry unless `Retry-After`; rate limit backs off (e.g. OpenRouter `402` / `429`). Shared outbound client with default timeout/retry → check bypasses; absent → propose under `Process Improvements`. Same wrapper copied → name for `bkit-audit-duplication`. **Done when:** every call from `Surfaces` has timeout, budget, retry, and safety verdict.
|
|
104
|
+
- [ ] **Step 6 — Idempotency:** Webhooks at-least-once; job step re-runs after failure. Per receiver/step, second run harmless: dedupe on provider event id, conditional update, or naturally idempotent. Side effects (email, charge, row insert) outside step run again on every retry. Outside caller repeating create → `bkit-audit-security` and `bkit-audit-red-team`; this step reads code. Run failed for good needs written replay/bulk-retry procedure, tried on preview — read only, do not run. Replay creates new runs → repeats side effects this step did not make safe; reaches back only as far as plan history retention. Terminal failure with no replay path = lost work. **Done when:** every receiver and step has verdict; replay path or replacing finding recorded.
|
|
105
|
+
- [ ] **Step 7 — Races:** Read-modify-write with no lock, conditional update, or unique constraint. Partial writes: two+ mutations outside transaction or stored procedure (e.g. client calls outside RPC). Concurrent jobs on same row/tenant with no concurrency key. Per job function: `concurrency` (key and scope), `throttle`, `rateLimit`, `idempotency`, `retries`, `onFailure` (or platform equivalents). Overlapping cron = finding. No failure handler leaving half-done state on terminal fail = finding. Unbounded work: loops over every tenant/row, queries with no limit (database-side limits → `bkit-audit-database`), fan-out with no cap, payloads with no size limit. Vendor ceilings (pooler client limit, job concurrency cap, mail send rate, model rate limit) vs expected peak product is sized for. Load test proposed under `Process Improvements`, not run. **Done when:** every function's flow-control settings and every unbounded site have verdict.
|
|
106
|
+
- [ ] **Step 8 — Time:** Product stores/sends user-local times → DST transitions, cron timezone vs user-local send time, recurrence crossing DST, month-end (31st, February). Name test pinning each case; no test = finding. No user-local times → skip with evidence. **Done when:** each case names test, or skip recorded.
|
|
107
|
+
- [ ] **Step 9 — Degradation:** Per `Surfaces` dependency: what user sees and whether right. Documented deliberate fallback is model. Each dependency failure labelled with one upstream signal so outage reads as one thing, not many bugs. Offline client: queued or lost write, user told which; reconnect does not double-submit; no infinite spinner. Walk every dependency on paper: take down in reasoning, follow call sites, write what breaks — no fault injection. Live injection = quarterly game day: one dependency down on preview, under `bkit-audit-red-team`, separate exercise, never this run. Record last game day date/outcome; >1 quarter overdue = finding. Name next dependency to fault-inject and alert that must fire when down. **Done when:** per-dependency answer and paper walk in `Degradation`; date, outcome, next dependency in `Game Day`.
|
|
108
|
+
- [ ] **Step 10 — Levers:** Per costly/risky subsystem abusable or runaway (paid model calls, inbound automation, scrapers, outbound fan-out): lever off/down without deploy (flag, kill switch, throttle). Record who pulls, how, last pulled/tested. Code change + redeploy is not a lever. No lever = finding; untried lever = finding. **Done when:** `Levers` row per subsystem: lever · who · how · last tested · verdict.
|
|
109
|
+
- [ ] **Step 11 — Recovery:** State RPO (data loss) and RTO (time to work again) per data store and per `Journeys` row; compare with setup delivers. Read platform backup docs, do not assume. Restore drill → `bkit-audit-database`; this step owns whether targets written and achievable. DB backups often omit file storage, in-flight jobs, replay history, DNS, developer account access. Per store: recovery path or finding. Per scenario: path and who carries it out — region outage (name region); vendor account suspended or billing lapsed; lost source-host org, deploy team, or sole-account developer; key compromised and revoked. No path = finding. **Done when:** `Recovery` holds RPO, RTO, each scenario path, or replacing finding.
|
|
110
|
+
- [ ] **Step 12 — Deploys:** Most outages follow a change. Version skew: client loaded pre-deploy keeps reaching server code it was built against where platform offers that. Framework may not pin custom client-side fetches (e.g. `fetch` from Next.js client components); check newer-server handling. Schema/code order: expand first, contract later so either rolls back alone. Rollback speed: last rollback duration or rollback runbook drill. No drill and no measured rollback = finding. Progressive rollout: staged rollout or what stops bad deploy reaching all users; neither = finding. Old native clients cannot roll back. API tolerates oldest supported version; forced-update/minimum-version gate; update channels map to runtime versions. Record oldest version in production traffic and support window. Store-side settings → `bkit-audit-app-store`. **Done when:** each check met, finding, or not applicable (why).
|
|
111
|
+
- [ ] **Step 13 — Alerts:** Map each Step 4–9 failure mode to alert (error-tracker, health endpoint, uptime monitors, canaries, data-freshness, dropped-work). No alert = finding; alert with no runbook = finding. Whether alarms fire → `bkit-audit-logs`; this step checks coverage. `Journeys` SLO alert = burn-rate, long and short windows per Workbook, not raw threshold. Near-zero traffic: one failed request can look like outage — minimum request count or synthetic probe behind alert. Each vendor status feed reaches alert channel. **Done when:** `Alerts` maps every failure mode to alert, runbook, sensitivity verdict.
|
|
112
|
+
- [ ] **Step 14 — Incidents:** Severity levels, incident lead per incident, who told at each level and how. User comms: status page or in-app banner for outage plus message template. Drill with date. Never rehearsed = finding. Incidents since previous run: each blameless postmortem with owned actions; record closed actions. Gap = finding with proposal; do not file — report is output. **Done when:** `Incidents` states each requirement met or finding.
|
|
113
|
+
- [ ] **Step 15 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per REL05 BP01–BP07, REL11, REL13, each SLO and error-budget checklist item → checked (name step) / not applicable (why) / finding. Each row pass / partial / fail with evidence. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
|
|
114
|
+
- [ ] **Step 16 — Anything Else:** (a) Everything changed since previous report's commit touching reliability (outbound calls and hosts, webhook receivers, job functions and flow-control, scheduled jobs, write paths, timeouts and duration limits, alerts and monitors) → one-line verdict each. (b) Bounded ~30 min pass: what senior SRE flags that no step asks; read since previous run (incidents and postmortems, log-audit sweeps, 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`.
|
|
115
|
+
|
|
116
|
+
### 🔒 Gate 2: Probes Check
|
|
117
|
+
|
|
118
|
+
**Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
|
|
119
|
+
|
|
120
|
+
- [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
|
|
121
|
+
- [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
|
|
122
|
+
- [ ] **Read-only:** no dependency taken down; no replay, send, charge, or restore executed; no alert or monitor changed.
|
|
123
|
+
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
|
|
124
|
+
|
|
125
|
+
## Findings
|
|
126
|
+
|
|
127
|
+
<!-- prettier-ignore -->
|
|
128
|
+
| Severity | Use |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `CRITICAL` | Silent failure that drops or corrupts data with no user signal and no retry; charge or send that can happen twice with no reversal; hard dependency down takes a core journey down with no degraded path |
|
|
131
|
+
| `HIGH` | Silent write, or a double effect a person can repair; call with no timeout on a user-facing or job path; core failure mode with no alert; no written recovery target, or a target the setup cannot meet; costly subsystem with no emergency lever |
|
|
132
|
+
| `MEDIUM` | Journey with no SLO or no measurement; no error-budget policy; retry on a client error; overlapping scheduled job; unbounded loop or fan-out; alert with no runbook; untested lever; game day more than one quarter overdue; incident process never drilled |
|
|
133
|
+
| `LOW` | Soft dependency whose failure is unlabelled but the journey still succeeds; wording drift in an alert title |
|
|
134
|
+
|
|
135
|
+
Scale per `.bkit/jsonl.md` § Severity. Within a severity: money and data first, then a broken core action. A silent write, or a charge or send that can happen twice, is at least `HIGH`. Do not lower either because traffic is low.
|
|
136
|
+
|
|
137
|
+
<!-- prettier-ignore -->
|
|
138
|
+
| ID | Severity | Location | Evidence | Expected |
|
|
139
|
+
| --- | --- | --- | --- | --- |
|
|
140
|
+
| PENDING | PENDING | PENDING | PENDING | PENDING |
|
|
141
|
+
|
|
142
|
+
Empty and clean → one row `None`.
|
|
143
|
+
|
|
144
|
+
## Report
|
|
145
|
+
|
|
146
|
+
### Summary
|
|
147
|
+
|
|
148
|
+
PENDING
|
|
149
|
+
|
|
150
|
+
### Previous Run
|
|
151
|
+
|
|
152
|
+
PENDING
|
|
153
|
+
|
|
154
|
+
### Surfaces
|
|
155
|
+
|
|
156
|
+
PENDING
|
|
157
|
+
|
|
158
|
+
### Journeys
|
|
159
|
+
|
|
160
|
+
PENDING
|
|
161
|
+
|
|
162
|
+
### Degradation
|
|
163
|
+
|
|
164
|
+
PENDING
|
|
165
|
+
|
|
166
|
+
### Game Day
|
|
167
|
+
|
|
168
|
+
PENDING
|
|
169
|
+
|
|
170
|
+
### Levers
|
|
171
|
+
|
|
172
|
+
PENDING
|
|
173
|
+
|
|
174
|
+
### Recovery
|
|
175
|
+
|
|
176
|
+
PENDING
|
|
177
|
+
|
|
178
|
+
### Alerts
|
|
179
|
+
|
|
180
|
+
PENDING
|
|
181
|
+
|
|
182
|
+
### Incidents
|
|
183
|
+
|
|
184
|
+
PENDING
|
|
185
|
+
|
|
186
|
+
### Checked
|
|
187
|
+
|
|
188
|
+
PENDING
|
|
189
|
+
|
|
190
|
+
### Not Checked
|
|
191
|
+
|
|
192
|
+
PENDING
|
|
193
|
+
|
|
194
|
+
### Standards Coverage
|
|
195
|
+
|
|
196
|
+
PENDING
|
|
197
|
+
|
|
198
|
+
### Beyond the Steps
|
|
199
|
+
|
|
200
|
+
PENDING
|
|
201
|
+
|
|
202
|
+
### Process Improvements
|
|
203
|
+
|
|
204
|
+
PENDING
|
|
205
|
+
|
|
206
|
+
### 🔒 Gate 3: Report Check
|
|
207
|
+
|
|
208
|
+
**Checkpoint.** Verify and check `[x]` all boxes below, then stop.
|
|
209
|
+
|
|
210
|
+
- [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
|
|
211
|
+
- [ ] **Summary:** names count per severity, journeys measured, and that every dependency was walked on paper.
|
|
212
|
+
- [ ] **Series:** every series beside previous report's numbers, or marked baseline.
|
|
213
|
+
- [ ] **Game Day:** states the date and outcome of the last game day, or that none is recorded, and names the next dependency.
|
|
214
|
+
- [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
|
|
215
|
+
- [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
|
|
216
|
+
- [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
|
|
217
|
+
|
|
218
|
+
> `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.
|
|
219
|
+
|
|
220
|
+
<!-- bkit:end -->
|
|
221
|
+
|
|
222
|
+
## Project Instructions
|
|
@@ -0,0 +1,224 @@
|
|
|
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. `@bkit-audit-generate` fills this template. -->
|
|
2
|
+
|
|
3
|
+
<!-- bkit:start -->
|
|
4
|
+
|
|
5
|
+
{{BKIT_MANAGED_MARKER}}
|
|
6
|
+
|
|
7
|
+
# Repo Audit
|
|
8
|
+
|
|
9
|
+
> [!CAUTION]
|
|
10
|
+
> **Purpose:** Verdict on leftovers and layout — worktrees, branches, stashes, ignored files, placement, and repository posture against the standards.
|
|
11
|
+
>
|
|
12
|
+
> **Rules:**
|
|
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 evidence (`file:line`, or command / query and its output) and tool behind it.
|
|
21
|
+
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
22
|
+
> - NEVER delete, prune, push, drop a stash, or rewrite history; name the command, do not run it.
|
|
23
|
+
> - NEVER copy a secret or personal-data value into the report; name the file and line.
|
|
24
|
+
> - Name the machine. Local leftovers absent on a fresh checkout stay `Not Checked`.
|
|
25
|
+
|
|
26
|
+
## Universal Instructions
|
|
27
|
+
|
|
28
|
+
### Context & Goals
|
|
29
|
+
|
|
30
|
+
Every task leaves a worktree, branch, stash, or scratch directory; nothing's job is to remove them. Stale copies look like live work — search and agents read them; a leftover something keeps producing is a bug in that producer. Worse: cleanup by age deletes the only copy of unpushed work. Target: **every leftover judged before anything is called removable**, and a producer that keeps writing leftovers named as the bug.
|
|
31
|
+
|
|
32
|
+
**Applies when:** a git checkout. None → one `N/A` row with evidence, never "clean".
|
|
33
|
+
|
|
34
|
+
**Cadence:** monthly. Extra pass after a burst of parallel agent work (worktrees and branches pile up fastest).
|
|
35
|
+
|
|
36
|
+
**Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
|
|
37
|
+
|
|
38
|
+
- OpenSSF Scorecard checks; record the version run.
|
|
39
|
+
- OpenSSF OSPS Baseline, the version marked current.
|
|
40
|
+
- Host branch rulesets (e.g. GitHub rulesets, GitLab protected branches).
|
|
41
|
+
- Secret scanning push protection (e.g. GitHub secret scanning, GitLab secret push protection).
|
|
42
|
+
- Secret scanners (e.g. gitleaks, TruffleHog); record versions.
|
|
43
|
+
- Repository size tool (e.g. git-sizer); record version.
|
|
44
|
+
- Workspace dependency-version linter (e.g. sherif, syncpack); record version.
|
|
45
|
+
- RFC 9116 `security.txt`.
|
|
46
|
+
|
|
47
|
+
### Scope
|
|
48
|
+
|
|
49
|
+
- Worktrees, local, and remote branches, stashes, tags, stale pull requests.
|
|
50
|
+
- Ignored and untracked leftovers, including scratch directories and files stranded at the root.
|
|
51
|
+
- Secret and personal-data scan of leftovers and of history (names only).
|
|
52
|
+
- Tracked layout: size, history size, toolchain agreement, accidental publish, attributes, placement, naming, contribution scaffolding.
|
|
53
|
+
- Repository posture: scorecard subset, branch protection, security settings, disclosure route, accumulating installations.
|
|
54
|
+
|
|
55
|
+
### Out of Scope
|
|
56
|
+
|
|
57
|
+
<!-- prettier-ignore -->
|
|
58
|
+
| Excluded item | Why | Where it belongs |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| Code or config nothing reaches | Dead-code sweep | `bkit-audit-dead-code` |
|
|
61
|
+
| Whether a doc is true | Documentation sweep | `bkit-audit-documentation` |
|
|
62
|
+
| Dependency-update bot branches | Dependency sweep | `bkit-audit-dependencies` |
|
|
63
|
+
| Workflow token permissions, pinned actions, dangerous workflow | Security sweep | `bkit-audit-security` |
|
|
64
|
+
| People, 2FA, deploy keys, long-lived tokens | Security sweep | `bkit-audit-security` |
|
|
65
|
+
| Actions secrets and variables; settings versus docs | Config sweep | `bkit-audit-config` |
|
|
66
|
+
| Personal-data lifecycle | Privacy sweep | `bkit-audit-privacy` |
|
|
67
|
+
| Deleting, moving, pruning, or pushing | Audit reports only | Plan from this report |
|
|
68
|
+
|
|
69
|
+
### Verdicts
|
|
70
|
+
|
|
71
|
+
- **REMOVE:** provably safe. Merged by ancestry, patch-equivalent on the integration branch (`git cherry` shows only `-`), its pull request merged, or a regenerable artefact (build output, cache, coverage, test results).
|
|
72
|
+
- **RESCUE:** holds work that exists nowhere else (unpushed commits, uncommitted worktree edits, a stash whose changes are on no branch). Name what it holds and who would know. Pushing it, or dropping it on purpose, is the next step. At least `HIGH`.
|
|
73
|
+
- **MOVE:** kept, but in the wrong place or under a misleading name.
|
|
74
|
+
- **KEEP:** in use. Say what uses it.
|
|
75
|
+
- **ASK:** cannot tell from the evidence. Name who would know.
|
|
76
|
+
- **OTHER:** fits none. Say why. Same `OTHER` on 2 runs → propose new verdict in `Process Improvements`.
|
|
77
|
+
|
|
78
|
+
**Two traps.** Squash merge stays ahead of the integration branch by ancestry: check the pull request and `git cherry`, never `git branch --merged` alone. A worktree whose branch is fully merged can still hold uncommitted edits: `git status --porcelain` before REMOVE.
|
|
79
|
+
|
|
80
|
+
### Pre-Flight / Dependencies
|
|
81
|
+
|
|
82
|
+
**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.
|
|
83
|
+
|
|
84
|
+
#### Core
|
|
85
|
+
|
|
86
|
+
Always verify.
|
|
87
|
+
|
|
88
|
+
- [ ] **Git:** Steps 2–7, 9 — local checkout, worktrees, branches, stashes. Fallback: none; no checkout → `N/A` and STOP.
|
|
89
|
+
- [ ] **Host API:** Steps 4, 8 — read-only, e.g. `gh api`. Fallback: local git only; remote branches, pull requests, and settings `Not Checked`.
|
|
90
|
+
- [ ] **Web:** Step 10 — fetch anchor standards. Fallback: versions recorded as unread.
|
|
91
|
+
|
|
92
|
+
#### Conditional
|
|
93
|
+
|
|
94
|
+
Verify only when applicable.
|
|
95
|
+
|
|
96
|
+
- [ ] **Secret Scanners:** Leftovers or history → Steps 6–7 — e.g. gitleaks, TruffleHog. Fallback: pattern search; verified-credential check `Not Checked`. Reports outside the repo.
|
|
97
|
+
- [ ] **Repo Sizer:** History size → Step 7 — e.g. git-sizer. Fallback: `git rev-list` blob sizes.
|
|
98
|
+
- [ ] **Dependency Version Linter:** Workspaces → Step 7 — e.g. sherif, syncpack. Fallback: diff manifests by reading.
|
|
99
|
+
- [ ] **Scorecard:** Host exposes one → Step 8 — e.g. OpenSSF Scorecard, read-only token. Fallback: settings API only; scores `Not Checked`.
|
|
100
|
+
|
|
101
|
+
### 🔒 Gate 1: Prerequisites Check
|
|
102
|
+
|
|
103
|
+
**Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
|
|
104
|
+
|
|
105
|
+
- [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
|
|
106
|
+
- [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
|
|
107
|
+
|
|
108
|
+
### Probe Steps
|
|
109
|
+
|
|
110
|
+
- [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
|
|
111
|
+
- [ ] **Step 2 — Checkout:** Name machine and checkout. Worktrees, stashes, scratch directories are local — fresh cloud checkout sees none; say so, not clean. Remote branches and pull requests are shared; every run checks those. **Done when:** machine, checkout, and which surfaces are local-only in `Checked`.
|
|
112
|
+
- [ ] **Step 3 — Worktrees:** `git worktree list --porcelain`. Per worktree: branch, ahead/behind integration branch, `git cherry`, pull-request state, uncommitted changes (`git status --porcelain`), last commit date, size (`du -sh`). Locked or files modified in the last day → KEEP or ASK, never REMOVE (agent may still be running). Also `git worktree prune --dry-run` for entries whose directory is gone. Never prune for real. **Done when:** `Worktrees` row per entry with verdict; totals in `Totals`.
|
|
113
|
+
- [ ] **Step 4 — Branches:** Local: merged by ancestry, merged by squash (pull request merged, or `git cherry` all `-`), upstream gone, agent-prefix branches with no worktree. Remote: branches other than integration, production, dependency-update bot's, with pull-request state. Record delete-on-merge; when off, merged pull request leaves its branch. Unmerged with no pull request: every commit is RESCUE until shown otherwise. Open pull requests with no activity for 30 days, and old drafts. Tags no release or deploy uses. **Done when:** `Branches` row per item with verdict; counts in `Totals`.
|
|
114
|
+
- [ ] **Step 5 — Stashes:** `git stash list` with dates, then `git stash show --stat` for each. Check whether changes already landed on integration branch. Stashes a commit hook creates when it fails: usually commit was retried — verify before REMOVE. **Done when:** `Stashes` row per stash with verdict.
|
|
115
|
+
- [ ] **Step 6 — Leftovers:** Untracked (`git status --porcelain`) and ignored (`git ls-files --others --ignored --exclude-standard --directory`), each sized. Sort: regenerable (dependencies, task cache, coverage, test results, native build folders, tool caches) — REMOVE is safe, report the size; hand-made (notes, plans, backups, logs, scripts in the scratch directory) — group by age and type; open issue or plan references → KEEP; produced and not cleaned up — leftover REMOVE, producer is finding; stranded at root — find writer; tool defaulting to root → point elsewhere. Ignore file: rules matching nothing; leftovers untracked because no rule covers them. Scan secrets and personal data before any MOVE or REMOVE on scratch, root, or plan logs; scanner reports outside repo. Personal-data hits are candidates: test fixtures carry fake addresses. A real hit in a tracked file is not fixed by removing the file — it stays in history. Name the file and line, never the value. Hooks: hooks path resolves at the hook directory, each hook executable, and the install script installs them. A checkout where hooks silently do not run looks clean here while skipping every pre-commit control. **Done when:** `Leftovers` grouped with verdicts; scan result named; sizes in `Totals`.
|
|
116
|
+
- [ ] **Step 7 — Layout:** Read where tracked files belong; find misfits. Size: largest blobs at `HEAD`. Committed generated output/logs → MOVE or REMOVE candidates. Record pack size as series. History size: deleted file still grows clones — repository sizer or blob sizes across all refs. Images/logs → recommend large-file storage or ignore; history rewrite owner's call (ASK). Secrets in history: scan all refs; list every sensitive file ever added (example env files expected). Verified live credential → `CRITICAL`: rotation first (rewrite does not reach existing clones). Name file and commit, never value. Toolchain agreement: runtime pin, engine field, package-manager field, CI setup, host build image, native build config; workspace dependency-version linter for cross-workspace drift or catalog bypass. Docs-versus-files → documentation audit; this step files versus each other. Accidental publish: every workspace package not meant for a registry is marked unpublishable (e.g. npm `private: true`, Cargo `publish = false`), and the root states the licence position. Attributes: end-of-line, generated-file linguist marks so review diffs collapse them, binary marks on images, and an editor config that agrees with the formatter. Placement: root files belonging to app/package, finished one-off scripts, drafts beside final doc, unlinked archive folders, near-empty packages. Naming: folders/files breaking neighbour conventions. Contribution scaffolding: owners file, pull-request and issue templates, contributing note — present and true; whether team needs them → owner (ASK). Template describing unfollowed process → MOVE or REMOVE. Owners file: propose paths that weaken a gate when edited → required human review; once exists, host owners-errors API must return none. Unimported file → dead-code audit; misplaced-but-wrong doc → documentation audit. **Done when:** `Layout` rows; pack size and largest history blobs in `Totals`.
|
|
117
|
+
- [ ] **Step 8 — Posture:** Config audit asks settings vs docs; this step asks vs anchor standards. Read that audit's latest report first; do not duplicate findings. Shared settings: every run checks (local or cloud). Scorecard: each check's score as series. Keep binary artifacts, branch protection, code review, dependency-update tool, security policy here; token permissions, pinned dependencies, dangerous workflow → `bkit-audit-security`. Branch protection (integration, production): pull request required, required check required, force-push and deletion blocked, squash-only or linear history, bypass list — compare with production-merge-requires-PR rule. Security settings: secret scanning and push protection on; who may bypass push protection. Private repo: push protection may need paid secret-protection plan — say so if plan excludes it. Push protection blocks at server (hook bypass does not reach). Also dependency alerts, private vulnerability reporting, default automation token read-only, automation creating/approving pull requests off. Disclosure: security policy or private vulnerability reporting, and `/.well-known/security.txt` on production web origin with RFC contact/expiry fields and expiry ahead. People, 2FA, deploy keys, long-lived tokens → security audit; automation secrets/variables → config audit. Read their latest reports; confirm 2FA enforcement recorded. List accumulators like branches: installed apps and permissions, webhooks, environments. App over-scoped or webhook to unused service → REMOVE or ASK. **Done when:** `Posture` holds each setting met / finding / not applicable; scores in `Totals`.
|
|
118
|
+
- [ ] **Step 9 — Verify:** Git state changes hourly. Record when each check ran; re-check every RESCUE and REMOVE at end. No finding without re-checkable evidence: command and output, or `file:line`. Destinations (name; do not act): REMOVE → exact command next step would run, batched for one review; RESCUE → what it holds, who would know, decision (push and open pull request, or drop on purpose); MOVE → move and every reference to update; ASK → who would know and question; OTHER → why no verdict fits; leftover something keeps producing → `docs/failures.jsonl` row against producer (report; do not write ledger); missing/stale ignore rule → line to add or remove; code or config nothing reaches → `bkit-audit-dead-code`; a doc that is wrong, not misplaced → `bkit-audit-documentation`; dependency-bot branch → `bkit-audit-dependencies`; secret in history, log, or leftover → `bkit-audit-security`, rotation first, file and commit only; personal data in log or leftover → `bkit-audit-privacy`; repository setting below standard → setting to change for owner, doc drift → `bkit-audit-config`; workflow-level scorecard failure → `bkit-audit-security`; toolchain versions disagree → file to change; host setting → `bkit-audit-config`; dependency versions → `bkit-audit-dependencies`. **Done when:** every RESCUE and REMOVE re-checked, with time, verdict, and destination.
|
|
119
|
+
- [ ] **Step 10 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per Scorecard check and per baseline control in sets this audit touches (e.g. OSPS-AC, OSPS-BR-07, OSPS-GV, OSPS-LE, OSPS-VM) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
|
|
120
|
+
- [ ] **Step 11 — Anything Else:** (a) Everything changed since previous report's commit touching the repository itself (new top-level files and folders, workspaces, ignore, and attribute files, hooks, branch, and ruleset settings, host apps, webhooks, environments, anything new that writes to the scratch directory or the root) → one-line verdict each. (b) Bounded ~30 min pass: what a senior platform engineer 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`.
|
|
121
|
+
|
|
122
|
+
### 🔒 Gate 2: Probes Check
|
|
123
|
+
|
|
124
|
+
**Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
|
|
125
|
+
|
|
126
|
+
- [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
|
|
127
|
+
- [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
|
|
128
|
+
- [ ] **No values:** no secret or personal-data value anywhere in the report.
|
|
129
|
+
- [ ] **Nothing removed:** no worktree, branch, stash, file, or remote ref deleted or pushed.
|
|
130
|
+
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
|
|
131
|
+
|
|
132
|
+
## Findings
|
|
133
|
+
|
|
134
|
+
<!-- prettier-ignore -->
|
|
135
|
+
| Severity | Use |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| `CRITICAL` | Verified live credential in history, a log, or a leftover. Rotation first; a history rewrite does not reach existing clones |
|
|
138
|
+
| `HIGH` | RESCUE — work one cleanup command would lose; unverified secret material in history |
|
|
139
|
+
| `MEDIUM` | Leftover a test or script keeps producing; toolchain versions disagree; repository setting below the standard |
|
|
140
|
+
| `LOW` | Regenerable cache, reported by size; naming drift; contribution scaffolding the owner must decide |
|
|
141
|
+
|
|
142
|
+
Scale per `.bkit/jsonl.md` § Severity. Within a severity: live credentials, then RESCUE, before REMOVE.
|
|
143
|
+
|
|
144
|
+
<!-- prettier-ignore -->
|
|
145
|
+
| ID | Severity | Verdict | Location | Evidence | Expected |
|
|
146
|
+
| --- | --- | --- | --- | --- | --- |
|
|
147
|
+
| PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
|
|
148
|
+
|
|
149
|
+
Empty and clean → one row `None`.
|
|
150
|
+
|
|
151
|
+
## Report
|
|
152
|
+
|
|
153
|
+
### Summary
|
|
154
|
+
|
|
155
|
+
PENDING
|
|
156
|
+
|
|
157
|
+
### Previous Run
|
|
158
|
+
|
|
159
|
+
PENDING
|
|
160
|
+
|
|
161
|
+
### Totals
|
|
162
|
+
|
|
163
|
+
PENDING
|
|
164
|
+
|
|
165
|
+
### Worktrees
|
|
166
|
+
|
|
167
|
+
PENDING
|
|
168
|
+
|
|
169
|
+
### Branches
|
|
170
|
+
|
|
171
|
+
PENDING
|
|
172
|
+
|
|
173
|
+
### Stashes
|
|
174
|
+
|
|
175
|
+
PENDING
|
|
176
|
+
|
|
177
|
+
### Leftovers
|
|
178
|
+
|
|
179
|
+
PENDING
|
|
180
|
+
|
|
181
|
+
### Layout
|
|
182
|
+
|
|
183
|
+
PENDING
|
|
184
|
+
|
|
185
|
+
### Posture
|
|
186
|
+
|
|
187
|
+
PENDING
|
|
188
|
+
|
|
189
|
+
### Checked
|
|
190
|
+
|
|
191
|
+
PENDING
|
|
192
|
+
|
|
193
|
+
### Not Checked
|
|
194
|
+
|
|
195
|
+
PENDING
|
|
196
|
+
|
|
197
|
+
### Standards Coverage
|
|
198
|
+
|
|
199
|
+
PENDING
|
|
200
|
+
|
|
201
|
+
### Beyond the Steps
|
|
202
|
+
|
|
203
|
+
PENDING
|
|
204
|
+
|
|
205
|
+
### Process Improvements
|
|
206
|
+
|
|
207
|
+
PENDING
|
|
208
|
+
|
|
209
|
+
### 🔒 Gate 3: Report Check
|
|
210
|
+
|
|
211
|
+
**Checkpoint.** Verify and check `[x]` all boxes below, then stop.
|
|
212
|
+
|
|
213
|
+
- [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
|
|
214
|
+
- [ ] **Summary:** names count per severity, the machine, and the checkout.
|
|
215
|
+
- [ ] **Series:** `Totals` beside previous report's numbers, or marked baseline.
|
|
216
|
+
- [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
|
|
217
|
+
- [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
|
|
218
|
+
- [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
|
|
219
|
+
|
|
220
|
+
> `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.
|
|
221
|
+
|
|
222
|
+
<!-- bkit:end -->
|
|
223
|
+
|
|
224
|
+
## Project Instructions
|