@warren-dean/code-kit 0.32.0 → 0.33.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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +6 -0
- package/README.md +17 -1
- package/bin/code-kit.mjs +60 -1
- package/hooks/guard-bash.mjs +48 -4
- package/hooks/lib/config.mjs +43 -2
- package/hooks/lib/costs.mjs +217 -0
- package/hooks/lib/instructions.mjs +4 -0
- package/hooks/lib/next.mjs +39 -0
- package/hooks/lib/shell.mjs +39 -1
- package/hooks/lib/verify.mjs +28 -1
- package/package.json +1 -1
- package/skills/decide/SKILL.md +1 -1
- package/skills/init/SKILL.md +2 -0
- package/skills/review/SKILL.md +1 -0
- package/skills/spec-design/SKILL.md +3 -0
- package/templates/agent.md +1 -0
- package/templates/claude-md.md +2 -0
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"name": "code-kit",
|
|
10
10
|
"source": "./",
|
|
11
11
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
12
|
-
"version": "0.
|
|
12
|
+
"version": "0.33.0",
|
|
13
13
|
"category": "development",
|
|
14
14
|
"tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
|
|
15
15
|
"license": "MIT"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.33.0",
|
|
4
4
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Warren Langeveldt"
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
|
|
4
4
|
|
|
5
|
+
## 0.33.0 (2026-11-06)
|
|
6
|
+
|
|
7
|
+
- **A running budget.** Projects were being designed on each provider's production defaults, with nothing adding up what they'd cost a month. spec-design now asks how much a month each environment may cost, in your currency, and the load to plan for; init writes it to `cost` in the config, with the project's infrastructure files. spec-design costs each architecture it proposes against it and, when your preferred one doesn't fit, offers options that do, each with what it gives up. The costs go in `docs/costs.md`, a row per paid thing with where its price came from, and `code-kit cost` adds them up against the budget. A branch that changes the infrastructure has to change the register (verify), lanes may write it, and a commit that takes an environment past its budget waits for your `cost` approval, which the lead can't give, under vibe either. `next` asks a project with infrastructure and no budget for one. It works for any provider: code-kit holds no prices, and the lead cites where each came from. Reading real spend from an account comes later.
|
|
8
|
+
- **A branch made where the checkout stands, then a commit.** `git checkout -b <branch> main && git add … && git commit …`, run with the checkout already at main, was refused as a command that may write files the commit can't see, because the branch named a start point. A start point that is the commit the checkout is at changes no file, so it now passes like a branch made with no start point. One at any other commit is still refused.
|
|
9
|
+
- **Reverting a commit that logged approvals.** A `git revert` of a merge, or of any commit that appended to `.claude/approval-log.jsonl`, takes those entries back out with the rest, so verify failed the branch as an edited log, and no shell command was allowed to put the log back: the only way out was to make the branch again by hand. A command that doesn't commit may now put the log back as the last commit has it (`git restore --staged --worktree .claude/approval-log.jsonl`, or `git checkout HEAD -- …`), which can lose only what isn't committed. Verify's problem now says what took the entries out and how to make the revert again: `git revert --no-commit <commit>`, then that restore, then commit. A restore from any other commit, or in the same command as a commit, is still refused, since the commit hook appends before the command runs.
|
|
10
|
+
|
|
5
11
|
## 0.32.0 (2026-11-06)
|
|
6
12
|
|
|
7
13
|
- **Writes outside the checkout before a commit.** Drafting a commit message in a scratchpad and committing it in one command (`git log -1 --format=%B > /tmp/msg && sed -i '' 's/…/…/' /tmp/msg && git commit --amend -F /tmp/msg`) was refused as a command that may write files the commit can't see. A read whose output goes only to full paths outside the project and the commit's checkout, and sed's substitutions on such files in place, can't change what's committed, so they're allowed. A path from a variable, a link back into the project, a sed that writes a file or runs a command, and any write into the checkout are still refused.
|
package/README.md
CHANGED
|
@@ -52,7 +52,8 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
|
|
|
52
52
|
|
|
53
53
|
- **Lanes:** each lane agent writes only its own paths. The main session (the lead) writes contracts, specs and config, and delegates the rest. Any other subagent is read-only. An edit outside those paths is refused before it happens; a file a shell command writes outside them is reported straight after, for the agent to revert, and the finish check refuses to finish until it's gone.
|
|
54
54
|
- **Layers:** each layer depends only on the layers it lists, and never on packages it's denied, for JavaScript and TypeScript imports. An edit that would add a violation is refused before it's written; the rules are checked again after each edit and before finishing, which is what catches a file a shell command wrote. In brownfield code, existing violations can be recorded in a baseline so only new ones block. Imports are found by pattern, not by parsing: see [the limits](#what-verify-proves-and-its-limits).
|
|
55
|
-
- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Only the lead writes these paths without an approval, and the person reviews them in the pull request. A lane needs an approval: the lead's for what `approvals.delegate` gives it, otherwise the person's.
|
|
55
|
+
- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Nobody edits the log: a shell command may only read it, or put it back as the last commit has it (`git restore --staged --worktree .claude/approval-log.jsonl`, in a command that doesn't commit), as after a `git revert --no-commit` took a reverted commit's entries out. Only the lead writes these paths without an approval, and the person reviews them in the pull request. A lane needs an approval: the lead's for what `approvals.delegate` gives it, otherwise the person's.
|
|
56
|
+
- **A running budget** (spec 29): the person sets how much a month each environment may cost, and `docs/costs.md` estimates each paid thing against it. A commit that takes an environment past its budget waits for the person's `cost` approval, whatever is delegated; before asking, the lead finds options that fit.
|
|
56
57
|
- **Spec-check before code:** when the project has specs, a lane can't write code on a branch until it has saved a spec-check report for that branch. The hook checks that the report exists; review checks what it says.
|
|
57
58
|
- **Designs before screens** (optional): a screen file can't be written until the design register holds its approved design as files, every state exported from the design tool; the review records its screenshot of each built state beside the design, and verify checks it did.
|
|
58
59
|
- **Shell rules**, matched against the command's text before it runs:
|
|
@@ -75,6 +76,7 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
|
|
|
75
76
|
- no screens without an approved design;
|
|
76
77
|
- no secret files (`.env`, `secrets/`, keys and keystores) anywhere in the branch's history, including ones committed and deleted again, and, where gitleaks is installed, no secrets in any commit's content;
|
|
77
78
|
- no test weakened (deleted, skipped or focused, cut down, or its snapshot rewritten) without the person's `tests` approval in the log;
|
|
79
|
+
- with a running budget, a branch that changes the infrastructure files changes the cost register too, and one that takes an environment past its budget has the person's `cost` approval in the log;
|
|
78
80
|
- a fix (a plan story with `**Fixes:**`, or a `<lane>/fix-…` branch) comes with a test that fails without it, as the bug, and passes with it;
|
|
79
81
|
- the project's checks pass.
|
|
80
82
|
|
|
@@ -424,6 +426,17 @@ For several people in one repository, each with their own agents. Not every deve
|
|
|
424
426
|
|
|
425
427
|
It's a preview: it's tested end to end against a stand-in for GitHub, and has been run once against a real private repository (claims, leases, intents as discussions, decision records, since-you-last-looked and the Project board). Spec: `docs/specs/16-teams.md`.
|
|
426
428
|
|
|
429
|
+
## What it costs to run
|
|
430
|
+
|
|
431
|
+
Spec 29. A build that nobody costs ends up on each provider's production defaults: a managed database with a standby, a NAT gateway per zone, containers that never stop. So the running cost is a guardrail, set once and checked as the work lands, for whatever providers the project uses.
|
|
432
|
+
|
|
433
|
+
- **The budget.** spec-design asks for it with the other constraints: how much a month each environment may cost, in the person's currency, and the load to plan for. 0 means free tiers only. init writes it to `cost` in the config, with the project's infrastructure files as `cost.paths`.
|
|
434
|
+
- **The register.** `docs/costs.md` has one table, `| Item | Provider | Environment | Size | Monthly | Basis |`: a row per paid thing, its monthly estimate as a number, and where the price came from, with the date. An `all` row counts in every environment. code-kit holds no price list: the lead estimates from each provider's published pricing, and `code-kit cost` adds it up and names a price older than 90 days.
|
|
435
|
+
- **The design fits first.** spec-design costs each architecture it proposes, and when the one the person prefers doesn't fit, it says by how much and offers options that do (a smaller size, a cheaper tier or provider, one environment instead of two, a service the product can do without at launch, less scope), each with what it gives up.
|
|
436
|
+
- **Each change is costed.** Any agent may write the register: a lane changes its row when its story adds or resizes something paid, and `verify` fails a branch that changes `cost.paths` without it. The review checks the sizes in the code against the rows.
|
|
437
|
+
- **Over the budget is the person's.** A commit that takes an environment past its budget, or further past it, is refused until the person approves `cost` (the lead can't, under vibe either); the log records the totals it allowed. A lane takes it to the lead, and the lead to the person with the options that fit and the cost of the one that doesn't.
|
|
438
|
+
- **Existing projects.** `next` names a project with infrastructure and no budget, and init's next run asks for one; the lead then costs what's built.
|
|
439
|
+
|
|
427
440
|
## Enforce it in CI
|
|
428
441
|
|
|
429
442
|
The hooks only see Claude Code sessions. For everything else, init offers `.github/workflows/code-kit.yml` (from `templates/github-workflow.yml`). It runs `verify --no-checks` on every pull request, through `npx @warren-dean/code-kit@<version>`, pinned so CI doesn't change under you: the rules, in seconds, with a 10-minute limit, and a new push cancels the run it replaces. The project's checks aren't run again there, because the merge queue ran them before each merge; the project's full CI runs on its release branches instead, once per release (`code-kit release <version>` cuts one). `code-kit ci check` says what in the project's own workflows still runs once per story, and `code-kit ci usage` what the project spent. The workflow needs no secret. Mark the `code-kit` check as required on the protected branches, and keep its install step: a fix story's test is run without its fix (REG-1). Add gitleaks to the workflow for the secret scan of commits' content.
|
|
@@ -482,6 +495,7 @@ code-kit sent-back <branch> [--reason "…"] # record a revie
|
|
|
482
495
|
code-kit ci check [--json] # what in the project's workflows runs once per story, or without a time limit, and the fix
|
|
483
496
|
code-kit ci usage [--days N] [--json] # the project's GitHub Actions runs and minutes, by workflow and trigger
|
|
484
497
|
code-kit release <version> # cut release/<version> from the base and push it: the project's full CI runs there once
|
|
498
|
+
code-kit cost [--json] # each environment's estimated running cost against its budget, the register's problems and the prices to recheck
|
|
485
499
|
code-kit decisions [--json] [--all] # what waits on you in this session, and a count in each other one; --all lists every session's
|
|
486
500
|
code-kit who # which session this is, whether it leads the project, and its task
|
|
487
501
|
code-kit sessions [--json] # the sessions working the project, which one leads, and each one's task
|
|
@@ -536,6 +550,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
|
|
|
536
550
|
| `version` | yes | `1` |
|
|
537
551
|
| `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
|
|
538
552
|
| `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
|
|
553
|
+
| `docs.costs` | no | The cost register (spec 29), default `docs/costs.md`: one table, `\| Item \| Provider \| Environment \| Size \| Monthly \| Basis \|`, a row per paid thing with its monthly estimate as a number and where the price came from, dated. Any agent may write it once `cost` is set |
|
|
539
554
|
| `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
|
|
540
555
|
| `docs.standards` | no | The project's standards (spec 22), default `docs/standards.md`: each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why`, `source` and, when enforced, `enforced by` naming the layer rule, protected path, check or shell rule that refuses a breach. The id's prefix is its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Each lane agent is given the ones for its layers; a refusal from an enforcing rule names the standard; reviews check the checked ones. Protect the file with the `standards` approval: removing a standard, or weakening a required one, always needs the person's, whatever is delegated |
|
|
541
556
|
| `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
|
|
@@ -556,6 +571,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
|
|
|
556
571
|
| `approvals.lead` | no | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals). |
|
|
557
572
|
| `approvals.delegate` | no | `false`, or `{ protected?: [approval names], merge?: true, push?: true, tests?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`; with `push`, pushes the protected branch, never by force (yours unless you set it, since a push can deploy; read from the config committed on that branch); with `tests`, weakened tests on a lane's branch. Left out, the lead decides everything technical: every protected approval but `spec`, `design`, `ci` and `kit`, packages, merges and weakened tests (WHO-1); `false` keeps everything for you. Lanes ask the lead for these, never you. npm packages are also checked against the npm registry, and a Python lane's against PyPI; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals). |
|
|
558
573
|
| `setup` | no | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it |
|
|
574
|
+
| `cost` | no | The running budget (spec 29): `{ currency, monthly, load?, paths? }`. `currency` is a three-letter code (USD, AUD, EUR); `monthly` maps each environment (`prod`, `dev`, …, not `all`) to what it may cost a month; `load` says in words what the budget plans for; `paths` are the infrastructure files, whatever defines them, and a branch that changes one changes the register too. A commit that takes an environment past its budget needs the person's `cost` approval, whatever is delegated |
|
|
559
575
|
| `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, the specs' titles and outcome lines, approvals, token use, the rules, the design register and the sessions at work; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
|
|
560
576
|
| `branches.protected` | no | Default `["main", "master"]` |
|
|
561
577
|
| `branches.publish` | no | How a merge reaches the remote's base: `push` (the base is pushed, fast-forward only) or `pull-request` (for a base the remote only lets change through pull requests: code-kit opens one from `code-kit/publish-<base>` after each merge, and merges it where `approvals.delegate.push` is on, otherwise it waits for you). Left out, code-kit leaves pushing the base to you |
|
package/bin/code-kit.mjs
CHANGED
|
@@ -246,6 +246,7 @@ import {
|
|
|
246
246
|
} from '../hooks/lib/worktrees.mjs';
|
|
247
247
|
import { decisionsFor, openDecisions } from '../hooks/lib/decisionstore.mjs';
|
|
248
248
|
import { WORKFLOWS_DIR, ciFindings, ciUsage, releaseBranch } from '../hooks/lib/ci.mjs';
|
|
249
|
+
import { COST_APPROVAL, costReport, infraFiles, money } from '../hooks/lib/costs.mjs';
|
|
249
250
|
import {
|
|
250
251
|
appliesTo,
|
|
251
252
|
projectStandards,
|
|
@@ -584,6 +585,7 @@ const VERIFY_GROUPS = {
|
|
|
584
585
|
tests: 'Weakened tests',
|
|
585
586
|
regression: 'Fixes and their tests',
|
|
586
587
|
standards: 'Standards',
|
|
588
|
+
cost: 'Running cost',
|
|
587
589
|
checks: 'Checks',
|
|
588
590
|
};
|
|
589
591
|
|
|
@@ -1823,6 +1825,56 @@ function settings() {
|
|
|
1823
1825
|
);
|
|
1824
1826
|
}
|
|
1825
1827
|
|
|
1828
|
+
/**
|
|
1829
|
+
* COST-3: each environment's estimated running cost from the register, against the budget the person
|
|
1830
|
+
* set, with what's wrong with the register and the prices to recheck. Exits 1 when anything's wrong.
|
|
1831
|
+
*/
|
|
1832
|
+
function costCommand() {
|
|
1833
|
+
const { config } = load();
|
|
1834
|
+
const root = resolve('.');
|
|
1835
|
+
const cost = config.cost;
|
|
1836
|
+
const some = (files) => `${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}`;
|
|
1837
|
+
if (!cost) {
|
|
1838
|
+
const infra = infraFiles(root);
|
|
1839
|
+
if (flag('--json'))
|
|
1840
|
+
return (out(JSON.stringify({ budget: null, infra }, null, 2)), process.exit(1));
|
|
1841
|
+
out(
|
|
1842
|
+
`No running budget is set${infra.length ? `, and the project has infrastructure (${some(infra)})` : ''}. The person sets how much a month each environment may cost; /code-kit:init asks for it and writes it to "cost" in ${file}.`,
|
|
1843
|
+
);
|
|
1844
|
+
process.exit(1);
|
|
1845
|
+
}
|
|
1846
|
+
const report = costReport(root, config);
|
|
1847
|
+
const infra = cost.paths.length ? infraFiles(root, cost.paths) : [];
|
|
1848
|
+
if (!report.exists && infra.length)
|
|
1849
|
+
report.problems.unshift(
|
|
1850
|
+
`There is no cost register (${report.file}), but the project has infrastructure (${some(infra)}). The lead costs it there: a row per paid thing, with its monthly estimate and where the price came from.`,
|
|
1851
|
+
);
|
|
1852
|
+
if (flag('--json')) {
|
|
1853
|
+
out(JSON.stringify({ budget: cost, ...report, infra }, null, 2));
|
|
1854
|
+
process.exit(report.problems.length ? 1 : 0);
|
|
1855
|
+
}
|
|
1856
|
+
out(
|
|
1857
|
+
`Running cost against the budget, ${cost.currency} a month${cost.load ? `, for ${cost.load}` : ''}${report.exists ? `, from ${report.file}` : `; no register yet (${report.file})`}:`,
|
|
1858
|
+
);
|
|
1859
|
+
for (const e of report.environments)
|
|
1860
|
+
out(
|
|
1861
|
+
` ${e.name.padEnd(10)} ${money(e.total).padStart(9)} of ${money(e.budget)}${e.over > 0 ? `, ${money(e.over)} over` : ''}`,
|
|
1862
|
+
);
|
|
1863
|
+
for (const r of report.rows)
|
|
1864
|
+
out(
|
|
1865
|
+
` ${r.environment.padEnd(8)} ${String(r.monthly).padStart(9)} ${r.item}${r.provider ? ` (${[r.provider, r.size].filter(Boolean).join(', ')})` : ''}`,
|
|
1866
|
+
);
|
|
1867
|
+
if (report.problems.length)
|
|
1868
|
+
out(`\nProblems:\n${report.problems.map((p) => ` ${p}`).join('\n')}`);
|
|
1869
|
+
if (report.stale.length)
|
|
1870
|
+
out(`\nPrices to recheck:\n${report.stale.map((p) => ` ${p}`).join('\n')}`);
|
|
1871
|
+
if (report.environments.some((e) => e.over > 0))
|
|
1872
|
+
out(
|
|
1873
|
+
"\nOver the budget, the lead brings the person options that fit (smaller sizes, cheaper tiers or providers, fewer environments, less at launch), each with what it gives up. A commit that raises a total past its budget needs the person's cost approval.",
|
|
1874
|
+
);
|
|
1875
|
+
if (report.problems.length) process.exit(1);
|
|
1876
|
+
}
|
|
1877
|
+
|
|
1826
1878
|
/**
|
|
1827
1879
|
* CIC-2, CIC-4: `ci check` lists what in the project's workflows multiplies their cost with a story per
|
|
1828
1880
|
* branch; `ci usage` sums the Actions runs of the last days, by workflow and trigger.
|
|
@@ -2352,7 +2404,12 @@ async function approve(given) {
|
|
|
2352
2404
|
);
|
|
2353
2405
|
if (laneName !== undefined && !config.lanes[laneName])
|
|
2354
2406
|
die(`There is no lane "${laneName}". Lanes: ${Object.keys(config.lanes).join(', ')}.`);
|
|
2355
|
-
const known = new Set([
|
|
2407
|
+
const known = new Set([
|
|
2408
|
+
'kit',
|
|
2409
|
+
TESTS_APPROVAL,
|
|
2410
|
+
COST_APPROVAL,
|
|
2411
|
+
...config.protected.map((p) => p.approval),
|
|
2412
|
+
]);
|
|
2356
2413
|
const isPackage = (n) => /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(n);
|
|
2357
2414
|
const names = given.map((n) =>
|
|
2358
2415
|
n.startsWith(DEPENDENCY_APPROVAL) || known.has(n) || !isPackage(n) ? n : dependencyApproval(n),
|
|
@@ -3442,6 +3499,7 @@ const commands = {
|
|
|
3442
3499
|
timeline,
|
|
3443
3500
|
'sent-back': () => (rest.length === 1 ? sentBackCommand(rest[0]) : usage()),
|
|
3444
3501
|
ci: ciCommand,
|
|
3502
|
+
cost: () => (rest.length === 0 ? costCommand() : usage()),
|
|
3445
3503
|
release: () => (rest.length === 1 ? releaseCommand(rest[0]) : usage()),
|
|
3446
3504
|
replay: () => (rest.length === 1 ? replayCommand(rest[0]) : usage()),
|
|
3447
3505
|
reconcile: () => (rest.length <= 1 ? reconcileCommand(rest[0]) : usage()),
|
|
@@ -3481,6 +3539,7 @@ function usage() {
|
|
|
3481
3539
|
' | who | task "<what>" --touches globs | task done | task take <session>\n' +
|
|
3482
3540
|
' | decisions [--json] [--all]\n' +
|
|
3483
3541
|
' | ci check [--json] | ci usage [--days N] [--json] | release <version>\n' +
|
|
3542
|
+
' | cost [--json]\n' +
|
|
3484
3543
|
' | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
|
|
3485
3544
|
' | queue [--json] | queue add|drop <branch> | queue rules | queue merge --delegated|--person\n' +
|
|
3486
3545
|
' | queue pause --reason "…" | queue resume\n' +
|
package/hooks/guard-bash.mjs
CHANGED
|
@@ -37,6 +37,7 @@ import { historyWrites, storyMerges } from './lib/queue.mjs';
|
|
|
37
37
|
import { approverOf } from './lib/journal.mjs';
|
|
38
38
|
import { loginHere } from './lib/sessions.mjs';
|
|
39
39
|
import { TESTS_APPROVAL, commitWeakenings } from './lib/regression.mjs';
|
|
40
|
+
import { COST_APPROVAL, overBudget, overWords, registerFile } from './lib/costs.mjs';
|
|
40
41
|
import {
|
|
41
42
|
STANDARDS_APPROVAL,
|
|
42
43
|
noteFor,
|
|
@@ -100,7 +101,7 @@ const ALWAYS = [
|
|
|
100
101
|
],
|
|
101
102
|
[
|
|
102
103
|
/approval-log\.jsonl/,
|
|
103
|
-
"The approval audit log is appended only by the commit hook; nobody edits it. A shell command may name it only to read it: git diff, log, show or blame, or cat, head, tail, grep, wc, jq, cut, sort, uniq, awk or sed -n printing lines, piped only into each other, with no redirect but 2>&1 or into /dev/null, no command's output in its arguments ($(…) or backticks) and no variable set before a command; other commands may come before or after it with ; or &&, if none defines a function or alias or sets a variable. Run the read in that form, or read the file with the Read tool, which can't write.",
|
|
104
|
+
"The approval audit log is appended only by the commit hook; nobody edits it. A shell command may name it only to read it: git diff, log, show or blame, or cat, head, tail, grep, wc, jq, cut, sort, uniq, awk or sed -n printing lines, piped only into each other, with no redirect but 2>&1 or into /dev/null, no command's output in its arguments ($(…) or backticks) and no variable set before a command; other commands may come before or after it with ; or &&, if none defines a function or alias or sets a variable. Run the read in that form, or read the file with the Read tool, which can't write. To put it back as the last commit has it (after a `git revert --no-commit` or `git cherry-pick --no-commit` took entries out), run `git restore --staged --worktree .claude/approval-log.jsonl` in the same form, and commit in a command after it.",
|
|
104
105
|
unreadNames(cmd, /approval-log\.jsonl/).join('\n'),
|
|
105
106
|
],
|
|
106
107
|
];
|
|
@@ -657,6 +658,39 @@ function recordApprovals() {
|
|
|
657
658
|
);
|
|
658
659
|
}
|
|
659
660
|
}
|
|
661
|
+
// COST-5: a commit that takes an environment's estimated running cost past its budget, or further
|
|
662
|
+
// past it, waits for the person's cost approval (never the lead's), which records what it allowed.
|
|
663
|
+
const costRegister = config.cost ? registerFile(config) : null;
|
|
664
|
+
const overCost =
|
|
665
|
+
costRegister &&
|
|
666
|
+
files.includes(costRegister) &&
|
|
667
|
+
!arrivesWithMerge(root, costRegister, { staged: true })
|
|
668
|
+
? overBudget(
|
|
669
|
+
git('show', `HEAD:${costRegister}`),
|
|
670
|
+
existsSync(join(root, costRegister))
|
|
671
|
+
? readFileSync(join(root, costRegister), 'utf8')
|
|
672
|
+
: '',
|
|
673
|
+
config.cost,
|
|
674
|
+
)
|
|
675
|
+
: [];
|
|
676
|
+
if (overCost.length) {
|
|
677
|
+
const granted = approval(root, COST_APPROVAL, actor);
|
|
678
|
+
if (!granted || granted.reason.includes(delegatedMark('').slice(0, -1))) {
|
|
679
|
+
const over = overWords(overCost, config.cost.currency);
|
|
680
|
+
recordRequest(root, actor, COST_APPROVAL, costRegister, `Over the running budget: ${over}.`);
|
|
681
|
+
const personOnly = { ...config, approvals: { ...config.approvals, delegate: null } };
|
|
682
|
+
block(
|
|
683
|
+
`Blocked: this commit takes the estimated running cost past the budget the person set: ${over}. Going past the budget is the person's call, never the lead's. First find options that fit it: a smaller size, a cheaper tier or provider, one environment instead of two, a service the product can do without at launch, or less scope, each with what it gives up. ${askHowTo(COST_APPROVAL, actor, root, personOnly, { allows: 'one commit over the running budget', need: 'the change, what it costs a month against the budget, and the options that fit, each with what it gives up' })}`,
|
|
684
|
+
);
|
|
685
|
+
}
|
|
686
|
+
record(costRegister, {
|
|
687
|
+
approval: COST_APPROVAL,
|
|
688
|
+
reason: granted.reason,
|
|
689
|
+
grantedAt: granted.grantedAt,
|
|
690
|
+
over: overCost,
|
|
691
|
+
});
|
|
692
|
+
useApproval(root, COST_APPROVAL, actor);
|
|
693
|
+
}
|
|
660
694
|
// The commit that switches code-kit on: the person approved the setup it holds as init showed it.
|
|
661
695
|
const setup = settingUp && files.includes(CONFIG_FILE) && beforeSetup(root);
|
|
662
696
|
for (const file of files) {
|
|
@@ -796,7 +830,7 @@ ${approvalHowTo(TESTS_APPROVAL, actor, root, 'weakening tests in one commit', pe
|
|
|
796
830
|
// The commit hook judges what the commit holds before the command runs, so a file a command earlier in
|
|
797
831
|
// the chain writes (a formatter, a script, a heredoc) can't be seen, and would go in unjudged and
|
|
798
832
|
// unlogged. Before the commit, a chain may only move into the checkout, make a branch where it stands
|
|
799
|
-
// (no start point, so no file changes), stage or unstage, make folders, take away a worktree (keepsFiles)
|
|
833
|
+
// (no start point, or one at the commit the checkout is at, so no file changes), stage or unstage, make folders, take away a worktree (keepsFiles)
|
|
800
834
|
// and run commands that only read (lib/shell.mjs readsOnly: git's status, diff, log and show among them,
|
|
801
835
|
// with no output file), or that write only outside the checkout (writesOutside). Errors sent into the
|
|
802
836
|
// output or /dev/null write no file.
|
|
@@ -812,15 +846,25 @@ const assignsOnly = (c) => ASSIGNS_ONLY.test(c.code) && !/`|\$\(|<\(/.test(c.tex
|
|
|
812
846
|
const recordsOnly = (c) =>
|
|
813
847
|
!/[<>]/.test(c.code) && (config.shell.records ?? []).some((re) => new RegExp(re).test(c.text));
|
|
814
848
|
// What changes no file a commit could take: making folders (git keeps no empty folder), taking away a
|
|
815
|
-
// worktree, which is a checkout of its own,
|
|
816
|
-
// leaves the files as they are). A reset to another commit with no paths moves HEAD, so it counts.
|
|
849
|
+
// worktree, which is a checkout of its own, unstaging (`git reset [HEAD] [--] [<paths>]`, which
|
|
850
|
+
// leaves the files as they are) and making a branch at the commit the checkout is at. A reset to another commit with no paths moves HEAD, so it counts.
|
|
817
851
|
const KEEPS_FILES = new RegExp(String.raw`^(?:mkdir\s|${GIT}worktree\s+(?:remove|prune)(?![\w-]))`);
|
|
852
|
+
// A branch made at a start point that is the commit the checkout is at already: no file changes.
|
|
853
|
+
const BRANCHES_AT =
|
|
854
|
+
/^git\s+(?:switch\s+(?:-q\s+|--quiet\s+)*(?:-c|--create)|checkout\s+(?:-q\s+|--quiet\s+)*-b)\s+[^\s-]\S*\s+([^\s-$`]\S*)\s*$/;
|
|
855
|
+
const commitOf = (ref) =>
|
|
856
|
+
spawnSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
|
|
857
|
+
encoding: 'utf8',
|
|
858
|
+
}).stdout.trim();
|
|
818
859
|
const RESETS = new RegExp(String.raw`^${GIT}reset((?:\s+\S+)*)\s*$`);
|
|
819
860
|
const isCommit = (w) =>
|
|
820
861
|
spawnSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${w}^{commit}`]).status === 0;
|
|
821
862
|
function keepsFiles(c) {
|
|
822
863
|
if (/[<>]/.test(c.code)) return false;
|
|
823
864
|
if (KEEPS_FILES.test(c.text)) return true;
|
|
865
|
+
const start = c.text.match(BRANCHES_AT)?.[1];
|
|
866
|
+
if (start && !/[$`]/.test(start))
|
|
867
|
+
return commitOf(start) !== '' && commitOf(start) === commitOf('HEAD');
|
|
824
868
|
const reset = c.text.match(RESETS);
|
|
825
869
|
if (!reset) return false;
|
|
826
870
|
const words = reset[1].trim().split(/\s+/).filter(Boolean);
|
package/hooks/lib/config.mjs
CHANGED
|
@@ -5,6 +5,7 @@ import { existsSync, readFileSync } from 'node:fs';
|
|
|
5
5
|
import { VIBE, harnessProblems, harnessSettings } from './harness.mjs';
|
|
6
6
|
import { teamProblems } from './team.mjs';
|
|
7
7
|
import { join } from 'node:path';
|
|
8
|
+
import { DEFAULT_REGISTER } from './costs.mjs';
|
|
8
9
|
import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
|
|
9
10
|
|
|
10
11
|
export const CONFIG_FILE = '.claude/code-kit.json';
|
|
@@ -82,7 +83,12 @@ export function withDefaults(c) {
|
|
|
82
83
|
paths: [...c.lead.paths, '.claude/**', '.mcp.json'],
|
|
83
84
|
outside: [...(c.lead.outside ?? []), ...CLAUDE_OWN],
|
|
84
85
|
},
|
|
85
|
-
|
|
86
|
+
// Spec 29: the cost register, which a lane changes with the infrastructure its story adds.
|
|
87
|
+
anyActor: [
|
|
88
|
+
...(c.anyActor ?? []).map(anyActorGlob),
|
|
89
|
+
'.claude/state/**',
|
|
90
|
+
...(c.cost ? [c.docs?.costs ?? DEFAULT_REGISTER] : []),
|
|
91
|
+
],
|
|
86
92
|
// Who reviews changes to files any agent may write; the lead unless an entry names a lane.
|
|
87
93
|
anyActorReviewers: (c.anyActor ?? [])
|
|
88
94
|
.filter((e) => typeof e === 'object' && e?.reviewer)
|
|
@@ -108,6 +114,14 @@ export function withDefaults(c) {
|
|
|
108
114
|
: delegateRules(c.approvals?.delegate, c.protected ?? []),
|
|
109
115
|
},
|
|
110
116
|
harness: harnessSettings(c.harness),
|
|
117
|
+
cost: c.cost
|
|
118
|
+
? {
|
|
119
|
+
currency: c.cost.currency,
|
|
120
|
+
monthly: c.cost.monthly,
|
|
121
|
+
load: c.cost.load ?? null,
|
|
122
|
+
paths: c.cost.paths ?? [],
|
|
123
|
+
}
|
|
124
|
+
: null,
|
|
111
125
|
};
|
|
112
126
|
}
|
|
113
127
|
|
|
@@ -363,7 +377,7 @@ export function validate(c) {
|
|
|
363
377
|
);
|
|
364
378
|
// A brownfield project may have no specs yet: then there is no spec-check gate.
|
|
365
379
|
need(c.docs === undefined || isObj(c.docs), '"docs" must be an object');
|
|
366
|
-
for (const k of ['specs', 'principles', 'plan', 'decisions', 'standards'])
|
|
380
|
+
for (const k of ['specs', 'principles', 'plan', 'decisions', 'standards', 'costs'])
|
|
367
381
|
need(c.docs?.[k] === undefined || isStr(c.docs[k]), `"docs.${k}" must be a path`);
|
|
368
382
|
need(isObj(c.lead) && isList(c.lead?.paths), '"lead.paths" must be a list of globs');
|
|
369
383
|
need(
|
|
@@ -465,11 +479,38 @@ export function validate(c) {
|
|
|
465
479
|
[undefined, 'push', 'pull-request'].includes(c.branches?.publish),
|
|
466
480
|
'"branches.publish" must be "push" or "pull-request": how merges reach the remote\'s base',
|
|
467
481
|
);
|
|
482
|
+
if (c.cost !== undefined) validateCost(c.cost, need);
|
|
468
483
|
p.push(...harnessProblems(c.harness));
|
|
469
484
|
p.push(...teamProblems(c));
|
|
470
485
|
return p;
|
|
471
486
|
}
|
|
472
487
|
|
|
488
|
+
// Spec 29: the running budget the person set, per environment, in one currency.
|
|
489
|
+
function validateCost(cost, need) {
|
|
490
|
+
if (!need(isObj(cost), '"cost" must be an object: { currency, monthly, load?, paths? }')) return;
|
|
491
|
+
need(
|
|
492
|
+
/^[A-Z]{3}$/.test(cost.currency ?? ''),
|
|
493
|
+
'"cost.currency" must be a three-letter currency code, such as USD, AUD or EUR',
|
|
494
|
+
);
|
|
495
|
+
need(
|
|
496
|
+
isObj(cost.monthly) &&
|
|
497
|
+
Object.keys(cost.monthly).length > 0 &&
|
|
498
|
+
Object.entries(cost.monthly).every(
|
|
499
|
+
([env, v]) =>
|
|
500
|
+
/^[a-z][a-z0-9-]*$/.test(env) && env !== 'all' && typeof v === 'number' && v >= 0,
|
|
501
|
+
),
|
|
502
|
+
'"cost.monthly" must map each environment (a lower-case name such as prod or dev, not "all") to its monthly budget, a number of 0 or more',
|
|
503
|
+
);
|
|
504
|
+
need(
|
|
505
|
+
cost.load === undefined || isStr(cost.load),
|
|
506
|
+
'"cost.load" must say, in words, the load the budget plans for',
|
|
507
|
+
);
|
|
508
|
+
need(
|
|
509
|
+
cost.paths === undefined || isList(cost.paths),
|
|
510
|
+
'"cost.paths" must be a list of globs: the infrastructure files',
|
|
511
|
+
);
|
|
512
|
+
}
|
|
513
|
+
|
|
473
514
|
/** A deliverable kind's name (a layer's or lane's `label`): one line, at most 60 characters. */
|
|
474
515
|
const isLabel = (v) => isStr(v) && v.trim().length > 0 && v.length <= 60 && !/[\r\n]/.test(v);
|
|
475
516
|
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
// Spec 29: what a project costs to run each month. The person sets a budget per environment in the
|
|
2
|
+
// config (`cost`); the lead keeps a register of estimated costs (docs/costs.md, a table with a row per
|
|
3
|
+
// paid thing); code-kit adds the register up against the budget. It knows no provider's prices: every
|
|
4
|
+
// figure is the lead's estimate, with where it came from.
|
|
5
|
+
import { execFileSync } from 'node:child_process';
|
|
6
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
7
|
+
import { join } from 'node:path';
|
|
8
|
+
import { matchesAny } from './glob.mjs';
|
|
9
|
+
|
|
10
|
+
export const COST_APPROVAL = 'cost';
|
|
11
|
+
export const DEFAULT_REGISTER = 'docs/costs.md';
|
|
12
|
+
// A price older than this is rechecked (COST-7).
|
|
13
|
+
export const STALE_DAYS = 90;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Infrastructure files, whatever tool defines them, for init's draft of `cost.paths` and for `next`
|
|
17
|
+
* to notice a project with infrastructure and no budget (COST-1, COST-6).
|
|
18
|
+
*/
|
|
19
|
+
export const INFRA_GLOBS = [
|
|
20
|
+
'**/*.tf',
|
|
21
|
+
'**/*.tfvars',
|
|
22
|
+
'**/cdk.json',
|
|
23
|
+
'**/Pulumi*.yaml',
|
|
24
|
+
'**/serverless.yml',
|
|
25
|
+
'**/serverless.yaml',
|
|
26
|
+
'**/sst.config.ts',
|
|
27
|
+
'**/docker-compose*.yml',
|
|
28
|
+
'**/docker-compose*.yaml',
|
|
29
|
+
'**/compose.yml',
|
|
30
|
+
'**/compose.yaml',
|
|
31
|
+
'**/fly.toml',
|
|
32
|
+
'**/vercel.json',
|
|
33
|
+
'**/netlify.toml',
|
|
34
|
+
'**/render.yaml',
|
|
35
|
+
'**/wrangler.toml',
|
|
36
|
+
'**/app.yaml',
|
|
37
|
+
'**/supabase/config.toml',
|
|
38
|
+
'**/k8s/**',
|
|
39
|
+
'**/kubernetes/**',
|
|
40
|
+
'**/helm/**',
|
|
41
|
+
'infra/**',
|
|
42
|
+
'infrastructure/**',
|
|
43
|
+
'terraform/**',
|
|
44
|
+
];
|
|
45
|
+
|
|
46
|
+
/** Where the project keeps its cost register. */
|
|
47
|
+
export const registerFile = (config) => config?.docs?.costs ?? DEFAULT_REGISTER;
|
|
48
|
+
|
|
49
|
+
const cells = (line) =>
|
|
50
|
+
line
|
|
51
|
+
.split('|')
|
|
52
|
+
.slice(1, -1)
|
|
53
|
+
.map((c) => c.trim());
|
|
54
|
+
|
|
55
|
+
/** A Monthly cell as a number (`25`, `7.80`, `$1,200`, `€30`), or null when it isn't one. */
|
|
56
|
+
export function amountOf(text) {
|
|
57
|
+
const m = String(text ?? '')
|
|
58
|
+
.trim()
|
|
59
|
+
.match(/^[$€£¥]?\s*(\d[\d,]*(?:\.\d+)?)$/);
|
|
60
|
+
return m ? Number(m[1].replaceAll(',', '')) : null;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The register's rows: { line, item, provider, environment, size, monthly, amount, basis }, `amount`
|
|
65
|
+
* null where Monthly isn't a number. `table` is false when the text has no table whose header starts
|
|
66
|
+
* `| Item |` with a Monthly column.
|
|
67
|
+
*/
|
|
68
|
+
export function parseRegister(text) {
|
|
69
|
+
const lines = String(text ?? '').split('\n');
|
|
70
|
+
const at = lines.findIndex((l) => /^\|\s*Item\s*\|/i.test(l));
|
|
71
|
+
if (at < 0) return { table: false, rows: [] };
|
|
72
|
+
const columns = cells(lines[at]).map((c) => c.toLowerCase());
|
|
73
|
+
const col = (name) => columns.findIndex((c) => c.startsWith(name));
|
|
74
|
+
if (col('monthly') < 0) return { table: false, rows: [] };
|
|
75
|
+
const rows = [];
|
|
76
|
+
for (let i = at + 1; i < lines.length && /^\|/.test(lines[i]); i++) {
|
|
77
|
+
if (/^\|\s*:?-/.test(lines[i])) continue;
|
|
78
|
+
const c = cells(lines[i]);
|
|
79
|
+
const get = (name) => (col(name) >= 0 ? (c[col(name)] ?? '') : '');
|
|
80
|
+
if (!get('item')) continue;
|
|
81
|
+
rows.push({
|
|
82
|
+
line: i + 1,
|
|
83
|
+
item: get('item'),
|
|
84
|
+
provider: get('provider'),
|
|
85
|
+
environment: get('env').toLowerCase(),
|
|
86
|
+
size: get('size'),
|
|
87
|
+
monthly: get('monthly'),
|
|
88
|
+
amount: amountOf(get('monthly')),
|
|
89
|
+
basis: get('basis'),
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
return { table: true, rows };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Each environment the budget names: { name, total, budget, over }, `all` rows counting in every one. */
|
|
96
|
+
export function totals(rows, cost) {
|
|
97
|
+
return Object.entries(cost?.monthly ?? {}).map(([name, budget]) => {
|
|
98
|
+
const total = rows
|
|
99
|
+
.filter((r) => r.amount !== null && (r.environment === name || r.environment === 'all'))
|
|
100
|
+
.reduce((sum, r) => sum + r.amount, 0);
|
|
101
|
+
const rounded = Math.round(total * 100) / 100;
|
|
102
|
+
return { name, total: rounded, budget, over: Math.round((rounded - budget) * 100) / 100 };
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** The money in the budget's currency, as people write it: `130`, `32.80`. */
|
|
107
|
+
export const money = (n, currency) =>
|
|
108
|
+
`${Number.isInteger(n) ? n : n.toFixed(2)}${currency ? ` ${currency}` : ''}`;
|
|
109
|
+
|
|
110
|
+
/** The newest date (YYYY-MM-DD) a Basis names, or null. */
|
|
111
|
+
function basisDate(basis) {
|
|
112
|
+
const dates = String(basis).match(/\d{4}-\d{2}-\d{2}/g);
|
|
113
|
+
const t = dates ? Math.max(...dates.map((d) => Date.parse(d))) : NaN;
|
|
114
|
+
return Number.isFinite(t) ? t : null;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* The register against the budget (COST-3, COST-7): { file, exists, environments, rows, problems, stale }.
|
|
119
|
+
* `problems` are what's wrong (an unreadable row, one without its basis or for an environment the budget
|
|
120
|
+
* doesn't name, no table, a total over its budget); `stale`, the rows whose price is more than 90 days
|
|
121
|
+
* old, to recheck.
|
|
122
|
+
*/
|
|
123
|
+
export function costReport(root, config, now = Date.now()) {
|
|
124
|
+
const file = registerFile(config);
|
|
125
|
+
const exists = existsSync(join(root, file));
|
|
126
|
+
return {
|
|
127
|
+
file,
|
|
128
|
+
exists,
|
|
129
|
+
...readCosts(exists ? readFileSync(join(root, file), 'utf8') : null, config, now),
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** costReport's reading of a register's text (null when there's none). */
|
|
134
|
+
export function readCosts(text, config, now = Date.now()) {
|
|
135
|
+
const cost = config?.cost;
|
|
136
|
+
const file = registerFile(config);
|
|
137
|
+
const { table, rows } = parseRegister(text ?? '');
|
|
138
|
+
const environments = totals(rows, cost);
|
|
139
|
+
const names = new Set([...environments.map((e) => e.name), 'all']);
|
|
140
|
+
const problems = [];
|
|
141
|
+
const stale = [];
|
|
142
|
+
if (text !== null && !table)
|
|
143
|
+
problems.push(
|
|
144
|
+
`${file} has no cost table: a table whose header row starts \`| Item |\`, with Provider, Environment, Size, Monthly and Basis columns.`,
|
|
145
|
+
);
|
|
146
|
+
for (const r of rows) {
|
|
147
|
+
const where = `${file}:${r.line} (${r.item})`;
|
|
148
|
+
if (r.amount === null)
|
|
149
|
+
problems.push(
|
|
150
|
+
`${where}: Monthly is "${r.monthly}", not a number. Write the estimate as a number in ${cost?.currency ?? "the budget's currency"}, such as 25 or 7.80.`,
|
|
151
|
+
);
|
|
152
|
+
if (!r.basis)
|
|
153
|
+
problems.push(
|
|
154
|
+
`${where} has no Basis: say where the price came from (the provider's pricing page and the date you read it).`,
|
|
155
|
+
);
|
|
156
|
+
if (!names.has(r.environment))
|
|
157
|
+
problems.push(
|
|
158
|
+
`${where} is for "${r.environment || '(none)'}", which the budget doesn't name. Environments: ${[...names].join(', ')}.`,
|
|
159
|
+
);
|
|
160
|
+
const dated = r.basis ? basisDate(r.basis) : null;
|
|
161
|
+
if (r.basis && (dated === null || now - dated > STALE_DAYS * 86_400_000))
|
|
162
|
+
stale.push(
|
|
163
|
+
`${where}: ${dated === null ? 'its Basis has no date' : `its price was read ${Math.floor((now - dated) / 86_400_000)} days ago`}; recheck it and date the Basis (YYYY-MM-DD).`,
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
for (const e of environments)
|
|
167
|
+
if (e.over > 0)
|
|
168
|
+
problems.push(
|
|
169
|
+
`${e.name} is estimated at ${money(e.total, cost.currency)} a month, ${money(e.over, cost.currency)} over its budget of ${money(e.budget, cost.currency)}.`,
|
|
170
|
+
);
|
|
171
|
+
return { environments, rows, problems, stale };
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* COST-5: the environments a change to the register takes over budget, or further over it:
|
|
176
|
+
* [{ name, before, after, budget }]. A change that leaves every total within budget, or lowers one
|
|
177
|
+
* that was already over, needs nothing.
|
|
178
|
+
*/
|
|
179
|
+
export function overBudget(beforeText, afterText, cost) {
|
|
180
|
+
const before = new Map(
|
|
181
|
+
totals(parseRegister(beforeText ?? '').rows, cost).map((e) => [e.name, e.total]),
|
|
182
|
+
);
|
|
183
|
+
return totals(parseRegister(afterText ?? '').rows, cost)
|
|
184
|
+
.filter((e) => e.over > 0 && e.total > (before.get(e.name) ?? 0))
|
|
185
|
+
.map((e) => ({
|
|
186
|
+
name: e.name,
|
|
187
|
+
before: before.get(e.name) ?? 0,
|
|
188
|
+
after: e.total,
|
|
189
|
+
budget: e.budget,
|
|
190
|
+
}));
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** The words for overBudget's environments: "prod would be 130 of 100, 30 over". */
|
|
194
|
+
export const overWords = (over, currency) =>
|
|
195
|
+
over
|
|
196
|
+
.map(
|
|
197
|
+
(e) =>
|
|
198
|
+
`${e.name} would be ${money(e.after, currency)} a month against its budget of ${money(e.budget, currency)}, ${money(Math.round((e.after - e.budget) * 100) / 100, currency)} over (it was ${money(e.before, currency)})`,
|
|
199
|
+
)
|
|
200
|
+
.join('; ');
|
|
201
|
+
|
|
202
|
+
/** The project's tracked files that look like infrastructure (`globs`, INFRA_GLOBS by default). */
|
|
203
|
+
export function infraFiles(root, globs = INFRA_GLOBS) {
|
|
204
|
+
let files = [];
|
|
205
|
+
try {
|
|
206
|
+
files = execFileSync('git', ['-C', root, 'ls-files'], {
|
|
207
|
+
encoding: 'utf8',
|
|
208
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
209
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
210
|
+
})
|
|
211
|
+
.split('\n')
|
|
212
|
+
.filter(Boolean);
|
|
213
|
+
} catch {
|
|
214
|
+
return [];
|
|
215
|
+
}
|
|
216
|
+
return files.filter((f) => matchesAny(f, globs));
|
|
217
|
+
}
|
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
standardLine,
|
|
13
13
|
standardsFile,
|
|
14
14
|
} from './standards.mjs';
|
|
15
|
+
import { registerFile } from './costs.mjs';
|
|
15
16
|
|
|
16
17
|
/** The version of code-kit's instructions: raised whenever the templates' rules change. */
|
|
17
18
|
export const INSTRUCTIONS_VERSION = 12;
|
|
@@ -68,6 +69,9 @@ function factsOf(root, config, lane = null) {
|
|
|
68
69
|
'docs.plan': config.docs?.plan ?? 'the plan',
|
|
69
70
|
'docs.principles': config.docs?.principles ?? "the project's principles",
|
|
70
71
|
'docs.standards': standardsFile(config),
|
|
72
|
+
// Spec 29: the running budget and its register.
|
|
73
|
+
cost: Boolean(config.cost),
|
|
74
|
+
'docs.costs': registerFile(config),
|
|
71
75
|
standards: laneStandards(root, config, lane),
|
|
72
76
|
'standards.all': standardsOf(root, config)
|
|
73
77
|
.map((s) => `${s.id} ${s.title}`)
|
package/hooks/lib/next.mjs
CHANGED
|
@@ -19,6 +19,7 @@ import { isTestFile } from './testfiles.mjs';
|
|
|
19
19
|
import { laneClaims } from './laneclaims.mjs';
|
|
20
20
|
import { keptBecause, worktrees } from './worktrees.mjs';
|
|
21
21
|
import { ciFindings } from './ci.mjs';
|
|
22
|
+
import { costReport, infraFiles, money } from './costs.mjs';
|
|
22
23
|
import { storyModels } from './dispatches.mjs';
|
|
23
24
|
import { pickPerLane } from './schedule.mjs';
|
|
24
25
|
import { reconcileAll } from './events.mjs';
|
|
@@ -78,6 +79,43 @@ export function readBrief(root, config) {
|
|
|
78
79
|
return { path, status: status ?? null, openQuestions: open.map((q) => q.question), open };
|
|
79
80
|
}
|
|
80
81
|
|
|
82
|
+
/**
|
|
83
|
+
* Spec 29: the running budget and the cost register, as next's attention. A project with infrastructure
|
|
84
|
+
* and no budget is asked for one (COST-6); with one, an estimate over it goes to the person with options
|
|
85
|
+
* (COST-5), and the register's other problems are named (COST-3).
|
|
86
|
+
*/
|
|
87
|
+
export function costAttention(root, config) {
|
|
88
|
+
const some = (files) => `${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}`;
|
|
89
|
+
if (!config.cost) {
|
|
90
|
+
const infra = infraFiles(root);
|
|
91
|
+
return infra.length
|
|
92
|
+
? [
|
|
93
|
+
`No running budget is set, and the project has infrastructure (${some(infra)}). Ask the person how much a month each environment may cost and the load to plan for; /code-kit:init records it, and the lead then costs what's built in the register.`,
|
|
94
|
+
]
|
|
95
|
+
: [];
|
|
96
|
+
}
|
|
97
|
+
const report = costReport(root, config);
|
|
98
|
+
const infra = config.cost.paths.length ? infraFiles(root, config.cost.paths) : [];
|
|
99
|
+
if (!report.exists)
|
|
100
|
+
return infra.length
|
|
101
|
+
? [
|
|
102
|
+
`There is no cost register (${report.file}) for the project's infrastructure (${some(infra)}). Cost it there, a row per paid thing with its monthly estimate and where the price came from; \`code-kit cost\` adds it up against the budget.`,
|
|
103
|
+
]
|
|
104
|
+
: [];
|
|
105
|
+
const words = [];
|
|
106
|
+
const over = report.environments.filter((e) => e.over > 0);
|
|
107
|
+
if (over.length)
|
|
108
|
+
words.push(
|
|
109
|
+
`The running cost is over the budget: ${over.map((e) => `${e.name} ${money(e.total, config.cost.currency)} a month against ${money(e.budget, config.cost.currency)}`).join(', ')}. Bring the person options that fit (smaller sizes, cheaper tiers or providers, fewer environments, less at launch), each with what it gives up, and let them decide.`,
|
|
110
|
+
);
|
|
111
|
+
const other = report.problems.length - over.length;
|
|
112
|
+
if (other > 0)
|
|
113
|
+
words.push(
|
|
114
|
+
`${report.file} has ${other} problem${other === 1 ? '' : 's'} (\`code-kit cost\` says which): an estimate that isn't a number, a row without where its price came from, or one for an environment the budget doesn't name.`,
|
|
115
|
+
);
|
|
116
|
+
return words;
|
|
117
|
+
}
|
|
118
|
+
|
|
81
119
|
const hasMarkdown = (dir) => {
|
|
82
120
|
try {
|
|
83
121
|
return readdirSync(dir, { recursive: true }).some((f) => String(f).endsWith('.md'));
|
|
@@ -390,6 +428,7 @@ export function nextStep(root, base) {
|
|
|
390
428
|
`${ci.length} thing${ci.length === 1 ? '' : 's'} in the project's CI (${files.join(', ')}) ${ci.length === 1 ? 'runs' : 'run'} once per story or without a time limit; \`code-kit ci check\` says what, and the fix for the person to approve.`,
|
|
391
429
|
);
|
|
392
430
|
}
|
|
431
|
+
attention.push(...costAttention(root, config));
|
|
393
432
|
const instructions = instructionsState(root, config);
|
|
394
433
|
const behind = instructions.filter((f) => ['stale', 'legacy'].includes(f.state));
|
|
395
434
|
// A file with no code-kit part may be one the project keeps without it: said, not insisted on.
|
package/hooks/lib/shell.mjs
CHANGED
|
@@ -304,7 +304,45 @@ export function unreadNames(cmd, pattern) {
|
|
|
304
304
|
if (andOr) i++;
|
|
305
305
|
}
|
|
306
306
|
}
|
|
307
|
-
|
|
307
|
+
// The commit hook appends to the log before the command runs: a restore beside a commit could drop that.
|
|
308
|
+
const restores = !runs(
|
|
309
|
+
cmd,
|
|
310
|
+
new RegExp(String.raw`^${GIT}(?:commit|merge|revert|cherry-pick|rebase|am|pull)(?![\w-])`),
|
|
311
|
+
);
|
|
312
|
+
return parts.filter(
|
|
313
|
+
(p) => pattern.test(p) && !readsOnly(p) && !(restores && restoresFromHead(p, pattern)),
|
|
314
|
+
);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
// git restore's flags that keep its source the last commit (or the index), and change nothing else.
|
|
318
|
+
const RESTORE_FLAG = /^(?:--staged|-S|--worktree|-W|-SW|-WS|--source=HEAD|-q|--quiet|--)$/;
|
|
319
|
+
|
|
320
|
+
/**
|
|
321
|
+
* Whether `part` only puts a file `pattern` names back as the last commit (or the index) has it:
|
|
322
|
+
* `git restore [--staged] [--worktree] <file>` or `git checkout [HEAD] -- <file>`. That can lose only
|
|
323
|
+
* what isn't committed, never what the history holds, as after `git revert --no-commit` took a file's
|
|
324
|
+
* committed lines out.
|
|
325
|
+
*/
|
|
326
|
+
export function restoresFromHead(part, pattern) {
|
|
327
|
+
const pieces = commandsOf(part);
|
|
328
|
+
if (pieces.length !== 1 || /[|<>`$]/.test(codeOf(part))) return false;
|
|
329
|
+
const words = wordsOf(pieces[0].text);
|
|
330
|
+
if (words[0] !== 'git' || words.length < 3) return false;
|
|
331
|
+
const file = words.at(-1);
|
|
332
|
+
if (!pattern.test(file) || /[*?[]/.test(file)) return false;
|
|
333
|
+
const flags = words.slice(2, -1);
|
|
334
|
+
if (words[1] === 'restore') {
|
|
335
|
+
for (let i = 0; i < flags.length; i++) {
|
|
336
|
+
if ((flags[i] === '-s' || flags[i] === '--source') && flags[i + 1] === 'HEAD') i++;
|
|
337
|
+
else if (!RESTORE_FLAG.test(flags[i])) return false;
|
|
338
|
+
}
|
|
339
|
+
return true;
|
|
340
|
+
}
|
|
341
|
+
if (words[1] === 'checkout')
|
|
342
|
+
return (
|
|
343
|
+
flags.join(' ') === '--' || flags.join(' ') === 'HEAD --' || flags.join(' ') === '-q HEAD --'
|
|
344
|
+
);
|
|
345
|
+
return false;
|
|
308
346
|
}
|
|
309
347
|
|
|
310
348
|
// What may come before a command it runs: a package runner (`npx`, `pnpm exec`, `uv run`…) or a wrapper
|
package/hooks/lib/verify.mjs
CHANGED
|
@@ -7,6 +7,7 @@ import { join } from 'node:path';
|
|
|
7
7
|
import { BASELINE_FILE, loadBaseline, newProblems } from './baseline.mjs';
|
|
8
8
|
import { runChecks } from './checks.mjs';
|
|
9
9
|
import { CONFIG_FILE } from './config.mjs';
|
|
10
|
+
import { COST_APPROVAL, overBudget, overWords, registerFile } from './costs.mjs';
|
|
10
11
|
import { isDependencyFile } from './dependencies.mjs';
|
|
11
12
|
import { entryProblems, freshEntries, readRegister, statesWithoutEvidence } from './designs.mjs';
|
|
12
13
|
import { evidenceRecords } from './reviews.mjs';
|
|
@@ -117,7 +118,9 @@ function logEntries(root, base) {
|
|
|
117
118
|
if (added === null)
|
|
118
119
|
return {
|
|
119
120
|
entries: [],
|
|
120
|
-
problems: [
|
|
121
|
+
problems: [
|
|
122
|
+
`${APPROVAL_LOG} was edited, not appended to; it is append-only. An entry it has where the branch left the base is gone or changed, as a \`git revert\` of a commit that logged approvals leaves it. Take that commit out of the branch and make it again without the log's change: \`git revert --no-commit <commit>\`, then \`git restore --staged --worktree ${APPROVAL_LOG}\`, then commit.`,
|
|
123
|
+
],
|
|
121
124
|
};
|
|
122
125
|
const entries = [];
|
|
123
126
|
const problems = [];
|
|
@@ -237,6 +240,7 @@ export function verifyBranch({
|
|
|
237
240
|
tests: [],
|
|
238
241
|
regression: [],
|
|
239
242
|
standards: [],
|
|
243
|
+
cost: [],
|
|
240
244
|
checks: [],
|
|
241
245
|
};
|
|
242
246
|
const { entries, problems: logProblems } = logEntries(root, from);
|
|
@@ -402,6 +406,29 @@ export function verifyBranch({
|
|
|
402
406
|
);
|
|
403
407
|
}
|
|
404
408
|
|
|
409
|
+
// COST-4: a branch that changes the infrastructure says in the register what that costs. COST-5: one
|
|
410
|
+
// that takes an environment past its budget carries the person's cost approval, which the commit logs.
|
|
411
|
+
if (config.cost) {
|
|
412
|
+
const register = registerFile(config);
|
|
413
|
+
const infra = changed.filter((f) => matchesAny(f, config.cost.paths));
|
|
414
|
+
if (infra.length && !changed.includes(register))
|
|
415
|
+
found.cost.push(
|
|
416
|
+
`${infra.slice(0, 3).join(', ')}${infra.length > 3 ? `, and ${infra.length - 3} more,` : ''} changed the infrastructure, but ${register} didn't change. Say there what the change costs a month: a new or changed row for each paid thing it adds or resizes, or a Basis saying why the cost didn't move.`,
|
|
417
|
+
);
|
|
418
|
+
if (changed.includes(register)) {
|
|
419
|
+
const over = overBudget(
|
|
420
|
+
showAt(root, from, register),
|
|
421
|
+
showAt(root, 'HEAD', register),
|
|
422
|
+
config.cost,
|
|
423
|
+
);
|
|
424
|
+
const approved = entries.some((e) => e.file === register && e.approval === COST_APPROVAL);
|
|
425
|
+
if (over.length && !approved)
|
|
426
|
+
found.cost.push(
|
|
427
|
+
`${register}: ${overWords(over, config.cost.currency)}. Going past the budget is the person's call: bring them options that fit, each with what it gives up, and the cost of this one; their cost approval is recorded in ${APPROVAL_LOG} by the commit.`,
|
|
428
|
+
);
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
|
|
405
432
|
// REG-1: a fix's tests fail without it, as the bug.
|
|
406
433
|
const fix = fixes ? fixOf(root, branch ?? currentBranchOf(root), config) : null;
|
|
407
434
|
if (fix) found.regression.push(...proveFix({ root, from, base, changed, config, fix }));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@warren-dean/code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.33.0",
|
|
4
4
|
"description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Warren Langeveldt",
|
package/skills/decide/SKILL.md
CHANGED
|
@@ -55,7 +55,7 @@ For each, read the lane's change request (its report, in `.claude/state/reports/
|
|
|
55
55
|
|
|
56
56
|
## 4. The person's requests
|
|
57
57
|
|
|
58
|
-
A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI,
|
|
58
|
+
A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, a weakened test, or the running budget. A `cost` request (a commit over the budget, spec 29) is the person's under vibe too, and never goes to them bare: first look for what fits the budget (a smaller size, a cheaper tier or provider, one environment instead of two, a service the story can do without at launch), and send the lane back with it if one does. If none fits, ask them with each option that comes closest, what it gives up and what it saves a month, and the over-budget one with its cost (`code-kit ask … --option …`; under vibe, `--needs payment`). Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already waiting for the person, in their band and the pane's Needs you. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
|
|
59
59
|
|
|
60
60
|
## 5. Report
|
|
61
61
|
|
package/skills/init/SKILL.md
CHANGED
|
@@ -80,6 +80,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
|
|
|
80
80
|
- **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so most stories don't need the session's model. Recommend `story`: each story runs on the model its `**Size:**` in the plan gives (Haiku for small, Sonnet for medium, Opus for large), raised to Opus for a security requirement, to Sonnet at least for a fix, and one step for each time its branch is sent back. Offer one model for every lane (`sonnet`) as the simpler choice, and say the lead, the reviewer and the security reviewer keep their own models either way. A lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "story" } }`, or leave it out for the session's model. A project set up before sizes existed has stories with none, which run on Sonnet until the lead sizes them.
|
|
81
81
|
- **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their band and the pane's Needs you: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
|
|
82
82
|
- **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
|
|
83
|
+
- **`cost`, the running budget (spec 29):** from the brief's running budget, or ask the person if it has none: how much a month each environment may cost, in their currency, and the load to plan for. Write `"cost": { "currency": "AUD", "monthly": { "prod": 100, "dev": 20 }, "load": "500 users at launch", "paths": [...] }`. `paths` lists the project's infrastructure files, whatever defines them (Terraform, CDK, Pulumi, Serverless, SST, Docker Compose, Kubernetes or Helm, `fly.toml`, `vercel.json`, `netlify.toml`, `render.yaml`, `wrangler.toml`, `supabase/config.toml`, an `infra/` folder); a branch that changes one has to say in the register what that costs. Set `docs.costs` only if the register isn't `docs/costs.md`. The register is written by any agent (a lane costs the infrastructure its story adds), and a commit that takes an environment past its budget waits for the person's `cost` approval, whatever the config delegates. Show the budget with the rest of the setup.
|
|
83
84
|
- **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
|
|
84
85
|
|
|
85
86
|
### Standards (spec 22)
|
|
@@ -184,6 +185,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
|
|
|
184
185
|
- the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
|
|
185
186
|
- `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
|
|
186
187
|
- project standards, when the project has no `docs/standards.md`: suggest them as section 2's Standards describes, moving the engineering rules out of `docs/principles.md`, and protect the file.
|
|
188
|
+
- a running budget, when the config has no `cost` (whatever its `setup`): ask the person for it as section 2 describes. Then cost what's already defined in the infrastructure files, or deployed, into `docs/costs.md`, a row per paid thing at its real size, and run `code-kit cost`. When it's over the budget, bring the person options that fit (spec-design's architecture step lists the kinds), each with what it gives up and what it saves a month, and record their choice in the brief's decision log; the stories that bring it within budget go in the plan.
|
|
187
189
|
3. **Show the difference:**
|
|
188
190
|
|
|
189
191
|
```bash
|
package/skills/review/SKILL.md
CHANGED
|
@@ -58,6 +58,7 @@ Read the story and every requirement it cites. Then start from what's already be
|
|
|
58
58
|
It's refused when the screenshot isn't a PNG at the design's viewport (1x to 4x); take it again at that size. `verify`, and the merge queue, report every approved state of the branch's screens with no screenshot recorded since the screen last changed, so a branch that moves after your review is compared again. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
|
|
59
59
|
|
|
60
60
|
- **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
|
|
61
|
+
- **Running cost (spec 29):** where the config has a budget, a branch that changes the infrastructure files (`cost.paths`) changes `docs/costs.md` too (verify fails it otherwise). Read the two together: the size, tier and count in the code are the ones in the register's rows, every new paid thing has a row, and the estimate is for the load the spec gives, not a provider's production default. A mismatch sends the branch back, naming the file and the row. `code-kit cost` shows the totals against the budget and the prices to recheck.
|
|
61
62
|
- **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
|
|
62
63
|
|
|
63
64
|
## 4. The security review
|
|
@@ -51,6 +51,7 @@ Get the problem straight before any solution:
|
|
|
51
51
|
- **Users:** each kind of user or actor, including admins, other systems and scheduled jobs, and what each is trying to get done.
|
|
52
52
|
- **Outcome:** what's different when this works, and how anyone will know. Prefer something observable ("a new customer books without calling us") over a feature list.
|
|
53
53
|
- **Why now, and constraints:** deadline, budget, team, required platforms and technology, regulation and data residency, existing systems it must fit.
|
|
54
|
+
- **Running budget (spec 29):** how much a month the person will spend running it (hosting, databases, queues, outside services), for each environment they'll have (production at least; dev or staging only if they'll run), in their currency, and the load to plan for at launch (users, requests, data). 0 is a real answer: free tiers only. It shapes the architecture as much as any requirement, so ask it in the first round, and record it in the brief.
|
|
54
55
|
- **Non-goals:** what this deliberately won't do. Ask for them; they are as useful as the goals.
|
|
55
56
|
|
|
56
57
|
Write `docs/brief.md` as soon as the frame is agreed, with `Status: framed`, and keep it current from then on.
|
|
@@ -107,7 +108,9 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
|
|
|
107
108
|
- how the quality targets from phase 3 are met;
|
|
108
109
|
- **recipes**: under `## Recipes`, a `### <recipe-name>` for each layer's common addition (a new screen, endpoint, migration, domain service, job): the steps in order, the files each step creates or changes, and how it's tested. Each becomes a project skill when init sets up the lanes, so every lane agent builds the same thing the same way;
|
|
109
110
|
- the **design tool** for screens, when there are any: the one the person uses (Paper, Figma, Pencil), or design files under `design/` when they have none.
|
|
111
|
+
- the **running cost** of each shape you propose (spec 29): every paid thing (a database, a container, a function's invocations, a queue, a domain, an outside API), its provider, the size or tier, and its monthly estimate at the expected load, per environment, from the provider's published pricing, with the page and the date you read it. Size for the load the brief gives, not for a provider's production default: one small instance before a cluster, a free or starter tier before a dedicated one, managed services that scale to zero before ones that run all the time, no standby, NAT gateway or second region unless a quality target needs it. At least one shape fits the budget. When the one the person prefers doesn't, say by how much, and offer options that fit (a smaller size, a cheaper tier or provider, one environment instead of two, a service the product can do without at launch, less scope), each with what it gives up; the person picks.
|
|
110
112
|
Propose the architecture from the specs and constraints, explain the choices, and ask about the ones that matter. Record each in the decision log.
|
|
113
|
+
- **`docs/costs.md`:** the chosen shape's costs, one table whose header is `| Item | Provider | Environment | Size | Monthly | Basis |`: a row per paid thing; Environment one the budget names, or `all`; Monthly a plain number in the budget's currency; Basis the pricing page and the date (YYYY-MM-DD). `code-kit cost` adds it up once init has written the budget. Write it before the plan: a design over the budget isn't planned.
|
|
111
114
|
- **`docs/standards.md`:** the engineering rules, each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why` and `source` lines, the id's prefix its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Draw them from the architecture (an `ARC-` standard for each layer rule, `enforced by: layers (<layer> may not import <layer>)`), the threat models (a `POL-` standard for what must never happen to sensitive data), and the decisions; cite each one's source. Propose them and ask about each: a standard is a guardrail, so the person decides it. Init checks the file and protects it.
|
|
112
115
|
- **`docs/principles.md`:** the privacy and data residency targets from the brief (where data may be stored and processed, what is never logged), which the security reviewer checks against; what counts as a contract; the definition of done (tests, checks, reviews, end-to-end working features); the test, lint, typecheck and database commands once they're known; and which commands only CI or a person may run, such as deploys.
|
|
113
116
|
- **`docs/plan.md`**, from `${CLAUDE_PLUGIN_ROOT}/templates/plan.md`:
|
package/templates/agent.md
CHANGED
|
@@ -26,6 +26,7 @@ Always:
|
|
|
26
26
|
- Write only in your owned paths. For anything else, write a short change request for the lead and stop.
|
|
27
27
|
- You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
|
|
28
28
|
- A new dependency needs the lead's approval. Before asking, check the project doesn't already have something that does the job. If the install is refused, put in a change request for the lead: the package, the story and requirement that need it, what you checked, and anything lighter that would do; then stop. The lead approves it, or tells you what to use instead.
|
|
29
|
+
- {{if cost}}The project has a running budget. When you add, remove or resize anything that costs money to run (a database, a container, a function, a queue, an outside service, a plan tier), change its row in `{{docs.costs}}` in the same branch: the item, provider, environment, size, its monthly estimate as a number, and the pricing page and date you read it. Size it for the load the spec gives, not the provider's production default. A branch that changes the infrastructure files without the register fails verify. If your commit is refused for going over the budget, don't look for a way round it: hand the lead a change request with what you need, what it costs a month, and the options that fit, each with what it gives up.{{end}}
|
|
29
30
|
- Build every feature end to end. No mocks, stubs, placeholder screens or "coming soon".
|
|
30
31
|
- A screen is built to its approved design: the brief names every state's image and code under `design/`. Read each before you write the screen, match its layout, copy, spacing and states, and build it from the project's components rather than pasting the export. Your report lists each state with what you built for it.
|
|
31
32
|
- Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
|
package/templates/claude-md.md
CHANGED
|
@@ -15,6 +15,8 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
|
|
|
15
15
|
|
|
16
16
|
{{if vibe}}Product and UX are yours: what the spec leaves open, a screen's visual design, the wording, what to build next. Answer from the brief, the specs and the principles, and record each product decision in the brief's decision log with why. Build everything that doesn't need the person, and stop only for what nobody else can give: an account with a service provider, an API key or secret from one, a payment, or an act outside the repository (DNS, an app store). Ask for it with `code-kit ask "<what you need, and what it's for>" --needs account|key|payment|outside` (`--story ST-n --blocks` holds the story until they answer), and carry on with everything else meanwhile, against a local or test stand-in where there is one. Lanes don't ask the person: they write the question for the lead.{{end}}
|
|
17
17
|
|
|
18
|
+
{{if cost}}The project has a running budget the person set, per environment, and `{{docs.costs}}` estimates what each paid thing costs a month; `code-kit cost` adds it up against the budget. Design and review to it: size each service for the load the spec gives, not a provider's production default. In review, check a branch that changes the infrastructure against its register rows: the size in the code is the size in the row, and every new paid thing has one; send it back otherwise. Going past the budget is always the person's call, under vibe too: a commit that does is refused until they approve `cost`. Before asking, find options that fit (a smaller size, a cheaper tier or provider, fewer environments, less at launch), and ask with `code-kit ask "<what's over, and by how much>" --option "<option>: <what it gives up, what it saves a month>"`, the over-budget choice among them (under vibe, with `--needs payment`).{{end}}
|
|
19
|
+
|
|
18
20
|
{{if standards.all}}The project's standards, in `{{docs.standards}}`: {{standards.all}}. Each lane is given the ones for its layers. In review, check each changed file against the checked standards for its layer (`code-kit standards --for <file>`): a broken required one sends the branch back, naming the standard; a broken recommended one is a concern, and advice at most a nit. Adding a recommended standard may be yours where the config delegates the `standards` approval; removing one, or weakening a required one, is always the person's.{{end}}
|
|
19
21
|
|
|
20
22
|
- {{if harness.report.on}}When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.{{end}}
|