@cbartens/bkit 5.5.1 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +35 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +91 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +12 -11
- package/.bkit/core/.bkit/trackers.md +51 -28
- package/.bkit/core/.bkit/workflows.md +394 -355
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +10 -7
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +46 -91
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +6 -6
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +250 -3
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +157 -20
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +32 -14
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +11 -11
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +16 -7
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +4 -4
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/CHANGELOG.md +112 -0
- package/README.md +50 -35
- package/dist/checks/after/ci-yml.js +39 -28
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +11 -8
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +39 -82
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +4 -4
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +343 -59
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -8
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +147 -9
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +247 -3
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +125 -17
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +113 -24
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
|
@@ -8,24 +8,14 @@
|
|
|
8
8
|
|
|
9
9
|
> [!CAUTION]
|
|
10
10
|
> **Purpose:** Implementation plan — pre-flight, gates, runbook, verification, rollback.
|
|
11
|
-
>
|
|
12
|
-
> **Rules:**
|
|
13
|
-
>
|
|
14
|
-
> - Any tools mentioned below are examples only; swap for actual tools in final output; drop inapplicable.
|
|
15
|
-
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
16
|
-
> - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
|
|
17
|
-
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
18
|
-
> - Source of truth: literal `[x]` vs `[ ]` checkboxes in this document; `[ ]` means not DONE regardless of context.
|
|
19
11
|
|
|
20
12
|
## Context & Goals
|
|
21
13
|
|
|
22
|
-
[
|
|
23
|
-
|
|
24
|
-
> Success criteria once in `Acceptance Scenario → Success Criteria`; each runbook task has own `Done when`. Do not restate success list here.
|
|
14
|
+
[Problem or feature, and why it is needed; initially set to `PENDING`.]
|
|
25
15
|
|
|
26
16
|
**Related Issues:**
|
|
27
17
|
|
|
28
|
-
- [
|
|
18
|
+
- [`#N — title (state)` per related issue. None → `None`; initially set to `PENDING`.]
|
|
29
19
|
|
|
30
20
|
---
|
|
31
21
|
|
|
@@ -37,35 +27,16 @@
|
|
|
37
27
|
>
|
|
38
28
|
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). Agent handles rest.
|
|
39
29
|
|
|
40
|
-
### Spec
|
|
41
|
-
|
|
42
|
-
> [!IMPORTANT]
|
|
43
|
-
> What good looks like; canonical for the plan phase. Subagents (plan generate, plan review, plan summary) must follow this spec. No plan subagent restates rules; this section = single source of truth for the plan.
|
|
44
|
-
|
|
45
|
-
- **Narrative:** 1–2 sentences, user POV (not system POV). User action + what they get back. Source, first that carries it wins: design `## Acceptance Scenario` → verbatim; issue `Narrative` (change shape, `.bkit/trackers.md` § Issue shapes) → verbatim; audits only (`docs/audits/`) → user/operator impact from in-scope findings. None → both fields = `⚠️ MISSING: no design doc, no issue Narrative and no audit report — human must provide before plan proceeds`; never fabricate; Gate 1 blocked until human fills.
|
|
46
|
-
- **Success Criteria:** <=5 bullets, measurable / testable. Outcomes (e.g. "user sees their event in the list within 2s"), not steps (e.g. "call API, render component"). Design count ≠ 5 → smallest set proving feature. Design → verbatim. No design → issue `Success Criteria` verbatim. Audits only → one bullet per in-scope finding id from `Expected`; no 5-bullet cap.
|
|
47
|
-
- **Process Sketch:** Design → plan inherits/refines. same happy-path (`Concrete Example`) + branches (`Edge Cases`) as `WHEN X → THEN Y` (3–7 lines); reuse exact examples, do not invent. Outcomes, not steps.
|
|
48
|
-
- **Key Edge Cases:** Design → plan inherits. Concurrency, conflicts, failures, cross-feature — not trivial validation (plan adds that).
|
|
49
|
-
- **Edge Cases:** Plan phase — design Key Edge Cases verbatim (no design → issue `Edge Cases` rows verbatim) + validation / error / boundary cases.
|
|
50
|
-
- **Concrete Example:** Plan phase only. Role, starting state, numbered steps, observable outcome. One scenario, not a list.
|
|
51
|
-
- **Derived Test Matrix:** Plan phase only. One row per testable behaviour → exactly one `Agent Execution Runbook` task. No row without a target file. In-scope audit behaviour → one row. Issue `Derived Test Matrix` rows → kept verbatim; add missing rows.
|
|
52
|
-
|
|
53
30
|
### Narrative
|
|
54
31
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Narrative. No design → per Spec above; initially set to `PENDING`.]
|
|
32
|
+
[1-2 sentences from the user's side: what they do, what they get back; initially set to `PENDING`.]
|
|
58
33
|
|
|
59
34
|
### Success Criteria
|
|
60
35
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Success Criteria. No design → per Spec above; initially set to `PENDING`.]
|
|
36
|
+
[Up to 5 measurable outcomes; initially set to `PENDING`.]
|
|
64
37
|
|
|
65
38
|
### Process Sketch
|
|
66
39
|
|
|
67
|
-
> Inherited from design; plan may refine. `Concrete Example` (happy path) + `Edge Cases` (branches) as `WHEN X → THEN Y`, not prose — same examples. Do not invent new examples. Sense-check top-level process HERE without prose below. Outcomes, not implementation steps.
|
|
68
|
-
|
|
69
40
|
- **WHEN** [trigger / user action] **→ THEN** [observable outcome]
|
|
70
41
|
- **WHEN** [next step] **→ THEN** [outcome]
|
|
71
42
|
- **IF** [edge case / failure — mirrors an Edge Cases row] **→ THEN** [handling]
|
|
@@ -74,8 +45,6 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
74
45
|
|
|
75
46
|
### Concrete Example
|
|
76
47
|
|
|
77
|
-
> Plan expands from design.
|
|
78
|
-
|
|
79
48
|
**Setup:** [User role, existing state, context]
|
|
80
49
|
|
|
81
50
|
**Steps:**
|
|
@@ -88,34 +57,15 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
88
57
|
|
|
89
58
|
### Edge Cases
|
|
90
59
|
|
|
91
|
-
> Plan expands from design's Key Edge Cases.
|
|
92
|
-
|
|
93
60
|
<!-- prettier-ignore -->
|
|
94
61
|
| Scenario | Expected Behavior |
|
|
95
62
|
| --- | --- |
|
|
96
|
-
| [
|
|
63
|
+
| [Design Key Edge Case or plan-added case] | [Specific behavior] |
|
|
97
64
|
| [e.g., concurrent edit from another device] | [e.g., last-write-wins, no crash] |
|
|
98
65
|
|
|
99
66
|
### Derived Test Matrix
|
|
100
67
|
|
|
101
|
-
|
|
102
|
-
>
|
|
103
|
-
> **Discrimination (no false-green):** assertion MUST hit the **affected** surface and FAIL if behaviour broken — not transport status (200/201), not proxy surfaces, never mock away the boundary under test.
|
|
104
|
-
|
|
105
|
-
**Tier Key** — use these exact tier names in the `Type` column (they must match `docs/testing.md`); pick the **lowest tier that actually exercises** the behaviour (a behaviour may need several):
|
|
106
|
-
|
|
107
|
-
<!-- prettier-ignore -->
|
|
108
|
-
| Tier | Use for | Example behaviour |
|
|
109
|
-
| --- | --- | --- |
|
|
110
|
-
| **Static** | every change — type / lint / format / prose / drift (global gate, not a per-feature row) | `tsc`, lint, and `bkit check` pass on the changed files |
|
|
111
|
-
| **Unit** | pure function / single module, no I/O | service parses a payload correctly |
|
|
112
|
-
| **Integration** | crosses a LOCAL stateful boundary (own DB / API), no mocks at the boundary, fresh instance | API endpoint enforces tenant isolation against a fresh local instance |
|
|
113
|
-
| **@live (golden)** | crosses an EXTERNAL / DEPLOYED boundary (3rd-party API, model, payment, deployed schema, RLS) — reach it, assert a ground-truth signal | a real 3rd-party API returns content and a boundary-only identity |
|
|
114
|
-
| **E2E** | user-visible UI flow / DOM state | user creates an event and sees it in the list |
|
|
115
|
-
| **fresh-DB replay** | new / changed migration or seed (`bkit-tests-migration`) | migration replays from empty and the seed loads |
|
|
116
|
-
| **Smoke** | post-deploy health of a deployed surface (global observability gate) | deployed health route returns 200 |
|
|
117
|
-
|
|
118
|
-
One row per behaviour (copy the tier name from the key above verbatim into `Type`):
|
|
68
|
+
`Type` = a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay, Smoke.
|
|
119
69
|
|
|
120
70
|
<!-- prettier-ignore -->
|
|
121
71
|
| Test description | Type | Target file |
|
|
@@ -130,9 +80,6 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
|
|
|
130
80
|
|
|
131
81
|
- [ ] **Acceptance Scenario confirmed:** I have reviewed the Narrative, Success Criteria, Process Sketch, Concrete Example, Edge Cases, and Derived Test Matrix above. They correctly describe what "done" looks like.
|
|
132
82
|
|
|
133
|
-
> [!CAUTION]
|
|
134
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
135
|
-
|
|
136
83
|
---
|
|
137
84
|
|
|
138
85
|
## 👤 ⚠️ Breaking Changes & Naming Review
|
|
@@ -141,15 +88,12 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
|
|
|
141
88
|
> **🛑 HUMAN must READ and CONFIRM this SECTION.**
|
|
142
89
|
> Review proposed names and breaking changes below.
|
|
143
90
|
|
|
144
|
-
[Proposed names
|
|
91
|
+
[Proposed names (pages, files, DB tables, routes, API contracts) and breaking changes (DB structure, global layout). None → `None`; initially set to `PENDING`.]
|
|
145
92
|
|
|
146
93
|
### 👤 ✅ Human Confirmation
|
|
147
94
|
|
|
148
95
|
- [ ] **Breaking Changes confirmed:** I have reviewed all breaking changes and naming decisions above.
|
|
149
96
|
|
|
150
|
-
> [!CAUTION]
|
|
151
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
152
|
-
|
|
153
97
|
---
|
|
154
98
|
|
|
155
99
|
## 👤 ⚠️ Open Questions & Assumptions
|
|
@@ -157,8 +101,6 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
|
|
|
157
101
|
> [!CAUTION]
|
|
158
102
|
> **🛑 HUMAN must READ and CONFIRM this SECTION.**
|
|
159
103
|
> Unknowns + assumptions this plan relies on. Unresolved question = risk; wrong assumption breaks downstream. If none, write "None".
|
|
160
|
-
> **Never a bare question.** Each carries 2-3 options, a recommendation, and default if unanswered — human must decide from the page alone. Canonical plan shape.
|
|
161
|
-
> Design → carry its options / recommendation forward where already answered.
|
|
162
104
|
|
|
163
105
|
- **Assumption:** [what the plan takes as given] → [what breaks if it's wrong]
|
|
164
106
|
- **Open Question:** [decision needed] → [who / how to resolve]
|
|
@@ -170,156 +112,109 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
|
|
|
170
112
|
|
|
171
113
|
- [ ] **Open Questions & Assumptions confirmed:** I have resolved or explicitly accepted every open question and assumption above.
|
|
172
114
|
|
|
173
|
-
> [!CAUTION]
|
|
174
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
175
|
-
|
|
176
115
|
---
|
|
177
116
|
|
|
178
117
|
## Alternative Approaches & Recommendations
|
|
179
118
|
|
|
180
|
-
[
|
|
181
|
-
|
|
182
|
-
**Selection Rule:** pick the approach with the best quality-of-end-state, not the smallest diff / lowest cost-of-change. In-scope work = complete or explicitly moved to `Out of Scope` — no 90% solutions or silent shortcuts.
|
|
119
|
+
[Rejected paths and why; future phase recommendations; initially set to `PENDING`.]
|
|
183
120
|
|
|
184
121
|
## Out of Scope
|
|
185
122
|
|
|
186
|
-
[
|
|
123
|
+
[Excluded items, each `Exempt`. None → `None`; initially set to `PENDING`.]
|
|
187
124
|
|
|
188
125
|
<!-- prettier-ignore -->
|
|
189
126
|
| Excluded item | Why `Exempt` | Where it belongs |
|
|
190
127
|
| --- | --- | --- |
|
|
191
128
|
| [feature/fix] | [why genuinely-additive] | [design non-goal / follow-up #N / future phase] |
|
|
192
129
|
|
|
193
|
-
> [!CAUTION]
|
|
194
|
-
> **Default = in-scope.** `Exempt` only if genuinely-additive — not required by `Success Criteria`, `Acceptance Scenario` / `Derived Test Matrix` row, or design (non-goals excepted). Required items → runbook task, never deferral; parking here = `Blocking` deferral → plan review / scope-check pulls back. Mirror each `Exempt` row in `docs/deferrals.jsonl`. Audit `LOW` → `Exempt` rows here.
|
|
195
|
-
|
|
196
130
|
## Suggested Scope Expansion
|
|
197
131
|
|
|
198
|
-
[
|
|
132
|
+
[Candidates overlapping this plan's surfaces. None → `None`; initially set to `PENDING`.]
|
|
199
133
|
|
|
200
134
|
<!-- prettier-ignore -->
|
|
201
135
|
| Candidate | Source | Overlaps | Recommendation |
|
|
202
136
|
| --- | --- | --- | --- |
|
|
203
137
|
| [what it is] | [`#N` / `docs/deferrals.jsonl` / `docs/failures.jsonl` / audit finding id] | [surface / task it touches] | [fold in / keep deferred / needs design decision] |
|
|
204
138
|
|
|
205
|
-
> [!CAUTION]
|
|
206
|
-
> **Candidates, not scope.** Human review only — not runbook tasks, must not expand scope. Fold in only on design scope or explicit human decision → becomes task, leaves list.
|
|
207
|
-
|
|
208
139
|
## Security & Privacy
|
|
209
140
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
- [ ] **
|
|
213
|
-
- [ ] **
|
|
214
|
-
- [ ] **
|
|
215
|
-
- [ ] **
|
|
216
|
-
- [ ] **
|
|
217
|
-
- [ ] **
|
|
218
|
-
- [ ] **Webhook** — signature verified? Secret declared in the env schema?
|
|
219
|
-
- [ ] **New Secret/Env Var** — added to the env schema? Stored in the project's secret manager (e.g. GCP Secret Manager / Vercel env)?
|
|
141
|
+
- [ ] **New API Route** — auth guard (e.g. a `requireMember`-style check); rate limit if auth-adjacent.
|
|
142
|
+
- [ ] **New DB Table/Column** — deny-by-default row / tenant access policy (e.g. RLS); tenant-scoped.
|
|
143
|
+
- [ ] **Role-Gated Mutation** — role checked at the API layer.
|
|
144
|
+
- [ ] **User Input** — schema-validated in the handler (e.g. Zod `parse()`).
|
|
145
|
+
- [ ] **PII** — absent from logs; audit / CDC trigger updated for new monitored columns.
|
|
146
|
+
- [ ] **Redirect URL** — allow-list validated.
|
|
147
|
+
- [ ] **Webhook** — signature verified; secret in the env schema.
|
|
148
|
+
- [ ] **New Secret/Env Var** — in the env schema and the project's secret manager.
|
|
220
149
|
|
|
221
150
|
_If none apply: "None — no new routes, DB writes, secrets, or user input."_
|
|
222
151
|
|
|
223
152
|
## Pre-Flight / Dependencies
|
|
224
153
|
|
|
225
|
-
**CRITICAL:** Check off all core items. Check conditional items only when applicable. Abort if anything required is missing.
|
|
226
|
-
|
|
227
154
|
### Core
|
|
228
155
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
- [ ] **
|
|
232
|
-
- [ ] **
|
|
233
|
-
- [ ] **
|
|
234
|
-
- [ ] **
|
|
235
|
-
- [ ] **
|
|
236
|
-
- [ ] **Testing & Quality:** Ensure testing strategy aligns with `docs/testing.md`.
|
|
237
|
-
- [ ] **Prerequisite Plans:** List `docs/plans/...` plans that must be fully executed and verified before this one.
|
|
156
|
+
- [ ] **Package Management:** packages declared; manifest and lockfile in sync.
|
|
157
|
+
- [ ] **Dependency Versions:** outdated deps and toolchain / stack CLI versions checked.
|
|
158
|
+
- [ ] **Existing-Solution Search (reuse over duplicate):** in-repo, dependency and ecosystem sweeps recorded in `Reuse Inventory`.
|
|
159
|
+
- [ ] **User Context:** file access confirmed; missing user information requested.
|
|
160
|
+
- [ ] **Project Context:** relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows read.
|
|
161
|
+
- [ ] **Testing & Quality:** testing strategy matches `docs/testing.md`.
|
|
162
|
+
- [ ] **Prerequisite Plans:** [plans to finish first, or `None`]
|
|
238
163
|
|
|
239
164
|
### Conditional
|
|
240
165
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
- [ ] **
|
|
244
|
-
- [ ] **
|
|
245
|
-
- [ ] **
|
|
246
|
-
- [ ] **Observability:** New logs / audit tables / traces → align with `docs/observability.md` (e.g. structured logger calls, correlation IDs, CDC / OTel).
|
|
247
|
-
- [ ] **Notifications:** Alerts / toasts → notifications doc via `.agents/docs.md` for tier (e.g. 1=inline, 2=toast, 3=bell).
|
|
166
|
+
- [ ] **Secrets & Env Vars:** secret store and service-account roles checked.
|
|
167
|
+
- [ ] **Schema State:** database state confirmed against `docs/data-schema.md`.
|
|
168
|
+
- [ ] **Architecture & UI:** `docs/architecture.md` topology; `docs/design.md` for UI.
|
|
169
|
+
- [ ] **Observability:** logs, audit tables and traces per `docs/observability.md`.
|
|
170
|
+
- [ ] **Notifications:** alert / toast tier per the notifications doc.
|
|
248
171
|
|
|
249
172
|
### 🔒 Gate 1: Prerequisites Check
|
|
250
173
|
|
|
251
|
-
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all applicable boxes above. **do not stop for user permission.** Proceed to `Data Schema Integration`.
|
|
252
|
-
|
|
253
174
|
- [ ] **Acceptance Scenario confirmed:** Human confirmed `👤 Acceptance Scenario` section (checkbox is `[x]`).
|
|
254
175
|
- [ ] **Breaking Changes confirmed:** Human confirmed `⚠️ Breaking Changes & Naming Review` section (checkbox is `[x]`).
|
|
255
176
|
- [ ] **Open Questions confirmed:** Human confirmed `👤 Open Questions & Assumptions` section (checkbox is `[x]`).
|
|
256
|
-
- [ ] **Security & Privacy checked:**
|
|
257
|
-
- [ ] **Reuse Inventory complete:** every capability has a row with
|
|
258
|
-
- [ ] **Gate 1 - Verified:**
|
|
177
|
+
- [ ] **Security & Privacy checked:** applicable rows verified, or `None` justified.
|
|
178
|
+
- [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision`; every `NEW` cites its reason.
|
|
179
|
+
- [ ] **Gate 1 - Verified:** Core items and applicable Conditional items checked.
|
|
259
180
|
|
|
260
181
|
## Data Schema Integration
|
|
261
182
|
|
|
262
|
-
[
|
|
263
|
-
|
|
264
|
-
**Invariant Conformance:** Multi-store or privileged writes → every mutation path maintains every store a read surface depends on, under a compatible privilege, with the returned error actually checked (never swallowed). If a write can fail on privilege/constraint, the plan says how that failure surfaces — not a silent 200.
|
|
183
|
+
[How this feature uses the existing schema and what changes; initially set to `PENDING`.]
|
|
265
184
|
|
|
266
185
|
### Data Schema Usage
|
|
267
186
|
|
|
268
|
-
[
|
|
187
|
+
[Existing `docs/data-schema.md` tables and fields read (Input) or written (Output). None → `None`; initially set to `PENDING`. e.g.,
|
|
269
188
|
|
|
270
189
|
- **Input (Read):** `users.id`, `items.title`
|
|
271
190
|
- **Output (Write):** `items.status`, `job_audits.log`]
|
|
272
|
-
If no existing fields are used, explicitly state "None".
|
|
273
191
|
|
|
274
192
|
### Data Schema Changes
|
|
275
193
|
|
|
276
|
-
[
|
|
194
|
+
[New tables, new fields, or changed fields to record in `docs/data-schema.md`. None → `None`; initially set to `PENDING`. e.g.,
|
|
277
195
|
|
|
278
196
|
- **ADD:** `items.new_field` (type: text)
|
|
279
197
|
- **MODIFY:** `users.role` (added enum value)]
|
|
280
|
-
If no schema changes are required, explicitly state "None".
|
|
281
198
|
|
|
282
199
|
## Reuse Inventory
|
|
283
200
|
|
|
284
|
-
[One row per capability plan introduces
|
|
201
|
+
[One row per capability the plan introduces; initially set to `PENDING`.]
|
|
285
202
|
|
|
286
203
|
<!-- prettier-ignore -->
|
|
287
|
-
| Capability | Search performed | Existing candidates | Decision | Justification |
|
|
288
|
-
| --- | --- | --- | --- | --- |
|
|
289
|
-
| [what the plan must do] | `grep -rn "..."`; references to `{symbol}`; `docs/capabilities.md`; `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
|
|
290
|
-
| [
|
|
291
|
-
|
|
292
|
-
> [!CAUTION]
|
|
293
|
-
> **Default = `EXTEND`.** `NEW` only allowed for:
|
|
294
|
-
> (a) no candidate — `Search performed` shows the commands establishing absence;
|
|
295
|
-
> (b) extending breaks the candidate's contract or callers — name both;
|
|
296
|
-
> (c) candidate is a `Supersession Inventory` `DELETE` — replacement, not duplicate.
|
|
297
|
-
>
|
|
298
|
-
> never accept cleaner-fresh / messy-existing / close-but-different as a `NEW` reason — messy candidate → extend and clean it, in scope. Empty `Search performed` = UNSEARCHED, not `NEW`-eligible.
|
|
299
|
-
>
|
|
300
|
-
> Each `EXTEND` row must land as `[MODIFY] path/to/existing` in `Architecture & Component Changes` and a task in `Agent Execution Runbook`; each `NEW` row as `[NEW]` carrying the same reason. `[NEW]` with no row = unjustified.
|
|
204
|
+
| Capability | File | Search performed | Existing candidates | Decision | Justification |
|
|
205
|
+
| --- | --- | --- | --- | --- | --- |
|
|
206
|
+
| [what the plan must do] | `path/to/existing` | `grep -rn "..."`; references to `{symbol}`; `docs/capabilities.md`; `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
|
|
207
|
+
| [e.g., item status column] | `supabase/migrations/{timestamp}_add_items_status.sql` | [exact commands / queries run] | None — [what was searched] | NEW | [reason (a)/(b)/(c)] |
|
|
208
|
+
| [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [exact commands / queries run] | None — [what was searched] | NEW | [reason (a)/(b)/(c)] |
|
|
301
209
|
|
|
302
210
|
## Architecture & Component Changes
|
|
303
211
|
|
|
304
|
-
[
|
|
305
|
-
**
|
|
306
|
-
**CRITICAL:** Prefer `[MODIFY]` over `[NEW]`. Every `[NEW]` must trace to a `Reuse Inventory` `NEW` row and carry its reason — no parallel reimplementation. Superseded → `Supersession Inventory` as `DELETE`.
|
|
307
|
-
**CRITICAL:** Frontend/Mobile → adhere to `docs/design.md`.
|
|
308
|
-
**CRITICAL:** Verify `[MODIFY]` files exist (else `[NEW]`). Before changing exported symbol/signature/contract: find callers/importers/schemas/consumers (language-server references when configured + text search), list blast radius.
|
|
309
|
-
**CRITICAL:** Include backend actions for new schema validations (e.g. Zod `schema.parse`).
|
|
310
|
-
**CRITICAL:** NEVER weaken gate to pass: no type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), deleted assertions, empty `catch` / error-swallowing, mocking-away unit under test. Fix root causes; per-file opt-out needs explicit human sign-off.
|
|
311
|
-
**CRITICAL:** Auto-capture (e.g. log drains / CDC) does not replace explicit logging — log edge cases escaping auto-capture with the project's structured logger (e.g. `console.error("[Context] Message", payload)`). See `docs/observability.md` for naming, severity, correlation IDs, label taxonomy.
|
|
212
|
+
[Files grouped by area (DB, API, Backend, Frontend, Cron, Observability), one header each; initially set to `PENDING`.]
|
|
213
|
+
**Ledger rows:** [Backticked `key` of every `docs/decisions.jsonl` / `docs/deferrals.jsonl` row written for this plan, comma-separated. If none, write "None"; initially set to `PENDING`.]
|
|
312
214
|
|
|
313
215
|
### Database Migrations
|
|
314
216
|
|
|
315
|
-
[
|
|
316
|
-
|
|
317
|
-
> [!WARNING]
|
|
318
|
-
> **If adding/removing columns on CDC/audit-monitored tables (e.g. `users` and the other tenant tables your project monitors):**
|
|
319
|
-
>
|
|
320
|
-
> 1. Update the monitored-column allow-list in the schema-assurance test (e.g. a `knownSafeColumns` list).
|
|
321
|
-
> 2. If a column contains PII → update the audit trigger to scrub it.
|
|
322
|
-
> 3. See `docs/data-schema.md` for the full checklist.
|
|
217
|
+
[New tables / columns / access policies (e.g. RLS) and the migration that adds them; initially set to `PENDING`.]
|
|
323
218
|
|
|
324
219
|
### [Component Area 1]
|
|
325
220
|
|
|
@@ -327,13 +222,13 @@ Verify only when applicable.
|
|
|
327
222
|
|
|
328
223
|
#### [MODIFY] `path/to/file.ext`
|
|
329
224
|
|
|
330
|
-
- **Existence Check:** [
|
|
331
|
-
- [
|
|
225
|
+
- **Existence Check:** [file exists]
|
|
226
|
+
- [Logic, schema, or API contract changes.]
|
|
332
227
|
|
|
333
228
|
#### [new] `path/to/file.ext`
|
|
334
229
|
|
|
335
|
-
- **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c)
|
|
336
|
-
- [
|
|
230
|
+
- **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c)]
|
|
231
|
+
- [Purpose, access policies (e.g. RLS), input validation (e.g. Zod), naming.]
|
|
337
232
|
|
|
338
233
|
#### [DELETE] `path/to/file.ext`
|
|
339
234
|
|
|
@@ -341,27 +236,20 @@ Verify only when applicable.
|
|
|
341
236
|
|
|
342
237
|
### Cron Jobs & Scheduled Tasks
|
|
343
238
|
|
|
344
|
-
[
|
|
239
|
+
[Scheduled tasks (e.g. Vercel cron, pg_cron, Inngest). None → `None`; initially set to `PENDING`.]
|
|
345
240
|
|
|
346
241
|
## Supersession Inventory
|
|
347
242
|
|
|
348
|
-
[Existing artifacts the new code replaces
|
|
243
|
+
[Existing artifacts the new code replaces. None → `None`; initially set to `PENDING`.]
|
|
349
244
|
|
|
350
245
|
<!-- prettier-ignore -->
|
|
351
246
|
| Existing artifact | Replaced by | Decision | Justification |
|
|
352
247
|
| --- | --- | --- | --- |
|
|
353
248
|
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
|
|
354
249
|
|
|
355
|
-
> [!CAUTION]
|
|
356
|
-
> **Default = `DELETE`.** `RETAIN-WITH-REASON` only allowed for:
|
|
357
|
-
> (a) external contract — atomic migration impossible (third-party callers, public API);
|
|
358
|
-
> (b) staged rollout with kill-date and follow-up issue link.
|
|
359
|
-
>
|
|
360
|
-
> never accept `@deprecated` and still exported as a resolution. Each `DELETE` row must be mirrored as `[DELETE] path/to/file` in `Architecture & Component Changes` and as a removal task in `Agent Execution Runbook`.
|
|
361
|
-
|
|
362
250
|
## Documentation Updates
|
|
363
251
|
|
|
364
|
-
|
|
252
|
+
[One row per doc this change touches; others via `.agents/docs.md`.]
|
|
365
253
|
|
|
366
254
|
<!-- prettier-ignore -->
|
|
367
255
|
| Doc | Change required |
|
|
@@ -375,8 +263,6 @@ Verify only when applicable.
|
|
|
375
263
|
| `docs/testing.md` | [new test files / patterns] |
|
|
376
264
|
| `docs/observability.md` | [new log names / spans] |
|
|
377
265
|
|
|
378
|
-
_Delete rows with no change; add a row per other affected doc (resolve via `.agents/docs.md`)._
|
|
379
|
-
|
|
380
266
|
## Rollback Strategy
|
|
381
267
|
|
|
382
268
|
<!-- prettier-ignore -->
|
|
@@ -390,92 +276,77 @@ _No DB changes: "Code-only — `git revert` sufficient."_
|
|
|
390
276
|
|
|
391
277
|
## Agent Execution Runbook
|
|
392
278
|
|
|
393
|
-
[Chronological
|
|
394
|
-
|
|
395
|
-
> [!IMPORTANT]
|
|
396
|
-
> **Continuous Execution:** Run runbook autonomously; no user permission at Gates; `[x]` as you go.
|
|
397
|
-
> **Step Isolation:** Finish task (verify + checkbox) before next.
|
|
398
|
-
> **Integration Shape:** may suggest PR / commit / sequencing — advisory, never a gate; one PR for all tasks always OK. Do not specify merge method.
|
|
279
|
+
[Chronological task checklist; initially set to `PENDING`.]
|
|
399
280
|
|
|
400
281
|
**Implementation Tasks (Examples):**
|
|
401
282
|
|
|
402
|
-
|
|
403
|
-
>
|
|
404
|
-
> **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
|
|
405
|
-
>
|
|
406
|
-
> **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
|
|
407
|
-
>
|
|
408
|
-
> **Test first.** Every task MUST include `**Test first:**` after `Done when`. Behaviour change at unit / integration tier → one or more tests, `;`-separated, each `` `{test file}` `` `` `{test name}` `` fails on {assertion} — repo-relative test files, test names as the runner reports them or their last segments, no `;` in assertion text; build sees each fail against stubs before writing the task's code. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}`.
|
|
409
|
-
>
|
|
410
|
-
> **Issue tasks.** Change-shape issue (`.bkit/trackers.md` § Issue shapes) → its `Tasks` lines are the starting runbook; keep each `Done when` / `Test first` (tighten, never weaken); renumber in build order.
|
|
283
|
+
<!-- bkit:group 1 start -->
|
|
411
284
|
|
|
412
|
-
|
|
413
|
-
- [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes]. **Test first:** [e.g., `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on the thrown validation error — stub accepts any status; `packages/api/items.integration.test.ts` `persists the new status` fails on the stored row — stub writes nothing].
|
|
414
|
-
- [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state]. **Test first:** [e.g., n/a — E2E tier only; runs in CI].
|
|
285
|
+
### GROUP 1: [e.g., Item status in the API]
|
|
415
286
|
|
|
416
|
-
|
|
287
|
+
<!-- bkit:task 1 start -->
|
|
417
288
|
|
|
418
|
-
|
|
289
|
+
- [ ] **TASK 1:** [e.g., Create DB migration with the repo's migration script (`pnpm db:diff`)]
|
|
290
|
+
- **CREATE:** `supabase/migrations/{timestamp}_add_items_status.sql`: [e.g., `items.status` column]
|
|
291
|
+
- **DONE WHEN:** [e.g., the migration exists; `pnpm db:reset` replays it cleanly]
|
|
292
|
+
- **TEST FIRST:** n/a — [e.g., migration; fresh-DB replay tier]
|
|
419
293
|
|
|
420
|
-
|
|
421
|
-
- [ ] **Test first:** every task naming `Test first` tests recorded a red per test before its code; tests unchanged since except added tests / formatting.
|
|
422
|
-
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
|
|
294
|
+
<!-- bkit:task 1 end -->
|
|
423
295
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
296
|
+
<!-- bkit:task 2 start -->
|
|
297
|
+
|
|
298
|
+
- [ ] **TASK 2:** [e.g., Implement backend API action `setStatus`]
|
|
299
|
+
- **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g., Zod-validated status change]
|
|
300
|
+
- **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
|
|
301
|
+
- **DEPENDS ON:** 1
|
|
302
|
+
- **DONE WHEN:** [e.g., unit test covers each status transition; integration test passes]
|
|
303
|
+
- **TEST FIRST:**
|
|
304
|
+
- `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
|
|
305
|
+
- `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
|
|
306
|
+
|
|
307
|
+
<!-- bkit:task 2 end -->
|
|
308
|
+
|
|
309
|
+
<!-- bkit:group 1 end -->
|
|
310
|
+
|
|
311
|
+
### 🔒 Gate 2: Code Implementation Check
|
|
312
|
+
|
|
313
|
+
- [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row; every `EXTEND` landed in its named artifact; no gate weakened.
|
|
314
|
+
- [ ] **Every task has a test or a TEST EXCEPTION:** every planned test recorded a red before its code and is unchanged since; test-order gaps cleared only by a human-committed `TEST EXCEPTION` field.
|
|
315
|
+
- [ ] **Gate 2 - Verified:** every box above checked.
|
|
432
316
|
|
|
433
317
|
**Mandatory Tasks (Testing & Documentation):**
|
|
434
318
|
|
|
435
|
-
- [ ] **Verify test coverage against Derived Test Matrix:**
|
|
436
|
-
- [ ] **Sweep existing tests:**
|
|
437
|
-
- [ ] **Sweep new tests:**
|
|
438
|
-
- [ ] **Verify observability:**
|
|
439
|
-
- [ ] **Update documentation:**
|
|
319
|
+
- [ ] **Verify test coverage against Derived Test Matrix:** each row's test sits in one task's `DONE WHEN`.
|
|
320
|
+
- [ ] **Sweep existing tests:** broken tests fixed; full suite green.
|
|
321
|
+
- [ ] **Sweep new tests:** every task's `DONE WHEN` tests exist and pass.
|
|
322
|
+
- [ ] **Verify observability:** errors logged and traced per `docs/observability.md`.
|
|
323
|
+
- [ ] **Update documentation:** affected docs rewritten to match.
|
|
440
324
|
|
|
441
325
|
### 🔒 Gate 3: Testing & Documentation Check
|
|
442
326
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
- [ ] **Docs updated:** Every row in `Documentation Updates` completed. `.agents/docs.md` still accurate.
|
|
446
|
-
- [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
|
|
327
|
+
- [ ] **Docs updated:** every `Documentation Updates` row done; `.agents/docs.md` accurate.
|
|
328
|
+
- [ ] **Gate 3 - Verified:** every box above checked.
|
|
447
329
|
|
|
448
330
|
## Verification Plan
|
|
449
331
|
|
|
450
|
-
> [!IMPORTANT]
|
|
451
|
-
> **Advisory build-phase checks, not merge gates.** Only `Agent Execution Runbook` `Done when` lines gate merge; nothing here does. Do not write "before merge" on untickable boxes — CI/human-only preconditions (lane RUN, deployed state, operator step) unenforceable. Work that MUST block merge → runbook task + codebase-verifiable `Done when`; lane that must run → CI config, not plan prose.
|
|
452
|
-
|
|
453
332
|
### Automated Tests
|
|
454
333
|
|
|
455
|
-
- [ ] **Full Local Gate Suite:**
|
|
456
|
-
- [ ] **Test Synchronization:** [
|
|
457
|
-
- [ ] **Build Configuration:** [
|
|
458
|
-
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [
|
|
459
|
-
- [ ] **Apply local migrations:** New migrations
|
|
460
|
-
- [ ] **Run all tests:** Local unit
|
|
461
|
-
|
|
462
|
-
> [!IMPORTANT]
|
|
463
|
-
> **No Architectural Downgrades:** Build / compiler / test errors during verification → never hot-fix or anti-pattern; follow `docs/architecture.md` + named reference repos. Halt if stuck.
|
|
334
|
+
- [ ] **Full Local Gate Suite:** deepest declared `bkit:gate:*` script and `bkit check` pass.
|
|
335
|
+
- [ ] **Test Synchronization:** [Existing E2E tests (e.g. Playwright) to update alongside.]
|
|
336
|
+
- [ ] **Build Configuration:** [Test-only files kept out of the production build (e.g. `tsconfig.json` `exclude`).]
|
|
337
|
+
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [Flows / unit / E2E additions and data hygiene needs.]
|
|
338
|
+
- [ ] **Apply local migrations:** [New migrations applied locally (e.g. `pnpm db:reset`).]
|
|
339
|
+
- [ ] **Run all tests:** [Local unit and integration suites (e.g. `pnpm test`, `pnpm test:integration`) pass.]
|
|
464
340
|
|
|
465
341
|
### 🔒 Gate 4: Automated Verification Check
|
|
466
342
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
- [ ] **Gate 4 - Verified:** Every checkbox in Automated Tests independently verified and checked off. Explicit proof (test outputs, CLI results, API responses) gathered.
|
|
343
|
+
- [ ] **Gate 4 - Verified:** every Automated Tests box checked, with proof (test output, CLI result, API response).
|
|
470
344
|
|
|
471
345
|
### 👤 Manual Verification
|
|
472
346
|
|
|
473
347
|
> [!CAUTION]
|
|
474
|
-
> **Owner-run acceptance checks — advisory only.**
|
|
475
|
-
|
|
476
|
-
> [!WARNING]
|
|
477
|
-
> **Dashboard Ban:** Proactively use local CLIs (e.g. `gh`, `vercel`, `npx supabase`) to verify CI/CD pipelines instead of asking users to check dashboards.
|
|
348
|
+
> **Owner-run acceptance checks — advisory only.** An unticked box blocks nothing: not the merge, not plan approval. This is not a Gate 1 human-confirmation section.
|
|
478
349
|
|
|
479
|
-
- [ ] **Step 1:** [
|
|
350
|
+
- [ ] **Step 1:** [How to verify the feature end-to-end via CLI / DB.]
|
|
480
351
|
|
|
481
352
|
<!-- bkit:end -->
|