[hhff]

PR 4 of 5 for the inspectable OODA loop (spec and plan in #193). Stacked on #201 (base ooda-lineage).

Adoption gate: merge only when every instance has v0.37.0 or later

This PR adds two top-level log fields, decision.knowledge and act.knowledge. A kit older than v0.37.0 (#193, reader tolerance) refuses lines carrying them. Workers never write decisions or worker-slots acts, so a stale worktree doesn't matter; only a whole instance on an older kit does. On the Render box today:

instance	upstream_base
stacks	v0.39.0
website	v0.39.0
mothership	v0.37.1
stacksbot	v0.33.2: must adopt v0.37.x first

What changes

• A decision cites the knowledge it rests on. decide --on <k-…|p-…>… stores decision.knowledge. It is never copied into refs, and authorise never reads it, so it grants nothing. It is refused for:

  • an unknown id, or one that isn't knowledge or a problem
  • a candidate or retired lesson
  • an id that is also in --refs
  • a bare --on, or more than 60 ids

  The decision sidepeek lists what it rests on, in each record's own words. Lineage draws "rests on" edges.

• A start records the lessons it was given. A fresh worker or planner start's worker-slots act carries knowledge: the ids knowledgeFor put in its prompt, newest first, at most 60. It is recorded only when the final resume is false, because a resumed session never reads the new prompt, and it is omitted when empty. The act sidepeek shows "What its instructions carried". Lineage draws lesson → start → ticket. This record is what makes a lesson's effect measurable (PR 5).

• Orientation debt: what fixed incidents taught. ooda.debt.incidents lists incidents that are resolved within 30 days, have an outcome citing them, and aren't cited by any knowledge's evidence or by a live orient-noise ruling. Incidents whose status the owner set are excluded. orient prints each one with a suggested knowledge add --evidence <p> <d> <outcome> (values shell-quoted), and the Orient tab lists them under the signals. orient-noise now accepts a problem id ("nothing to keep").

• Docs: supervisor.md §3 (--on, starts' knowledge, incident debt) and spec §3.

For the operator's review (#190 follow-up)

The review can read:

• log --json → decision.knowledge and act.knowledge
• dashboard-data → ooda.debt.incidents

orient --json is unchanged, because readers count its list as the recurring signals.

Tests

test/ooda-knowledge.test.mjs covers:

• --on: each refusal, authority left unchanged by --on <owner standing rule>, and the lineage edge
• real worker and planner starts in the fixture's private tmux: one lesson, none, a resume, 61 lessons capped to 60 (line under 4,096 bytes)
• incident debt: listed, cleared by a lesson, cleared by a ruling, absent with no outcome

The G1 golden is re-recorded; only "incidents": [] was added. Full suite on Node 24: 416 of 417 passed, with 1 existing skip.

One-way doors

None. The two new fields are additive (constitution §4), behind the adoption gate above.

🤖 Generated with Claude Code

[hhff]

Fable reviewed it and found no authority hole: nothing reads knowledge as authority, act refs are unchanged, and the new fields are top-level and supervisor-only. Findings fixed: an edge reads "rests on" only for accepted knowledge or a problem, a lesson's status is shown, "What it drew on (not its authority)", and --on is deduped. CI 9/9 at cfcd8d9 with main merged in.