@cbartens/bkit 6.1.0 → 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.
- package/.bkit/README.md +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# --- Tracker guard: identical in the Claude and Cursor preflight hooks (bkit renders it
|
|
2
|
+
# from one source). Uses bash + python3 + curl, and bkit for Jira. Needs `emit_context`,
|
|
3
|
+
# which the host's code above defines in that host's output shape. Dispatches on
|
|
4
|
+
# `bkit.tracker.default` in the repo's package.json. An unset tracker uses Linear only
|
|
5
|
+
# when LINEAR_ISSUE_ID is present. Passes on a readable issue carrying `bkit:auto` that is not finished by
|
|
6
|
+
# the tracker's state category; any unreadable answer is a HARD STOP naming tracker + reason.
|
|
7
|
+
|
|
8
|
+
CURL_LIMITS=(--connect-timeout 5 --max-time 15)
|
|
9
|
+
|
|
10
|
+
# bkit_guard_fail TRACKER ID REASON — HARD STOP naming the tracker and the reason.
|
|
11
|
+
bkit_guard_fail() {
|
|
12
|
+
echo "Guard pre-check: FAIL. ${1} issue ${2}: ${3}" >&2
|
|
13
|
+
emit_context "Guard pre-check: FAIL. ${1} issue ${2}: ${3}. HARD STOP: refuse any ${1}-related work on this issue. Report the failure to the user, then stop."
|
|
14
|
+
exit 1
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
BKIT_GUARD_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
|
18
|
+
BKIT_GUARD_TRACKER=$(ROOT="$BKIT_GUARD_ROOT" python3 -c '
|
|
19
|
+
import json, os
|
|
20
|
+
try:
|
|
21
|
+
with open(os.path.join(os.environ["ROOT"], "package.json")) as f:
|
|
22
|
+
print(((json.load(f).get("bkit") or {}).get("tracker") or {}).get("default") or "none")
|
|
23
|
+
except Exception:
|
|
24
|
+
print("none")
|
|
25
|
+
' 2>/dev/null || echo none)
|
|
26
|
+
|
|
27
|
+
if [[ "$BKIT_GUARD_TRACKER" == "none" ]]; then
|
|
28
|
+
if [[ -n "${LINEAR_ISSUE_ID:-}" ]]; then
|
|
29
|
+
BKIT_GUARD_TRACKER="linear"
|
|
30
|
+
else
|
|
31
|
+
exit 0
|
|
32
|
+
fi
|
|
33
|
+
fi
|
|
34
|
+
|
|
35
|
+
case "$BKIT_GUARD_TRACKER" in
|
|
36
|
+
github)
|
|
37
|
+
# Issue id: GITHUB_ISSUE_ID, else the leading digits of the `feat/{FID}` branch.
|
|
38
|
+
GH_ISSUE="${GITHUB_ISSUE_ID:-}"
|
|
39
|
+
if [[ -z "$GH_ISSUE" ]]; then
|
|
40
|
+
GH_BRANCH=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
|
|
41
|
+
if [[ "$GH_BRANCH" =~ ^feat/([0-9]+) ]]; then GH_ISSUE="${BASH_REMATCH[1]}"; fi
|
|
42
|
+
fi
|
|
43
|
+
if [[ -z "$GH_ISSUE" ]]; then
|
|
44
|
+
emit_context "Guard pre-check: SKIPPED — no issue id; bkit:auto not verified"
|
|
45
|
+
exit 0
|
|
46
|
+
fi
|
|
47
|
+
# The id goes into the API address, so only an issue number is accepted.
|
|
48
|
+
if [[ ! "$GH_ISSUE" =~ ^[0-9]+$ ]]; then
|
|
49
|
+
bkit_guard_fail "GitHub" "(GITHUB_ISSUE_ID)" "GITHUB_ISSUE_ID must be digits only, got \"${GH_ISSUE}\""
|
|
50
|
+
fi
|
|
51
|
+
# BKIT_GH_TOKEN reads the issue over the GitHub REST API.
|
|
52
|
+
if [[ -z "${BKIT_GH_TOKEN:-}" ]]; then
|
|
53
|
+
echo "Guard pre-check: FAIL. BKIT_GH_TOKEN not set, so the GitHub issue cannot be validated." >&2
|
|
54
|
+
emit_context "Guard pre-check: FAIL. BKIT_GH_TOKEN is not set, so bkit cannot check the GitHub issue. HARD STOP: refuse any GitHub-related work. Report the failure to the user, then stop."
|
|
55
|
+
exit 1
|
|
56
|
+
fi
|
|
57
|
+
GH_REMOTE=$(git remote get-url origin 2>/dev/null || true)
|
|
58
|
+
GH_REPO=$(printf '%s' "$GH_REMOTE" | sed -E 's#^(https://([^@/]*@)?|ssh://git@|git@)github\.com[:/]##; s#\.git$##')
|
|
59
|
+
if [[ "$GH_REPO" != */* ]]; then
|
|
60
|
+
bkit_guard_fail "GitHub" "#${GH_ISSUE}" "could not read owner/repo from the origin remote"
|
|
61
|
+
fi
|
|
62
|
+
GH_RESPONSE=$(curl -sS --fail "${CURL_LIMITS[@]}" \
|
|
63
|
+
-H "Authorization: Bearer ${BKIT_GH_TOKEN}" \
|
|
64
|
+
-H "Accept: application/vnd.github+json" \
|
|
65
|
+
"https://api.github.com/repos/${GH_REPO}/issues/${GH_ISSUE}" 2>/dev/null) \
|
|
66
|
+
|| bkit_guard_fail "GitHub" "#${GH_ISSUE}" "the GitHub API request failed (network, auth or not found)"
|
|
67
|
+
IFS=$'\t' read -r ISSUE_STATE LABELS < <(RESPONSE="$GH_RESPONSE" python3 -c '
|
|
68
|
+
import json, os
|
|
69
|
+
try:
|
|
70
|
+
d = json.loads(os.environ["RESPONSE"])
|
|
71
|
+
state = d["state"]
|
|
72
|
+
labels = ",".join((l["name"] if isinstance(l, dict) else str(l)) for l in (d.get("labels") or []))
|
|
73
|
+
print(state + "\t" + (labels if labels else "-"))
|
|
74
|
+
except Exception:
|
|
75
|
+
print("UNKNOWN\t-")
|
|
76
|
+
')
|
|
77
|
+
if [[ "$ISSUE_STATE" == "UNKNOWN" ]]; then
|
|
78
|
+
bkit_guard_fail "GitHub" "#${GH_ISSUE}" "the GitHub API answer could not be read"
|
|
79
|
+
fi
|
|
80
|
+
ISSUE_ID_DISPLAY="#${GH_ISSUE}"
|
|
81
|
+
TRACKER_NAME="GitHub"
|
|
82
|
+
TERMINAL="false"
|
|
83
|
+
[[ "$ISSUE_STATE" == "closed" ]] && TERMINAL="true"
|
|
84
|
+
;;
|
|
85
|
+
linear)
|
|
86
|
+
# BKIT_LINEAR_API_KEY required to call the Linear GraphQL API.
|
|
87
|
+
if [[ -z "${BKIT_LINEAR_API_KEY:-}" ]]; then
|
|
88
|
+
echo "Guard pre-check: FAIL. BKIT_LINEAR_API_KEY not set, so ${LINEAR_ISSUE_ID:-(unset)} cannot be validated." >&2
|
|
89
|
+
emit_context "Guard pre-check: FAIL. BKIT_LINEAR_API_KEY is not set, so bkit cannot check ${LINEAR_ISSUE_ID:-(unset)}. HARD STOP: refuse any Linear-related work. Report the failure to the user, then stop."
|
|
90
|
+
exit 1
|
|
91
|
+
fi
|
|
92
|
+
|
|
93
|
+
# LINEAR_ISSUE_ID required (Claude's trigger above already demands it; a Cursor Cloud
|
|
94
|
+
# Agent sets it from workflow context).
|
|
95
|
+
if [[ -z "${LINEAR_ISSUE_ID:-}" ]]; then
|
|
96
|
+
echo "Guard pre-check: FAIL. LINEAR_ISSUE_ID not set." >&2
|
|
97
|
+
emit_context "Guard pre-check: FAIL. LINEAR_ISSUE_ID is not set. HARD STOP: refuse any Linear-related work. Report the failure to the user, then stop."
|
|
98
|
+
exit 1
|
|
99
|
+
fi
|
|
100
|
+
|
|
101
|
+
# Query Linear for issue state (name + category type) and labels.
|
|
102
|
+
QUERY='query($id: String!) { issue(id: $id) { identifier title state { name type } labels { nodes { name } } } }'
|
|
103
|
+
|
|
104
|
+
BODY=$(LINEAR_ISSUE_ID="$LINEAR_ISSUE_ID" Q="$QUERY" python3 -c '
|
|
105
|
+
import json, os
|
|
106
|
+
print(json.dumps({"query": os.environ["Q"], "variables": {"id": os.environ["LINEAR_ISSUE_ID"]}}))
|
|
107
|
+
')
|
|
108
|
+
|
|
109
|
+
RESPONSE=$(curl -sS "${CURL_LIMITS[@]}" \
|
|
110
|
+
-X POST \
|
|
111
|
+
-H "Content-Type: application/json" \
|
|
112
|
+
-H "Authorization: ${BKIT_LINEAR_API_KEY}" \
|
|
113
|
+
--data "$BODY" \
|
|
114
|
+
"https://api.linear.app/graphql" 2>/dev/null) \
|
|
115
|
+
|| bkit_guard_fail "Linear" "$LINEAR_ISSUE_ID" "the Linear API request failed (could not be reached)"
|
|
116
|
+
|
|
117
|
+
# Parse response: identifier, state name, state type, labels (tab-separated, "-" empty).
|
|
118
|
+
IFS=$'\t' read -r ISSUE_ID_DISPLAY ISSUE_STATE STATE_TYPE LABELS < <(RESPONSE="$RESPONSE" LINEAR_ISSUE_ID="$LINEAR_ISSUE_ID" python3 -c '
|
|
119
|
+
import json, os
|
|
120
|
+
try:
|
|
121
|
+
d = json.loads(os.environ["RESPONSE"])
|
|
122
|
+
except Exception:
|
|
123
|
+
d = {}
|
|
124
|
+
issue = (d.get("data") or {}).get("issue")
|
|
125
|
+
if not issue:
|
|
126
|
+
print(os.environ["LINEAR_ISSUE_ID"] + "\tUNKNOWN\t-\t-")
|
|
127
|
+
else:
|
|
128
|
+
state = issue.get("state") or {}
|
|
129
|
+
labels = ",".join(n["name"] for n in ((issue.get("labels") or {}).get("nodes") or []))
|
|
130
|
+
print("\t".join([issue.get("identifier") or os.environ["LINEAR_ISSUE_ID"], state.get("name") or "-", state.get("type") or "-", labels if labels else "-"]))
|
|
131
|
+
')
|
|
132
|
+
if [[ "$ISSUE_STATE" == "UNKNOWN" ]]; then
|
|
133
|
+
bkit_guard_fail "Linear" "$LINEAR_ISSUE_ID" "the Linear API answer carried no issue"
|
|
134
|
+
fi
|
|
135
|
+
TRACKER_NAME="Linear"
|
|
136
|
+
TERMINAL="false"
|
|
137
|
+
[[ "$STATE_TYPE" == "completed" || "$STATE_TYPE" == "canceled" ]] && TERMINAL="true"
|
|
138
|
+
;;
|
|
139
|
+
jira)
|
|
140
|
+
JIRA_BRANCH=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
|
|
141
|
+
JIRA_ISSUE=""
|
|
142
|
+
if [[ "$JIRA_BRANCH" =~ ^feat/([A-Za-z][A-Za-z0-9]*-[0-9]+)(-|$) ]]; then
|
|
143
|
+
JIRA_ISSUE=$(printf '%s' "${BASH_REMATCH[1]}" | tr '[:lower:]' '[:upper:]')
|
|
144
|
+
fi
|
|
145
|
+
if [[ -z "$JIRA_ISSUE" ]]; then
|
|
146
|
+
emit_context "Guard pre-check: SKIPPED — no issue id; bkit:auto not verified"
|
|
147
|
+
exit 0
|
|
148
|
+
fi
|
|
149
|
+
BKIT_JIRA_BIN="$BKIT_GUARD_ROOT/node_modules/.bin/bkit"
|
|
150
|
+
if [[ ! -x "$BKIT_JIRA_BIN" ]]; then
|
|
151
|
+
bkit_guard_fail "Jira" "$JIRA_ISSUE" "node_modules/.bin/bkit is missing or not executable"
|
|
152
|
+
fi
|
|
153
|
+
BKIT_JIRA_TMPDIR=$(mktemp -d "${TMPDIR:-/tmp}/bkit-guard.XXXXXX") \
|
|
154
|
+
|| bkit_guard_fail "Jira" "$JIRA_ISSUE" "could not create a temporary issue outbox"
|
|
155
|
+
JIRA_FETCH=("$BKIT_JIRA_BIN" issues fetch --issue "$JIRA_ISSUE" --outbox "$BKIT_JIRA_TMPDIR" --json)
|
|
156
|
+
if command -v timeout >/dev/null 2>&1; then
|
|
157
|
+
JIRA_FETCH=(timeout 20 "${JIRA_FETCH[@]}")
|
|
158
|
+
fi
|
|
159
|
+
JIRA_STATUS=0
|
|
160
|
+
JIRA_RESPONSE=$("${JIRA_FETCH[@]}" 2>/dev/null) || JIRA_STATUS=$?
|
|
161
|
+
rm -rf -- "$BKIT_JIRA_TMPDIR"
|
|
162
|
+
if [[ "$JIRA_STATUS" == "124" ]]; then
|
|
163
|
+
bkit_guard_fail "Jira" "$JIRA_ISSUE" "the issue fetch timed out"
|
|
164
|
+
fi
|
|
165
|
+
if [[ "$JIRA_STATUS" != "0" ]]; then
|
|
166
|
+
JIRA_REASON=$(RESPONSE="$JIRA_RESPONSE" python3 -c '
|
|
167
|
+
import json, os
|
|
168
|
+
try:
|
|
169
|
+
reason = json.loads(os.environ["RESPONSE"]).get("reason")
|
|
170
|
+
print(reason if reason in {"auth", "network", "not-found", "unavailable"} else "unreadable reply")
|
|
171
|
+
except Exception:
|
|
172
|
+
print("unreadable reply")
|
|
173
|
+
')
|
|
174
|
+
bkit_guard_fail "Jira" "$JIRA_ISSUE" "the issue fetch failed (exit ${JIRA_STATUS}, ${JIRA_REASON})"
|
|
175
|
+
fi
|
|
176
|
+
IFS=$'\t' read -r ISSUE_STATE TERMINAL LABELS < <(RESPONSE="$JIRA_RESPONSE" python3 -c '
|
|
177
|
+
import json, os
|
|
178
|
+
try:
|
|
179
|
+
d = json.loads(os.environ["RESPONSE"])
|
|
180
|
+
state, terminal, labels = d["state"], d["terminal"], d["labels"]
|
|
181
|
+
if not isinstance(state, str) or not state or not isinstance(terminal, bool) or not isinstance(labels, list) or not all(isinstance(label, str) for label in labels):
|
|
182
|
+
raise ValueError("invalid issue facts")
|
|
183
|
+
print(state + "\t" + str(terminal).lower() + "\t" + (",".join(labels) or "-"))
|
|
184
|
+
except Exception:
|
|
185
|
+
print("UNKNOWN\t-\t-")
|
|
186
|
+
')
|
|
187
|
+
if [[ "$ISSUE_STATE" == "UNKNOWN" ]]; then
|
|
188
|
+
bkit_guard_fail "Jira" "$JIRA_ISSUE" "the issue fetch answer could not be read"
|
|
189
|
+
fi
|
|
190
|
+
ISSUE_ID_DISPLAY="$JIRA_ISSUE"
|
|
191
|
+
TRACKER_NAME="Jira"
|
|
192
|
+
;;
|
|
193
|
+
*)
|
|
194
|
+
echo "Guard pre-check: FAIL. bkit.tracker.default in package.json is \"${BKIT_GUARD_TRACKER}\", not a tracker bkit knows (valid: github, linear, jira, none)." >&2
|
|
195
|
+
emit_context "Guard pre-check: FAIL. bkit.tracker.default in package.json is \"${BKIT_GUARD_TRACKER}\", not a tracker bkit knows (valid: github, linear, jira, none). HARD STOP: refuse any tracker-related work. Report the failure to the user, then stop."
|
|
196
|
+
exit 1
|
|
197
|
+
;;
|
|
198
|
+
esac
|
|
199
|
+
|
|
200
|
+
FAIL_REASON=""
|
|
201
|
+
|
|
202
|
+
# Guard 1: `bkit:auto` label must be present.
|
|
203
|
+
if [[ ",${LABELS}," != *",bkit:auto,"* ]]; then
|
|
204
|
+
FAIL_REASON="bkit:auto label missing (labels: ${LABELS})"
|
|
205
|
+
fi
|
|
206
|
+
|
|
207
|
+
# Guard 2: Issue must not be finished (terminal by state category, never by name).
|
|
208
|
+
if [[ "$TERMINAL" == "true" ]]; then
|
|
209
|
+
FAIL_REASON="the issue is in a terminal state (${ISSUE_STATE})"
|
|
210
|
+
fi
|
|
211
|
+
|
|
212
|
+
if [[ -n "$FAIL_REASON" ]]; then
|
|
213
|
+
echo "Guard pre-check: FAIL. Issue ${ISSUE_ID_DISPLAY}: ${FAIL_REASON}" >&2
|
|
214
|
+
emit_context "Guard pre-check: FAIL. Issue ${ISSUE_ID_DISPLAY}: ${FAIL_REASON}. HARD STOP: refuse any ${TRACKER_NAME}-related work on this issue. Report the failure to the user, then stop."
|
|
215
|
+
exit 1
|
|
216
|
+
fi
|
|
217
|
+
|
|
218
|
+
emit_context "Guard pre-check: PASS | issue: ${ISSUE_ID_DISPLAY} | status: ${ISSUE_STATE} | labels: ${LABELS}"
|
|
219
|
+
exit 0
|
|
@@ -40,7 +40,7 @@ autoCompactWindow: 300000
|
|
|
40
40
|
|
|
41
41
|
**Protocol:** Work through this file exactly as written.
|
|
42
42
|
|
|
43
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
43
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
44
44
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
45
45
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
46
46
|
|
|
@@ -91,7 +91,7 @@ autoCompactWindow: 300000
|
|
|
91
91
|
- **Narrow text search first:** Run `grep -l` / `rg -l` with path and file-type filters first, then `grep -n -m {N}` on the matched files. Do not run a broad recursive grep that returns full match lists.
|
|
92
92
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
93
93
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
94
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
94
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
95
95
|
- **Format:** Write plain, complete sentences that keep their grammar words (articles, plurals), and cut filler, hedges and repetition. Prefer tables to prose, and bullets to paragraphs.
|
|
96
96
|
- **Verify tools:** Verify every return; do not assume success.
|
|
97
97
|
- **Empty is inconclusive:** An empty or zero read never proves absence. Re-run it once on a known hit and corroborate it with an independent call; when the known hit is missing, the read is broken, so report it as unavailable, not as clean. A capped or windowed read is partial: page or chunk to the tool's limit, and record the part not read. False empties: `rg` skips dot-dirs and ignored files → use `--hidden` or `git grep`; `rg` prints only "binary file matches" once it meets a NUL byte → use `-a` on history output; a wildcard `git grep` pathspec like `dir/*/src` matches that path only, not the files under it → end it with `/**`; `git grep -E`, BSD `sed -E` and `awk` have no `\s` → use `[[:space:]]`.
|
|
@@ -129,7 +129,20 @@ autoCompactWindow: 300000
|
|
|
129
129
|
- **If** it exits non-zero → **STOP** and report the reason.
|
|
130
130
|
- NEVER hand-write or edit the `bkit:anchor` block or the `bkit:outdated` line the stamp writes under it.
|
|
131
131
|
3. Read every supplied input once at the start, and work from what it says, not from session memory. Do not re-read the template on every loop iteration.
|
|
132
|
-
4. Read `.agents/docs.md
|
|
132
|
+
4. Read the `.agents/docs.md` index, and load the project documents the audit's surface needs, with or without a plan: `docs/architecture.md` for structure and boundaries, `docs/technology.md` for stack choices, `docs/security.md` for trust boundaries, `docs/testing.md` for test and gate rules, plus `docs/data-schema.md`, `docs/design.md`, `docs/observability.md`, `docs/deployments.md`, `docs/noise.md` or `docs/setup.md` when the audit's surface touches them.
|
|
133
|
+
- Read the recommended path or a valid indexed equivalent (`Equivalent to docs/{topic}.md` in its Scope cell).
|
|
134
|
+
- **If** the index or a document is missing, empty or still the starter → warn and continue from repository evidence; never skip the topic silently. Mark an irrelevant topic not applicable, with the reason.
|
|
135
|
+
- Safeguards that need genuine evidence stay in force (secrets, permissions, untrusted input).
|
|
136
|
+
- Write each gap as one JSON object per line in a fenced `jsonl` block under `## Documentation Warnings`, with the fields `topic`, `gap`, `recommendedPath`, `alternativeEvidence` and `action` (all non-empty; `"None available"` when no alternative evidence exists):
|
|
137
|
+
```jsonl
|
|
138
|
+
{
|
|
139
|
+
"topic": "testing",
|
|
140
|
+
"gap": "missing",
|
|
141
|
+
"recommendedPath": "docs/testing.md",
|
|
142
|
+
"alternativeEvidence": "The CI workflow defines the lanes.",
|
|
143
|
+
"action": "Copy the testing starter and describe the project's tiers and lanes."
|
|
144
|
+
}
|
|
145
|
+
```
|
|
133
146
|
5. Update **Create** — replace each `PENDING` via `Edit` as content becomes available.
|
|
134
147
|
- **If** a section has no content → `None`.
|
|
135
148
|
6. Populate the template sections in template order, without changing the order. Take each section's shape from the template and every rule from this prompt, and verify every gate before you proceed:
|
|
@@ -155,10 +168,14 @@ autoCompactWindow: 300000
|
|
|
155
168
|
- The approach is settled, not broken into tasks → `/bkit-plan`.
|
|
156
169
|
- The change is clear → `/bkit-build`.
|
|
157
170
|
- `Reason` = the deciding fact, in one clause.
|
|
158
|
-
11. Write ledger entries to `docs/failures.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom)
|
|
171
|
+
11. Write ledger entries to `docs/failures.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom).
|
|
172
|
+
- Issue one runless invocation first with `bkit status invocation --standalone=audit --name={slug}` and hold its `invocation`.
|
|
173
|
+
- Pass it as `--invocation` with a fresh `--operation` on each `bkit ledgers append`, and retry a lost response with the same `--operation`; `receipt.replayed: true` means the rows are already on disk.
|
|
174
|
+
- The engine fills `by` and the model fields from the invocation; never write `by` or a model name into a row.
|
|
159
175
|
- **If** the template audits `docs/failures.jsonl` or `docs/deferrals.jsonl` → skip this step.
|
|
160
176
|
- Complete the report first.
|
|
161
|
-
-
|
|
177
|
+
- Serialize the findings once: write the audit result JSON `{slug, status, report, findings: [{severity, title, location, priorKey}], notChecked}` (plus `stopped`, `overview`, `issue`, `parent` when they apply) to a scratch file, then render the summary with `bkit steps stub --agent=bkit-audit-generate --result-file=<json> --to=<Create>`. A report that already exists at `<Create>` is never overwritten: the summary goes to `<json>`'s sibling `.summary.md` (printed as `file`). The engine assigns the finding IDs, the totals and the header, and prints `ledgerRows` for the append below. Leave `priorKey` out for a new problem; the engine derives its `key`.
|
|
178
|
+
- Open rows = the winners of `bkit ledgers query --ledger=failures` (follow `nextCursor` until it is null, then route on `coverage.status`: `missing` = the ledger has no rows, `partial` = use the rows and report the diagnosed lines, `unreadable` = stop and report), `status` != `CLOSED`, covering every `key`, whichever workflow wrote it.
|
|
162
179
|
- Same problem = the same defect at the same `file:line`, test title, or error signature. A finding that only cites an open row's `file:line` is a different problem.
|
|
163
180
|
- For each `MEDIUM`+ finding:
|
|
164
181
|
- **If** an open row names the same problem → reuse its `key`, with the higher of the finding's and the row's `severity`.
|
|
@@ -266,7 +283,7 @@ autoCompactWindow: 300000
|
|
|
266
283
|
|
|
267
284
|
**Report format:**
|
|
268
285
|
|
|
269
|
-
See `docs/templates/bkit-audit-*.md`. An open question the report poses carries lettered
|
|
286
|
+
See `docs/templates/bkit-audit-*.md`. An open question the report poses carries options, one lettered option per line (`A)`, `B)`), and a `Recommended` naming the chosen letter.
|
|
270
287
|
|
|
271
288
|
**Output format:**
|
|
272
289
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bkit-build-challenge-1
|
|
3
3
|
description: Veteran reviewer probing diffs for bugs, edge-case failures, and broken error paths.
|
|
4
|
-
effort:
|
|
4
|
+
effort: xhigh
|
|
5
5
|
model: claude-opus-5-5
|
|
6
6
|
tools:
|
|
7
7
|
- Read
|
|
@@ -21,7 +21,7 @@ autoCompactWindow: 300000
|
|
|
21
21
|
|
|
22
22
|
**Protocol:** Work through this file exactly as written.
|
|
23
23
|
|
|
24
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
24
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
25
25
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
26
26
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
27
27
|
|
|
@@ -42,7 +42,7 @@ autoCompactWindow: 300000
|
|
|
42
42
|
- **Narrow text search first:** Run `grep -l` / `rg -l` with path and file-type filters first, then `grep -n -m {N}` on the matched files. Do not run a broad recursive grep that returns full match lists.
|
|
43
43
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
44
44
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
45
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
45
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
46
46
|
- **Verify tools:** Verify every return; do not assume success.
|
|
47
47
|
- **Commits:** Commit early and often, without asking for confirmation; subagents do not commit. Assume other agents are editing the same working tree in parallel, so commit only the files you touched, named explicitly (`git commit -- {paths}`), and never whatever is already staged. Use `git add -A` / `git add .` / `git commit -a` only when the whole tree is your task; otherwise add your own paths by name. **If** a file you touched also carries another agent's edits → **STOP** and ask. Do not stage `.DS_Store`, `*.log`, editor swaps or dependency / build dirs (e.g. `node_modules/`).
|
|
48
48
|
- **Pushes:** ALWAYS ask before a push; one approval covers that one push, not later ones. Before asking, show `git log origin/{branch}..HEAD`. Exception: `/bkit-*` workflow steps that mandate a push (Orchestrator Rules).
|
|
@@ -55,7 +55,7 @@ autoCompactWindow: 300000
|
|
|
55
55
|
|
|
56
56
|
1. Write the **Create** output stub, with `PENDING` in every placeholder.
|
|
57
57
|
2. Read every supplied input once at the start, and work from what it says, not from session memory.
|
|
58
|
-
3. Read `.agents/docs.md`, and load the docs it lists for this task.
|
|
58
|
+
3. Read `.agents/docs.md`, and load the docs it lists for this task, also `docs/architecture.md` and `docs/security.md` when they are present (warn and continue if any is missing). If the index or a listed doc is missing, empty or still the starter, warn and continue; never skip it silently.
|
|
59
59
|
4. Update **Create** after each finding: append the entry at EOF with Bash `echo {log entry} >> {output}`.
|
|
60
60
|
- **If** the entry spans several lines → append it with a heredoc instead.
|
|
61
61
|
- **If** any finding is `CRITICAL` → set `Verdict` = `FAIL` with `Edit` immediately, without waiting for the final pass.
|
|
@@ -87,6 +87,7 @@ autoCompactWindow: 300000
|
|
|
87
87
|
- `class: architectural` = a redesign, such as a wrong layer or abstraction, an expansion of scope, a multi-step write that is not atomic, a broken design principle, or work that needs the plan or design redone → `fixable: false`. Its `done when` names why no agent can settle it and the decision the owner must make.
|
|
88
88
|
8. Cross-reference each finding against the relevant docs that `.agents/docs.md` lists.
|
|
89
89
|
9. Set `Failures` in **Create** with `Edit` = the number of `CRITICAL` findings, counting only complete ones.
|
|
90
|
+
- **If** your Context names a structured result file (`Result:`) → write it as one JSON object with only these keys: `findings` (array; each item has `severity` (`CRITICAL`, `HIGH`, `MEDIUM` or `LOW`), boolean `fixable`, `location` (`path:line`) and `doneWhen`, plus optional `title`, `cls` and `tests`), `judgments` (object of header-field name to text, number or boolean; it holds `Verdict` and each header field the engine does not derive, never `Failures` or `Fixable`), `body` (the report text below the header, written in full: Scope, Notes and every section of your Output format except the generated Findings Log; omit it and the report keeps nothing but the header) and `evidenceComplete` (always `true` or `false`; `false` when you could not check everything). The engine sets `Failures` to the number of entries in `findings`, of every severity, in place of any other count in your steps, so list there only items that need a fix and keep the rest in `body`. A missing or invalid result file makes `bkit steps stub` exit 6 and sends the step to its Failure Path, so write the file before you finish; the caller deletes any older file at that path before it launches you, so a file there is always yours. If you cannot write it, say so in your final reply and do not leave the step to fail silently. The caller renders **Create** with `bkit steps stub --agent=bkit-build-challenge-1 --result-file`, and the engine derives `Failures` and the header `Fingerprint`, so write neither by hand.
|
|
90
91
|
10. Set `Verdict` in **Create** with `Edit`:
|
|
91
92
|
- `PASS` = no findings.
|
|
92
93
|
- `CONCERNS` = findings present, max `severity` <= `HIGH`.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bkit-build-challenge-2
|
|
3
3
|
description: Veteran security researcher probing diffs for auth holes, exploits and data exposure.
|
|
4
|
-
effort:
|
|
4
|
+
effort: xhigh
|
|
5
5
|
model: claude-opus-5-5
|
|
6
6
|
tools:
|
|
7
7
|
- Read
|
|
@@ -21,7 +21,7 @@ autoCompactWindow: 300000
|
|
|
21
21
|
|
|
22
22
|
**Protocol:** Work through this file exactly as written.
|
|
23
23
|
|
|
24
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
24
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
25
25
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
26
26
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
27
27
|
|
|
@@ -42,7 +42,7 @@ autoCompactWindow: 300000
|
|
|
42
42
|
- **Narrow text search first:** Run `grep -l` / `rg -l` with path and file-type filters first, then `grep -n -m {N}` on the matched files. Do not run a broad recursive grep that returns full match lists.
|
|
43
43
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
44
44
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
45
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
45
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
46
46
|
- **Verify tools:** Verify every return; do not assume success.
|
|
47
47
|
- **Commits:** Commit early and often, without asking for confirmation; subagents do not commit. Assume other agents are editing the same working tree in parallel, so commit only the files you touched, named explicitly (`git commit -- {paths}`), and never whatever is already staged. Use `git add -A` / `git add .` / `git commit -a` only when the whole tree is your task; otherwise add your own paths by name. **If** a file you touched also carries another agent's edits → **STOP** and ask. Do not stage `.DS_Store`, `*.log`, editor swaps or dependency / build dirs (e.g. `node_modules/`).
|
|
48
48
|
- **Secrets:** NEVER stage `.env*`, credentials, tokens or API keys. Review `git status` before every commit.
|
|
@@ -59,7 +59,7 @@ autoCompactWindow: 300000
|
|
|
59
59
|
|
|
60
60
|
1. Write the **Create** output stub, with `PENDING` in every placeholder.
|
|
61
61
|
2. Read every supplied input once at the start, and work from what it says, not from session memory.
|
|
62
|
-
3. Read `.agents/docs.md`, and load the docs it lists for this task,
|
|
62
|
+
3. Read `.agents/docs.md`, and load the docs it lists for this task, also `docs/security.md` when it is present (warn and continue if it is missing). If the index or a listed doc is missing, empty or still the starter, warn and continue; never skip it silently.
|
|
63
63
|
4. Update **Create** after each finding: append the entry at EOF with Bash `echo {log entry} >> {output}`.
|
|
64
64
|
- **If** the entry spans several lines → append it with a heredoc instead.
|
|
65
65
|
- **If** any finding is `CRITICAL` → set `Verdict` = `FAIL` with `Edit` immediately, without waiting for the final pass.
|
|
@@ -92,8 +92,9 @@ autoCompactWindow: 300000
|
|
|
92
92
|
- A finding with an empty field does not count toward `Failures`.
|
|
93
93
|
- `class: mechanical` = a surgical edit with no redesign, such as a missing soft-delete filter, auth check, input validator or redaction, or a hardcoded secret to move into an env var → `fixable: true`.
|
|
94
94
|
- `class: architectural` = a redesign, such as a wrong auth model, a tenancy boundary in the wrong layer, a data-access policy broken by design, or work that needs the plan or design redone → `fixable: false`. Its `done when` names why no agent can settle it and the decision the owner must make.
|
|
95
|
-
8. Cross-reference each finding against the relevant docs that `.agents/docs.md` lists,
|
|
95
|
+
8. Cross-reference each finding against the relevant docs that `.agents/docs.md` lists, including `docs/security.md` when it is present (warn and continue if it is missing).
|
|
96
96
|
9. Set `Failures` in **Create** with `Edit` = the number of `CRITICAL` findings, counting only complete ones.
|
|
97
|
+
- **If** your Context names a structured result file (`Result:`) → write it as one JSON object with only these keys: `findings` (array; each item has `severity` (`CRITICAL`, `HIGH`, `MEDIUM` or `LOW`), boolean `fixable`, `location` (`path:line`) and `doneWhen`, plus optional `title`, `cls` and `tests`), `judgments` (object of header-field name to text, number or boolean; it holds `Verdict` and each header field the engine does not derive, never `Failures` or `Fixable`), `body` (the report text below the header, written in full: Scope, Notes and every section of your Output format except the generated Findings Log; omit it and the report keeps nothing but the header) and `evidenceComplete` (always `true` or `false`; `false` when you could not check everything). The engine sets `Failures` to the number of entries in `findings`, of every severity, in place of any other count in your steps, so list there only items that need a fix and keep the rest in `body`. A missing or invalid result file makes `bkit steps stub` exit 6 and sends the step to its Failure Path, so write the file before you finish; the caller deletes any older file at that path before it launches you, so a file there is always yours. If you cannot write it, say so in your final reply and do not leave the step to fail silently. The caller renders **Create** with `bkit steps stub --agent=bkit-build-challenge-2 --result-file`, and the engine derives `Failures` and the header `Fingerprint`, so write neither by hand.
|
|
97
98
|
10. Set `Verdict` in **Create** with `Edit`:
|
|
98
99
|
- `PASS` = no findings.
|
|
99
100
|
- `CONCERNS` = findings present, max `severity` <= `HIGH`.
|
|
@@ -19,7 +19,7 @@ autoCompactWindow: 300000
|
|
|
19
19
|
|
|
20
20
|
**Protocol:** Work through this file exactly as written.
|
|
21
21
|
|
|
22
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
22
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
23
23
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
24
24
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
25
25
|
|
|
@@ -49,7 +49,7 @@ autoCompactWindow: 300000
|
|
|
49
49
|
**Process:**
|
|
50
50
|
|
|
51
51
|
1. Read every supplied input once at the start, and work from what it says, not from session memory.
|
|
52
|
-
2. Read `.agents/docs.md`, and load the docs it lists for this task.
|
|
52
|
+
2. Read `.agents/docs.md`, and load the docs it lists for this task. If the index or a listed doc is missing, empty or still the starter, warn and continue; never skip it silently.
|
|
53
53
|
3. Identify the technologies that the feature requires.
|
|
54
54
|
4. List the folder names under `.agents/skills/`, without reading the folders' contents. Each folder name is the identity of one installed skill when you look for gaps.
|
|
55
55
|
5. Identify each skill gap: a required technology that no folder name matches.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bkit-build-plan-convert
|
|
3
3
|
description: Senior engineer turning an issue or a free-form plan into a plan in task-block form.
|
|
4
|
-
effort:
|
|
4
|
+
effort: high
|
|
5
5
|
model: claude-sonnet-5-5
|
|
6
6
|
tools:
|
|
7
7
|
- Read
|
|
@@ -21,7 +21,7 @@ autoCompactWindow: 300000
|
|
|
21
21
|
|
|
22
22
|
**Protocol:** Work through this file exactly as written.
|
|
23
23
|
|
|
24
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
24
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
25
25
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
26
26
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
27
27
|
|
|
@@ -33,9 +33,9 @@ autoCompactWindow: 300000
|
|
|
33
33
|
- **Input dates:** Where two sections of the `*-input-*.md` file disagree, the newer one wins; older text still counts wherever nothing newer contradicts it.
|
|
34
34
|
- **Same scope:** Every task traces to the input file or the existing plan. Add no work that they do not ask for, and drop no work that they do ask for.
|
|
35
35
|
- **No anchor authoring:** Do not write a `<!-- bkit:anchor` block; keep an existing one byte-for-byte.
|
|
36
|
-
- **Matrix shape:** The plan's `Derived Test Matrix` has
|
|
36
|
+
- **Matrix shape:** The plan's `Derived Test Matrix` has exactly the header `Test description | Type | Target file | Task`, in that order, with no extra columns. Each `Task` cell in it names the one runbook task that lands that row's test.
|
|
37
37
|
- **Runbook tasks:** The runbook is groups of task blocks in build order (schema, then API, then UI). A group is `<!-- bkit:group N start -->`, `### TASK GROUP N: {title}`, its task blocks and `<!-- bkit:group N end -->`, holding tasks and `TEST FIRST` tests within the per-group plan caps your Context names (`bkit.workflows.tasks`: tasks, and `TEST FIRST` tests in all); bigger → split the group. A task is `<!-- bkit:task N start -->`, `- [ ] **TASK N:** {title}`, one sub-bullet per field and `<!-- bkit:task N end -->`, its number unique across the plan. Fields, uppercase: `**CREATE:**` / `**READ:**` / `**UPDATE:**` / `**DELETE:**` (`` `{symbol}` in `{file}`: {what} `` or `` `{file}`: {what} ``, one line per reference), `**DEPENDS ON:**` (task numbers, same or earlier group), `**DONE WHEN:**`, `**TEST FIRST:**`, `**TEST EXCEPTION:**`; `bkit tests plan-check` refuses task-like text outside every block. `DONE WHEN` is short, testable and checkable in the codebase (a file exists, a signature matches, a test passes, a behaviour shows). A task that adds or changes logic names its own tests and fixes the tests it breaks; no task leaves its tests to a later one. Behaviour tests come only from `Derived Test Matrix` rows, and a task crossing a boundary (DB, API, model, network, migration) pairs them with non-mock tests. An audit plan has one task per in-scope finding id; tasks group findings only on one shared root cause and still name every id.
|
|
38
|
-
- **TEST FIRST:** Each task carries a `**TEST FIRST:**` field after `DONE WHEN`. A behaviour change at the unit or integration tier lists one or more tests, within the per-task plan caps your Context names (tests, test files), one sub-bullet per test, each `` `{test file}` `` `` `{test name}` `` fails on {what goes wrong}: a repo-relative test file, the test name as the runner reports it or its last segments, and {what goes wrong} as the wrong behaviour a stub shows, not a literal assertion. When the planned failure prints a phrase no other failure would, put that phrase in double quotes inside {what goes wrong}, e.g. fails on the total "expected 12" being 0: `tests red` refuses a red whose failure message and failure text hold none of the quoted phrases. More tests or files → split the task. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}` on the field line. A regenerated baseline (a snapshot, a coverage list, a generated doc) is never a `TEST FIRST` test: regenerating it makes it pass, so it cannot fail first.
|
|
38
|
+
- **TEST FIRST:** Each task carries a `**TEST FIRST:**` field after `DONE WHEN`. A behaviour change at the unit or integration tier lists one or more tests, within the per-task plan caps your Context names (tests, test files), one sub-bullet per test, each `` `{test file}` `` `` `{test name}` `` fails on {what goes wrong}: a repo-relative test file, the test name as the runner reports it or its last segments, and {what goes wrong} as the wrong behaviour a stub shows, not a literal assertion. When the planned failure prints a phrase no other failure would, put that phrase in double quotes inside {what goes wrong}, e.g. fails on the total "expected 12" being 0: `tests red` refuses a red whose failure message and failure text hold none of the quoted phrases. More tests or files → split the task. When a later task changes what an earlier task's planned test asserts, name that test on the later task's `TEST FIRST` too: the build records it failing again before the later task's code exists. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}` on the field line. A regenerated baseline (a snapshot, a coverage list, a generated doc) is never a `TEST FIRST` test: regenerating it makes it pass, so it cannot fail first.
|
|
39
39
|
- **TEST EXCEPTION:** Only the owner writes a `**TEST EXCEPTION:**` field, or the build orchestrator after the owner approves it. NEVER write one on your own judgement. It sits inside the task's block, with entries in `TEST FIRST` form each ending `— {reason}`.
|
|
40
40
|
- **Issue tasks:** A change-shape issue's `Tasks` blocks (`.bkit/trackers.md` § Issue shapes) seed the runbook. Each keeps its `DONE WHEN` and `TEST FIRST`, tightened and never weakened, and is renumbered in build order. An issue's `TEST EXCEPTION` is a request: copy it into its task word for word, and NEVER write one of your own.
|
|
41
41
|
- **Reuse Inventory:** Each capability the plan introduces has a `Reuse Inventory` row, written before `Architecture & Component Changes`, recording the searches run (in-repo text and symbol search, framework built-ins, current practice) and a decision. The default is `EXTEND`: a `[MODIFY]` of the named file plus a runbook task. `NEW` needs one reason: (a) the searches find no candidate, (b) extending breaks the candidate's contract or callers, both named, or (c) the candidate is a `Supersession Inventory` `DELETE`. A cleaner fresh start or a messy or close-but-different candidate is no reason, and a row with no search is unsearched, not `NEW`. Each `[NEW]` file carries its row's reason. Each row names the file it decides in `File`, and each task `CREATE` file needs a `NEW` row naming it.
|
|
@@ -50,7 +50,7 @@ autoCompactWindow: 300000
|
|
|
50
50
|
- **Narrow text search first:** Run `grep -l` / `rg -l` with path and file-type filters first, then `grep -n -m {N}` on the matched files. Do not run a broad recursive grep that returns full match lists.
|
|
51
51
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
52
52
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
53
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
53
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
54
54
|
- **Verify tools:** Verify every return; do not assume success.
|
|
55
55
|
- **Commits:** Commit early and often, without asking for confirmation; subagents do not commit. Assume other agents are editing the same working tree in parallel, so commit only the files you touched, named explicitly (`git commit -- {paths}`), and never whatever is already staged. Use `git add -A` / `git add .` / `git commit -a` only when the whole tree is your task; otherwise add your own paths by name. **If** a file you touched also carries another agent's edits → **STOP** and ask. Do not stage `.DS_Store`, `*.log`, editor swaps or dependency / build dirs (e.g. `node_modules/`).
|
|
56
56
|
- **Destructive git:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git stash clear`, `git push --force` (any flavour). In-progress rebase resolution (`git checkout --theirs|--ours {conflicted}`, `git rebase --continue` / `--abort`) is not covered.
|
|
@@ -62,10 +62,24 @@ autoCompactWindow: 300000
|
|
|
62
62
|
**Process:**
|
|
63
63
|
|
|
64
64
|
1. Read every supplied input once at the start, and work from what it says, not from session memory.
|
|
65
|
+
- Read the `.agents/docs.md` index, and consult the project documents the converted tasks need: always assess `docs/architecture.md`, `docs/technology.md`, `docs/security.md` and `docs/testing.md`; add `docs/data-schema.md` when a task changes the database, `docs/design.md` for UI work, `docs/observability.md` for logging, `docs/deployments.md` for release or CI work, and `docs/noise.md` or `docs/setup.md` when a task touches them.
|
|
66
|
+
- Read the recommended path or a valid indexed equivalent (`Equivalent to docs/{topic}.md` in its Scope cell).
|
|
67
|
+
- **If** the index or a document is missing, empty or still the starter → warn and continue from repository evidence; never skip the topic silently. Mark an irrelevant topic not applicable, with the reason.
|
|
68
|
+
- Record each topic, the path and section used, coverage, gap and action in the plan's `Documentation Consultation`, and put each `READ` / `UPDATE` line for these documents in the task that needs it.
|
|
69
|
+
- Write each gap as one JSON object per line in a fenced `jsonl` block under `## Documentation Warnings`, with the fields `topic`, `gap`, `recommendedPath`, `alternativeEvidence` and `action` (all non-empty; `"None available"` when no alternative evidence exists):
|
|
70
|
+
```jsonl
|
|
71
|
+
{
|
|
72
|
+
"topic": "security",
|
|
73
|
+
"gap": "starter-only",
|
|
74
|
+
"recommendedPath": "docs/security.md",
|
|
75
|
+
"alternativeEvidence": "The CI configuration defines token permissions.",
|
|
76
|
+
"action": "Populate the security document with the project's credential and permission boundaries."
|
|
77
|
+
}
|
|
78
|
+
```
|
|
65
79
|
2. Read `docs/templates/bkit-plan.md` § `Agent Execution Runbook` for the shape of a group and of a task block. The rules for filling them are the **Runbook tasks**, **TEST FIRST** and **TEST EXCEPTION** clauses above.
|
|
66
80
|
3. Set up the plan file:
|
|
67
|
-
- **If** the plan file exists → keep every section except `Agent Execution Runbook` as written, and rewrite the runbook.
|
|
68
|
-
- **Else** → create the plan with `# {title} Implementation Plan`, `## Context & Goals` (the goal in 1-3 lines), `## Reuse Inventory` and `## Agent Execution Runbook`.
|
|
81
|
+
- **If** the plan file exists → keep every section except `Agent Execution Runbook` as written (add or refresh `Documentation Consultation` and `Documentation Warnings` from step 1), and rewrite the runbook.
|
|
82
|
+
- **Else** → create the plan with `# {title} Implementation Plan`, `## Context & Goals` (the goal in 1-3 lines), `## Documentation Consultation`, `## Documentation Warnings`, `## Reuse Inventory` and `## Agent Execution Runbook`.
|
|
69
83
|
- In both cases, carry over every end state and test that the inputs name, in their order. You may tighten them, but never weaken them.
|
|
70
84
|
4. Split the work into tasks, each one a testable change, and group the tasks in build order:
|
|
71
85
|
- Keep each group within the per-group plan caps that your Context names (`bkit.workflows.tasks`: tasks, and `TEST FIRST` tests in all).
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bkit-build-plan-current
|
|
3
3
|
description: Senior reviewer judging whether changes landed since the plan was written leave it executable.
|
|
4
|
-
effort:
|
|
4
|
+
effort: xhigh
|
|
5
5
|
model: claude-opus-5-5
|
|
6
6
|
tools:
|
|
7
7
|
- Read
|
|
@@ -21,7 +21,7 @@ autoCompactWindow: 300000
|
|
|
21
21
|
|
|
22
22
|
**Protocol:** Work through this file exactly as written.
|
|
23
23
|
|
|
24
|
-
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules
|
|
24
|
+
- **Rules file:** Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.
|
|
25
25
|
- **Order:** Execute steps sequentially unless stated otherwise.
|
|
26
26
|
- **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
|
|
27
27
|
|
|
@@ -41,7 +41,7 @@ autoCompactWindow: 300000
|
|
|
41
41
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
42
42
|
- **Command output:** Request structured, bounded output from CLIs, APIs and SQL (`--json` plus limit flags, SQL `LIMIT`, `jq` field selection), and filter at the source (time window, environment, issue ID). Do not re-run a fetch whose output is already in context.
|
|
43
43
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
44
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
44
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
45
45
|
- **Verify tools:** Verify every return; do not assume success.
|
|
46
46
|
- **Commits:** Commit early and often, without asking for confirmation; subagents do not commit. Assume other agents are editing the same working tree in parallel, so commit only the files you touched, named explicitly (`git commit -- {paths}`), and never whatever is already staged. Use `git add -A` / `git add .` / `git commit -a` only when the whole tree is your task; otherwise add your own paths by name. **If** a file you touched also carries another agent's edits → **STOP** and ask. Do not stage `.DS_Store`, `*.log`, editor swaps or dependency / build dirs (e.g. `node_modules/`).
|
|
47
47
|
- **Pushes:** ALWAYS ask before a push; one approval covers that one push, not later ones. Before asking, show `git log origin/{branch}..HEAD`. Exception: `/bkit-*` workflow steps that mandate a push (Orchestrator Rules).
|
|
@@ -54,7 +54,7 @@ autoCompactWindow: 300000
|
|
|
54
54
|
|
|
55
55
|
1. Write the **Create** output stub, with `PENDING` in every placeholder.
|
|
56
56
|
2. Read every supplied input once at the start, and work from what it says, not from session memory.
|
|
57
|
-
3. Read `.agents/docs.md`, and load the docs it lists for this task.
|
|
57
|
+
3. Read `.agents/docs.md`, and load the docs it lists for this task. If the index or a listed doc is missing, empty or still the starter, warn and continue; never skip it silently.
|
|
58
58
|
4. Update **Create** after each affected task: append the entry at EOF with Bash `echo {log entry} >> {output}`.
|
|
59
59
|
- **If** the entry spans several lines → append it with a heredoc instead.
|
|
60
60
|
- **If** any task `Broken` → set `Verdict` = `FAIL` with `Edit` immediately, without waiting for the final pass.
|
|
@@ -76,6 +76,7 @@ autoCompactWindow: 300000
|
|
|
76
76
|
A finding that lacks any of the four fields does not count toward `Affected`.
|
|
77
77
|
|
|
78
78
|
10. Set `Affected` in **Create** with `Edit` to the number of `Reword` plus `Broken` findings. Count only complete findings.
|
|
79
|
+
- `bkit steps finish` derives the attempt number and records `Strategy` and the summed `Failures` on the step's row. Write no attempt number, timestamp, invocation id or model name into the artifact.
|
|
79
80
|
11. Set `Verdict` in **Create** with `Edit`:
|
|
80
81
|
- `PASS` = no task is affected.
|
|
81
82
|
- `CONCERNS` = at least one task is `Reword`, and none is `Broken`.
|