@cbartens/bkit 6.1.1 → 6.2.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 (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -0,0 +1,54 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/noise.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/observability.md`.
4
+ >
5
+ > **Finish against:** none.
6
+ >
7
+ > **Where the facts come from:** the log-level changes in the code, the error tracker's archived and muted issues, and the alert rules whose thresholds were raised.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/noise.md`. The table starts empty, because the file is append-only.
12
+ > 2. Add one row for each signal already downgraded: a log-level reduction, an archived or muted error-tracker issue or a raised alert threshold.
13
+ > 3. Add a row in the same change as every later downgrade, before the signal goes quiet.
14
+ > 4. Record unresolved facts under `## Open questions`.
15
+ > 5. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/noise.md` | — | — | ○ | ● | ○ | Intentional signal downgrades: log levels, error-tracker archives and mutes, and alert thresholds, each with its trigger and reason. |
16
+ > 6. Check the document against each completion check, then delete this introduction.
17
+ >
18
+ > **If it does not apply:** a project with no downgraded signal keeps the empty table.
19
+ >
20
+ > **Completion checks:**
21
+ >
22
+ > - Every downgraded signal has one row with a trigger and a reason it is safe.
23
+ > - Every row names the signal in the way `docs/observability.md` § Signals names it.
24
+
25
+ # Noise
26
+
27
+ > [!CAUTION]
28
+ > **Purpose:** Intentional signal downgrades: log levels, error-tracker archives and mutes, and alert thresholds, each with its trigger and reason.
29
+ >
30
+ > **Rules:**
31
+ >
32
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
33
+ > - This file is append-only.
34
+ > - Add one row per downgraded file or line, archived issue or raised threshold.
35
+ > - Downgrade a signal only when its trigger is known and expected.
36
+ > - Record the trigger, not just the verdict.
37
+ > - Never silence a signal at its source. Log it at a lower level instead.
38
+ > - Archive or mute an issue only when it is recorded here.
39
+ >
40
+ > **Not here:** The signals themselves and the alerts go in `docs/observability.md`.
41
+ >
42
+ > **Update when:** A signal is downgraded, or a recheck condition in a row is met. Add a row for either, and leave every earlier row as it is.
43
+
44
+ ## Downgrades
45
+
46
+ [One row per downgraded signal, added at the bottom.]
47
+
48
+ <!-- prettier-ignore -->
49
+ | Date | Signal | Where | Change | Trigger | Why it is safe | Recheck when |
50
+ | --- | --- | --- | --- | --- | --- | --- |
51
+
52
+ ## Open questions
53
+
54
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -0,0 +1,99 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/observability.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/architecture.md`.
4
+ >
5
+ > **Finish against:** `docs/security.md` for `## Log format`, which is checked against the personal data that doc lists, so none of it gets logged.
6
+ >
7
+ > **Where the facts come from:** the logger module and its configuration, the code that emits named log events, spans and metrics, the error-tracker and log-drain configuration, and the alert rules.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/observability.md`.
12
+ > 2. Redraw `## Signal pipeline` as the path a signal takes from the application to the people who act on it.
13
+ > 3. Fill `## Log format` by naming the logger module and the call every log line goes through, then the fields each line carries.
14
+ > 4. Fill `## Signals` with one row per named log event, span, metric or audit record that an alert, a test, a `docs/noise.md` row or another doc relies on. Leave out ordinary log lines.
15
+ > 5. Fill `## Correlation` with the identifier that ties one request together across runtimes, and where it is set.
16
+ > 6. Fill `## Error tracking` with the tool that collects errors and how an error reaches it.
17
+ > 7. Fill `## Alerts` with one row per alert: what fires it, the threshold and who is told.
18
+ > 8. Fill `## Where to look` with where to read each kind of signal when something fails.
19
+ > 9. Record unresolved facts under `## Open questions`.
20
+ > 10. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/observability.md` | ○ | ○ | ● | ● | ○ | Logging architecture, correlation tracing, telemetry pipelines, error tracking and alerts. |
21
+ > 11. Check the document against each completion check, then delete this introduction.
22
+ >
23
+ > **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Alerts` for a project with none.
24
+ >
25
+ > **Completion checks:**
26
+ >
27
+ > - The chart names every place a signal is sent to.
28
+ > - `## Log format` names a logger module that exists in the code.
29
+ > - Every signal an alert reads has a row in `## Signals`.
30
+ > - `## Log format` lists no field that `docs/security.md` marks as personal data.
31
+ > - No example row remains.
32
+
33
+ # Observability
34
+
35
+ > [!CAUTION]
36
+ > **Purpose:** Logging architecture, correlation tracing, telemetry pipelines, error tracking and alerts.
37
+ >
38
+ > **Rules:**
39
+ >
40
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
41
+ > - NEVER log PII. Scrub sensitive fields at the source.
42
+ > - Observability never blocks business logic.
43
+ >
44
+ > **Not here:** Smoke checks that probe a deployed release go in `docs/testing.md`. Downgraded signals go in `docs/noise.md`. Failure-evidence fetching for `/bkit-debug` is configured in `.agents/context.md`.
45
+ >
46
+ > **Update when:** A logger, signal, correlation identifier, error tracker, alert or log drain is added, changed or removed.
47
+
48
+ ## Signal pipeline
49
+
50
+ [The path a signal takes from the application to the people who act on it.]
51
+
52
+ ```mermaid
53
+ flowchart LR
54
+ APP["Application"] --> LOGS["Log drain"]
55
+ APP --> ERR["Error tracker"]
56
+ LOGS --> ALERT["Alert rules"]
57
+ ERR --> ALERT
58
+ ALERT --> PEOPLE["On-call people"]
59
+ ```
60
+
61
+ ## Log format
62
+
63
+ [The logger module, the call every log line goes through, and the fields each line carries.]
64
+
65
+ ## Signals
66
+
67
+ <!-- prettier-ignore -->
68
+ | Signal | Kind | Emitted from | Lands in |
69
+ | --- | --- | --- | --- |
70
+ | [Signal name] | [Log event, span, metric or audit record.] | [Module that emits it.] | [Where it is stored or shown.] |
71
+ | [e.g., report.saved] | Log event | The report service. | The log drain. |
72
+
73
+ ## Correlation
74
+
75
+ [The identifier that ties one request together across runtimes, and where it is set.]
76
+
77
+ ## Error tracking
78
+
79
+ [The tool that collects errors and how an error reaches it.]
80
+
81
+ ## Alerts
82
+
83
+ <!-- prettier-ignore -->
84
+ | Alert | Fires when | Threshold | Notifies |
85
+ | --- | --- | --- | --- |
86
+ | [Alert name] | [Signal or condition.] | [Limit and window.] | [Who is told.] |
87
+ | [e.g., Report failures] | The report service logs errors. | 5 in 10 minutes. | The on-call channel. |
88
+
89
+ ## Where to look
90
+
91
+ <!-- prettier-ignore -->
92
+ | Question | Look in |
93
+ | --- | --- |
94
+ | [Question a person asks.] | [Tool and view.] |
95
+ | [e.g., Why did a report fail?] | The error tracker, then the log drain filtered by request identifier. |
96
+
97
+ ## Open questions
98
+
99
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -0,0 +1,137 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/security.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/architecture.md`.
4
+ >
5
+ > **Finish against:** `docs/data-schema.md` for the "Where stored" column of the `## PII` table.
6
+ >
7
+ > **Where the facts come from:** the authentication and session code, the route and permission definitions, the input-validation schemas, the secret stores and the CI secret configuration, and the data models that hold personal data.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/security.md`.
12
+ > 2. Fill `## Trust boundaries` with where untrusted input enters the system. Read the runtimes from `docs/architecture.md`.
13
+ > 3. Fill `## Authentication` with how a user or service proves who it is. Redraw the sequence chart for one authenticated request.
14
+ > 4. Fill `## Authorization` with one row per role or service account and what it may do.
15
+ > 5. Fill `## Input validation` with where each kind of input is checked, on the server.
16
+ > 6. Fill `## Rate limiting` with each limited route or action and its limit.
17
+ > 7. Fill `## Secrets` with one row per secret: its name, the store that holds it, who can read it and how it rotates. Write names, never values.
18
+ > 8. Fill `## PII` with each kind of personal data and how it is protected. Leave "Where stored" to be finished once `docs/data-schema.md` exists.
19
+ > 9. Fill the `### This project` slot under `## Supply-Chain (GitHub Actions)` with the project's own dependency and CI rules. Keep the rest of that section.
20
+ > 10. Record unresolved facts under `## Open questions`.
21
+ > 11. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/security.md` | ● | ● | ● | ○ | ○ | Authentication, authorization, input validation, rate limiting, secrets management and PII handling. |
22
+ > 12. Check the document against each completion check, then delete this introduction.
23
+ >
24
+ > **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Authentication` for a tool with no users.
25
+ >
26
+ > **Completion checks:**
27
+ >
28
+ > - The sequence chart matches the authentication code path.
29
+ > - Every secret the CI configuration or the code reads has a row in `## Secrets`.
30
+ > - Every service account has a row in `## Authorization`.
31
+ > - Every kind of personal data in `docs/data-schema.md` has a row in `## PII`.
32
+ > - No secret value appears in the document.
33
+ > - No example row remains.
34
+
35
+ # Security
36
+
37
+ > [!CAUTION]
38
+ > **Purpose:** Authentication, authorization, input validation, rate limiting, secrets management and PII handling.
39
+ >
40
+ > **Rules:**
41
+ >
42
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
43
+ > - Auth standards live only here. Other docs link to this file and do not restate them.
44
+ > - Never write a secret value. Write its name and the store that holds it.
45
+ >
46
+ > **bkit practice:** `## Supply-Chain (GitHub Actions)` is bkit's own practice. Keep it and its heading, and put the project's own rules in its `### This project` slot. Sections marked **bkit practice** keep their heading text and stay separate sections. Do not rename, merge or compress them, because bkit's CI template, advisories and audits cite them by name.
47
+ >
48
+ > **Not here:** The variables a developer sets locally go in `docs/setup.md` § Environment variables. How each environment's config is synced goes in `docs/deployments.md` § Secrets and env config. The tables and fields that hold personal data go in `docs/data-schema.md`.
49
+ >
50
+ > **Update when:** A role, service account, secret, validation point, limit or kind of personal data is added, changed or removed.
51
+
52
+ ## Trust boundaries
53
+
54
+ [Where untrusted input enters the system, and which runtime checks it.]
55
+
56
+ ## Authentication
57
+
58
+ [How a user or service proves who it is, and how a session or token is kept.]
59
+
60
+ ```mermaid
61
+ sequenceDiagram
62
+ participant U as User
63
+ participant A as Application
64
+ participant S as Session store
65
+ U->>A: Request with credentials
66
+ A->>S: Check the session
67
+ S-->>A: Identity
68
+ A-->>U: Response
69
+ ```
70
+
71
+ ## Authorization
72
+
73
+ <!-- prettier-ignore -->
74
+ | Role or service account | Kind | May | Granted by |
75
+ | --- | --- | --- | --- |
76
+ | [Role or service account] | [User role or service account.] | [What it may do.] | [Where the grant is defined.] |
77
+ | [e.g., Reviewer] | User role | Read and comment on reports. | The role table in the application. |
78
+
79
+ ## Input validation
80
+
81
+ <!-- prettier-ignore -->
82
+ | Input | Checked in | How |
83
+ | --- | --- | --- |
84
+ | [Kind of input] | [Handler or layer.] | [Schema or rule.] |
85
+ | [e.g., Report form] | The report service handler. | A schema parsed on the server. |
86
+
87
+ ## Rate limiting
88
+
89
+ <!-- prettier-ignore -->
90
+ | Route or action | Limit | Keyed by |
91
+ | --- | --- | --- |
92
+ | [Route or action] | [Requests per window.] | [User, address or token.] |
93
+ | [e.g., Sign-in] | 5 requests per minute. | Network address. |
94
+
95
+ ## Secrets
96
+
97
+ <!-- prettier-ignore -->
98
+ | Secret name | Store | Who can read it | Rotation |
99
+ | --- | --- | --- | --- |
100
+ | [Secret name] | [Store that holds it.] | [Roles and service accounts.] | [How and how often it rotates.] |
101
+ | [e.g., SESSION_KEY] | The hosting platform's secret store. | The report service. | Every 90 days. |
102
+
103
+ ## PII
104
+
105
+ <!-- prettier-ignore -->
106
+ | Personal data | Why it is held | Protection | Where stored |
107
+ | --- | --- | --- | --- |
108
+ | [Kind of personal data] | [Why the project holds it.] | [Encryption, masking or retention.] | [Table and field, from `docs/data-schema.md`.] |
109
+ | [e.g., Email address] | Account sign-in. | Never logged. | Users table, email field. |
110
+
111
+ ## Supply-Chain (GitHub Actions)
112
+
113
+ > **bkit practice:** keep this section; bkit's audits and advisories cite its heading by name, so leave the heading text unchanged.
114
+
115
+ Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, Trivy scan, CVE handling) are described in `deployments.md` § Dependency updaters. This section holds the security invariants only.
116
+
117
+ **Token isolation:**
118
+
119
+ - Renovate PRs get a restricted `GITHUB_TOKEN`.
120
+ - They have no access to the cloud lane's model-auth secrets (`secrets.BKIT_ANTHROPIC_API_KEY` / the provider `BKIT_` keys / `secrets.BKIT_OPENAI_API_KEY`).
121
+ - They have no access to federated Claude tokens either. Only a `bkit-cloud.yml` job that matches the federation rule mints those.
122
+ - `bkit-cloud.yml` does not dispatch on Renovate PRs.
123
+ - As a result, a compromised dependency PR cannot reach agent API credentials.
124
+
125
+ **Scanner isolation:** The CI vulnerability scanner (e.g. `bkit-trivy.yml`) runs with `contents: read`, `persist-credentials: false` and no secret. Its image or action is pinned by digest, never by a floating tag. Setup is in `.bkit/templates.md` § Trivy.
126
+
127
+ The untrusted-content rules bkit applies to every workflow are in `.bkit/prompts.md` § Untrusted Content & Prompt Injection.
128
+
129
+ ### This project
130
+
131
+ > **Project slot:** the project's own dependency and CI rules, such as which updater it runs and who reviews its pull requests.
132
+
133
+ [The project's dependency and CI supply-chain rules.]
134
+
135
+ ## Open questions
136
+
137
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -0,0 +1,93 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/setup.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/technology.md`.
4
+ >
5
+ > **Finish against:** `docs/architecture.md` for `## Local services`, and `docs/security.md` for `## Environment variables`; both sections wait for the secrets and services those docs name.
6
+ >
7
+ > **Where the facts come from:** the package manifests and their scripts, the example environment file, the local service configuration, the CI configuration and a clean checkout run on a fresh machine.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/setup.md`.
12
+ > 2. Fill `## Prerequisites` with the tools a developer installs first, and name the file that holds each required version.
13
+ > 3. Run the setup on a clean checkout, and write each command into `## First-time setup` in the order that worked.
14
+ > 4. Fill `## Environment variables` with what a developer sets on their own machine. Write names and where each value comes from, and never a secret value.
15
+ > 5. Fill `## Local services` with each local service, its start command and its reset command. An integration test run needs both.
16
+ > 6. Fill `## Everyday commands` with the commands a developer runs most, read from the manifest scripts.
17
+ > 7. Fill `## Troubleshooting` with the failures new contributors hit and the fix for each.
18
+ > 8. Record unresolved facts under `## Open questions`.
19
+ > 9. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/setup.md` | — | — | ○ | ○ | — | How a developer sets up and runs the project locally: prerequisites, first-time setup, environment variables, local services, everyday commands and troubleshooting. |
20
+ > 10. Check the document against each completion check, then delete this introduction.
21
+ >
22
+ > **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Local services` for a project with none.
23
+ >
24
+ > **Completion checks:**
25
+ >
26
+ > - The first-time commands ran in order on a clean checkout.
27
+ > - Every local service has a start command and a reset command.
28
+ > - No secret value appears in the document.
29
+ > - No example row remains.
30
+
31
+ # Setup
32
+
33
+ > [!CAUTION]
34
+ > **Purpose:** How a developer sets up and runs the project locally: prerequisites, first-time setup, environment variables, local services, everyday commands and troubleshooting.
35
+ >
36
+ > **Rules:**
37
+ >
38
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
39
+ > - Never write a secret value. Write its name and where it comes from.
40
+ > - Local seed data and test fixtures must NEVER run against a remote project.
41
+ >
42
+ > **Not here:** Secret names, stores and rotation go in `docs/security.md` § Secrets. How a deployed environment gets its configuration goes in `docs/deployments.md` § Secrets and env config. Agent host and remote access setup is in `.bkit/install.md`.
43
+ >
44
+ > **Update when:** A prerequisite, a setup command, an environment variable, a local service or a script changes.
45
+
46
+ ## Prerequisites
47
+
48
+ <!-- prettier-ignore -->
49
+ | Tool | Needed for | Version from |
50
+ | --- | --- | --- |
51
+ | [Tool] | [What it is used for.] | [File that holds the version.] |
52
+ | [e.g., Language runtime] | Running and testing the project. | The version file in the repository root. |
53
+
54
+ ## First-time setup
55
+
56
+ 1. [The first command, and what it does.]
57
+ 2. [The next command, and what it does.]
58
+
59
+ ## Environment variables
60
+
61
+ <!-- prettier-ignore -->
62
+ | Variable | Used by | Where the value comes from |
63
+ | --- | --- | --- |
64
+ | [Variable name] | [What reads it.] | [Where a developer gets the value.] |
65
+ | [e.g., DATABASE_URL] | The local database client. | The example environment file. |
66
+
67
+ ## Local services
68
+
69
+ <!-- prettier-ignore -->
70
+ | Service | Start command | Reset command |
71
+ | --- | --- | --- |
72
+ | [Service] | [Command that starts it.] | [Command that resets it to a clean state.] |
73
+ | [e.g., Local database] | The project's start script. | The project's reset script. |
74
+
75
+ ## Everyday commands
76
+
77
+ <!-- prettier-ignore -->
78
+ | Task | Command |
79
+ | --- | --- |
80
+ | [Task] | [Command.] |
81
+ | [e.g., Run the unit tests] | The project's test script. |
82
+
83
+ ## Troubleshooting
84
+
85
+ <!-- prettier-ignore -->
86
+ | Symptom | Cause | Fix |
87
+ | --- | --- | --- |
88
+ | [What the developer sees.] | [Why it happens.] | [What to do.] |
89
+ | [e.g., The database connection is refused] | The local database is not running. | Start the local services. |
90
+
91
+ ## Open questions
92
+
93
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -0,0 +1,70 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/technology.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/components.md`.
4
+ >
5
+ > **Finish against:** none.
6
+ >
7
+ > **Where the facts come from:** the package manifests and lockfiles, the build and tool configuration files, the CI configuration and the lint and format settings.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/technology.md`.
12
+ > 2. List every layer the components in `docs/components.md` need, and read each layer's technology from the manifest or configuration file that declares it.
13
+ > 3. Fill `## Stack` with one row per technology. In `Version from`, name the file that holds the version, and never type the number.
14
+ > 4. Fill `## Conventions` with each rule a reviewer enforces, and name the tool or review step that enforces it.
15
+ > 5. Fill `## Not used` with technologies a contributor might expect, and name what the project uses instead.
16
+ > 6. Record unresolved facts under `## Open questions`.
17
+ > 7. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/technology.md` | ● | ● | ○ | ○ | ○ | Which frameworks, libraries and styling systems the project uses, and the coding conventions a reviewer enforces. Why a choice was made goes in `decisions.jsonl`. |
18
+ > 8. Check the document against each completion check, then delete this introduction.
19
+ >
20
+ > **If it does not apply:** every project uses some technology. Write `Not applicable: {reason}` under a section that does not apply, such as `## Not used` for a project with no alternatives in play.
21
+ >
22
+ > **Completion checks:**
23
+ >
24
+ > - Every layer in `docs/components.md` has a row in `## Stack`.
25
+ > - Every `Version from` cell names an existing file, and no version number is typed in the document.
26
+ > - Every convention names what enforces it.
27
+ > - No example row remains.
28
+
29
+ # Technology
30
+
31
+ > [!CAUTION]
32
+ > **Purpose:** Which frameworks, libraries and styling systems the project uses, and the coding conventions a reviewer enforces. Why a choice was made goes in `decisions.jsonl`.
33
+ >
34
+ > **Rules:**
35
+ >
36
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
37
+ > - Name the file that holds a version, and never type a version number.
38
+ > - List each technology once, with how it is used.
39
+ >
40
+ > **Not here:** The reason for a choice goes in `decisions.jsonl`. Service boundaries and deployment topology go in `docs/architecture.md`. Setup commands go in `docs/setup.md`.
41
+ >
42
+ > **Update when:** A framework, library or styling system is added, replaced or removed, or a convention a reviewer enforces changes.
43
+
44
+ ## Stack
45
+
46
+ <!-- prettier-ignore -->
47
+ | Layer | Technology | Version from | Chosen for |
48
+ | --- | --- | --- | --- |
49
+ | [Layer] | [Technology] | [File that holds the version.] | [What it is used for.] |
50
+ | [e.g., Web interface] | A component framework | The package manifest. | Rendering the report screens. |
51
+
52
+ ## Conventions
53
+
54
+ <!-- prettier-ignore -->
55
+ | Convention | Rule | Enforced by |
56
+ | --- | --- | --- |
57
+ | [Convention] | [What a contributor does.] | [Tool or review step.] |
58
+ | [e.g., Formatting] | One formatter settings file for the whole repository. | The formatter check in CI. |
59
+
60
+ ## Not used
61
+
62
+ <!-- prettier-ignore -->
63
+ | Technology | Use instead |
64
+ | --- | --- |
65
+ | [Technology a contributor might expect] | [What the project uses.] |
66
+ | [e.g., A second test runner] | The project's one test runner. |
67
+
68
+ ## Open questions
69
+
70
+ [Each unresolved fact, who can answer it and which section it affects.]