@intentius/behold 0.14.0 → 0.16.0

package/AGENTS.md

@@ -54,6 +54,13 @@ preview-locked, and one load runs at a time (409 otherwise).
    per-node observed state, drift and field ownership; `/api/reconcile?env=`
    summarizes the pending change set; `/api/substrates` reports substrate
    readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`.
+   With `?components=1&env=`, each component node carries `_liveStatus` (the
+   `chant components status` verdict) and, when the release ledger recorded
+   one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
+   timestamp, actor, approver?}` (#165). `url` is present only when the record
+   itself carries an address (chant#2045); `originSource: "inferred"` means
+   behold read the id's spelling and nothing more, and a `forge: "unknown"` id
+   is never resolved to a link on behold's guess.
    `?ops=1` is the ops lens — the project's declared Ops as a phase track, read
    from each emitted `dist/ops/<name>/op.json`, with the current run painted
    over it (`meta.run`, `meta.gate`); `/api/ops/<name>/status` reads that Op's
@@ -164,6 +171,33 @@ and nothing else about the run is behold's to decide: a stream that dies leaves
 the playhead at the last settled step and says so, and a gate paints as pending
 only when chant's `gateState` query named it.
 
+### The executor contract (#165, #61)
+
+`.behold.json` may designate which forge deploys an environment:
+
+```json
+{ "executor": { "prod": { "forge": "github", "workflow": "deploy-prod.yml" } } }
+```
+
+It designates the committed WORKFLOW, not just the forge: two environments'
+generated pipelines carry identical job ids, so a picker cannot tell them
+apart, and a contract that names prod must not sit on a guess. For a
+designated env, `POST /api/apply` and a committed ApplyOp's `/api/ops/:name/run`
+answer `409 {code: "executor-forge"}`, auto-sync declines out loud, and the
+only deploy is `POST /api/ci/dispatch?env=<env>`, which runs the designated
+workflow through the operator's own `gh` and follows it on the dial. Any
+approval the workflow's environment requires is granted on the forge by a
+GitHub identity behold does not have; the dial links the run's page and offers
+nothing else. Fail-closed: a designation behold cannot honour (a typo'd forge,
+a missing or non-dispatchable workflow, a forge with no trigger here) disables
+Deploy for that env with the reason on `/api/project`'s `executor` block, and
+never falls back to running it here. `/api/project` reports `{forge, workflow,
+ok, reason?}` per designated env.
+
+Without a designation, dispatch picks the committed workflow named for the env
+(`chant-components-<env>`, chant ≥ 0.54.0) and refuses a tie on the older
+job-overlap match rather than letting directory order choose.
+
 ## The operating loop (a strip, a timeline, and a gate that is not the run gate)
 
 A project that declares a `ConvergeOp` gets an operator strip on the ops lens:
@@ -257,3 +291,39 @@ own Terraform is not edited either. The only request-derived value is `select`,
 and it must be an address the served report already ranks — the value that
 reaches the spawn's argv comes from a closed set read off disk. No cloud write,
 no Terraform mutation, no edit to anyone's chant source.
+
+## Changing behold (for agents working on this repo)
+
+The sections above are about driving a running behold. This one is about
+changing it — the working rules that used to live in a handoff note and now
+live here, with the enforceable ones enforced.
+
+- **Branches and merges.** Work on a branch off `main` (an isolated worktree
+  when more than one agent is active). `main` is protected by a ruleset: every
+  change arrives as a PR, and the `check` job in `ci.yml` must be green before
+  it merges. A check that has merely settled is not a pass — read the lines.
+  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
+  next onto what landed.
+- **The local gate** is `just check` (tsc, tests, build). `just test` keeps
+  the reporter's full output in `vitest.log`, because #334's one-shot
+  first-run failures kept losing the failing file's name — if the suite fails
+  once and passes on rerun, the log from the first run is the evidence; attach
+  it to #334.
+- **Releasing** is `just release`, after the version-bump PR merged: it tags
+  `behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
+  waits for npm to show the version. It refuses in every state where a tag
+  push would be wrong. Never re-push a `behold-v*` tag by hand — a tag push
+  re-fires publish. Tags absent from origin (behold-v0.10.0, 0.10.1) stay
+  absent for that reason.
+- **Scratch infrastructure** is governed by `src/scratch.ts`, asserted by
+  `scratch.test.ts` across every boot site: anything behold boots is named
+  `behold-*`, refuses if the name is taken, tears down only what it created,
+  and never binds the shared emulator ports. The protected names — `floci*`,
+  `chant-floci*`, the kubemicrovm and fountain k3d clusters, :4566 — are
+  listed there, not in prose. A new boot site calls `assertScratch` before
+  its spawn and gets a row in the test.
+- **The write boundary** is the Invariant section above. Apply is never a
+  button; `/api/carve/apply` does not exist and the route test asserts it
+  stays that way.
+- **chant's working rules** (its single-lane checkout, its release path) are
+  chant's and live in chant's repo, not here.