@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.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,129 +1,147 @@
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
  # Agent Config Audit
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Per coding-agent host: instruction loading, permissions, hooks, tool servers, agent definitions, model pins — hosts agree, bkit-shipped gates included.
10
+ > **Purpose:** For each coding-agent host: instruction loading, permissions, hooks, tool servers, agent definitions and model pins — and the hosts agree, bkit-shipped gates included.
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - NEVER print or copy a token, key, or secret value; names, scopes, and presence only.
15
- > - never run `bkit install` / `bkit upgrade`.
16
- > - never call a tool-server tool; listing its tools only.
17
- > - Name the machine. User-level / local-override config absent on a fresh checkout → `Not Checked`.
14
+ > - NEVER print or copy a token, key or secret value. Record names, scopes and presence only.
15
+ > - Do not run `bkit install` / `bkit upgrade`.
16
+ > - Do not call a tool-server tool. Only list its tools.
17
+ > - Name the machine the audit runs on.
18
+ > - **If** user-level or local-override config is absent because the checkout is fresh → mark it `Not Checked`.
18
19
 
19
20
  ## Universal Instructions
20
21
 
21
22
  ### Context & Goals
22
23
 
23
- Each agent host reads its own permissions, hooks, tool servers, model picks; nobody reviews them as config. Broad allow rule lands in a one-line diff; local override lives on one laptop; tool server holds a write token nobody scoped. Target failure: **an agent does something one host's config would have blocked, because the host it ran in was configured differently** — e.g. force-push denied in one host, allowed in another; tool server with admin token where read suffices; hook wired but script not executable, never fires; issue body tells an agent with push rights to push, and nothing but prompt text stops it.
24
+ Each agent host reads its own permissions, hooks, tool servers and model picks, and nobody reviews them as config. A broad allow rule lands in a one-line diff, a local override lives on one laptop, and a tool server holds a write token nobody scoped. The failure this audit targets is an agent doing something that one host's config would have blocked, because the host it ran in was configured differently. Examples: force-push is denied in one host and allowed in another; a tool server holds an admin token where read access would do; a hook is wired, but its script is not executable, so it never fires; or an issue body tells an agent with push rights to push, and nothing but prompt text stops it.
24
25
 
25
- **Applies when:** repo carries config for >=1 coding agent (e.g. `AGENTS.md`, `.claude/`, `.cursor/`, `.codex/`, `.opencode/`, `.mcp.json`), or anyone works on it with one. None → one `N/A` row with evidence, never "clean".
26
+ **Applies when:** the repo carries config for at least one coding agent (e.g., `AGENTS.md`, `.claude/`, `.cursor/`, `.codex/`, `.opencode/`, `.mcp.json`), or anyone works on it with one. **If** neither holds → write one `N/A` row with its evidence, and never report the surface as "clean".
26
27
 
27
- **Cadence:** monthly. Extra pass after new agent host or tool server, bkit upgrade, or permission / hook / tool-server file change.
28
+ **Cadence:** Run once a month. Run an extra pass after adding an agent host or tool server, after a bkit upgrade, and after a change to a permission, hook or tool-server file.
28
29
 
29
30
  **Anchor Standards:**
30
31
 
31
32
  - OWASP Top 10 for Agentic Applications, 2026 (ASI01-ASI10).
32
- - Tool-server specification authorization and security best practices (e.g. Model Context Protocol); record the specification date read.
33
+ - Tool-server specification authorization and security best practices (e.g., Model Context Protocol). Record the specification date read.
33
34
  - OpenSSF Security-Focused Guide for AI Code Assistant Instructions.
34
- - Each host's settings, permission, sandbox, and hook reference (e.g. Claude Code, Cursor, Codex, opencode); record date read.
35
- - bkit, when installed: `.bkit/README.md` § File ownership — permissions and hooks bkit writes per host.
35
+ - Each host's settings, permission, sandbox and hook reference (e.g., Claude Code, Cursor, Codex, opencode). Record the date read.
36
+ - bkit, when installed: `.bkit/README.md` § File ownership — the permissions and hooks bkit writes for each host.
36
37
 
37
38
  ### Scope
38
39
 
39
- - Hosts in use; config files each loads per layer (managed policy, user, repo, local override); precedence.
40
- - Instruction files each host loads.
41
- - Permissions: allow / ask / deny, default approval mode, sandbox, fetch allowlist; parity across hosts.
42
- - Hooks and guard scripts: wired, runnable, fire, fail mode.
43
- - Tool servers: inventory per host, transport, pinning, credential source and scope, pre-approved writes, unused servers, tool-description changes.
44
- - Agent definitions, commands, skills: tool allowlists, model pins, sources.
45
- - Secrets in agent config and env files agents load.
46
- - Untrusted input: text outsiders can write that each agent reads, what that agent can do in the same session, what stops a planted instruction.
47
- - bkit, when installed: shipped permissions and hooks agree across hosts.
40
+ - List the hosts in use.
41
+ - For each host, list the config files it loads per layer (managed policy, user, repo, local override), and their precedence.
42
+ - List the instruction files each host loads.
43
+ - Check permissions: allow / ask / deny, the default approval mode, the sandbox and the fetch allowlist, and their parity across hosts.
44
+ - Check that hooks and guard scripts are wired and runnable, that they fire, and how they fail.
45
+ - Inventory the tool servers for each host: transport, pinning, credential source and scope, pre-approved writes, unused servers and tool-description changes.
46
+ - Check agent definitions, commands and skills: tool allowlists, model pins and sources.
47
+ - Check for secrets in agent config and in env files that agents load.
48
+ - Map untrusted input: text outsiders can write that each agent reads, what that agent can do in the same session, and what stops a planted instruction.
49
+ - **If** bkit is installed → check that its shipped permissions and hooks agree across hosts.
48
50
 
49
51
  ### Out of Scope
50
52
 
51
53
  <!-- prettier-ignore -->
52
54
  | Excluded item | Why | Where it belongs |
53
55
  | --- | --- | --- |
54
- | Instruction files contradicting each other; always-loaded size | Documentation sweep | `bkit-audit-documentation` |
55
- | Model calls the product makes; tool servers the product exposes | LLM sweep | `bkit-audit-llm` |
56
- | Whether product prompts are clear, well structured, and fit their model | Prompt sweep | `bkit-audit-prompts` |
57
- | Product model registry, deprecation, fallback chains | Model sweep | `bkit-audit-models` |
58
- | CI workflow token permissions, pinned actions; rotating a leaked secret | Security sweep | `bkit-audit-security` |
59
- | Worktrees, branches, stashes agents leave behind; version-control hooks | Repo sweep | `bkit-audit-repo` |
60
- | Hosted environment variables, dashboards, repository rulesets | Config sweep | `bkit-audit-config` |
61
- | Agent and model spend | Cost sweep | `bkit-audit-cost` |
62
- | Whether a sweep here should become a gate | Gate sweep | `bkit-audit-gates` |
63
- | bkit install state: version, `bkit check`, `bkit doctor`, hosts installed, managed blocks, templates adopted and wired | bkit adoption sweep | `bkit-audit-adoption` |
64
- | Changing config, or running `bkit install` / `bkit upgrade` | Audit reports only | Plan from this report |
56
+ | Instruction files that contradict each other; the size of always-loaded files | The documentation sweep owns them | `bkit-audit-documentation` |
57
+ | Model calls the product makes; tool servers the product exposes | The LLM sweep owns them | `bkit-audit-llm` |
58
+ | Whether product prompts are clear, well structured and fit their model | The prompt sweep owns it | `bkit-audit-prompts` |
59
+ | The product's model registry, deprecations and fallback chains | The model sweep owns them | `bkit-audit-models` |
60
+ | CI workflow token permissions and pinned actions; rotating a leaked secret | The security sweep owns them | `bkit-audit-security` |
61
+ | Worktrees, branches and stashes agents leave behind; version-control hooks | The repo sweep owns them | `bkit-audit-repo` |
62
+ | Hosted environment variables, dashboards, repository rulesets | The config sweep owns them | `bkit-audit-config` |
63
+ | Agent and model spend | The cost sweep owns it | `bkit-audit-cost` |
64
+ | Whether a sweep here should become a gate | The gate sweep owns it | `bkit-audit-gates` |
65
+ | bkit install state: version, `bkit check`, `bkit doctor`, hosts installed, managed blocks, templates adopted and wired | The bkit adoption sweep owns it | `bkit-audit-adoption` |
66
+ | Changing config, or running `bkit install` / `bkit upgrade` | The audit only reports | A plan made from this report |
65
67
 
66
68
  ### Pre-Flight / Dependencies
67
69
 
68
70
  #### Core
69
71
 
70
- - [ ] **Permissions:** blocked calls recorded
71
- - [ ] **Checkout:** Steps 2-10 — repo-level agent config. Fallback: none; no checkout → `N/A` and STOP.
72
- - [ ] **Effective Config:** Steps 2, 4, 6 — host's merged-config view where offered (e.g. `claude mcp list`, a host's permissions or MCP panel). Fallback: files + documented precedence by hand; effective state = hypothesis.
73
- - [ ] **Web:** Steps 7, 11 — anchor standards, host references, live model catalogues. Fallback: versions recorded as unread; model pins `Not Checked`.
72
+ - [ ] **Permissions:** every blocked call is recorded.
73
+ - [ ] **Checkout:** Steps 2-10 — the repo-level agent config. Fallback: none. **If** there is no checkout → write `N/A`, then **STOP**.
74
+ - [ ] **Effective Config:** Steps 2, 4, 6 — the host's merged-config view, where it offers one (e.g., `claude mcp list`, a host's permissions or MCP panel). Fallback: work out the effective state by hand from the files and the documented precedence, and treat it as a hypothesis.
75
+ - [ ] **Web:** Steps 7, 11 — the anchor standards, host references and live model catalogues. Fallback: record the versions as unread, and mark model pins `Not Checked`.
74
76
 
75
77
  #### Conditional
76
78
 
77
- - [ ] **Machine Config:** Audit runs on a developer machine → Steps 2, 4, 6, 8 — user-level and local-override files (e.g. `~/.claude/settings.json`, `.claude/settings.local.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`). Fallback: repo-level only; machine layers `Not Checked`.
78
- - [ ] **Managed Policy:** Org-managed agent policy → Step 2 — policy file or admin console, read-only. Fallback: `Not Checked`; name who holds it.
79
- - [ ] **Token Scopes:** Tool servers or hooks use credentials → Step 6 — scopes, value never printed (e.g. `gh auth status`, the `X-OAuth-Scopes` response header, provider token introspection). Fallback: scopes `Not Checked`.
79
+ - [ ] **Machine Config:** **If** the audit runs on a developer machine → Steps 2, 4, 6, 8 — the user-level and local-override files (e.g., `~/.claude/settings.json`, `.claude/settings.local.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`). Fallback: check the repo level only, and mark the machine layers `Not Checked`.
80
+ - [ ] **Managed Policy:** **If** the org manages agent policy → Step 2 — the policy file or admin console, read-only. Fallback: `Not Checked`, naming who holds it.
81
+ - [ ] **Token Scopes:** **If** tool servers or hooks use credentials → Step 6 — the scopes, NEVER printing the value (e.g., `gh auth status`, the `X-OAuth-Scopes` response header, provider token introspection). Fallback: mark scopes `Not Checked`.
80
82
 
81
83
  ### 🔒 Gate 1: Prerequisites Check
82
84
 
83
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
84
- - [ ] **Gate 1 — Verified:** All Core items checked. All applicable Conditional items checked.
85
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
86
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
85
87
 
86
88
  ### Probe Steps
87
89
 
88
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
89
- - [ ] **Step 2 — Hosts and Layers:** Name machine and checkout. Hosts with repo config or in team use (e.g. Claude Code, Cursor, Codex, opencode). Per host: config file per layer (managed policy, user, repo shared, repo local override, flags / env); documented precedence. Findings: config for unused host; host in use with no repo config; local-override file tracked or not ignored. Fresh cloud checkout: no user / local layer → say so, not clean. **Done when:** `Hosts` row per host x layer: file, present, tracked / ignored, precedence.
90
- - [ ] **Step 3 — Instructions:** Per host: instruction files loaded at session start (e.g. `AGENTS.md`, `CLAUDE.md`, always-applied IDE rule files, per-directory files, imports). Findings: host reaching no shared rules; rule file / import → missing path. Contradictions, size → `bkit-audit-documentation`. **Done when:** `Instructions` row per host: files loaded, shared rules reached yes / no.
91
- - [ ] **Step 4 — Permissions:** Per host x layer: allow / ask / deny, default approval mode, sandbox mode, fetch / network allowlist. Findings: wildcard shell allow; arbitrary-text interpreter allow (e.g. `bash -c`, `node -e`, `python -c`); deny overridden by broader higher-precedence allow; approval-bypass mode in shared config outside a sandbox; fetch allowlist wider than needed per host matching rules (e.g. apex vs subdomain). `Parity` matrix: action x host → blocker: deny rule / hook / sandbox / prompt prose only / nothing. Minimum actions: force push, history rewrite, branch delete, hook skip (e.g. `--no-verify`), merge or push to protected branch, publish / release, delete outside the working tree, credential-file read (e.g. `.env*`), fetch to unlisted host, tool-server write to a shared or production system. Findings: blocked in one host, open in another; blocked by prompt prose only. **Done when:** `Permissions` row per host x layer; `Parity` matrix with no empty cell.
92
- - [ ] **Step 5 — Hooks:** Per host, each wired hook: event, matcher, command. Script exists, executable, interpreter present. Fire test: synthetic tool-call payload on stdin → record exit code / decision. Hook writing anything (telemetry, logs, state) → read, do not run. Findings: sole blocker for a `Parity` row fails open on crash / timeout / missing dependency; matcher misses a tool doing the same action (e.g. a tool server's shell tool). **Done when:** `Hooks` row per hook: wired, runnable, fires on fixture, fail mode.
93
- - [ ] **Step 6 — Tool Servers:** Per host, each tool server (e.g. MCP): layer, transport (local command / remote URL), package pinned or floating (e.g. `npx -y pkg@latest`), publisher, credential source (env var name vs literal), credential scope vs need, toolsets enabled vs used, write tools pre-approved. List tools → hash names + descriptions. Findings: floating package; same server differing across hosts (token, toolsets, URL); server no workflow uses; hash changed since previous run with no version change. **Done when:** `Tool Servers` row per server x host, hashes recorded.
94
- - [ ] **Step 7 — Agents and Models:** Per host: agent definitions, commands, skills / plugins. Per agent: tool allowlist vs role; model pin vs provider's live catalogue (never inferred from version digits). Per skill / plugin: source, pinned version, ships scripts. Findings: write tools on read-only role; dead pin; floating alias; same agent on different model classes across hosts, undocumented; unknown-source skill with scripts. **Done when:** `Agents` row per agent x host; skills listed.
95
- - [ ] **Step 8 — Secrets:** Agent config + env files agents load (e.g. `.envrc`, tool-server env files, agent-tooling env file). Findings: literal token in tracked file (file and line, never value); env file not ignored; app credential in agent-tooling env. Agent read of credential files → Step 4 `Parity`. **Done when:** `Secrets` row per file.
96
- - [ ] **Step 9 — Untrusted Input:** Per agent, command, skill, and automated agent run (CI job, scheduled or comment-triggered session) from Step 7: (a) text it reads that someone outside the team can write (e.g. issue / PR body and comments, fork commit messages, PR checkout files, CI logs, fetched pages, dependency READMEs and changelogs, tool-server results, inbound mail); (b) what it can do in the same session (shell, file write, push, merge, publish, tracker or tool-server write, outbound fetch), from Steps 4, 6, 7; (c) what stops a planted instruction: deny rule / hook / sandbox / human approval / read-only agent handing a summary to a separate writer / prompt prose only / nothing; (d) who can start the run (e.g. issue label, `@`-mention, comment command, `pull_request_target`). Read how prompts fence and label untrusted text as data; prose is defence-in-depth, never the stop. Exfiltration: same session holds a secret or private data and reaches a host or surface an outsider reads (fetch allowlist, tracker comment, PR body, public commit). Findings: (a) + write / push / shell with stop = prompt prose only or nothing (ASI01, LLM01); (a) + secret or private data + outsider-readable outbound; outsider can start a run that holds write credentials. Product model calls → `bkit-audit-llm`. **Done when:** `Untrusted Input` row per agent: untrusted sources · capabilities · who starts it · stop · verdict.
97
- - [ ] **Step 10 — bkit Gates:** `.bkit/version` absent → explicit skip with evidence. Else per installed bkit host: every permission and hook bkit writes (`.bkit/README.md` § File ownership) appears in Steps 4-5 and in `Parity`; same bkit gate enforced in one host, open in another → upstream bkit fix. Version, drift, hosts with no bkit install, managed blocks, templates → `bkit-audit-adoption`. **Done when:** `bkit` section lists bkit gates per host with verdict, or skip with evidence.
98
- - [ ] **Step 11 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per agentic risk (ASI01-ASI10), per tool-server security best practice, and per assistant-instructions guide recommendation this audit touches → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
99
- - [ ] **Step 12 — Anything Else:** (a) Everything changed since previous report's commit touching agent config (settings, hooks, tool-server files, agent definitions, skills, instruction load paths, bkit version) → 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 (agent incidents, new `docs/failures.jsonl` rows, friction logs) — 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`.
90
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
91
+ - [ ] **Step 2 — Hosts and Layers:** Name the machine and the checkout. List the hosts that have repo config or are in team use (e.g., Claude Code, Cursor, Codex, opencode). For each host, record the config file at each layer (managed policy, user, repo shared, repo local override, flags / env) and the documented precedence. Record these as findings: config for a host nobody uses; a host in use with no repo config; and a local-override file that is tracked or not ignored. **If** the checkout is a fresh cloud checkout with no user or local layer → say so, and do not call it clean. **Done when:** `Hosts` holds one row per host and layer: file · present · tracked / ignored · precedence.
92
+ - [ ] **Step 3 — Instructions:** For each host, list the instruction files it loads at session start (e.g., `AGENTS.md`, `CLAUDE.md`, always-applied IDE rule files, per-directory files, imports). Record these as findings: a host that reaches no shared rules; and a rule file or import that points to a missing path. Contradictions and size go to `bkit-audit-documentation`. **Done when:** `Instructions` holds one row per host: files loaded · shared rules reached yes / no.
93
+ - [ ] **Step 4 — Permissions:** For each host and layer, record allow / ask / deny, the default approval mode, the sandbox mode and the fetch / network allowlist. Record these as findings: a wildcard shell allow; an allow for an interpreter that runs arbitrary text (e.g., `bash -c`, `node -e`, `python -c`); a deny overridden by a broader allow with higher precedence; an approval-bypass mode in shared config outside a sandbox; and a fetch allowlist wider than needed under each host's matching rules (e.g., apex vs subdomain). Build the `Parity` matrix: for each action and host, name what blocks it — deny rule / hook / sandbox / prompt prose only / nothing. Cover at least these actions: force push, history rewrite, branch delete, hook skip (e.g., `--no-verify`), merge or push to a protected branch, publish / release, delete outside the working tree, credential-file read (e.g., `.env*`), fetch to an unlisted host, and a tool-server write to a shared or production system. Record these as findings: an action blocked in one host and open in another; and an action blocked by prompt prose only. **Done when:** `Permissions` holds one row per host and layer, and `Parity` has no empty cell.
94
+ - [ ] **Step 5 — Hooks:** For each host, record each wired hook's event, matcher and command. Check that the script exists, is executable and has its interpreter present. Fire test: send a synthetic tool-call payload on stdin, and record the exit code or decision. **If** a hook writes anything (telemetry, logs, state) → read it, and do not run it. Record these as findings: the sole blocker for a `Parity` row fails open on a crash, a timeout or a missing dependency; and a matcher misses a tool that does the same action (e.g., a tool server's shell tool). **Done when:** `Hooks` holds one row per hook: wired · runnable · fires on fixture · fail mode.
95
+ - [ ] **Step 6 — Tool Servers:** For each host, record each tool server (e.g., MCP): layer, transport (local command / remote URL), package pinned or floating (e.g., `npx -y pkg@latest`), publisher, credential source (env var name vs literal), credential scope vs need, toolsets enabled vs used, and write tools pre-approved. List its tools, and hash their names and descriptions. Record these as findings: a floating package; the same server set up differently across hosts (token, toolsets, URL); a server no workflow uses; and a hash that changed since the previous run with no version change. **Done when:** `Tool Servers` holds one row per server and host, with hashes recorded.
96
+ - [ ] **Step 7 — Agents and Models:** For each host, list the agent definitions, commands and skills / plugins. For each agent, compare its tool allowlist with its role, and its model pin with the provider's live catalogue. Never infer a pin's validity from version digits. For each skill or plugin, record its source, its pinned version and whether it ships scripts. Record these as findings: write tools on a read-only role; a dead pin; a floating alias; the same agent on different model classes across hosts, undocumented; and a skill of unknown source that ships scripts. **Done when:** `Agents` holds one row per agent and host, and skills are listed.
97
+ - [ ] **Step 8 — Secrets:** Read the agent config and the env files agents load (e.g., `.envrc`, tool-server env files, the agent-tooling env file). Record these as findings: a literal token in a tracked file (file and line, NEVER the value); an env file that is not ignored; and an app credential in the agent-tooling env. An agent's read of credential files goes to the Step 4 `Parity` matrix. **Done when:** `Secrets` holds one row per file.
98
+ - [ ] **Step 9 — Untrusted Input:** For each agent, command, skill and automated agent run (CI job, scheduled or comment-triggered session) from Step 7, record:
99
+ - (a) the text it reads that someone outside the team can write (e.g., issue / PR body and comments, fork commit messages, PR checkout files, CI logs, fetched pages, dependency READMEs and changelogs, tool-server results, inbound mail)
100
+ - (b) what it can do in the same session (shell, file write, push, merge, publish, tracker or tool-server write, outbound fetch), from Steps 4, 6, 7
101
+ - (c) what stops a planted instruction: deny rule / hook / sandbox / human approval / read-only agent handing a summary to a separate writer / prompt prose only / nothing
102
+ - (d) who can start the run (e.g., issue label, `@`-mention, comment command, `pull_request_target`).
103
+ - Read how prompts fence and label untrusted text as data. Prose is defence in depth, never the stop.
104
+ - Exfiltration means the same session holds a secret or private data and reaches a host or surface an outsider reads (fetch allowlist, tracker comment, PR body, public commit).
105
+ - Record these as findings:
106
+ - (a) together with write, push or shell, where the stop is prompt prose only or nothing (ASI01, LLM01)
107
+ - (a) together with a secret or private data and an outbound path an outsider can read
108
+ - an outsider able to start a run that holds write credentials
109
+ - Product model calls go to `bkit-audit-llm`.
110
+
111
+ **Done when:** `Untrusted Input` holds one row per agent: untrusted sources · capabilities · who starts it · stop · verdict.
112
+
113
+ - [ ] **Step 10 — bkit Gates:** **If** `.bkit/version` is absent → skip the step explicitly, with evidence. **If** it is present → for each installed bkit host, check that every permission and hook bkit writes (`.bkit/README.md` § File ownership) appears in Steps 4-5 and in `Parity`. **If** the same bkit gate is enforced in one host and open in another → the fix is upstream in bkit. Version, drift, hosts with no bkit install, managed blocks and templates go to `bkit-audit-adoption`. **Done when:** `bkit` lists the bkit gates per host with a verdict, or records the skip with evidence.
114
+ - [ ] **Step 11 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. Give `Standards Coverage` one row per agentic risk (ASI01-ASI10), one per tool-server security best practice and one per assistant-instructions guide recommendation this audit touches, each marked checked (naming 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.
115
+ - [ ] **Step 12 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches agent config: settings, hooks, tool-server files, agent definitions, skills, instruction load paths or the bkit version. (b) In a bounded pass of about 30 minutes, note what a senior platform engineer would flag that no step asks about. Read what happened since the previous run (agent incidents, new `docs/failures.jsonl` rows, friction logs), and ask 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`.
100
116
 
101
117
  ### 🔒 Gate 2: Probes Check
102
118
 
103
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
104
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
105
- - [ ] **No secrets:** no token, key, or secret value anywhere in the report.
106
- - [ ] **Config untouched:** no agent config, hook, tool-server file, agent definition, or bkit-managed file changed; no `bkit install` / `bkit upgrade` run; no tool-server tool called.
107
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
119
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
120
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
121
+ - [ ] **No secrets:** no token, key, or secret value appears anywhere in the report.
122
+ - [ ] **Config untouched:** no agent config, hook, tool-server file, agent definition or bkit-managed file changed.
123
+ - [ ] **No install:** no `bkit install` / `bkit upgrade` was run.
124
+ - [ ] **No tool calls:** no tool-server tool was called.
125
+ - [ ] **Gate 2 — Verified:** every item above holds.
108
126
 
109
127
  ## Findings
110
128
 
111
129
  <!-- prettier-ignore -->
112
130
  | Severity | Use |
113
131
  | --- | --- |
114
- | `CRITICAL` | Live credential in tracked agent config; outsider can start an agent run that reads their text and holds write / push credentials with no structural stop; unprompted production write via tool server in shared config; approval-bypass mode in shared config outside a sandbox |
115
- | `HIGH` | Action blocked in one host, open in another; blocked by prompt prose only; agent reads untrusted text and can write, push, or run shell with no structural stop; agent reads untrusted text, holds a secret or private data, and reaches an outsider-readable host; sole blocking hook never fires or fails open; tool-server credential write / admin where read suffices; arbitrary-interpreter allow; floating tool-server package |
116
- | `MEDIUM` | Unused host config or tool server; tool description changed, no version change; dead or cross-host-inconsistent model pin; tracked local override; agent tools beyond role |
117
- | `LOW` | Naming drift, no behaviour change; doc wrong about agent config while config right |
132
+ | `CRITICAL` | A live credential in tracked agent config. An outsider can start an agent run that reads their text and holds write or push credentials, with no structural stop. An unprompted production write through a tool server in shared config. An approval-bypass mode in shared config outside a sandbox |
133
+ | `HIGH` | An action blocked in one host and open in another. An action blocked by prompt prose only. An agent reads untrusted text and can write, push or run shell, with no structural stop. An agent reads untrusted text, holds a secret or private data, and reaches a host an outsider can read. The sole blocking hook never fires or fails open. A tool-server credential with write or admin access where read would do. An allow for an arbitrary interpreter. A floating tool-server package |
134
+ | `MEDIUM` | An unused host config or tool server. A tool description changed with no version change. A dead model pin, or one inconsistent across hosts. A tracked local override. Agent tools beyond its role |
135
+ | `LOW` | Naming drift with no behaviour change. A doc that is wrong about agent config while the config is right |
118
136
 
119
- Within a severity: production writes, credentials, then parity gaps.
137
+ Within a severity, list production writes first, then credentials, then parity gaps.
120
138
 
121
139
  <!-- prettier-ignore -->
122
140
  | ID | Severity | Host | Location | Evidence | Expected |
123
141
  | --- | --- | --- | --- | --- | --- |
124
142
  | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
125
143
 
126
- Empty and clean → one row `None`.
144
+ **If** the run finds nothing → write one row: `None`.
127
145
 
128
146
  ## Report
129
147
 
@@ -204,13 +222,17 @@ PENDING
204
222
 
205
223
  ### 🔒 Gate 3: Report Check
206
224
 
207
- - [ ] **No placeholders:** no `PENDING` left
208
- - [ ] **Summary:** names count per severity, machine, and hosts read.
209
- - [ ] **Series:** `Parity` and tool-server hashes diffed against previous report's, or marked baseline.
210
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
211
- - [ ] **Process Improvements:** `Universal` and `Project` filled
212
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
213
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
225
+ - [ ] **No placeholders:** no `PENDING` is left.
226
+ - [ ] **Summary:** `Summary` gives the count per severity.
227
+ - [ ] **Machine:** `Summary` names the machine.
228
+ - [ ] **Hosts read:** `Summary` names the hosts read.
229
+ - [ ] **Series:** `Parity` and the tool-server hashes are diffed against the previous report's, or the run is marked baseline.
230
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
231
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
232
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
233
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
234
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
235
+ - [ ] **Gate 3 — Verified:** every item above holds.
214
236
 
215
237
  <!-- bkit:end -->
216
238
 
@@ -1,134 +1,151 @@
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
  # AIO SEO Audit
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Whether search engines and answer engines can find, read, and correctly describe public pages.
10
+ > **Purpose:** Whether search engines and answer engines can find, read and correctly describe public pages.
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - never change search-console, webmaster, robots, sitemap, IndexNow, or firewall settings; record the owner's decision.
15
- > - Name a personal-data field and its page for `bkit-audit-privacy`; never copy a personal-data value into the report.
14
+ > - Do not change search-console, webmaster, robots, sitemap, IndexNow or firewall settings.
15
+ > - Record the owner's decision on the AI-crawler policy in `robots.txt` and on the search-console control for generative answers.
16
+ > - Name each personal-data field and its page for `bkit-audit-privacy`.
17
+ > - NEVER copy a personal-data value into the report.
16
18
 
17
19
  ## Universal Instructions
18
20
 
19
21
  ### Context & Goals
20
22
 
21
- - Search and answer engines read the same public pages; silent failures (`noindex` from preview config, canonical to preview URL, sitemap listing login-gated pages) stop traffic while the site still works.
22
- - Search engines rank pages; answer engines quote facts → plain factual copy matters.
23
- - Engine ignores `llms.txt` but shares one index with AI answers → indexing basics cover both.
23
+ Search engines and answer engines read the same public pages. The failure this audit targets is a silent indexing fault that stops traffic while the site still works. Examples: `noindex` leaking from preview config, a canonical pointing at a preview URL, or a sitemap listing login-gated pages.
24
+
25
+ Search engines rank pages, and answer engines quote facts, so plain factual copy matters. An engine that ignores `llms.txt` still shares one index with its AI answers, so the indexing basics cover both.
24
26
 
25
- **Applies when:** a web origin crawlers can request. None → one `N/A` row with evidence, never "clean".
27
+ **Applies when:** there is a web origin crawlers can request. **If** there is none → write one `N/A` row with its evidence, and never report the surface as "clean".
26
28
 
27
- **Cadence:** quarterly. Extra pass when routing, locales, or the public site change.
29
+ **Cadence:** Run once a quarter. Run an extra pass when routing, locales or the public site change.
28
30
 
29
31
  **Anchor Standards:**
30
32
 
31
- - Search essentials and the search-documentation updates log (e.g. Google Search Essentials, Bing Webmaster Guidelines); record the date of the newest entry read.
32
- - The engine's AI-features and generative-AI optimisation guides (e.g. Google's AI features and your website); record each page's last-updated date.
33
- - Search-console help, including the control for generative answers (e.g. Search Console Help); record the date read.
34
- - Index submission protocol (e.g. IndexNow); record the date read.
35
- - Structured-data vocabulary release and the engine's supported-type list (e.g. schema.org, Google's structured-data gallery); record release number and date read.
36
- - Robots Exclusion Protocol (e.g. RFC 9309).
37
- - Each AI vendor's crawler documentation (e.g. OpenAI, Anthropic, Perplexity, Apple, Google's common crawlers); record each page's date or the date read.
38
- - Core Web Vitals, owned by `bkit-audit-app-performance`; this audit reads only what the search console reports.
33
+ - Search essentials and the search-documentation updates log (e.g., Google Search Essentials, Bing Webmaster Guidelines). Record the date of the newest entry read.
34
+ - The engine's AI-features and generative-AI optimisation guides (e.g., Google's AI features and your website). Record each page's last-updated date.
35
+ - Search-console help, including the control for generative answers (e.g., Search Console Help). Record the date read.
36
+ - Index submission protocol (e.g., IndexNow). Record the date read.
37
+ - The structured-data vocabulary release and the engine's supported-type list (e.g., schema.org, Google's structured-data gallery). Record the release number and the date read.
38
+ - Robots Exclusion Protocol (e.g., RFC 9309).
39
+ - Each AI vendor's crawler documentation (e.g., OpenAI, Anthropic, Perplexity, Apple, Google's common crawlers). Record each page's date, or the date read.
40
+ - Core Web Vitals, owned by `bkit-audit-app-performance`. This audit reads only what the search console reports.
39
41
 
40
42
  ### Scope
41
43
 
42
- - Public URLs vs previews (previews not indexable).
43
- - Crawling / indexing: robots, sitemap, canonicals, locales, status codes, HTML with and without JavaScript.
44
- - Metadata, structured data, plain answers answer engines quote.
45
- - AI crawler policy, firewall agreement, engine responses when asked.
46
- - Site structure, trust pages, search-console reports.
44
+ - Separate public URLs from previews, and check that previews are not indexable.
45
+ - Check crawling and indexing: robots, sitemap, canonicals, locales, status codes, and the HTML with and without JavaScript.
46
+ - Check metadata, structured data and the plain answers that answer engines quote.
47
+ - Check the AI crawler policy, the firewall's agreement with it, and how engines respond when asked.
48
+ - Check site structure, trust pages and search-console reports.
47
49
 
48
50
  ### Out of Scope
49
51
 
50
52
  <!-- prettier-ignore -->
51
53
  | Excluded item | Why | Where it belongs |
52
54
  | --- | --- | --- |
53
- | Page speed; Core Web Vitals beyond the search console's report | Speed sweep | `bkit-audit-app-performance` |
54
- | Heading order, alt text, contrast | Accessibility sweep | `bkit-audit-accessibility` |
55
- | Whether structure or copy works for people | Usability sweep | `bkit-audit-usability` |
56
- | Personal data on a public page | Privacy sweep | `bkit-audit-privacy` |
57
- | Screen a search-to-app link opens | Store sweep | `bkit-audit-app-store` |
58
- | How AI referral traffic is measured | Tracking sweep | `bkit-audit-analytics` |
59
- | A doc that describes the site wrongly | Documentation sweep | `bkit-audit-documentation` |
60
- | Applying fixes / changing robots, consoles, or firewall | Audit reports only | Plan from this report |
55
+ | Page speed; Core Web Vitals beyond the search console's report | The speed sweep owns them | `bkit-audit-app-performance` |
56
+ | Heading order, alt text, contrast | The accessibility sweep owns them | `bkit-audit-accessibility` |
57
+ | Whether structure or copy works for people | The usability sweep owns it | `bkit-audit-usability` |
58
+ | Personal data on a public page | The privacy sweep owns it | `bkit-audit-privacy` |
59
+ | The screen a search-to-app link opens | The store sweep owns it | `bkit-audit-app-store` |
60
+ | How AI referral traffic is measured | The tracking sweep owns it | `bkit-audit-analytics` |
61
+ | A doc that describes the site wrongly | The documentation sweep owns it | `bkit-audit-documentation` |
62
+ | Applying fixes; changing robots, consoles or the firewall | The audit only reports | A plan made from this report |
61
63
 
62
64
  ### Pre-Flight / Dependencies
63
65
 
64
66
  #### Core
65
67
 
66
- - [ ] **Permissions:** blocked calls recorded
67
- - [ ] **Live Fetch:** Steps 2-9 — request public URLs, headers, and HTML, e.g. `curl`, a browser. Fallback: source read; live claims = hypotheses.
68
- - [ ] **Web:** Step 10 — fetch anchor standards. Fallback: versions recorded as unread.
68
+ - [ ] **Permissions:** every blocked call is recorded.
69
+ - [ ] **Live Fetch:** Steps 2-9 — request public URLs, headers and HTML (e.g., `curl`, a browser). Fallback: read the source, and treat live claims as hypotheses.
70
+ - [ ] **Web:** Step 10 — fetch the anchor standards. Fallback: record the versions as unread.
69
71
 
70
72
  #### Conditional
71
73
 
72
- - [ ] **Search Consoles:** Indexable public pages → Step 9 — e.g. Google Search Console, Bing Webmaster Tools. Fallback: none; consoles missing while indexable pages exist = finding.
73
- - [ ] **Edge Logs:** Bot firewall or CDN → Step 6 — crawler status codes, e.g. Vercel Firewall, Cloudflare. Fallback: `robots.txt` only; log rows `Not Checked`.
74
- - [ ] **Schema Validators:** Structured data present → Step 5 — rich-results test and a schema.org validator, e.g. Google Rich Results Test, Schema Markup Validator. Fallback: read required properties from the engine's docs.
75
- - [ ] **Answer Engines:** Indexable public pages → Step 6 — signed-out prompts, e.g. ChatGPT search, Perplexity, Gemini, Google AI Mode, Copilot, Claude. Fallback: page-text checks only; prompt rows `Not Checked`.
74
+ - [ ] **Search Consoles:** **If** there are indexable public pages → Step 9 (e.g., Google Search Console, Bing Webmaster Tools). Fallback: none. **If** consoles are missing while indexable pages exist → that is a finding.
75
+ - [ ] **Edge Logs:** **If** there is a bot firewall or CDN → Step 6 — the status codes it returns to crawlers (e.g., Vercel Firewall, Cloudflare). Fallback: read `robots.txt` only, and mark the log rows `Not Checked`.
76
+ - [ ] **Schema Validators:** **If** structured data is present → Step 5 — a rich-results test and a schema.org validator (e.g., Google Rich Results Test, Schema Markup Validator). Fallback: read the required properties from the engine's docs.
77
+ - [ ] **Answer Engines:** **If** there are indexable public pages → Step 6 — signed-out prompts (e.g., ChatGPT search, Perplexity, Gemini, Google AI Mode, Copilot, Claude). Fallback: check the page text only, and mark the prompt rows `Not Checked`.
76
78
 
77
79
  ### 🔒 Gate 1: Prerequisites Check
78
80
 
79
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
80
- - [ ] **Gate 1 — Verified:** All Core items checked. All applicable Conditional items checked.
81
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
82
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
81
83
 
82
84
  ### Probe Steps
83
85
 
84
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
85
- - [ ] **Step 2 — Public URLs:** List public URLs from sitemap if present, else crawl from home. Record production host and tools available in `Checked`. First: no preview deployment indexable (`X-Robots-Tag: noindex` or host deployment protection); crawled preview competes with production and can expose unreleased pages. Marketing site outside repo → name where; audit from live URL. **Done when:** host, URL list, preview verdict in `Public URLs`. No web origin → `N/A` and STOP. No indexable page → say so; `Indexing` still runs; steps needing indexable page skip with evidence in `Not Checked`.
86
- - [ ] **Step 3 — Indexing:** `robots.txt` + sitemap: present, valid, public URLs only. `lastmod` only when that page's content changes — trusted only when consistently accurate. Sitemap submitted in each webmaster console. Robots meta + `X-Robots-Tag` per page type: auth/previews `noindex`, public indexable. No `noindex` also `Disallow`ed: blocked crawler never sees `noindex` → URL can stay indexed from links. Canonicals: absolute, production host, one per page. Host canonicalisation: `http`→`https`, apex↔`www`, trailing-slash policy each one hop; HSTS set; sitemap uses canonical form only. Status codes: chain <=1 hop, no loops, missing →404. Locales: `hreflang` per variant → existing pages; `hreflang="x-default"`; sets reciprocal and include self; canonical same-locale, never another locale; no forced `/` redirect by `Accept-Language` or IP — crawler without `Accept-Language` from one country (e.g. Googlebot) must see other locales. Content in HTML without JavaScript. Rendered HTML: one URL per page type — no-JS view vs engine render after JS (e.g. URL Inspection). Mobile/desktop same content when engine indexes mobile (e.g. Google). **Done when:** `Indexing` row per check: met / finding / not applicable (why).
87
- - [ ] **Step 4 — Metadata:** Indexable public page → title + description present, unique, right length. Open Graph + Twitter card tags; images exist, right size. `lang`, favicon, web manifest. Store listings → Smart App Banner (`apple-itunes-app`); `apple-app-site-association` + `assetlinks.json` reachable so search opens app. Link target screen → `bkit-audit-app-store`. **Done when:** `Metadata` row per page: tag · verdict, or skip in `Not Checked`.
88
- - [ ] **Step 5 — Structured Data:** Indexable public page → JSON-LD per page type: `Organization`, `WebSite`, `SoftwareApplication` or `MobileApplication` with store links, `FAQPage` only mirroring on-page Q&A, `BreadcrumbList` where depth exists. Validate each block; must match visible page — disagreeing markup worse than none. Engine rich-results test (supported) + schema.org validator (vocabulary). App types: engine software-app required props + `operatingSystem`, `applicationCategory`. Ratings from real on-page user ratings, never self-assigned. Retired rich-result type (`Project Instructions`) missing != finding. Generative answers need no special markup; structured data earns rich results and states facts plainly. **Done when:** `Structured Data` row per block: type · valid · agrees with page · verdict, or skip in `Not Checked`.
86
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
87
+ - [ ] **Step 2 — Public URLs:** List the public URLs from the sitemap. **If** there is no sitemap → crawl from the home page. Record the production host and the tools available in `Checked`. Check first that no preview deployment is indexable (`X-Robots-Tag: noindex`, or the host's deployment protection), because a crawled preview competes with production and can expose unreleased pages. **If** the marketing site lives outside the repo → name where, and audit it from the live URL. **If** there is no web origin → write `N/A`, then **STOP**. **If** there is no indexable page → say so. `Indexing` still runs, and the steps that need an indexable page skip with evidence in `Not Checked`. **Done when:** `Public URLs` holds the host, the URL list and the preview verdict.
88
+ - [ ] **Step 3 — Indexing:** Check that `robots.txt` and the sitemap are present and valid.
89
+ - Check that the sitemap lists public URLs only.
90
+ - Check that `lastmod` changes only when that page's content changes. Engines trust it only when it is consistently accurate.
91
+ - Check that the sitemap is submitted in each webmaster console.
92
+ - Check the robots meta tag and `X-Robots-Tag` per page type: auth pages and previews are `noindex`, and public pages are indexable.
93
+ - Check that no `noindex` page is also `Disallow`ed, because a blocked crawler never sees the `noindex`, so the URL can stay indexed from links.
94
+ - Check that each canonical is absolute, on the production host, and one per page.
95
+ - Check host canonicalisation: `http` → `https`, apex ↔ `www` and the trailing-slash policy each take one hop, HSTS is set, and the sitemap uses the canonical form only.
96
+ - Check status codes: redirect chains are <= 1 hop, there are no loops, and missing pages return 404.
97
+ - Check locales: each variant's `hreflang` points to existing pages; `hreflang="x-default"` is present; each set is reciprocal and includes itself; the canonical stays in the same locale, never another; and no forced `/` redirect by `Accept-Language` or IP exists, because a crawler that sends no `Accept-Language` from one country (e.g., Googlebot) must still see the other locales.
98
+ - Check that content is in the HTML without JavaScript.
99
+ - Compare the rendered HTML for one URL per page type: the no-JavaScript view vs the engine's render after JavaScript (e.g., URL Inspection).
100
+ - **If** the engine indexes the mobile version (e.g., Google) → check that mobile and desktop have the same content.
101
+
102
+ **Done when:** `Indexing` holds one row per check: met / finding / not applicable (saying why).
103
+
104
+ - [ ] **Step 4 — Metadata:** Run this step only when the project has an indexable public page. Check that the title and description are present, unique and the right length. Check the Open Graph and Twitter card tags, and that their images exist at the right size. Check `lang`, the favicon and the web manifest. **If** the project has store listings → check the Smart App Banner (`apple-itunes-app`), and that `apple-app-site-association` and `assetlinks.json` are reachable, so search opens the app. The screen the link opens goes to `bkit-audit-app-store`. **Done when:** `Metadata` holds one row per page: tag · verdict, or the skip is in `Not Checked`.
105
+ - [ ] **Step 5 — Structured Data:** Run this step only when the project has an indexable public page. Check the JSON-LD for each page type: `Organization`, `WebSite`, `SoftwareApplication` or `MobileApplication` with store links, `FAQPage` only where it mirrors on-page Q&A, and `BreadcrumbList` where the site has depth. Validate each block, and check that it matches the visible page, because markup that disagrees with the page is worse than none. Use the engine's rich-results test for supported types and a schema.org validator for the vocabulary. For app types, check the engine's required software-app properties, plus `operatingSystem` and `applicationCategory`. Ratings must come from real on-page user ratings, never self-assigned ones. A missing rich-result type that is retired (listed in `Project Instructions`) is not a finding. Generative answers need no special markup: structured data earns rich results and states facts plainly. **Done when:** `Structured Data` holds one row per block: type · valid · agrees with page · verdict, or the skip is in `Not Checked`.
89
106
  - [ ] **Step 6 — Answer Engines:**
90
- - `llms.txt` / `llms-full.txt` optional. Engines ignore or use unevenly → missing file != finding. If present: current, links to existing pages; stale = `LOW`.
91
- - Indexable page → plain facts in HTML text (not only images/scripts): product, audience, cost, platforms. Direct Q&A near top of owning page. One name for product/company across site, store, social. Off-site description/pricing/platforms match store, reviews, forums, press — answer engines often cite these over product site. List third-party sources prompt pass cited.
92
- - AI crawler policy: `robots.txt` per group. Allow/block both fine; no recorded decision = finding. Owner decides; report records. Blocking one group != blocking others. Training: GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot. Search: OAI-SearchBot, Claude-SearchBot, PerplexityBot, Bingbot (feeds some assistants) — block → out of those answers. User-triggered: ChatGPT-User, Claude-User, Perplexity-User; some vendors say may not follow `robots.txt`. "Block training, allow search" common; write per group.
93
- - Edge/firewall + CDN "block AI bots" agree with `robots.txt`. Firewall `403` to allowed search crawler overrides `robots.txt` silently. Check edge/server logs for each search crawler requests + status codes, not `robots.txt` alone.
94
- - Search-console control for generative answers inclusion/exclusion. Owner decides; report records. Does not govern training.
95
- - Indexable page → same questions to same answer engines. Record date, each answer, citations. Answers drift daily → signal not test; wrong answer = finding about these pages, not the engine. Repeatable: fixed prompts (brand, category, named competitor comparison, pricing); fixed engine set from ChatGPT search, Perplexity, Gemini, Google AI Mode, Copilot, Claude; signed out; verbatim answers + cited URLs; mention/citation share vs previous report or baseline.
96
- - AI referrals from answer-engine hosts + tagged visits per `bkit-audit-analytics`. Unmeasurable → name that audit; do not invent method here.
97
-
98
- **Done when:** `Answer Engines` holds policy per group, the console control, prompt rows or a skip, and referral status.
99
-
100
- - [ ] **Step 7 — Structure:** Indexable public page → URL format (lowercase, hyphenated, stable), click depth from home, orphan pages, broken internal links, nav/breadcrumbs reach every public page. Hierarchy for people → `bkit-audit-usability`; flag, do not decide. **Done when:** `Structure` row per check: met / finding, or skip in `Not Checked`.
101
- - [ ] **Step 8 — Trust:** Indexable public page → about/company, contact, support, pricing, privacy, terms; dated attributed content where published. `Organization` `sameAs` → store + social. Generative-AI guides: unique non-commodity content first → flag pages restating elsewhere only. Copy for people → `bkit-audit-usability`. **Done when:** `Trust` row per required page: present / finding, or skip in `Not Checked`.
102
- - [ ] **Step 9 — Consoles:** Indexable pages + consoles → indexing errors, indexed vs submitted, top queries + delta vs previous report. Consoles missing while indexable pages exist = finding; else `Indexing` only signal. Search console: generative-AI performance, Core Web Vitals (speed → `bkit-audit-app-performance`), page-indexing reasons per type (soft 404, duplicate without user-selected canonical, crawled not indexed). Other webmaster: AI-performance (citations, grounding queries, cited pages) + delta. IndexNow: public URL add/update/delete submitted; webmaster shows received. **Done when:** `Consoles` row per report: figure · delta · verdict, missing-console finding, or skip in `Not Checked`.
103
- - [ ] **Step 10 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per anchor + per search-doc or AI-crawler change since previous → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
104
- - [ ] **Step 11 — Anything Else:** (a) Changes since previous report's commit on public pages + crawl surface (routes, `robots.txt`, sitemap, metadata, structured data, locale routing, redirects, middleware, firewall/bot settings) → one-line verdict each. (b) Bounded ~30 min: senior technical SEO flags no step asks; read since previous run (incidents, new `docs/failures.jsonl`, `bkit-audit-logs` output, vendor status) — 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`.
107
+ - `llms.txt` and `llms-full.txt` are optional. Engines ignore them or use them unevenly, so a missing file is not a finding. **If** one is present → check that it is current and links to existing pages. A stale file is `LOW`.
108
+ - **If** there is an indexable page → check that the plain facts are in the HTML text, not only in images or scripts: product, audience, cost and platforms. Check for a direct Q&A near the top of the page that owns each answer. Check that the product and company use one name across the site, store and social. Check that the off-site description, pricing and platforms match the store, reviews, forums and press, because answer engines often cite those over the product site. List the third-party sources the prompt pass cited.
109
+ - Read the AI crawler policy in `robots.txt` for each crawler group. Allowing and blocking are both fine; a group with no recorded decision is a finding. The owner decides, and the report records the decision. Blocking one group does not block the others. Training crawlers: GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot. Search crawlers: OAI-SearchBot, Claude-SearchBot, PerplexityBot, Bingbot (which feeds some assistants); blocking one keeps the site out of those answers. User-triggered crawlers: ChatGPT-User, Claude-User, Perplexity-User; some vendors say these may not follow `robots.txt`. "Block training, allow search" is common. Write the policy per group.
110
+ - Check that the edge or firewall and any CDN "block AI bots" setting agree with `robots.txt`. A firewall `403` to an allowed search crawler silently overrides `robots.txt`. Check the edge or server logs for each search crawler's requests and status codes, not `robots.txt` alone.
111
+ - Read the search-console control for including or excluding pages from generative answers. The owner decides, and the report records the decision. The control does not govern training.
112
+ - **If** there is an indexable page → ask the same questions of the same answer engines. Record the date, each answer and its citations. Answers drift daily, so treat them as a signal, not a test. A wrong answer is a finding about these pages, not about the engine. Keep the pass repeatable: fixed prompts (brand, category, comparison with a named competitor, pricing); a fixed engine set from ChatGPT search, Perplexity, Gemini, Google AI Mode, Copilot and Claude; signed out; verbatim answers and cited URLs; and the mention and citation share against the previous report or the baseline.
113
+ - Read AI referrals from answer-engine hosts and tagged visits as `bkit-audit-analytics` defines them. **If** referrals cannot be measured → name that audit, and do not invent a method here.
114
+
115
+ **Done when:** `Answer Engines` holds the policy per group, the console control, the prompt rows or a skip, and the referral status.
116
+
117
+ - [ ] **Step 7 — Structure:** Run this step only when the project has an indexable public page. Check the URL format (lowercase, hyphenated, stable), the click depth from home, orphan pages, broken internal links, and that navigation and breadcrumbs reach every public page. Whether the hierarchy works for people goes to `bkit-audit-usability`: flag it, and do not decide it. **Done when:** `Structure` holds one row per check: met / finding, or the skip is in `Not Checked`.
118
+ - [ ] **Step 8 — Trust:** Run this step only when the project has an indexable public page. Check for the about or company, contact, support, pricing, privacy and terms pages, and for dated, attributed content where the site publishes any. Check that `Organization` `sameAs` points to the store and social profiles. The generative-AI guides put unique, non-commodity content first, so flag pages that only restate what exists elsewhere. Copy for people goes to `bkit-audit-usability`. **Done when:** `Trust` holds one row per required page: present / finding, or the skip is in `Not Checked`.
119
+ - [ ] **Step 9 — Consoles:** **If** there are indexable pages **and** consoles → read the indexing errors, indexed vs submitted, and the top queries with their delta against the previous report. **If** consoles are missing while indexable pages exist → that is a finding, and `Indexing` is the only signal. In the search console, read generative-AI performance, Core Web Vitals (speed goes to `bkit-audit-app-performance`) and the page-indexing reasons per type (soft 404, duplicate without user-selected canonical, crawled but not indexed). In other webmaster consoles, read AI performance (citations, grounding queries, cited pages) and its delta. For IndexNow, check that public URL additions, updates and deletions are submitted, and that the webmaster console shows them received. **Done when:** `Consoles` holds one row per report: figure · delta · verdict, or the missing-console finding, or the skip is in `Not Checked`.
120
+ - [ ] **Step 10 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. Give `Standards Coverage` one row per anchor and one per search-documentation or AI-crawler change since the previous report, each marked checked (naming 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.
121
+ - [ ] **Step 11 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches public pages or the crawl surface: routes, `robots.txt`, the sitemap, metadata, structured data, locale routing, redirects, middleware, or firewall and bot settings. (b) In a bounded pass of about 30 minutes, note what a senior technical SEO would flag that no step asks about. Read what happened since the previous run (incidents, new `docs/failures.jsonl` rows, `bkit-audit-logs` output, vendor status), and ask 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`.
105
122
 
106
123
  ### 🔒 Gate 2: Probes Check
107
124
 
108
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
109
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
110
- - [ ] **Settings untouched:** no search-console, webmaster, robots, sitemap, IndexNow, or firewall setting changed.
111
- - [ ] **No values:** no personal-data value anywhere in the report.
112
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
125
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
126
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
127
+ - [ ] **Settings untouched:** no search-console, webmaster, robots, sitemap, IndexNow or firewall setting changed.
128
+ - [ ] **No values:** no personal-data value appears anywhere in the report.
129
+ - [ ] **Gate 2 — Verified:** every item above holds.
113
130
 
114
131
  ## Findings
115
132
 
116
133
  <!-- prettier-ignore -->
117
134
  | Severity | Use |
118
135
  | --- | --- |
119
- | `CRITICAL` | An indexed preview or signed-in page exposes personal or unreleased data; production canonical points at a host that serves the wrong site and there is no workaround |
120
- | `HIGH` | Production removed from search; a page that should not be indexed is (auth, preview, signed-in), or an indexable page is `noindex`; `noindex` combined with `Disallow` so the URL can stay indexed; firewall blocks a search crawler the recorded policy allows |
121
- | `MEDIUM` | Wrong or missing metadata; structured data that disagrees with the page; canonical, `hreflang`, or redirect defect; consoles absent while indexable pages exist; an answer engine states a wrong fact taken from these pages; off-site listing disagrees with the site |
122
- | `LOW` | Stale `llms.txt`; naming drift that does not change which page is indexed. A missing `llms.txt`, or a missing retired rich-result type, is not a finding |
136
+ | `CRITICAL` | An indexed preview or signed-in page exposes personal or unreleased data. The production canonical points at a host that serves the wrong site, and there is no workaround |
137
+ | `HIGH` | Production is removed from search. A page that should not be indexed is indexed (auth, preview, signed-in), or an indexable page is `noindex`. `noindex` is combined with `Disallow`, so the URL can stay indexed. The firewall blocks a search crawler that the recorded policy allows |
138
+ | `MEDIUM` | Wrong or missing metadata. Structured data that disagrees with the page. A canonical, `hreflang` or redirect defect. Consoles absent while indexable pages exist. An answer engine states a wrong fact taken from these pages. An off-site listing disagrees with the site |
139
+ | `LOW` | A stale `llms.txt`. Naming drift that does not change which page is indexed. A missing `llms.txt`, or a missing retired rich-result type, is not a finding |
123
140
 
124
- Within a severity: indexing first.
141
+ Within a severity, list indexing findings first.
125
142
 
126
143
  <!-- prettier-ignore -->
127
144
  | ID | Severity | Location | Evidence | Expected |
128
145
  | --- | --- | --- | --- | --- |
129
146
  | PENDING | PENDING | PENDING | PENDING | PENDING |
130
147
 
131
- Empty and clean → one row `None`.
148
+ **If** the run finds nothing → write one row: `None`.
132
149
 
133
150
  ## Report
134
151
 
@@ -201,13 +218,17 @@ PENDING
201
218
 
202
219
  ### 🔒 Gate 3: Report Check
203
220
 
204
- - [ ] **No placeholders:** no `PENDING` left
205
- - [ ] **Summary:** names count per severity, whether any indexable public page exists, and the production host.
206
- - [ ] **Series:** mention and citation share, and console query deltas, beside previous report's numbers, or marked baseline.
207
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
208
- - [ ] **Process Improvements:** `Universal` and `Project` filled
209
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
210
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
221
+ - [ ] **No placeholders:** no `PENDING` is left.
222
+ - [ ] **Summary:** `Summary` gives the count per severity.
223
+ - [ ] **Indexable page:** `Summary` states whether any indexable public page exists.
224
+ - [ ] **Production host:** `Summary` names the production host.
225
+ - [ ] **Series:** the report shows mention and citation share, and console query deltas, beside the previous report's numbers, or marks the run as baseline.
226
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
227
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
228
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
229
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
230
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
231
+ - [ ] **Gate 3 — Verified:** every item above holds.
211
232
 
212
233
  <!-- bkit:end -->
213
234