diff --git a/AGENTS.md b/AGENTS.md index 7ef43d2..6ed3033 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,8 +16,8 @@ used elsewhere in the ops-djbclark suite (e.g. `site-private/memory/`): separate "ok to push" prompt. - This exception is narrow: `docs/handoffs/` only. Ordinary code/doc changes in this repo go through the standing rule below (a PR with a - cross-model frontier review); this file doesn't blanket-authorize - pushing arbitrary work. + cross-model review whose depth is tiered by what the change can break; + rule 3); this file doesn't blanket-authorize pushing arbitrary work. ## Standing rule: most important work — be pedantic, pay for the best models (2026-10-31) @@ -59,15 +59,94 @@ path cannot preserve these checks, hold the review and report the missing check. `route_agent.py plan` picks, through `/bigteam`. Never use a weaker tier (GLM, Gemini Flash, Cursor Auto, `gpt-6-luna`) in these repos. A slice climbs a tier only on evidence of failure. -3. **Review is cross-model, never same-model.** An Opus review of Opus work is +3. **Review is cross-model, never same-model, and its depth is tiered by what + the change can break.** An Opus review of Opus work is one model with a fresh context, not an independent check. No PR merges on a review by the model family that wrote the change. For Opus- or Sonnet-authored work, astra, Fable or Argon count; for a Codex-authored - slice, Fable or Argon count. - - Every PR, docs-only included (this rule's own PR was reviewed this way), - gets one frontier review before merge. `docs/handoffs/` commits are not - PRs and keep the push-in-place exception above. Try the reviewers in this - order: + slice, Fable or Argon count. Operator ruling, 2026-11-14, B10: "1. Spike + lane, 2. Tiered review, 3. Docs freeze" (options O1, O2 and O4). **O6 was + not chosen** and O5 (dogfood the gate) was not asked; neither is in force. + - **Tiered review (O2).** Operator ruling, 2026-11-14, B10 (record line + L22): O2 is "tiered review (light for docs and spike notes, one frontier + review for device code, two for root/trust-root/key/handshake code)". + **Light** review for docs and spike notes; **one frontier review** for + device code; **two frontier reviews** for root, trust-root, key and + handshake code (the two are the independent astra-and-Fable pair + described under design rulings below). This supersedes the earlier text + "Every PR, docs-only included, gets one frontier review before merge" + (this rule's own first PR was reviewed that way). + Who may perform a light review: "2. Cheaper reviewer allowed" (operator + ruling, 2026-11-14, PR 62 review Q2; record line L58): any model outside + the author's family that is not on the weaker-tier ban list in rule 2 + (GLM, Gemini Flash, Cursor Auto, `gpt-6-luna`) may perform a light + review; if the reviewer is a frontier model, the frontier checks (the + frontier allowance, fresh quota readings, estimate floors and caps, + reservation and admission) still apply to that launch. + Lead and reviewer reading of Q2, **not part of the ruling**: the + cross-model rule above is what says which families are "outside the + author's family", and it implies that Opus and Sonnet are one family + (an Opus review of Sonnet work, or the reverse, is not outside it), + while Fable, astra and Argon count as outside it for Opus- or + Sonnet-authored work. "Light" changes the depth and scope of the review. + It does **not** waive model routing, quota readings, reservation or + admission rules. + **Lead notes in force until the operator rules otherwise.** The three + notes below (the light-docs limits, the spike-workflow hardening worded + under the spike lane, and the compiler, CI and tooling tier) are lead and + reviewer text that is not part of the O1, O2 or Q2 rulings (except that + limit (a)'s widening below is L64's own wording). They are "in force as + lead practice until djbclark rules otherwise" (operator ruling, + 2026-11-14, PR 62 round-2 review, L64: "1. In force + widen"). Where this + file says "not part of the ruling", that means the text is not the + operator's wording; it does not mean the text is not in force. That + sentence covers only these three notes and the readings this file labels + as readings (the Q2 family reading above, and Android item 5), all of + which only tighten. Those two readings are in force as lead practice, on + the lead's authority; L64 covers only the three notes. A reading that + loosens a rule needs an operator ruling; it is not in force on this + file's say-so. + 1. **Four limits on what counts as "light docs"** (limit (a)'s widening is + the operator's own L64 wording; limits (b) to (d) are lead practice, in + force per L64). (a) Not light (operator ruling, 2026-11-14, PR 62 + round-2 review, L64): **every edit to this file, in any section**, and + every doc that defines or instructs privileged, trust, consent, key, + deploy or enforcement behaviour (an open "including ..." list, not a + closed one). Such an edit takes **at least one frontier review, and two + if the PR changes a design ruling** (the design-ruling tier below). L64 + names no files; the lead's current examples are the architecture map's + trust, consent and privilege sections, + `docs/architecture/change-process.md`, + `docs/architecture/linux-targets.md` section 3, + `docs/architecture/nixos-passthrough-plan.md` and + `docs/architecture/tendcf-validate-proposal-2026-11-03.md`. (b) A PR that carries a design + ruling takes the design-ruling tier below. (c) A mixed PR takes its + highest tier. (d) Policy run by a root `cf-execd` counts as root code. + 2. **Spike workflow hardening** (lead practice, in force per L64): see the + spike lane below. + 3. **Compiler, CI or tooling PRs keep one frontier review** (lead practice, + in force per L64; the operator was not asked this sub-question when + ruling O2). A PR that is neither docs, a spike note nor device code + (compiler, CI or tooling, say) keeps the one frontier review this rule + required of every PR before 2026-11-14. + - **Spike lane (O1).** A `spike/*` branch is never merged, so it gets no + frontier review. Each spike runs on a real, non-production device and + leaves a one-page note, which is reviewed under the light tier. What a + spike proves is then built in a normal PR that takes its own tier. + Safety rails, word for word from the option the operator chose (O1, + `docs/review-2026-11-13/13-premortem-and-ideas.md` X-pm-07): "a spike + never runs as root on the daily-driver Mac and never on pastebin. It runs + only on a test phone, a spare Mac or VM, or as an unprivileged user. It + touches no real secrets and no keys used elsewhere." + Hardening added by the lead and reviewers on PR 62, **not part of the + operator's ruling O1**, and "in force as lead practice until djbclark + rules otherwise" (operator ruling, 2026-11-14, PR 62 round-2 review, L64): + a spike workflow runs with `permissions: contents: read` and no secrets. + - **Docs freeze (O4).** No new design doc is written for a state-1 piece + until a spike for that piece has run. + - A PR that needs a frontier review gets it before merge. `docs/handoffs/` + commits are not PRs and keep the push-in-place exception above. Try the + reviewers in this order: 1. Astra: Codex provider, `gpt-6-astra`, `high`. 2. Fable: Claude provider, its current Fable frontier model, `high`. 3. Gemini 4 Argon: Antigravity provider, `gemini-4-argon`, `high`. @@ -78,7 +157,7 @@ path cannot preserve these checks, hold the review and report the missing check. Plan each review with `~/src/djbclark-ade/bin/route_agent.py plan --kinds frontier --repo tendcf --json`. Keep the reviewer order and model-family independence above; a non-frontier model - cannot satisfy this rule. Re-plan immediately before admission and launch. + cannot satisfy a frontier review (it may do a light one, above). Re-plan immediately before admission and launch. Record the reason `tendcf standing rule: cross-model review` in the brief and admission evidence. @@ -127,8 +206,9 @@ path cannot preserve these checks, hold the review and report the missing check. comparison alone did not establish that astra was short. Only fresh quota, fit and admission evidence establish availability. - Design rulings (a `schema_version` bump, the privilege or enforcement - scope on a host, a deploy plan, the unit-writer or consent-diff design) - get two independent frontier reviews, astra and Fable. Argon stands in + scope on a host, a deploy plan, the unit-writer or consent-diff design), + and root, trust-root, key and handshake code (O2, above), get two + independent frontier reviews, astra and Fable. Argon stands in for one of them and never counts twice. With both astra and Fable short, take the Argon review now and wait for a reset for the second. A disagreement goes to djbclark, not to the lead to settle. @@ -138,8 +218,9 @@ path cannot preserve these checks, hold the review and report the missing check. - The additional adversary round still runs where the current ADE workflow calls for it, using an eligible judgment route. It never counts as the cross-model frontier review and must not revive the retired omp client. - - The PR body names each reviewer model and effort, quotes the verdict (or - "no findings") and lists what was fixed. + - The PR body names each reviewer model and effort (for a light review, + the reviewer and the tier), quotes the verdict (or "no findings") and + lists what was fixed. 4. **Limits that still hold.** Preserve the effective frontier allowance and per-wave caps from ADE's `config/gates.toml [frontier]`, estimate floors/caps, headroom and in-flight reservation accounting. The 20-point @@ -253,8 +334,14 @@ a book: `site-private/AGENTS.md` ("Book knowledge base"). `SKIP (loader not all-or-nothing): `, never passes silently, and the run is expected to pass with SKIP lines and a count (not yet run on the Mac: derived from the parser behaviour). The Mac dev build stays a target - (operator, 2026-11-14, "keep Mac, SKIPs"). The Linux CI legs set - `TENDCF_REQUIRE_FORK_LOADER=1`, which makes a skip a failure. Run it through + (operator ruling, 2026-11-14, B11 round 2 item 2, adversary D1 / Astra r2 B3: + "1. Keep Mac, SKIPs"). The Linux CI legs set + `TENDCF_REQUIRE_FORK_LOADER=1`, which makes a skip a failure. Follow-up of the + same ruling: assertions that hold only with the strict loader (the + `strict_case` policy refusals) are gated the same way, so a non-fork run + passes with SKIPs rather than failing (implemented in the base: the + `strict_case` calls with POLICY `fork` go through `fork_only` in + `tests/policy/run.sh`). Run it through `~/ops/site-private/bin/bg`. Two checks are opt-in because they reshape the host and need root: `TENDCF_TEST_SYSTEMD=1` (check 6, the real-systemd lifecycle; the ubuntu VM jobs) and `TENDCF_TEST_NIXOS_SHAPE=1` (check 7, @@ -278,6 +365,86 @@ a book: `site-private/AGENTS.md` ("Book knowledge base"). - Plan and status: `docs/architecture/linux-targets.md` §3; the NixOS side in `docs/architecture/nixos-passthrough-plan.md`. Live hosts: pastebin (root install, canary enforced), get.sipb.cloud (module installed, nothing scheduled). +- **macOS check 8 of PR 52 (gate 2) ran on WarpBuild (historical gate).** + Operator ruling, 2026-11-14, PR 52 gate 2: "let's finish the codewarp setup + and then try running on their fastest mac setup". `frdminc/tendcf` is added + to WarpBuild runner group 1 (the app already sees all repos); the spike + branch `spike/macos-check8-warp` builds the fork pin on + `warp-macos-26-arm64-12x` and runs `tests/policy/run.sh` (worker 68cf038a). + The ruling's original gate text was: "Merge of PR 52 waits on that run." + Outcome, 2026-11-14: the run ("macOS check 8 spike (WarpBuild)", branch + `spike/macos-check8-warp` at 299f219, [run + 43602684071](https://github.com/frdminc/tendcf/actions/runs/43602684071)) + completed with conclusion success, and PR 52 merged at 2026-11-14T14:29:23Z + (merge 2c78680). Like every spike branch (rule 3, spike lane) the branch is + never merged. +- **PR 52 follow-ups: three issues and one tracker.** Operator ruling, + 2026-11-14, PR 52 follow-ups 1-8: "1. 3 issues + 1 tracker". Filed the same + day, each linking PR 52: item 2 (install data skips the projector) is + [frdminc/tendcf#53](https://github.com/frdminc/tendcf/issues/53), item 3 + (projector filter scope) is + [frdminc/tendcf#54](https://github.com/frdminc/tendcf/issues/54), item 4 (re + `$` before a trailing newline) is + [frdminc/tendcf#55](https://github.com/frdminc/tendcf/issues/55), and the + tracker, with checkboxes for items 1 and 5-8, is + [frdminc/tendcf#56](https://github.com/frdminc/tendcf/issues/56). + +## Android work: ShizukuTendCF builds (2026-11-14) + +Operator ruling, 2026-11-14, Smaller 1 (ShizukuTendCF fleet-signer override, +C-android-03): "2. Dev mode + separate dev build" (the operator first asked +"Is there a way we could make this of equal high convienience to everyone? +Maybe have a development mode and/or build?"). + +1. **Every build has a developer mode, open to any owner:** an owner-enrolled + standing approval for a signer of the owner's choice (the B2 mechanism); + revoke and deny are always honoured; a persistent indicator shows the mode + is on. +2. **A separate developer build** exists for tendcf contributors' test + devices. It keeps the ignore-revoke override. It is never the published + public build. +3. **Build only the appropriate flavour.** Operator ruling, 2026-11-14, + Smaller 1 rider: "We don't have to always do both builds when in + development, just the modt [sic] appropriate one for any given situation." + A development task builds and tests only the flavour that fits it (the + public build with developer mode, or the dev build), not both every time. +4. **Reading of the ruling, not new policy (adversary review of PR 62, finding + 5):** nothing in the ruling yet keeps the ignore-revoke dev build from + shipping as the published build. A distinct `applicationId`, a distinct + signing key, and a release pipeline that refuses the dev flavour are + **recommended follow-ups, not ruled**. +5. **A reading of the ruling (L5, B2), not part of it (adversary review of PR + 62, finding 4; wording: lead decision, PR 62 round-3 review):** a standing + approval drops only the per-change nonce (DC-2's device nonce); it is signed + by an owner-held trusted key and keeps B1's other content checks (signed by + trusted keys, fresh, names this device) and the rest of DC-2 (per-target + validity, monotonic-counter single use or high-water mark, persisted + rejects); its ceremony class is still checked against the validator's + derived requirement (§9.8); until the operator rules, a standing approval + covers `ordinary` changes only; whether one may cover `privileged` or + `baseline` changes is for the schema design review to propose and the + operator to rule; it names its signer and algorithm only if X-trust-06 is + adopted (proposed, not ruled); every standing mode (hold window, standing + approval, standing "wait for user", standing refusal) is owner-enrolled and + refusable, and none is a default; dropping any other check needs an operator + ruling; the schema design review confirms the approval-record shape. + +## Licensing: the review TUI is AGPL-3.0-only (2026-11-14) + +Operator ruling, 2026-11-14, B12: "2. Borrow both freely; raise Python" (first: +"I am thinking 2, May 26th isn't that long ago, but see if there are any +important ignored issues or other traffic in the repos. AGPL is a fine license +for us, as long as it doesn't prevent us from using any other code we need."). + +1. Toad and textual-diff-view (AGPL-3.0) may be borrowed as needed. The review + TUI becomes **AGPL-3.0-only** and moves to **Python >=3.14** (Toad's floor; + Toad pins `textual==8.2.7`). +2. **Keep licences that AGPL-3.0 cannot combine with out of the TUI module**: + GPL-2.0-only, CDDL, EPL-2.0 without a secondary-licence designation, and + proprietary code. Nothing tendcf uses today is affected (the licence + research note, which is not in this repository, found no security or + licence red flags). +3. Follow-ups: check that Python >=3.14 is available on Termux and on the Mac. ## Editing in a worktree: absolute paths only (2026-10-31) diff --git a/docs/architecture/architecture-DEFINITIVE-v3.md b/docs/architecture/architecture-DEFINITIVE-v3.md index 4be25c4..c74c5e3 100644 --- a/docs/architecture/architecture-DEFINITIVE-v3.md +++ b/docs/architecture/architecture-DEFINITIVE-v3.md @@ -11,7 +11,21 @@ guide disagree on the current design, **the guide wins**. Numbered v1/v2 files, panel drafts, and the v2 trust spec are archival — see `deprecated/README.md`. -- **Date:** 2026-08-15 (§9 rewritten for Model B; D43/D44 added) +- **Date:** 2026-08-15 (§9 rewritten for Model B; D43/D44 added); + amended 2026-11-14 (operator rulings of the goal review written in: + D47–D50 added; §0, §1, §2 (R4, R5), §5, §6, §8, §9.1, §9.6, §9.11, §11, + §12, §13, §17, D6, D8, D12, D14, D16, D18, D22, D45 and D46 amended; new + §9.12, the safety score). Rulings are quoted as + `operator ruling, 2026-11-14, `; the full proposals are in + [`../review-2026-11-13/`](../review-2026-11-13/README.md) and the + rulings record is + [`../review-2026-11-13/rulings-record-2026-11-14.md`](../review-2026-11-13/rulings-record-2026-11-14.md). + Corrected the same day to the merged state (schema v6, PRs 52, 42 and + 41 merged); items not decided are marked "open" (only the AI reviewer + "up to 30" count still is, marked "open: deferred to the schema design + review (operator ruling, 2026-11-14, PR 62 review Q7)"; Q1-Q6 of PR 62 are + ruled, including the G4 sentence, Q5, and the reviewer-proposed map text, + Q6). - **Tracker:** frdminc/tendcf#1. This document describes the **current design and what is planned next**. @@ -25,18 +39,37 @@ cannot start its own privileged helper”). ## 0. Orientation for the AI that implements this -1. **This is a freedom project.** Interesting and correct beats minimal - and safe when they conflict. Token spend is the cost that matters - (§13). +1. **This is free software for people who want control of their own + devices.** Correct beats interesting; when correct and safe conflict, + stop and ask (item 5). Development cost is secondary to getting it + right (operator, 2026-10-31). A user's own AI token cost at run time + is a design constraint (R12). (Replaces "This is a freedom project. + Interesting and correct beats minimal and safe …"; operator ruling, + 2026-11-14, Smaller 2 (M-§0-02), "1. Adopt the proposed text".) 2. **The reference target is a stock Linux distro on bare metal**, not NixOS. Nix is used for builds, as one of two equal Site Model authoring languages, and verbatim on hosts that already run NixOS or nix-darwin (D12, [`linux-targets.md`](linux-targets.md) §5) — never as the installed OS a stranger must adopt. Ubuntu Server LTS is the working - default; the distro name is open until Step 4. -3. **The trust/consent layer is the point.** A person should understand a - proposed change in ordinary language, refuse it, and keep a personal - branch — using **their** AI, not ours. + default; the distro name is open until Step 4. (Platform order is + D48, not this item: macOS first, Linux fourth and fifth; Nix is first + among authoring languages, D49. This item's Linux statement holds for + Linux hosts; operator ruling, 2026-11-14, B4, "1. Adopt D47-D50".) +3. **The aim is an adoptable tool that gives people control of their own + devices** (goal G1, + [`00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md)). + A person works through their own AI or directly in code, whichever + they prefer at the moment. The safety mechanism is see-and-refuse + (G4): nothing changes a device except as an exact, mechanically + checked difference that its owner can see and refuse. Measure every + step against the finish line (G8). State 1 comes first: one Mac and + one Android device converge from Nix-authored config, accept updates + only after the handshake, and archive logs on the Mac. (Replaces "The + trust/consent layer is the point."; D47 supersedes it and item 1's old + wording: operator ruling, 2026-11-14, Smaller 3 (M-§15-01), "1. Yes, + supersede D8's wording"; text from M-§0-01. The trust layer stays, as + G4's mechanism; a person still keeps a personal branch using **their** + AI, not ours, §11.) 4. **Facts live in site data; behavior lives in tendcf.** Every tool (CFEngine, mise, Nix-for-builds, `tendcf-validate`, tendcf-agent) is a replaceable consumer. @@ -91,8 +124,10 @@ cannot start its own privileged helper”). ▼ JSONL log (capture) append-only; the durable record - SQLite (index) rebuildable from JSONL; tendcf-agent on - Android, owner open elsewhere (§12) + SQLite (index) rebuildable from JSONL; one per device, + plus a fleet-wide one on the log archive + (§8); owner: tendcf-agent on Android, open + elsewhere (§12) ``` Collision of the same identity from two peer inputs is a **compile @@ -106,6 +141,8 @@ error**. Only site-private may bind a winner or a short name. Android (Termux + tendcf-agent + a Shizuku-class helper). Intel Mac mini out of scope. tendcf-agent is Android-only; Linux and macOS run CFEngine plus the `tendcf-validate` command, with no daemon (D45). + Platform order: D48 (macOS as server, Android as client, macOS as + client, Linux as server, Linux as client). - **R2** No permanent control node. Feature roles `{main, backups[], peers[]}` are data. - **R3** Resource efficiency; no fat containers; no VMs as the build @@ -113,8 +150,17 @@ error**. Only site-private may bind a winner or a short name. - **R4** Android keeps Termux (+api, +x11), the built-in Terminal app, a Shizuku-class helper, tendcf-agent (Kotlin, D45), CFEngine. No nix-on-droid. Nix may build zero-on-device-footprint artifacts only. + tendcf never holds a DPC slot (profile owner or device owner) and never + requires MDM enrolment; it works with Island/Insular through shell + (`--user N`) and the owner app's API (operator ruling, 2026-11-14, B3 + sub 3 (X-android-09), "1. Never"). - **R5** No bare-metal Nix. A mainstream stock distro is the reference. - Ubuntu Server is the default answer, not the requirement. + Ubuntu Server is the default answer, not the requirement. **Amended + 2026-11-14:** Nix may be required to build a release (operator ruling, + 2026-11-14, B4 rider, Nix on release path, "2. Allow on release path"), + scope "1. Build-time only": devices never need Nix at run time. What + R5 forbids is Nix or NixOS as something a device or a stranger must + install; the change-process §2 amendment is in that file. - **R7 / R10** Push and pull. Pull becomes user sovereignty: the person’s own AI, suggested default prompt plus their extras, auto-review or a conversation. Generic layer publishable (GPL-3.0-or-later for code). @@ -286,11 +332,15 @@ repository is archived), and in the restructure its command becomes `tendcf compile`, which replaces `nix2cf buildfile` with no alias. The name `nix2cf` moves to the Nix module frontend (D12). Frontends, supervisor renderers and importers are plugins, all compile -time only. Third-party frontends and importers are to be found through +time only. ~~Third-party frontends and importers are to be found through the public Python entry-point groups `tendcf.frontends` and -`tendcf.importers`; plugins in this repository are to be found through a -static import table, never through entry points (planned, restructure -step 4; no loader exists today); supervisor renderers are in tree only. Plugins are trusted build-time code the +`tendcf.importers`~~ (**amended 2026-11-14, D46:** all plugins live in +tree and run only at compile time, never on a device; Python +entry-point discovery of out-of-tree plugins is deferred until a user +needs one and out-of-tree plugins can be pinned); plugins in this +repository are to be found through a static import table, never through +entry points (planned, restructure step 4; no loader exists today); +supervisor renderers are in tree only. Plugins are trusted build-time code the operator explicitly allows, not sandboxed: a plugin cannot make a device accept anything that device's own diff does not show (on Linux and macOS that is `tendcf-validate`, planned, D45), and cannot emit a shape the schema forbids, @@ -307,6 +357,13 @@ CFEngine’s [Masterfiles Policy Framework](https://github.com/cfengine/masterfi already consumes that data layer. Common case: emit data, not `.cf` text. Merge once in the compiler; do not also use `mergedata()`. +**Carry-over from other tools (B7).** Operator ruling, 2026-11-14, B7, +"1. Importer + matching names": a one-shot importer for pure-data option +families (it lists what it did not carry), plus tendcf option names that +match nix-darwin and NixOS where the meaning is the same. Ruled; +implementation pending (full text: X-nix-02 and X-nix-05 in +[`08-nix-ecosystem.md`](../review-2026-11-13/08-nix-ecosystem.md)). + Build **first** inside this pipeline: “exactly what device X would receive, without touching X” ([Bcfg2 `buildfile`](https://docs.bcfg2.org/) shape). Then conflict check, extra-entry reporting, then inference. @@ -366,10 +423,21 @@ model. - `provides` / `requires` inference and origin - Goal-file render, canonicalization, and the ChangePlan validator (§9) - Consent slot + default prompt (the advisor is theirs) -- JSONL capture + SQLite index (§8; tendcf-agent's on Android) +- JSONL capture + SQLite index (§8; tendcf-agent's on Android per D45, a support role; operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role") - Generic bundle that picks a supervisor - Peer actions as typed cross-machine help +**Review TUI borrows (B12).** Borrow Toad and textual-diff-view +(AGPL-3.0) as needed. The review TUI becomes AGPL-3.0-only and moves to +Python >=3.14 (Toad's floor; Toad pins `textual==8.2.7`). The rest of the +repository's licence is unchanged (R7 / R10). AGPL blocks GPL-2.0-only, +CDDL, EPL-2.0 without a secondary designation and proprietary code in +that module, so keep incompatible licences out of the TUI module; nothing +tendcf uses today is affected. Follow-ups: Termux and Mac availability of +Python >=3.14. Operator ruling, 2026-11-14, B12, "2. Borrow both freely; +raise Python"; the licence question is X-safety-11 in +[`09-safety-score-and-tui.md`](../review-2026-11-13/09-safety-score-and-tui.md). + ncf/Rudder has no macOS or Android. CFEngine `services:` talks systemd/Windows/sysv, not launchd. Linux packages and systemd are mostly assembly; launchd, Termux/runit, Jobber, and the supervisor switch are @@ -432,12 +500,19 @@ is incomplete in exactly those windows. likewise logs results as JSON lines. 2. **Index:** SQLite, for queries, extra-entry counts, “what release am I on.” Rebuildable from JSONL. If the DB is corrupt, history still - exists. On Android it lives inside **tendcf-agent**; on Linux and - macOS its owner is open (below). + exists. Every device keeps its own index over its own JSONL, and the + log archive keeps a fleet-wide one as well (ruled 2026-11-14, below). + On Android a device's index lives inside **tendcf-agent** per D45 + (2026-11-02), and the B3 ruling ("trust and consent only", §12) does not + remove that role from the thin agent: "only" is about decisions, and the + thin Kotlin agent still writes the device JSONL and index as a support + role (operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role"). On Linux + and macOS its owning command is not yet named (below). CFEngine never opens SQLite. Single writer to JSONL (engine or its wrapper); single writer to SQLite (on Android the agent, which tails or -receives the log). +receives the log, as D45 stands; the B3 ruling does not change that: operator ruling, +2026-11-14, PR 62 review Q3, "1. Agent keeps log role", see above). **Linux and macOS (D45, 2026-11-02).** No daemon runs beside CFEngine: `tendcf-validate` (§12) is a command that runs and exits, not a process @@ -445,9 +520,11 @@ that tails the log. What holds there is the capture: JSONL, written by the engine or its wrapper. It is not built yet on any host — nothing writes report rows (`report-row.schema.json`), and the Linux writer is open in [`linux-targets.md`](linux-targets.md) §4. D45 gives the SQLite -index no owner on these platforms; that is an operator question (§12), -and nothing above depends on it, because the index is rebuildable and -the JSONL is the record. +index no owner on these platforms; the operator has ruled that every +device keeps one (below, and §12 item 7), and nothing above depends on +it, because the index is rebuildable and the JSONL is the record. Which +command owns a device's index on Linux and macOS is implementation work +and is not named yet. **Android UID isolation (looked up, 2026-08-14).** Termux (`com.termux`) and tendcf-agent are different UIDs. The APK **cannot** read @@ -455,7 +532,11 @@ and tendcf-agent are different UIDs. The APK **cannot** read is a user-granted bridge with stdout via `PendingIntent`, not a log directory. Therefore: -- tendcf-agent owns **both** JSONL and SQLite in **app-private storage**. +- tendcf-agent owns **both** JSONL and SQLite in **app-private storage** + (D45, 2026-11-02, unchanged by any ruling; the B3 ruling "trust and + consent only" is about decisions, so the thin Kotlin agent still writes + the device JSONL and index as a support role: operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role"; map and D18 + stand). - Either cf-agent runs as a native helper of the agent (same UID), or a Termux-side reporter **pushes** lines to the agent (localhost / ContentProvider). Never “agent opens Termux’s files.” @@ -467,6 +548,25 @@ Optional best-effort push of a subset into Vector / OpenObserve / Grafana is never the record of truth. Fleet-wide yes/no questions query reachable devices and treat the rest as unknown. +**Log archive (G8 state 1).** A device holding the `log-archive` role +receives other devices' JSONL rows, authenticated by device public key, +and appends them keyed by device public key and release stamp. Shipping +is retried, idempotent by row identity, and never blocks convergence. +The sending device's JSONL stays authoritative; the archive is an +authenticated copy. **SQLite index (D45 item 7), ruled:** the log archive +keeps a fleet-wide SQLite index over every device, **and** each device +keeps its own index; device JSONL stays authoritative (operator ruling, +2026-11-14, Smaller 6 REVISED, "make that both", option 3 "Both"; M-§8-01). +The earlier answer the same day, "2. Per-device indexes" (every device +its own index, the archive storing JSONL only), is superseded; it was +also not the reviewers' recommendation. The JSONL writer on macOS and on +Android is on the path to G8 state 1 (nothing writes report rows yet). +In state 1 the archive server is the macOS VM on bigmac (§12); it is +reachable only while bigmac is awake, so devices buffer JSONL until it is. +The `monitor` role (monitoring of other machines) is G8 state 2: state 1 +needs only the log archive (operator ruling, 2026-11-14, B4 rider, +monitor role, "1. State 2"; G8.1). + Every row carries the release stamp. Each device records which release it is converged to. @@ -575,6 +675,31 @@ file stays rejected as circular. The validator MUST recompute every hash. DC-2 applies in full: per-target validity, device nonce, monotonic-counter single use, persisted rejects. +- **Standing modes (ruled; implementation pending; a schema bump).** + Operator ruling, 2026-11-14, B2, "3 but also the existance of standing + wait for user and standing refusal": option 3 (a hold window, or an + owner-enrolled standing approval, shown and refusable before apply; new + approval-record shape without a per-change nonce, i.e. a schema bump), + PLUS two further standing modes: a standing "wait for user" (hold until + the owner answers) and a standing refusal. The record fields above + describe the per-change shape, which stands until that bump lands. How + the new shape sits with DC-2 is for the design review the schema bump + requires (two frontier reviews), within the reading below (dropping any + check other than the per-change nonce needs an operator ruling). **A reading of the ruling (L5, B2), not + part of it (lead decision, PR 62 round-3 review):** a standing approval drops + only the per-change nonce (DC-2's device nonce); it is signed by an + owner-held trusted key and keeps B1's other content checks (signed by trusted + keys, fresh, names this device) and the rest of DC-2 (per-target validity, + monotonic-counter single use or high-water mark, persisted rejects); its + ceremony class is still checked against the validator's derived requirement + (§9.8); until the operator rules, a standing approval covers `ordinary` + changes only; whether one may cover `privileged` or `baseline` changes is for + the schema design review to propose and the operator to rule; it names its + signer and algorithm only if X-trust-06 is adopted (proposed, not ruled); + every standing mode (hold window, standing approval, standing "wait for + user", standing refusal) is owner-enrolled and refusable, and none is a + default; dropping any other check needs an operator ruling; the schema design + review confirms the approval-record shape (AGENTS.md, Android item 5). - `cf-agent --simulate` remains an **optional human-facing confirmation** of actual-state delta, never a mechanism of the gate. File the upstream `--simulate-output=json` issue before Step 3 code. @@ -731,6 +856,22 @@ Cost, accepted: the compiler carries multi-version render ability for a window and tracks per-host versions. The price is paid in one place rather than as device-side leniency on every device. +**Ruled 2026-11-14 (schema).** (a) C-policy-01: "1. Bump to 6": a strict +narrowing of `pre_action.command` still bumps `schema_version`; same +version = same acceptance set (operator ruling, 2026-11-14, +C-policy-01 schema version). (b) C-policy-01 `contract_version`: +"1. Confirm `const: 2`": an exact pin, not a floor (operator ruling, +2026-11-14, C-policy-01 contract_version form). (a) and (b) are +**implemented**: the schema is at v6 (`"const": 6`, commit 83d7280) with +`contract_version` const 2, merged by PR 52 (merge 2c78680, 2026-11-14). +(c) The Android profile field (§12) rides the same bump as the `agent` id +change (§12 item 4; M-§12-05 item 4); the standing-modes record (§9.1) is +a schema bump too. Both are still pending and take **the next unused +schema version (v7 or later)**, never v6, which has shipped. Ruled: "the next unused version (v7 or later); grouping not +ruled; the schema design review (two frontier reviews) decides" (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"). Whether the profile/agent-id change and the +standing-modes record are one version, and which number each takes, is +that review's call. + **Amended 2026-11-13 (D46).** There is no device outside the operator's own hosts to strand yet, so the compiler renders only the current `schema_version`, and its older-version @@ -896,7 +1037,10 @@ when a genuinely offline root is lost and every `consented` device becomes unupdatable. DC-20 also asks for every root version to be retained and served, a written out-of-band runbook, and a machine-assisted fingerprint compare rather than an eyeball-hex one. -None of those is built. +None of those is built. **Ruled first build (operator ruling, 2026-11-14, +B1, "1. Content checks; v0 first"):** SSH-signature v0, that is +`ssh-keygen -Y` over the goal-file bytes plus a counter; the 2-of-3 +offline-root floor above may lag until TUF. **First-run root (D41).** The [TUF spec](https://theupdateframework.github.io/specification/latest/) assumes a good trusted `root.json` shipped with the updater, out of @@ -925,6 +1069,53 @@ operator-chosen `managed`) hosts. Push to a `consented` device still requires that device’s consent grant. Pull: each host’s own schedule, gated on timestamp role + quotas before it is autonomous. +**The handshake is content checks (D50).** G3's "correct cryptographic +handshake" means content checks: the goal file is signed by trusted keys, +is fresh, names this device, and carries the owner's approval. Transport +authentication decides only who may talk (operator ruling, 2026-11-14, +B1, "1. Content checks; v0 first"; B13 item 1, "1. Keep text; B1 is the +reading": goal text unchanged). Any device may relay a release; delivery +never authorizes. + +### 9.12 The safety score (G4; operator rulings, 2026-11-14, B8) + +What G4 adds to Model B. The scan **advises**: it never authorizes (the +device-computed diff, the approval record and the validator do). Ruled +(implementation pending; the full text is in +[`09-safety-score-and-tui.md`](../review-2026-11-13/09-safety-score-and-tui.md) +and M-§9-03): + +- **A capped 0-100 score.** Operator ruling, 2026-11-14, B8, "1. Capped + 0-100 score": "score from 0 to 100"; mechanical checks set a ceiling + that AI review can lower but never raise; an explanation of each part; + a measured hit rate once a corpus exists (B13 wording 3, X-pm-03). + This settles B13 items 2 and 3 (the G4 figure). +- **Values.** B8 sub 1, "1. 09's table, top 95": base 95, never 100; + penalties, caps and bands are 09's table, fixed in the schema and + changed only by a ruling (later backed by a labelled corpus). The table + is in M-§9-03 and 09 (01 Idea 1, 09 Idea 1); it is not copied here. + **One part is undecided:** the table's AI-reviewer deduction ("up to + 30") does not say whether 30 is the maximum per AI reviewer or the + maximum in total across reviewers; this aggregation is "open: deferred + to the schema design review (operator ruling, 2026-11-14, PR 62 review + Q7)". Nothing here chooses either reading. +- **Owner-set auto-refuse floor.** B8 sub 2, "1. Allowed, off by + default": an owner may set a floor; a bundle below it is refused + automatically, logged, and the owner notified with the diff; no default + floor; tighten-only (no score ever auto-accepts); the owner can + re-request and accept a refused bundle (G-§7-01). +- **Build order, not scope.** B8 sub 3, "1. Build order, not scope": G4 + stays whole in state 1. The CLI diff and y/N is built first and used on + the VM and dev devices before any TUI or score work; state 1 is + declared only once score, explanation, highlighting and TUI land. No + "state 1.5". +- **The authoring AI.** B8 sub 4, "2. Should not (as written)" (X-safety-06, + also placed in §11): the scanning AI SHOULD NOT be the authoring model; + it sees only the canonical diff as quoted data, never the author's + prose; the diff is hostile input; two model families where the owner + has them, and their disagreement caps the score (70). The same model is + allowed with no extra cap. + --- ## 10. Per-device trust (D38) @@ -971,7 +1162,10 @@ offer a change and accept a signed yes/no. Same shape as a enrolled key, bound to the baseline and proposed goal-file hashes and the device nonce (§9.1). A reject MAY carry the hunks that drove it; accept is all-or-nothing (§9.3). Timeout is deny. Advisor down → fail - closed for *installs* (revocation still applies, §9). + closed for *installs* (revocation still applies, §9). The owner's own + enrolled alternatives to this default are the standing modes of §9.1 + (hold window or standing approval, standing "wait for user", standing + refusal; operator ruling, 2026-11-14, B2). - Custom tools (OpenPGP WoT, a transparency log, a chain, gossip of signed apply-attestations) are theirs. Deadlock among “everyone waiting for everyone else” is a separate project that consumes @@ -981,6 +1175,17 @@ offer a change and accept a signed yes/no. Same shape as a Proposing side and consenting side are different programs. The advisor never authorizes; the executor does, against the signed grant. +**The scanning AI is not the authoring AI** (operator ruling, 2026-11-14, +B8 sub 4, "2. Should not (as written)"; X-safety-06). The AI that scans a +change SHOULD NOT be the model that authored it, and sees only the +canonical diff as quoted data, never the author's prose. The diff is +hostile input to it. Two model families, where the owner has them, are +better than one; their disagreement caps the score (70). The same model is +allowed with no extra cap. (Self-preference bias: [arXiv +2404.13076](https://arxiv.org/abs/2404.13076), fetched and verified +2026-11-14; cited for self-preference bias only, not for anything about +code review.) + Personal branch: theirs, applied under their consent; never auto-merges into anyone else’s trust domain. Upstream-heal is a suggestion their agent evaluates. @@ -996,13 +1201,87 @@ the primary workstation adopts nix-darwin is Step 7, gated on §14.1. Unit-writers lint is the safety rail on a live daily driver. Runtime: CFEngine + `tendcf-validate` (D45, below). +*Ruled 2026-11-14: state 1's Mac.* macOS is platform 1, as a server (D48). + +- **Plain Mac, launchd by tendcf.** State 1's Mac has no nix-darwin; + tendcf renders launchd; Nix is for authoring and building only + (operator ruling, 2026-11-14, B6, "1. Plain Mac, launchd by tendcf"). +- **Which Mac.** An Apple Silicon macOS VM (tart / Virtualization.framework) + on bigmac (MacBookPro18,1): current macOS, snapshot/rollback, and CI can + run the same image; it is a client, not an always-on server (operator + ruling, 2026-11-14, B6 sub 1, "1. macOS VM on bigmac"; 13 E-2). +- **Image size.** The state-1 macOS VM image is minimised: start from the + smallest base (vanilla, not a dev-tools image) and strip what tendcf's + state 1 does not need (operator ruling, 2026-11-14, B6 sub 1 rider, + "Try to cut down the MacOS VM image so be smaller, remove stuff we don't + need."). Queued as build work: research the floor (what macOS can drop + in a guest, e.g. tart vanilla vs base images). +- **May the daily driver enforce.** "1. Dry-run only": bigmac may run + tendcf in dry-run (compute and report the diff, log drift, apply + nothing); the VM is the only enforcing Mac in state 1 (operator ruling, + 2026-11-14, B6 sub 2, M-§12-01 / Q18). The VM is also the G8 log-archive + server, reachable only while bigmac is awake; devices buffer JSONL (§8). +- **Root or user.** "1. Root in VM, user on bigmac": the enforcing VM runs + tendcf as a root LaunchDaemon; bigmac's dry-run runs as a user + LaunchAgent, no root (operator ruling, 2026-11-14, B6 sub 3, 13 E-2). + State 1 must verify the root launchd render path, which the WarpBuild + spike skipped. + **Android (adapter #2).** Same Site Model vocabulary. Runtime: Termux + tendcf-agent (Kotlin, D45) + Shizuku-class helper + CFEngine. Agent owns -logs (§8). Peer actions cover devices that need external ADB help. +logs as a support role (§8, as D45 stands; operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role", see below). Peer actions cover devices that need external ADB help. + +*Ruled 2026-11-14: Android (platform 2, client, D48).* + +- **State 1 on Android:** "3. Termux CFEngine + thin Kotlin": Termux + CFEngine fed tendcf projections; the Kotlin agent holds trust and + consent only (operator ruling, 2026-11-14, B3; 05 Idea 4). That ruling + decides the trust, consent and Termux split. It does not name who owns + the Android JSONL log and SQLite index (§8, D18); operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role": + "only" is about decisions; the thin Kotlin agent still writes the device + JSONL and index as a support role; map and D18 stand. +- **Profile model.** "1. Field on entries": one host per phone (one key, + baseline, review); each Android promise names its target user (`owner`, + `work`, `private`) and the work profile's owner app (`island`, + `insular`, `none`), per X-android-05's text; an unreachable profile + reports `not_kept`. A `profile` field on entries is a schema bump, a + design ruling with two frontier reviews; it rides the same bump as the + `agent` id (§12 item 4; M-§12-05 item 4) (operator ruling, 2026-11-14, + B3 sub 1, M-§12-04). +- **Validator on Android.** The single Python `tendcf-validate` runs in + Termux; the Kotlin agent independently re-checks signature and + high-water mark, keeps the trust anchor and the approval record in its + own app-private storage, and shows consent; no full Kotlin port + ("1. Termux + Kotlin trust check", B3 sub 2, M-§12-06; amends D45 + (1)-(2)). +- **Never a DPC slot.** tendcf never holds a DPC slot (profile owner or + device owner); it works with Island/Insular through shell (`--user N`) + and the owner app's API; an unreachable profile reports `not_kept`; + tendcf never requires MDM enrolment ("1. Never", B3 sub 3, + X-android-09). +- **Phone review surface.** "1. Native screen + Termux": one review + document rendered three ways (CLI `--plain`/`--json`, Textual TUI + including Termux/SSH, native screen in tendcf-agent); goldens hold all + three; renderers compute nothing. The agent notification opens the + native screen with Accept/Refuse; the Termux CLI/TUI is the operator's + path. No answer = held; a refusal is logged ("1. Native screen + + Termux", B3 sub 4, X-safety-08 / X-android-14; replaces the former + Step 9 row, §13). +- **The public claim (G5).** "1. Keep G5; word public claim": G5 is + unchanged; public docs use "we know of no other tool that converges an + owner's own unrooted phone, including its Island/Insular work profile, + from a signed goal file, without MDM enrollment or root" and state the + developer-verification terms (ADB exempt; advanced flow one-day wait; + limited distribution 20 vs 50 devices discrepancy) (operator ruling, + 2026-11-14, B9). **Linux (adapter #3, adoptability keystone).** Stock distro; mise toolchains + CFEngine everything else, plus `tendcf-validate` (D45, -below). Distro choice open until this step. +below). Distro choice open until this step. *Ruled 2026-11-14:* under D48 +Linux is platforms 4 and 5 (server, then client): "1. Order language": +Linux is later in the order, not paused (operator ruling, 2026-11-14, B4 +rider, Linux). The pastebin canary stays the standing end-to-end proof: +"1. Keep it" (operator ruling, 2026-11-14, B4 rider, canary). **NixOS / nix-darwin (passthrough).** The host's existing Nix configuration, unchanged; tendcf supplies distribution, consent and @@ -1036,13 +1315,22 @@ It is Python, `bin/projector.py` promoted, so the code CI's golden gate runs is the code the host runs: one implementation on these platforms, with nothing to drift. Each host needs `python3`; per the ruling, Debian has it, NixOS gets it through the derivation, and macOS from a bundled -interpreter or the Command Line Tools. On Android the Kotlin agent runs +interpreter or the Command Line Tools. ~~On Android the Kotlin agent runs the same validation and projection logic as a port, held byte-for-byte to the same checked-in goldens in CI (residue R22 of -`projector-reconciliation-2026-08-16.md`, whose §9 placed the code); the -Python implementation stays the one normative source. It is -built after schema v5 lands and before any further host is enforced -(§13). Nothing device-side runs today: pastebin's canary data is a +`projector-reconciliation-2026-08-16.md`, whose §9 placed the code)~~. +**Amended 2026-11-14 (D45 (1)-(2)):** on Android the single Python +`tendcf-validate` runs in Termux, and the Kotlin agent independently +re-checks signature and high-water mark, keeps the trust anchor and +approval record in app-private storage and shows consent; there is no +full Kotlin port of the validator (operator ruling, 2026-11-14, B3 +sub 2, "1. Termux + Kotlin trust check"). The Python implementation is +the one normative source on every platform. It is +built after schema v5 lands (it has; the schema is at v6) and before any +further host is enforced (§13). Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): the §13 stage 1 macOS VM +may enforce a root `cf-execd` early, before `tendcf-validate` exists at +stage 4, as an explicit exception like pastebin's: canary only, +operator-authored data. The stage order is not changed. Nothing device-side runs today: pastebin's canary data is a projection made in this repository by `bin/projector.py`, checked by `deploy/linux/canary/check.py` and installed by `tendcf-install.sh install --data`. @@ -1107,9 +1395,12 @@ nothing: explicitly trusted host runtime outside that artifact. Pinning a version alone does not satisfy DC-11. R-S3-4's accidents-only model applies to the passthrough hard checks, not this consent gate. Timing: - the schema is at v4 and v5 is in flight; an id change decided before - v5 lands rides that bump, afterwards it costs v6 and a baseline - ceremony per device. + the schema is already at v6 (`"const": 6`, PR 52; v5 was the earlier + state), so an id change now costs the next unused schema version (v7 + or later) and a baseline ceremony per device. Ruled 2026-11-14 (B3 sub + 1, "1. Field on entries"): the schema bump for the Android `profile` + field rides this agent-id bump (M-§12-05 item 4). Ruled (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled (whether the standing-modes record, §9.1, shares that + version included); the schema design review (two frontier reviews) decides. 5. **The `rfc8785` dependency.** `bin/projector.py` declares the PyPI package `rfc8785` and runs under `uv run --script`; D45 names only `python3`. Vendor it, package it, or implement JCS in the command. @@ -1133,15 +1424,26 @@ nothing: compatibility; otherwise use a compatible bundled interpreter. Also open: the execution identity and privilege boundary for validation and projection publication on each platform. -7. **The SQLite index on Linux and macOS (§8, D18).** No owner: - `tendcf-validate` is not a daemon and CFEngine never opens SQLite. - Deferred, owned by another command, or not built on these platforms. +7. **The SQLite index on Linux and macOS (§8, D18).** **Ruled + 2026-11-14** (Smaller 6 REVISED, "make that both", option 3 "Both"; + it supersedes the same day's "2. Per-device indexes"): the log archive + keeps a fleet-wide SQLite index over every device, **and** each device + keeps its own; device JSONL stays authoritative. What stays open is + the owning command on a Linux or macOS device: `tendcf-validate` is + not a daemon and CFEngine never opens SQLite. 8. **The v5 detector.** `schema-v5-dpkg-reconciliation-2026-11-02.md` R4 left open whether tendcf-agent later takes over the Linux unit detector. D45 (1) closes that as posed: no tendcf-agent exists on Linux. Open is only whether any other component (`tendcf-validate` or a further command) ever takes it over from the policy bundle. +**Engine pin (B5).** "1. Keep fork; spike stock" (operator ruling, +2026-11-14, B5): the full fork pin on every platform, with the macOS fork +build in CI; run report 11's 2-3 day stock/Termux spike before deciding +the adopter path (options 2-4 of +[`11-engine-alternatives.md`](../review-2026-11-13/11-engine-alternatives.md)). +The spike is a spike-lane branch (never merged, §13). + Future classes (extension points, no build-out): OpenWrt; consented iPhone/wearables that consume artifacts; firmware as Nix-built artifacts; image-based appliances (RAUC / OSTree family). @@ -1157,27 +1459,77 @@ before apply. ## 13. Build order -Each step leaves a coherent system. Not a schedule. - -| Step | What | +**Order, ruled 2026-11-14.** Operator ruling, 2026-11-14, B4, "1. Adopt +D47-D50": the guide's build order +([`02-response-guide.md`](../review-2026-11-13/02-response-guide.md) +G-§18-02, "Build order from here") is the base, with this map's Step 0 +(M-§13-01: merge, the D46 restructure, the ruled schema changes) and an +explicit macOS CI step folded in. Each stage leaves a coherent system and names +the G8 state it serves ([`00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md) +G8). Not a schedule. Each state is reached in this order, but work toward +state 3 may start once state 1 holds (operator ruling, 2026-11-14, B13 +item 4, "1. Adopt the clarification"). Linux is later in the order, not +paused ("1. Order language", B4 rider); the pastebin canary stays the +standing end-to-end proof ("1. Keep it", B4 rider); ordering inference +(D16) is deferred explicitly ("1. Defer explicitly", B4 rider). + +| Stage | What | G8 | +| --- | --- | --- | +| 0 | Merge #42, then #41 (operator ruling, 2026-11-14, B11; historical: both merged 2026-11-14, #42 at acec5b5 and #41 at daa4530); the D46 restructure (`tendcf compile`, in-tree `plugins/`). The ruled schema changes: C-policy-01 (schema v6 with `contract_version` const 2) is done, merged by PR 52 (2c78680); the Android `profile` field with the `agent` id (§12 item 4) and the standing-modes approval record (§9.1) are still pending and take the next unused schema version (v7 or later); how they group is not ruled (§9.6; operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review": the next unused version (v7 or later), the schema design review of two frontier reviews decides). | 1 | +| 1 | **The fork on the Mac.** Build the pinned fork for macOS arm64 into `/opt/tendcf` in the state-1 macOS VM on bigmac (§12; minimised image); root LaunchDaemon `cf-execd`; one canary launchd service enforced; bigmac itself dry-run only, as a user LaunchAgent. Verify the root launchd render path. Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): this stage enforces a root `cf-execd` in the VM before `tendcf-validate` exists at stage 4 and the handshake at stage 5; D45 says the validator is built "before any further host is enforced", and the VM is an explicit, ruled exception like pastebin's canary: it may enforce early, canary only, operator-authored data. The order is not changed. | 1 | +| 2 | **macOS CI (explicit step).** A CI job builds the pinned fork on macOS and runs `tests/policy/run.sh`; the VM image is one CI can run. The WarpBuild spike (`spike/macos-check8-warp`, `warp-macos-26-arm64-12x`) is the first run. Historical: PR 52's merge waited on it (operator ruling, 2026-11-14, PR 52 gate 2); the run ("macOS check 8 spike (WarpBuild)", [run 43602684071](https://github.com/frdminc/tendcf/actions/runs/43602684071)) completed with conclusion success and PR 52 merged 2026-11-14 (2c78680). | 1 | +| 3 | **Nix authoring, minimal.** A module system with tendcf options for services, interlocks and roles, named after nix-darwin and NixOS where the meaning is the same (B7), evaluating to today's Site Model JSON; YAML twins stay as fixtures. | 1 | +| 4 | **`tendcf-validate`, first build, with the CLI review.** Stored, integrity-checked baseline; the device computes the diff; the CLI shows it and takes y/N; projection only after accept. Built first, and used on the VM and on dev devices before any TUI or score work (operator ruling, 2026-11-14, B8 sub 3, "1. Build order, not scope"). | 1 | +| 5 | **Signed releases and the handshake.** Content checks (§9.11); SSH-signature v0 first (B1), TUF later; any device may relay. | 1 | +| 6 | **Android client.** Termux CFEngine fed tendcf projections; the thin Kotlin agent (trust and consent only; it keeps the log and index as a support role: operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role", §8); `tendcf-validate` in Termux; runit services via termux-services; the `profile` field on entries; ShizukuPlus helper; the native review screen (§12). | 1 | +| 7 | **Peer actions and the archive.** The Mac starts ShizukuPlus over ADB when the phone cannot; JSONL capture on both devices (on Android the thin agent writes it as a support role: operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role", §8); the `log-archive` role on the VM, fleet-wide index (§8); the phone buffers while the VM sleeps. The `monitor` role is not here: state 2. | 1 | +| 8 | **Safety score, explanation, highlighting; then the TUI** (§9.12). State 1 is declared only once these land; G4 stays whole in state 1, and there is no "state 1.5". | 1 | +| 9 | Pull: every device self-updates from any peer; roles move by editing data; the `monitor` role (operator ruling, 2026-11-14, B4 rider, "1. State 2"). | 2 | +| 10 | macOS as client: the other Macs; nix-darwin passthrough (§14.1 for a workstation). | 2 | +| 11 | Extra-entry reporting per domain, so the `not-yet-migrated` count measures what is left. | 2 | +| 12 | Migrate the old stack's services one domain at a time, then retire it (`~/ops`). | 2 | +| 13 | Linux as server: the existing Debian host, canary to full. | 2 | +| 14 | Linux as client; NixOS and nix-darwin hosts as passthrough. | 2 | +| 15-16 | State 3: the publishable layer, install and first-run root ceremony a person with no admin skill can complete, the default advisor prompt, public docs; then the `consented` tier. From state 1 on, a clean machine with a fresh AI session that has only the public docs rehearses this in CI (operator ruling, 2026-11-14, B13 item 5, "1. Add the rehearsal sentence"). | 3 | +| later | Demand-driven: branch management (G9); ordering inference (D16, deferred explicitly); the builder/cache; APK provenance; web of trust as advisor tools; out-of-tree plugin discovery (D46, deferred). | later | + +State 1 is reached when the Mac and the phone each converge from a +Nix-authored site, each refuses a release that fails the handshake and a +diff its owner refused, and both devices' logs are in the Mac's archive, +with stage 8 landed. Spike lane, tiered review and the docs freeze: +`AGENTS.md` standing rule 3 (operator ruling, 2026-11-14, B10). + +**The earlier numbered steps** below are the names of pieces of work, kept +for their status notes and for the references to them elsewhere (this map, +`change-process.md`, `linux-targets.md`); the order is the stage table +above. The guide's own Steps 0-15 +([`02-response-guide.md`](../review-2026-11-13/02-response-guide.md) +G-§18-02) keep macOS CI inside their Step 1, so guide Step 0 = stage 0, +guide Step 1 = stages 1-2, and guide Step n for n = 2 to 15 = stage n+1 +(stages 3 to 16). Rough correspondence of the former steps: Step 1 = stages 1-2, Step 2 = stage 6, Step 3 +(compiler) = built, stage 0, Steps 4-5 = stages 13-14, Step 6 = stages 4-5, +Step 7 = stage 10, Step 8 = stage 9, Step 9 = stage 8. + +| Former step | What | | --- | --- | | 0 | Schemas in **tendcf** (`schema/`, `examples/`, `bin/schema_lint.py` — provides/requires, interlocks, comprehensive, report-row). Remaining: peer_actions, trust-policy shape, generic unit-writers, lookup stub, YAML canonicalize. Transcribe reality (`not-yet-migrated` is the correct day-one state). | -| 1 | macOS services adapter. Dry-run default. No nix-darwin. **Started** (`policy/tendcf_services.cf`, `222da45`: launchd present/absent and interlock refusal, verified against a real `cf-agent`; package/file promises, environment rendering, the unit-writer detector still open). 2026-10-29: the satisfied-interlock path had never opened (verdict class fixed in pass 1 before the check ran); the check moved to `tendcf_interlocks`, sequenced before `tendcf_services`, and `tests/policy/run.sh` proves both paths on Linux CI and the Mac. The CFEngine it was verified against is upstream plus the patch overlay (`overlay/`, [`upstream-overlay.md`](upstream-overlay.md)); Linux CI builds the full fork ([`linux-targets.md`](linux-targets.md)). | -| 2 | Android under the Site Model; Termux types; agent owns JSONL+SQLite. **Deferred** (operator, 2026-10-29): Linux comes first, see [`linux-targets.md`](linux-targets.md). Not started as code: the schema already carries a `termux` supervisor flavour (`services.schema.json`) and the `android-termux-services` domain fixture, but no adapter bundle, no agent, no JSONL/SQLite ownership. `frdminc/ShizukuTendCF` is the R4 helper (a tool fork), not this step. | +| 1 | macOS services adapter. Dry-run default. No nix-darwin. **Started** (`policy/tendcf_services.cf`, `222da45`: launchd present/absent and interlock refusal, verified against a real `cf-agent`; package/file promises, environment rendering, the unit-writer detector still open). 2026-10-29: the satisfied-interlock path had never opened (verdict class fixed in pass 1 before the check ran); the check moved to `tendcf_interlocks`, sequenced before `tendcf_services`, and `tests/policy/run.sh` proves both paths on Linux CI and the Mac. The CFEngine it was verified against is upstream plus the patch overlay (`overlay/`, [`upstream-overlay.md`](upstream-overlay.md)); Linux CI builds the full fork ([`linux-targets.md`](linux-targets.md)). **Ruled 2026-11-14:** the enforcing Mac in state 1 is the macOS VM on bigmac, not the daily driver (§12). | +| 2 | Android under the Site Model; Termux types; agent writes JSONL+SQLite as a support role (operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role", §8). ~~**Deferred** (operator, 2026-10-29): Linux comes first, see [`linux-targets.md`](linux-targets.md).~~ **Reversed 2026-11-13 (D48):** Android is platform 2; Linux is later in the order, not paused. Not started as code: the schema already carries a `termux` supervisor flavour (`services.schema.json`) and the `android-termux-services` domain fixture, but no adapter bundle, no agent, no JSONL/SQLite ownership. `frdminc/ShizukuTendCF` is the R4 helper (a tool fork), not this step. | | 3 | Compiler (`tendcf compile`; ~~nix2cf~~): `buildfile` first, conflict, extra-entry, then inference (needs step 1 and a Linux systemd adapter; Android is deferred). **Unblocked** on 2026-10-29 by the operator's decision recorded on [#4](https://github.com/frdminc/tendcf/issues/4); `frdminc/nix2cf` had one compilation command, `buildfile`, plus the `eval-nix` evaluation hook. **Amended 2026-11-13 (D46):** the compiler moved into tendcf under `compiler/` (#45; `frdminc/nix2cf` archived) and the restructure splits it into plugins ([`plugin-layout.md`](plugin-layout.md)); ~~its `tendcf.lock` is specified in [`change-process.md`](change-process.md) §2~~ with schema and compiler in one repository there is no `tendcf.lock` (it was specified, never built). | -| 4 | Linux reference path on a stock distro. | -| 5 | First real Linux host; prove roles are data. | +| 4 | Linux reference path on a stock distro. (Later in the order, not paused: D48.) | +| 5 | First real Linux host; prove roles are data. (Later in the order, not paused: D48.) | | 6 | Signed releases, push-only; goal-file render + diff + on-device validator (§9). Operator hosts. The lockfile, release, rollback and CI-gate design is [`change-process.md`](change-process.md) (#2); the code is not written. On Linux and macOS the on-device validator is `tendcf-validate`, built after schema v5 lands and before any further host is enforced; how much of this step's validator its first build carries is open (D45, §12). | | 7 | Mac substrate on the primary workstation (nix-darwin) if §14.1 says yes. The nix-darwin passthrough adapter itself is [`linux-targets.md`](linux-targets.md) Step 8 and does not wait on §14.1. | | 8 | Pull / self-update. | -| 9 | Consent surface + default prompt + advisor slot. | +| 9 | Consent surface + default prompt + advisor slot. One review document rendered three ways: command line (`--plain`, `--json`), TUI (Textual; also under Termux and SSH), and a native screen in tendcf-agent. Renderers compute nothing; golden fixtures hold all three (operator ruling, 2026-11-14, B3 sub 4, "1. Native screen + Termux"; X-safety-08, which replaces this row's former text). | | 10+ | Demand: builder/cache, APK provenance, WoT-as-advisor-tools, extracting the publishable layer when a second person runs it. | -Dry-run is the standing posture on the first platform (the machine that -cannot easily be reimaged). Reporting is an adoption requirement. +Dry-run is the standing posture on the daily driver (the machine that +cannot easily be reimaged), bigmac; the state-1 VM is the only enforcing +Mac (§12). Reporting is an adoption requirement. The §9.9 schema family and the §14.2 review of it **MUST** land before the -Step 6 validator is coded. Nothing else gates them — no fleet, no +Step 6 validator (stage 4) is coded. Nothing else gates them — no fleet, no compiler — so they may be written as soon as someone is free to write them. @@ -1211,20 +1563,20 @@ Older “superseded by” archaeology lives in | # | Decision | Resolution | | --- | --- | --- | | D2 | Site Model formality | Schemas at Step 0; writer-lint immediate. | -| D6 | Nix on bare metal | No. Builds / dev shells / authoring language / passthrough where a host already runs NixOS or nix-darwin. Never the OS a stranger must install. | -| D8 | Trust layer | Build it, gated. Sovereignty is the point. | +| D6 | Nix on bare metal | No. Builds / dev shells / authoring language / passthrough where a host already runs NixOS or nix-darwin. Never the OS a stranger must install. **Amended 2026-11-14:** Nix may be required to build a release (operator ruling, 2026-11-14, B4 rider, Nix on release path, "2. Allow on release path"), scope "1. Build-time only": devices never need Nix at run time. | +| D8 | Trust layer | Build it, gated. ~~Sovereignty is the point.~~ **Superseded in wording 2026-11-14 by D47:** adoption is the aim and see-and-refuse (G4) is its safety mechanism; the trust layer stays, as G4's mechanism (operator ruling, 2026-11-14, Smaller 3 (M-§15-01), "1. Yes, supersede D8's wording"). | | D10 | Task runner | `just` for humans; mise for toolchains. | -| D12 | Authoring frontend | **Amended 2026-10-29.** Two equal frontends, Nix modules and YAML, rendering to byte-identical goal files; a Nix-authored site runs on hosts without Nix. Existing NixOS/nix-darwin configurations are used verbatim (passthrough). JSON remains the wire format. [`linux-targets.md`](linux-targets.md) §5. **Amended 2026-11-13 (D46):** the Nix frontend is the compiler plugin `plugins/frontends/nix/` and carries the name `nix2cf`; the YAML frontend is `plugins/frontends/yaml/` (built in); a Guix frontend may follow. Not built yet ([`plugin-layout.md`](plugin-layout.md)). **Amended 2026-11-13 (D46 (9), issue #48):** every Nix evaluation runs under restricted evaluation with no import-from-derivation, an empty `allowed-uris` and no network, and recipes from other sites are imported, pinned and scanned before compile; a Guix frontend waits for a sandbox design of its own (all planned). | +| D12 | Authoring frontend | **Amended 2026-10-29.** Two equal frontends, Nix modules and YAML, rendering to byte-identical goal files; a Nix-authored site runs on hosts without Nix. Existing NixOS/nix-darwin configurations are used verbatim (passthrough). JSON remains the wire format. [`linux-targets.md`](linux-targets.md) §5. **Amended 2026-11-13 (D46):** the Nix frontend is the compiler plugin `plugins/frontends/nix/` and carries the name `nix2cf`; the YAML frontend is `plugins/frontends/yaml/` (built in); a Guix frontend may follow. Not built yet ([`plugin-layout.md`](plugin-layout.md)). **Amended 2026-11-13 (D46 (9), issue #48):** every Nix evaluation runs under restricted evaluation with no import-from-derivation, an empty `allowed-uris` and no network, and recipes from other sites are imported, pinned and scanned before compile; a Guix frontend waits for a sandbox design of its own (all planned). **Amended 2026-11-14 (D49):** Nix is first, not one of two equals: "Real Nix first, YAML beneath."; whether the byte-identical YAML twin stays as the frontend's test is open (D49). | | D13 | Service owner | CFEngine promises everywhere; mise toolchains only. | -| D14 | Deployment shape | Git-synced policy; `cf-serverd` on every host; push and pull are one mechanism. | +| D14 | Deployment shape | Git-synced policy; `cf-serverd` on every host; push and pull are one mechanism. **Amended 2026-11-14 (D50):** a device takes updates from any peer that completes the content-check handshake (§9.11); delivery never authorizes. | | D15 | Compile target | CFEngine Augments, not freehand `.cf`. (By way of the per-host goal file, which the device projects to Augments after approval: D43, D44, §5, §9.) | -| D16 | Ordering | No Puppet catalog. Inference + fixpoint + authored `depends_on`. Interlocks. Default-on comprehensiveness. | +| D16 | Ordering | No Puppet catalog. Inference + fixpoint + authored `depends_on`. Interlocks. Default-on comprehensiveness. **Ordering inference deferred explicitly, 2026-11-14:** operator ruling, 2026-11-14, B4 rider, D16, "1. Defer explicitly"; it is demand-driven (§13, "later"; G-§10-01), and the rest of D16 stands. | | D17 | ncf | Vendor generic methods as a reference corpus; strip Rudder reporting. | -| D18 | Local record | ~~JSONL is the durable capture; SQLite in tendcf-agent is the index. On Android the agent owns both in app-private storage.~~ **Amended 2026-11-02 by D45:** JSONL is the durable capture; SQLite is the index, rebuildable from it. On Android tendcf-agent owns both in app-private storage. On Linux and macOS there is no agent, and the index's owner there is open (§8, §12). | +| D18 | Local record | ~~JSONL is the durable capture; SQLite in tendcf-agent is the index. On Android the agent owns both in app-private storage.~~ **Amended 2026-11-02 by D45:** JSONL is the durable capture; SQLite is the index, rebuildable from it. On Android tendcf-agent owns both in app-private storage. On Linux and macOS there is no agent, and the index's owner there is open (§8, §12). **Amended 2026-11-14 (Smaller 6 REVISED, "make that both"):** every device keeps its own SQLite index over its own JSONL, **and** the log archive keeps a fleet-wide SQLite index over every device; device JSONL stays authoritative (§8, §12 item 7). The owning command on a Linux or macOS device is not yet named. **Android ownership of the log and index:** operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role": "only" is about decisions; the thin Kotlin agent still writes the device JSONL and index as a support role; map and D18 stand. The B3 ruling decides only trust, consent and Termux CFEngine (§12). | | D19 | Composition | Private-site lockfile pins inputs (DAG). Signed release is the deploy artifact. No sibling-repo tag lockstep. | | D20 | Nix store locality | Single writer per host. | | D21 | Schema home | **tendcf** owns schemas/types. ~~nix2cf is the compiler.~~ **Amended 2026-11-13 (D46):** the compiler also lives in tendcf (`compiler/`, command `tendcf compile`); schemas stay in `schema/`, outside the compiler's code, and the two live under one pin and change in separate commits whenever a change touches `tools/`, `schema/` or the projector (D46 (9d), operator rulings 20 and 21). `nix2cf` names the Nix frontend plugin. | -| D22 | Platform sequence | macOS, Linux. Android deferred by the operator on 2026-10-29 ([`linux-targets.md`](linux-targets.md)). | +| D22 | Platform sequence | ~~macOS, Linux. Android deferred by the operator on 2026-10-29 ([`linux-targets.md`](linux-targets.md)).~~ **Superseded 2026-11-13 by D48** (ruled 2026-11-14, B4, "1. Adopt D47-D50"). | | D23 | YAML canonicalize | Parse, re-serialize, diff on the YAML path. | | D24 / D40 | Lookup + auto-provide | Registry/token CLI; default `service:`; compile errors teach names. | | D25 | Schema/example pairing | Lint fails if unpaired. | @@ -1246,8 +1598,12 @@ Older “superseded by” archaeology lives in | D42 | Emergency | Restrictive metadata without consent; new installs still gated. | | D43 | ChangePlan model | ~~Model A: a closed `capability` vocabulary per operation, executor refuses effects outside the declared set.~~ **Superseded 2026-08-15 by Model B** (synthesis finding E1, adjudicated in `e1-adjudication-xhigh-2026-08-15.md`, which is final and supersedes `e1-adjudication-2026-08-15.md`): the wire artifact is the complete canonical per-host **goal file**; the ChangePlan is the **diff** against the device’s approved baseline; the executor is a **validator** over that diff, not an interpreter. Rationale: CFEngine has no runtime capability confinement, so Model A’s executor requires an interpreter plus a vocabulary-to-policy correspondence proof that does not exist and is not in budget; and coverage closes by construction when compiler and validator share one schema. The vocabulary, its versioning, and its skew policy are dropped. See §9. | | D44 | Goal-file schema family | The consent artifact is three paired schemas (goal file, goal diff, approval record) with canonical-byte fixtures. Binding sub-decisions, all from E1 §5 and normative in §9: diff computed **device-side**, full file on the wire, compiler diff is preview (§9.1 / E1 §5.1); RFC 8785 canonical JSON, no defaults, no empty collections, refuse-never-normalize, entry-granular structural hunks (§9.2 / E1 §5.2); accept is all-or-nothing, refusal annotated, no dependency groups (§9.3 / E1 §5.3); first adoption and schema migration are bounded **baseline ceremonies**, migration must diff to empty (§9.4 / E1 §5.4); hunk attribution is **excluded from the format** — impossible device-side — and replaced by an `explain-hunk` query (§9.5 / E1 §5.5); `schema_version` fails closed on unknown kinds, strandedness prevented at the compiler, two-phase bumps (§9.6 / E1 §5.6); per-domain coverage travels **in** the goal file (§9.7 / E1 §5.7). §14.2’s pre-build review applies to this family. | -| D45 | Device-side component per platform | **Operator, 2026-11-02.** (1) tendcf-agent is **Android-only**, written in Kotlin. A Linux or macOS host runs CFEngine plus "a small validate-and-project command" (the ruling's words; the name **`tendcf-validate`** was chosen by the amending session on 2026-11-02 and may change without reopening the ruling), run before cf-agent reads `host_specific.json`; no daemon. (2) `tendcf-validate` is Python, the promotion of `bin/projector.py`: one implementation, so no byte-identity drift on those platforms. It needs `python3` on each host (Debian ships it, NixOS through the derivation, macOS bundled or the Command Line Tools). The Android agent's Kotlin projector is a port held to the same golden bytes in CI (residue R22), not a second normative source. (3) Built after schema v5 lands, before any further host is enforced. **Supersedes** every reading that ran the validator, the projector or the SQLite index inside tendcf-agent on every host: the §1 diagram's "CFEngine + tendcf-agent" per device, §8's index owner and D18 as written, §9's "run inside tendcf-agent" and "the agent binary" as the projector's call site, `goal-file-schema-reconciliation-2026-08-15.md` §0 item 7, §9 and §13 ("CI invokes the agent's own projector"), and `projector-reconciliation-2026-08-16.md` §9 and R22 ("tendcf-agent must reproduce" the reference). Not decided by it, and open for the operator: §12's list. | -| D46 | Repository layout and compiler plugins | **Operator, 2026-11-13.** (1) `frdminc/nix2cf` folds into tendcf with full history, first under `compiler/` ([#45](https://github.com/frdminc/tendcf/pull/45)), and is archived as soon as that import merges. Both done 2026-11-13 (merge commit `ca4fa90`; the repository archived the same day). (2) The repository takes the plugin-type layout of [`plugin-layout.md`](plugin-layout.md): `schema/`, `examples/`, `policy/`, `overlay/`, `deploy/` unchanged; `tools/` (was `bin/`); `compiler/` (merge, conflict check, render); `plugins/frontends/` (`yaml`, `nix`, later `guix`, an authoring frontend), `plugins/supervisors/` (`launchd`, `systemd`, `runit`), `plugins/importers/` (`ansible`, `salt`); `contrib/` for in-tree third-party frontends and importers. It becomes one Python package, import name `tendcf`. (3) Third-party frontends and importers are found through the public entry-point groups `tendcf.frontends` and `tendcf.importers`, so they can live out of tree as a pip package; plugins in this repository are found through a static import table, never entry points (9a). Supervisor renderers are in tree only; there is no public `tendcf.supervisors` group, because the goal file's `unit` is a closed `oneOf` and an out-of-tree renderer could only shadow a built-in. (4) Plugins are compile-time only: none runs on a device. The device artifact (`tendcf-validate`, D45) is built from the validator's own source alone, never imports `compiler/`, `plugins/` or `contrib/` and never calls entry-point discovery; the schema lint and the projector never import the compiler; a CI import check is to enforce both (planned). Plugins are trusted build-time code that the operator explicitly allows, not sandboxed: a plugin cannot make a device accept anything that device's own diff does not show (on Linux and macOS that validation is `tendcf-validate`, planned, D45, and does not exist yet; the Android agent was not checked), and cannot emit a shape the schema forbids, but it can make the goal file say something other than what the Site Model says, and it sees the site's private data. Release gates (schema lint, projector, preview diff) and signing are to run in a separate environment with no plugin installed, and the compile step is to hold no signing key (planned, Step 6; nothing enforces this today, and amendment (9) says what the environment is). A compile-side preview diff or `explain-hunk` (D44) is compiler output and inherits the plugins' trust. `contrib/`'s lower bar waives support and maintenance promises, never the standing review rule. Out-of-tree trust establishment and plugin management: [#47](https://github.com/frdminc/tendcf/issues/47). (5) Activation (the loader is planned, restructure step 4): a plugin is selected only if site-private names it (name → distribution, version, hash); an installed but unnamed plugin is not selected (installing a package can still run code, amendment (9)); a duplicate name in a group is a compile error; built-in names are reserved; until out-of-tree pinning exists (#47) a release build loads in-tree plugins only; the release's `targets.json` `custom` records the plugin set. (6) No users and no backward compatibility yet, so no shims: the compiler's command becomes `tendcf compile`, which replaces `nix2cf buildfile` with no alias (it compiles every host; `--host` renders one); `eval-nix` moves to the Nix frontend; `bin/` → `tools/` leaves no symlink or wrapper and rewrites every path reference in every file, dated records included (djbclark, 2026-11-13, a one-time exception to their append-only convention; only paths change, and prose naming nix2cf as the old repository stays as history); `nix2cf` names the Nix frontend (D12). The compiler renders only the current `schema_version`; older-version rendering is removed in the restructure, and §9.6's ceiling design applies once the first device that is not an operator host enrolls. (7) The keys `nix2cf_services` and `nix2cf_edges` were only ever illustrative: they occurred in guide §16.A's preview-channel example and its copy in the paper, and no schema, fixture, projector or bundle carried them (the projection's keys are `tendcf_service` and `tendcf_interlock`). In the same change that recorded this decision they were renamed `preview_services` and `preview_edges` (illustrative only, chosen so they cannot be mistaken for the `tendcf_services` bundle or the real projected keys `tendcf_service`/`tendcf_interlock`). No schema change is involved ([`plugin-layout.md`](plugin-layout.md) §6). (8) Consequence for [`change-process.md`](change-process.md): the compiler is no longer a separately pinned input, the two-repository bump order and the compiler's `tendcf.lock` go away; `site.lock` loses only its `nix2cf` entry. One tendcf rev is the unit a site pins, so a compiler fix brings the `schema/` and `policy/` commits before it; accepted, with no maintenance-branch machinery, revisited when the first device that is not an operator host enrolls. Moving `bin/` to `tools/` and the plugin split wait until open PRs #41 and #42 merge. (9) **Amended 2026-11-13 ([issue #48](https://github.com/frdminc/tendcf/issues/48), the adversary review of this decision; operator decisions D-a to D-d recorded in [its comment](https://github.com/frdminc/tendcf/issues/48#issuecomment-6857866487); full text in [`plugin-layout.md`](plugin-layout.md) §4). Nothing below is built; each part is tagged with its step.** (a) **In-tree proof (D-a), planned with the loader:** a plugin is in-tree when its module's realpath sits under the gate-1-verified tendcf tree, checked before the module's code runs (a release build runs the compiler from that tree without installing it); every in-tree plugin (frontends, supervisors, importers) is found through a static import table, never through entry points, which are read only for third-party plugins after #47: list every one without deduplication by name, refuse duplicate names and every entry point that claims a reserved name, whatever its distribution name, load only the named ones; release builds never resolve `tendcf` from a package index; a release build pins or refuses `TENDCF_DIR`. This replaces the first sentence of (3) for in-tree plugins: only third-party plugins use the public groups. (b) **Frontend inputs are code (D-b), planned, Step 6:** external (site-shared or foreign) recipes are imported, never fetched at compile time; the import pins by content digest, runs a static scan and an AI review, and records the verdict with the pin; compile evaluates only pinned recipes with an accepting verdict bound to the digest and fails closed on a failed scan, a rejecting review or a missing or mismatched verdict (the no-AI setting never overrides a negative result; only the gate-5 ceremony marker does, recorded with the pin and shown in every later gate-5 review; the recorded verdict is advisory, because job B′ re-runs the static scan and the AI review on the pinned digest and fails on a negative result), and a site-shared or foreign `site.lock` input is not an import by being pinned; every Nix evaluation, the site's own included, runs under `restrict-eval` with import-from-derivation off, an empty `allowed-uris`, no unsafe native code and no network, with the whole directory tree that the import digested and scanned passed to `-I` and nothing wider (the import refuses a symlink that resolves outside it); `pure-eval` is not used because it cannot evaluate a file named on the command line (tested 2026-11-13 on Nix 2.35.6 in CI, [run 43483740436](https://github.com/frdminc/tendcf/actions/runs/43483740436): the positive recipe evaluates, and file reads outside the recipe (a symlink escape, `readDir` and `builtins.path` included), `fetchurl`, `fetchTarball`, a local `fetchGit`, a `` lookup and `builtins.exec` are each refused, each flag shown by relaxing it alone, while `getEnv` returns the empty string; the import-from-derivation flag is the layer that refuses it (on a fresh store the read-only `--eval` stops it first, with a store-state-specific message) and was proven with `--read-write-mode`; the exact command and what stays untested are in `plugin-layout.md` §4); no Guix frontend until it has a sandbox design of its own; with no AI reachable at import the static scan still runs and `external_import.without_ai` (`require-human-ack` by default, or `warn`, or `refuse`) decides, for the import step only (job B′ still requires an AI review, or the ceremony override, before anything is signed), set in the site-private file that names plugins. (c) **Separate environment (D-c), planned, Step 6:** interim, a separate Unix user on the builder holds the key and the gate tools; the default before the first real release is a two-job split (job A on a throwaway runner with no secrets compiles, runs gate 2 and uploads goal-file bytes plus a digest manifest; job B in a protected signing environment builds the gate tools from the previous release's tendcf pin, never the pin under test (the first release uses the tip of the protected branch the trust root declares, resolved once by job B′ and bound to the approval), with hash-locked dependencies, installs no `tendcf`, runs gates 3 to 5 and signs exactly the digests it checked; job B′ is job B without the key, runs gates 3 to 5 for pull requests so that the reviewed preview is computed outside the plugins); signers in the first real release are one of n (operator rulings, 2026-11-13): the CI key held as a GitHub environment secret, which alone suffices; hardware tokens, optional, at least two if any is enrolled; and the separate Unix user, opt-in and non-default, whose enrolment lowers every release to its level; each enrolled signer signs alone (`vps-hub` and the Hyades podman runner are not signers); both token paths normally sign only the approved pull request's job A digests (merged tree equal to the approved head), path 1 after verifying a passing job B′ run and path 2 after re-running gates 3 to 5 itself with the previous release's gate tools, hash-locked, and `targets.json` `custom` records which; a break-glass route with no merged pull request is allowed, privileged and recorded there too, and is one person's act, bounded only by the threshold-one trust in that signer (ruling 19); job A's egress is unrestricted for now, a stated exfiltration risk left open in `plugin-layout.md` §7. (d) **Signed is what was reviewed (D-d), planned, Step 6:** the pull request's own job A artifacts, previewed by job B′, are what reviewers approve (the approval is bound to head commit, job A run, manifest, preview and baseline release) and what merge signs when the merged tree equals the approved head tree and nothing bound changed (otherwise the gates run and are reviewed again); branch protection on site-private; a changed pin `url`, a pin that does not descend from the previous one and a changed plugin set (the operator's list), and a tendcf bump that changes `tools/`, `schema/` or the projector (issue #48's fixes; such a bump ships as its own release with unchanged data, because the gate tools come from the previous release's pin, ruling 18; a planned tendcf CI check fails a commit that changes `tools/`, `schema/` or the projector together with the compiler goldens or with `policy/`, rulings 20 and 21) need the gate-5 ceremony marker, and so do (operator rulings) a new `site.lock` input, the files the gate jobs run, CI workflow and signer configuration, a signer backend change and a lowered `external_import.without_ai`; the tendcf pin's `url` and `ref` must be what the site's trust root declares (default `frdminc/tendcf` and `master`, or a listed release-branch set, each with required review, no force-push, no deletion and no administrator bypass), any other ref is refused, and a site may declare its own tendcf repository and branch set in its trust root, a privileged change that no per-pull-request marker substitutes for, and gate 1 reads the trust root from the protected base, never from the pull request, so one pull request cannot both change it and move the pin; a backward pin move across a `schema_version` bump is forbidden (roll forward) and within one version is privileged; for a pull request that changes a pin `url` or the plugin set, adds a `site.lock` input or changes the trust-root declaration, job A does not run until the marker is present; the marker must be an attestation the author cannot produce, bound to one head and the named changes, and verified by jobs B′ and B from definitions outside the pull request, and the approval record is produced by job B′ and verified by job B (mechanisms open, `plugin-layout.md` §7); a break-glass route and a change of the trust-root declaration are also privileged; until built the preview diff is advisory. (e) **Statements corrected:** the claim that installing a package activates nothing was false (`.pth` files run when the interpreter starts and sdist build backends run at install time), so rule (5) says an unnamed plugin is "not selected"; hashes are to be checked at install time from a hash-locked, wheels-only resolution, plugin dependency closures pinned and the gate tools' dependencies locked; a plugin or recipe can copy one host's private data into another host's goal file and nothing in gates 3 to 5 checks that yet (planned: the projection lint checks for values from other hosts' slices; each host reads only its own goal files from the release store, by a per-host path and credential, while the operator and the signing job read all); folding the compiler in removed the producer/checker independence, listed as a cost in [`change-process.md`](change-process.md) §9; importers follow the naming and pinning rules of frontends, and gate 5 compares the plugin set with the previous release's. Amends D12, D15 (a pointer), D21, §1, §3, §5, §9.6 (when it applies) and Step 3. | +| D45 | Device-side component per platform | **Operator, 2026-11-02.** (1) tendcf-agent is **Android-only**, written in Kotlin. A Linux or macOS host runs CFEngine plus "a small validate-and-project command" (the ruling's words; the name **`tendcf-validate`** was chosen by the amending session on 2026-11-02 and may change without reopening the ruling), run before cf-agent reads `host_specific.json`; no daemon. (2) `tendcf-validate` is Python, the promotion of `bin/projector.py`: one implementation, so no byte-identity drift on those platforms. It needs `python3` on each host (Debian ships it, NixOS through the derivation, macOS bundled or the Command Line Tools). ~~The Android agent's Kotlin projector is a port held to the same golden bytes in CI (residue R22), not a second normative source.~~ (3) Built after schema v5 lands, before any further host is enforced (exception: the stage 1 macOS VM may enforce early, canary only, operator-authored data, like pastebin's; operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"; §12, §13). **Supersedes** every reading that ran the validator, the projector or the SQLite index inside tendcf-agent on every host: the §1 diagram's "CFEngine + tendcf-agent" per device, §8's index owner and D18 as written, §9's "run inside tendcf-agent" and "the agent binary" as the projector's call site, `goal-file-schema-reconciliation-2026-08-15.md` §0 item 7, §9 and §13 ("CI invokes the agent's own projector"), and `projector-reconciliation-2026-08-16.md` §9 and R22 ("tendcf-agent must reproduce" the reference). Not decided by it, and open for the operator: §12's list. **Amended 2026-11-14 ((1)-(2) and item 7):** (1)-(2) on Android the single Python `tendcf-validate` runs in Termux; the Kotlin agent independently re-checks the signature and the high-water mark, keeps the trust anchor and the approval record in its own app-private storage, and shows consent; there is no full Kotlin port of the validator (operator ruling, 2026-11-14, B3 sub 2 (Q21 / M-§12-06), "1. Termux + Kotlin trust check"). Item 7 (the SQLite index): every device keeps its own index **and** the log archive keeps a fleet-wide one; device JSONL stays authoritative; this was revised the same day from "2. Per-device indexes" to option 3 "Both" ("make that both") (operator ruling, 2026-11-14, Smaller 6 / M-§8-01; §8, §12 item 7). | +| D46 | Repository layout and compiler plugins | **Operator, 2026-11-13.** (1) `frdminc/nix2cf` folds into tendcf with full history, first under `compiler/` ([#45](https://github.com/frdminc/tendcf/pull/45)), and is archived as soon as that import merges. Both done 2026-11-13 (merge commit `ca4fa90`; the repository archived the same day). (2) The repository takes the plugin-type layout of [`plugin-layout.md`](plugin-layout.md): `schema/`, `examples/`, `policy/`, `overlay/`, `deploy/` unchanged; `tools/` (was `bin/`); `compiler/` (merge, conflict check, render); `plugins/frontends/` (`yaml`, `nix`, later `guix`, an authoring frontend), `plugins/supervisors/` (`launchd`, `systemd`, `runit`), `plugins/importers/` (`ansible`, `salt`); `contrib/` for in-tree third-party frontends and importers. It becomes one Python package, import name `tendcf`. (3) ~~Third-party frontends and importers are found through the public entry-point groups `tendcf.frontends` and `tendcf.importers`, so they can live out of tree as a pip package;~~ (deferred, see the amendment at the end of this row) plugins in this repository are found through a static import table, never entry points (9a). Supervisor renderers are in tree only; there is no public `tendcf.supervisors` group, because the goal file's `unit` is a closed `oneOf` and an out-of-tree renderer could only shadow a built-in. (4) Plugins are compile-time only: none runs on a device. The device artifact (`tendcf-validate`, D45) is built from the validator's own source alone, never imports `compiler/`, `plugins/` or `contrib/` and never calls entry-point discovery; the schema lint and the projector never import the compiler; a CI import check is to enforce both (planned). Plugins are trusted build-time code that the operator explicitly allows, not sandboxed: a plugin cannot make a device accept anything that device's own diff does not show (on Linux and macOS that validation is `tendcf-validate`, planned, D45, and does not exist yet; the Android agent was not checked), and cannot emit a shape the schema forbids, but it can make the goal file say something other than what the Site Model says, and it sees the site's private data. Release gates (schema lint, projector, preview diff) and signing are to run in a separate environment with no plugin installed, and the compile step is to hold no signing key (planned, Step 6; nothing enforces this today, and amendment (9) says what the environment is). A compile-side preview diff or `explain-hunk` (D44) is compiler output and inherits the plugins' trust. `contrib/`'s lower bar waives support and maintenance promises, never the standing review rule. Out-of-tree trust establishment and plugin management: [#47](https://github.com/frdminc/tendcf/issues/47). (5) Activation (the loader is planned, restructure step 4): a plugin is selected only if site-private names it (name → distribution, version, hash); an installed but unnamed plugin is not selected (installing a package can still run code, amendment (9)); a duplicate name in a group is a compile error; built-in names are reserved; until out-of-tree pinning exists (#47) a release build loads in-tree plugins only; the release's `targets.json` `custom` records the plugin set. (6) No users and no backward compatibility yet, so no shims: the compiler's command becomes `tendcf compile`, which replaces `nix2cf buildfile` with no alias (it compiles every host; `--host` renders one); `eval-nix` moves to the Nix frontend; `bin/` → `tools/` leaves no symlink or wrapper and rewrites every path reference in every file, dated records included (djbclark, 2026-11-13, a one-time exception to their append-only convention; only paths change, and prose naming nix2cf as the old repository stays as history); `nix2cf` names the Nix frontend (D12). The compiler renders only the current `schema_version`; older-version rendering is removed in the restructure, and §9.6's ceiling design applies once the first device that is not an operator host enrolls. (7) The keys `nix2cf_services` and `nix2cf_edges` were only ever illustrative: they occurred in guide §16.A's preview-channel example and its copy in the paper, and no schema, fixture, projector or bundle carried them (the projection's keys are `tendcf_service` and `tendcf_interlock`). In the same change that recorded this decision they were renamed `preview_services` and `preview_edges` (illustrative only, chosen so they cannot be mistaken for the `tendcf_services` bundle or the real projected keys `tendcf_service`/`tendcf_interlock`). No schema change is involved ([`plugin-layout.md`](plugin-layout.md) §6). (8) Consequence for [`change-process.md`](change-process.md): the compiler is no longer a separately pinned input, the two-repository bump order and the compiler's `tendcf.lock` go away; `site.lock` loses only its `nix2cf` entry. One tendcf rev is the unit a site pins, so a compiler fix brings the `schema/` and `policy/` commits before it; accepted, with no maintenance-branch machinery, revisited when the first device that is not an operator host enrolls. Moving `bin/` to `tools/` and the plugin split wait until open PRs #41 and #42 merge (historical: both merged 2026-11-14, #42 at acec5b5 and #41 at daa4530). (9) **Amended 2026-11-13 ([issue #48](https://github.com/frdminc/tendcf/issues/48), the adversary review of this decision; operator decisions D-a to D-d recorded in [its comment](https://github.com/frdminc/tendcf/issues/48#issuecomment-6857866487); full text in [`plugin-layout.md`](plugin-layout.md) §4). Nothing below is built; each part is tagged with its step.** (a) **In-tree proof (D-a), planned with the loader:** a plugin is in-tree when its module's realpath sits under the gate-1-verified tendcf tree, checked before the module's code runs (a release build runs the compiler from that tree without installing it); every in-tree plugin (frontends, supervisors, importers) is found through a static import table, never through entry points, which are read only for third-party plugins after #47: list every one without deduplication by name, refuse duplicate names and every entry point that claims a reserved name, whatever its distribution name, load only the named ones; release builds never resolve `tendcf` from a package index; a release build pins or refuses `TENDCF_DIR`. This replaces the first sentence of (3) for in-tree plugins: only third-party plugins use the public groups. (b) **Frontend inputs are code (D-b), planned, Step 6:** external (site-shared or foreign) recipes are imported, never fetched at compile time; the import pins by content digest, runs a static scan and an AI review, and records the verdict with the pin; compile evaluates only pinned recipes with an accepting verdict bound to the digest and fails closed on a failed scan, a rejecting review or a missing or mismatched verdict (the no-AI setting never overrides a negative result; only the gate-5 ceremony marker does, recorded with the pin and shown in every later gate-5 review; the recorded verdict is advisory, because job B′ re-runs the static scan and the AI review on the pinned digest and fails on a negative result), and a site-shared or foreign `site.lock` input is not an import by being pinned; every Nix evaluation, the site's own included, runs under `restrict-eval` with import-from-derivation off, an empty `allowed-uris`, no unsafe native code and no network, with the whole directory tree that the import digested and scanned passed to `-I` and nothing wider (the import refuses a symlink that resolves outside it); `pure-eval` is not used because it cannot evaluate a file named on the command line (tested 2026-11-13 on Nix 2.35.6 in CI, [run 43483740436](https://github.com/frdminc/tendcf/actions/runs/43483740436): the positive recipe evaluates, and file reads outside the recipe (a symlink escape, `readDir` and `builtins.path` included), `fetchurl`, `fetchTarball`, a local `fetchGit`, a `` lookup and `builtins.exec` are each refused, each flag shown by relaxing it alone, while `getEnv` returns the empty string; the import-from-derivation flag is the layer that refuses it (on a fresh store the read-only `--eval` stops it first, with a store-state-specific message) and was proven with `--read-write-mode`; the exact command and what stays untested are in `plugin-layout.md` §4); no Guix frontend until it has a sandbox design of its own; with no AI reachable at import the static scan still runs and `external_import.without_ai` (`require-human-ack` by default, or `warn`, or `refuse`) decides, for the import step only (job B′ still requires an AI review, or the ceremony override, before anything is signed), set in the site-private file that names plugins. (c) **Separate environment (D-c), planned, Step 6:** interim, a separate Unix user on the builder holds the key and the gate tools; the default before the first real release is a two-job split (job A on a throwaway runner with no secrets compiles, runs gate 2 and uploads goal-file bytes plus a digest manifest; job B in a protected signing environment builds the gate tools from the previous release's tendcf pin, never the pin under test (the first release uses the tip of the protected branch the trust root declares, resolved once by job B′ and bound to the approval), with hash-locked dependencies, installs no `tendcf`, runs gates 3 to 5 and signs exactly the digests it checked; job B′ is job B without the key, runs gates 3 to 5 for pull requests so that the reviewed preview is computed outside the plugins); signers in the first real release are one of n (operator rulings, 2026-11-13): the CI key held as a GitHub environment secret, which alone suffices; hardware tokens, optional, at least two if any is enrolled; and the separate Unix user, opt-in and non-default, whose enrolment lowers every release to its level; each enrolled signer signs alone (`vps-hub` and the Hyades podman runner are not signers); both token paths normally sign only the approved pull request's job A digests (merged tree equal to the approved head), path 1 after verifying a passing job B′ run and path 2 after re-running gates 3 to 5 itself with the previous release's gate tools, hash-locked, and `targets.json` `custom` records which; a break-glass route with no merged pull request is allowed, privileged and recorded there too, and is one person's act, bounded only by the threshold-one trust in that signer (ruling 19); job A's egress is unrestricted for now, a stated exfiltration risk left open in `plugin-layout.md` §7. (d) **Signed is what was reviewed (D-d), planned, Step 6:** the pull request's own job A artifacts, previewed by job B′, are what reviewers approve (the approval is bound to head commit, job A run, manifest, preview and baseline release) and what merge signs when the merged tree equals the approved head tree and nothing bound changed (otherwise the gates run and are reviewed again); branch protection on site-private; a changed pin `url`, a pin that does not descend from the previous one and a changed plugin set (the operator's list), and a tendcf bump that changes `tools/`, `schema/` or the projector (issue #48's fixes; such a bump ships as its own release with unchanged data, because the gate tools come from the previous release's pin, ruling 18; a planned tendcf CI check fails a commit that changes `tools/`, `schema/` or the projector together with the compiler goldens or with `policy/`, rulings 20 and 21) need the gate-5 ceremony marker, and so do (operator rulings) a new `site.lock` input, the files the gate jobs run, CI workflow and signer configuration, a signer backend change and a lowered `external_import.without_ai`; the tendcf pin's `url` and `ref` must be what the site's trust root declares (default `frdminc/tendcf` and `master`, or a listed release-branch set, each with required review, no force-push, no deletion and no administrator bypass), any other ref is refused, and a site may declare its own tendcf repository and branch set in its trust root, a privileged change that no per-pull-request marker substitutes for, and gate 1 reads the trust root from the protected base, never from the pull request, so one pull request cannot both change it and move the pin; a backward pin move across a `schema_version` bump is forbidden (roll forward) and within one version is privileged; for a pull request that changes a pin `url` or the plugin set, adds a `site.lock` input or changes the trust-root declaration, job A does not run until the marker is present; the marker must be an attestation the author cannot produce, bound to one head and the named changes, and verified by jobs B′ and B from definitions outside the pull request, and the approval record is produced by job B′ and verified by job B (mechanisms open, `plugin-layout.md` §7); a break-glass route and a change of the trust-root declaration are also privileged; until built the preview diff is advisory. (e) **Statements corrected:** the claim that installing a package activates nothing was false (`.pth` files run when the interpreter starts and sdist build backends run at install time), so rule (5) says an unnamed plugin is "not selected"; hashes are to be checked at install time from a hash-locked, wheels-only resolution, plugin dependency closures pinned and the gate tools' dependencies locked; a plugin or recipe can copy one host's private data into another host's goal file and nothing in gates 3 to 5 checks that yet (planned: the projection lint checks for values from other hosts' slices; each host reads only its own goal files from the release store, by a per-host path and credential, while the operator and the signing job read all); folding the compiler in removed the producer/checker independence, listed as a cost in [`change-process.md`](change-process.md) §9; importers follow the naming and pinning rules of frontends, and gate 5 compares the plugin set with the previous release's. Amends D12, D15 (a pointer), D21, §1, §3, §5, §9.6 (when it applies) and Step 3. **Amended 2026-11-14 (operator ruling, 2026-11-14, Smaller 5 (D46 out-of-tree plugin entry points, G-§4-01 / map Step 0, v2 C3), "1. Defer out-of-tree discovery"):** all plugins live in tree, compile-time only, never on a device; Python entry-point discovery of out-of-tree plugins is deferred until a user needs one and out-of-tree plugins can be pinned. The public entry-point groups of (3) are not built until then. | +| D47 | Goal | **Operator, 2026-11-13.** The goal is G1–G9 of [`../review-2026-11-13/00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md), as its rulings table records: primary aim "Adoptable tool" (row 1); first adopter "Nobody named yet." (row 2); finish line "The ladder of three states in G8" (row 7); wording "Agreed, with two changes to the draft", framing "focus on the user's freedom to control their own computing devices as they see fit", and "G9 added" (row 8). Adoption is the aim and see-and-refuse (G4) is its safety mechanism; this supersedes D8's "Sovereignty is the point" (the trust layer stays, as G4's mechanism) and §0 items 1 and 3. **Ruled 2026-11-14:** operator ruling, 2026-11-14, Smaller 3 (M-§15-01), "1. Yes, supersede D8's wording"; adopted with D48-D50, B4, "1. Adopt D47-D50". | +| D48 | Platform sequence | **Operator, 2026-11-13** (rulings row 6): "The first platforms should be MacOS as server and Android as client, followed by MacOS as client, followed by linux server, followed by linux client. Android is one of the most important pieces as it will be the major marketplace differentiator". Goal G5 (wording agreed, row 8) adds that Android management "works with Island/Insular profiles and with user-space ShizukuPlus". This supersedes D22 and the 2026-10-29 Linux-first ruling and Android deferral ([`linux-targets.md`](linux-targets.md)). Linux work already done stays: pastebin's canary keeps running as the standing proof (operator, 2026-10-31; "1. Keep it", B4 rider, canary), and Linux is later in the order, not paused ("1. Order language", B4 rider, Linux). **Ruled 2026-11-14** (B4, "1. Adopt D47-D50"; M-§15-02). | +| D49 | Authoring | **Operator, 2026-11-13** (rulings row 4): "Real Nix first, YAML beneath." Goal G2 (wording agreed, row 8): config is written in the real Nix language with NixOS-style options, so existing NixOS and nix-darwin configs carry over; plain YAML/JSON sits beneath it as the data form Nix evaluates to and can be written by hand; what a person is shown reads clearly without manuals. This amends D12 (Nix is first, not one of two equals). Carry-over: a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin and NixOS where the meaning is the same (operator ruling, 2026-11-14, B7, "1. Importer + matching names"). Nix may be required to build a release, build-time only (R5, D6). **Ruled 2026-11-14** (B4, "1. Adopt D47-D50"; M-§15-03). Still open, not decided by that ruling: whether `schema/` or the Nix module options is the schema authority (§4.1 says JSON Schema is generated from the module options), and whether a byte-identical YAML twin stays as the frontend's test. | +| D50 | Device shape | **Operator, 2026-11-13** (rulings row 6b): "I am not trying to change the architecture; client and server are not entirely meaningful here as each device will be self-sufficient and able to take updates from any other device that uses the correct crytoographic handshake. So when I say server I am refering only to the machines that are a server for services like recieving and archiving logs and doing monitoring of other machines." Goal G3 (wording agreed, row 8): every device converges on its own and there is no control node. This confirms D33, amends D14's git-synced policy, and amends §9.11's push rule (peer delivery). The handshake: "the correct cryptographic handshake" means content checks (signed by trusted keys, fresh, names this device, owner approval); transport authentication decides only who may talk; first build SSH-signature v0; the 2-of-3 offline-root floor may lag until TUF (operator ruling, 2026-11-14, B1, "1. Content checks; v0 first"; B13 item 1, "1. Keep text; B1 is the reading"; §9.11). Owners may also enrol standing modes (§9.1, B2). **Ruled 2026-11-14** (B4, "1. Adopt D47-D50"; M-§15-04). | Silence = proceed from Step 0. Objections amend this register. @@ -1345,6 +1701,14 @@ with full mesh) is **D38**. - `plugin-layout.md` — the repository's plugin-type layout, the plugin kinds and their two public entry-point groups, the plugin trust and activation rules, and the order of the move (D46). +- `../review-2026-11-13/` — the 2026-11-13 goal review: the goal + (`00-goal-definition.md`, G1-G9), the proposals behind D47-D50 and the + 2026-11-14 rulings written into this file, and the checks; + `../review-2026-11-13/rulings-record-2026-11-14.md` is the operator's + rulings record (the L-numbers cited in `14-synthesis-and-rulings.md`), + and 14 lists the one item still open: the AI reviewer "up to 30" count + (per reviewer or total), "open: deferred to the schema design review + (operator ruling, 2026-11-14, PR 62 review Q7)". - `tendcf-validate-proposal-2026-11-03.md` — a proposal, deciding nothing: options and a recommendation for each of §12's open D45 items, a minimal first build, and an operator picklist. diff --git a/docs/architecture/change-process.md b/docs/architecture/change-process.md index ed400a3..ec6519a 100644 --- a/docs/architecture/change-process.md +++ b/docs/architecture/change-process.md @@ -112,8 +112,12 @@ Rules for the file, each with the reason it is a rule: commit, reachable from what branch); `tree` is what the build verifies after fetching, because a rewritten branch can move `rev` out from under a `ref` while `tree` still proves the content. Both are plain git - objects: no Nix is needed to compute or check them, which R5 and D6 - require (Nix is an optional builder, never a dependency of the path). + objects: no Nix is needed to compute or check them. Nix may be required + to build a release; devices never need Nix at run time (operator ruling, + 2026-11-14, B4 rider "Nix on release path": "2. Allow on release path", + scope "1. Build-time only"). This amends the earlier reading of R5/D6 + (Nix an optional builder, never a dependency of the release path); the + map's R5/D6 text is amended to match there. 3. **A build never follows `ref`, but `ref` is verified.** The resolver updates `rev`/`tree` from `ref` on request, and a build never replaces the pinned `rev` with the tip of the moving `ref`. Gate 1 does fetch @@ -127,7 +131,11 @@ Rules for the file, each with the reason it is a rule: is content inside the tendcf input; a built binary or the Android agent's APK enters a release only as a digest-bound fetched artifact (map §9.8, DC-11). The lockfile - pins sources, not binaries. + pins sources, not binaries. A person's own fork (G9, later) is not a + tool fork in this sense. Its build, like a tool fork's, reaches a device + only as a digest-bound artifact; its upstream pin is in site.lock, and + its patches are site content. (Operator ruling, 2026-11-14, Smaller 4, + X-forks-05: "1. Yes, a site.lock source input".) 6. **A changed `url` is a privileged change** (decision D-d, issue #48; planned, Step 6). Gate 1 below verifies that `rev` belongs to `ref` at `url` and that `tree` matches, so a pull request that repoints a pin @@ -199,7 +207,7 @@ Three properties follow: exists ([#47](https://github.com/frdminc/tendcf/issues/47)), a release build loads only in-tree plugins named by site-private, so the tendcf pin covers them, and plugins installed on the builder but not named - are not selected (map D46; installing one can still run code, plugin-layout §4). Reproducing the release byte for byte also + are not selected (map D46; installing one can still run code, plugin-layout §4). Out-of-tree discovery is itself deferred until a user needs it and out-of-tree plugins can be pinned (operator ruling, 2026-11-14, Smaller 5). Reproducing the release byte for byte also needs a fixed dependency and toolchain closure for the build and controlled or recorded external inputs (environment, network); those are not specified yet. @@ -427,7 +435,7 @@ the review artifact; a diff computed in the compile job never is): verifies the pins itself; jobs B′ and B take nothing from job A but goal-file bytes and the digest manifest (plugin-layout §4). 2. Compile every host, loading only the compiler plugins site-private - names (in-tree only until #47; map D46; the loader is planned, + names (in-tree only; out-of-tree discovery is deferred, with #47, until a user needs it and plugins can be pinned: operator ruling, 2026-11-14, Smaller 5; map D46; the loader is planned, [`plugin-layout.md`](plugin-layout.md) §4). Conflict-as-error (map §3): the same identity from two peer inputs without a private bind refuses the whole release, and so does a duplicate plugin name within a group. @@ -711,8 +719,11 @@ moved on since. says), and makes the public engine's history irrelevant to its users. 5. **Nix `flake.lock` as the mandatory lock.** The shape is right and the resolver is battle-tested, but it needs Nix to compute `narHash`, which - makes Nix a dependency of the release path on the builder; R5/D6 keep Nix - optional. `site.lock` keeps the two git hashes Nix does not need and can + makes Nix a dependency of the release path on the builder. The operator + has since allowed Nix on the release path, build-time only (§2 rule 2; + operator ruling, 2026-11-14, B4 rider "Nix on release path"), so Nix is + no longer excluded on principle; this choice stands on the other + grounds: `site.lock` keeps the two git hashes Nix does not need and can be converted into flake inputs when a Nix builder exists (Step 7/10+). 6. **Devices reading git directly** (a device fetches the policy tree from a branch). This is what "git-synced policy" is sometimes taken to mean and diff --git a/docs/architecture/plugin-layout.md b/docs/architecture/plugin-layout.md index e9fa1b1..34a6fb6 100644 --- a/docs/architecture/plugin-layout.md +++ b/docs/architecture/plugin-layout.md @@ -15,6 +15,23 @@ > code enforces yet is tagged "planned", with its step.** Today there is > no plugin loader, no release pipeline, no gate separation, no import > step and no device-side validation command. +> +> **Amended 2026-11-14 (operator ruling, 2026-11-14, Smaller 5 (D46 +> out-of-tree plugin entry points, G-§4-01 / map Step 0, v2 C3), "1. Defer +> out-of-tree discovery"; map D46, amendment at the end of the row).** All +> plugins live in tree, run at compile time only and never on a device. +> Python entry-point discovery of out-of-tree plugins is **deferred until a +> user needs one and out-of-tree plugins can be pinned** (both, not either; +> pinning is [#47](https://github.com/frdminc/tendcf/issues/47)). The +> deliverable of restructure step 4 (§5) is the **static in-tree import +> table**; the public entry-point groups `tendcf.frontends` and +> `tendcf.importers` are not built, and no release build reads an entry +> point. Every passage below that describes third-party entry-point +> discovery (§1 item 3, §2's entry-point row, §3's table, §4's activation +> steps 2 and 5 and the "Out of tree" item, §5 step 4, §7's #47 item) is +> now **deferred design, kept as history** and marked "deferred" where it +> stands; it takes effect only if both conditions are met (a user needs +> one, and out-of-tree plugins can be pinned). ## 1. The decision @@ -26,14 +43,19 @@ 2. The repository takes the plugin-type layout of §2. It becomes one Python package, import name `tendcf` (today's `nix2cf` package is renamed; how the directories map onto it is open, §7). -3. A third-party frontend or importer can live outside this repository as +3. ~~A third-party frontend or importer can live outside this repository as an ordinary pip package, found through the public Python entry-point - groups `tendcf.frontends` and `tendcf.importers` (§3). Every plugin in - this repository (frontends, supervisor renderers and importers) is - found through a static import table, never through entry points (§4, - activation; planned, restructure step 4: no table exists today). - Supervisor renderers are in tree only; there is no public - `tendcf.supervisors` group (§3). + groups `tendcf.frontends` and `tendcf.importers` (§3).~~ **Amended + 2026-11-14 (Smaller 5, "1. Defer out-of-tree discovery"):** all plugins + live in tree and run only at compile time; entry-point discovery of + out-of-tree plugins is deferred until a user needs one and out-of-tree + plugins can be pinned, and the public groups are not built until then + (the deferred design stays in §3 and §4). Every plugin in this + repository (frontends, supervisor renderers and importers) is found + through a static import table, never through entry points (§4, + activation; planned, restructure step 4: no table exists today; this + table is the deliverable). Supervisor renderers are in tree only; there + is no public `tendcf.supervisors` group (§3). 4. Plugins run at compile time only, and they are trusted build-time code that the operator explicitly allows, not sandboxed code (§4). 5. A plugin is selected only if site-private names it (§4, activation; @@ -102,7 +124,7 @@ tendcf/ | `plugins/supervisors/systemd/`, `runit/` | nothing: a service selected for a systemd or runit host is a compile error (`RENDERED_SUPERVISORS` in `compile.py`) | written in tree ([`linux-targets.md`](linux-targets.md) §3, step 6) | | `plugins/importers/` | nothing | optional | | `contrib/` | nothing | as third parties contribute | -| entry-point groups | none; nix2cf's `pyproject.toml` declares only the `nix2cf` script | the two public groups of §3, read for third-party plugins only; in-tree plugins are found through a static import table (§4) | +| entry-point groups | none; nix2cf's `pyproject.toml` declares only the `nix2cf` script | none for now: the two public groups of §3 are deferred (Smaller 5, 2026-11-14); in-tree plugins are found through a static import table (§4) | A supervisor plugin renders a service record into the goal file's `unit` entry for that supervisor and resolves that supervisor's defaults (for @@ -115,10 +137,19 @@ Wherever it lands, the device boundary rules of §4 apply to it. ## 3. Plugin kinds and entry-point groups +> **Amended 2026-11-14 (operator ruling, 2026-11-14, Smaller 5, "1. Defer +> out-of-tree discovery"):** the two public groups in this table are the +> **deferred design**, not a deliverable. All plugins live in tree and are +> found through a static import table; discovery of out-of-tree plugins by +> Python entry points waits until a user needs one **and** out-of-tree +> plugins can be pinned ([#47](https://github.com/frdminc/tendcf/issues/47)). +> The table below keeps the old design as history, so a later ruling can +> revive it without rewriting it. + | Kind | Entry-point group | What it is | | --- | --- | --- | -| Frontend | `tendcf.frontends` (public; third-party plugins only, §4) | A language a site keeps authoring in. It turns its source into the Site Model's JSON, which the compiler then merges, checks and renders like any other. YAML and Nix are the two equal frontends of map D12; Guix may follow as an authoring frontend (Guile records → Site Model JSON) once it has a sandbox design of its own (§4). | -| Importer | `tendcf.importers` (public; third-party plugins only, §4) | An optional one-shot migration from another tool's configuration (Ansible, Salt) into Site Model files, which the site then keeps and edits as its own. Not run on every compile. | +| Frontend | `tendcf.frontends` (deferred: public group for third-party plugins only, §4) | A language a site keeps authoring in. It turns its source into the Site Model's JSON, which the compiler then merges, checks and renders like any other. YAML and Nix are the two equal frontends of map D12; Guix may follow as an authoring frontend (Guile records → Site Model JSON) once it has a sandbox design of its own (§4). | +| Importer | `tendcf.importers` (deferred: public group for third-party plugins only, §4) | An optional one-shot migration from another tool's configuration (Ansible, Salt) into Site Model files, which the site then keeps and edits as its own. Not run on every compile. | | Supervisor renderer | none: in tree only | A unit renderer for one supervisor (launchd, systemd, runit): service record in, goal-file `unit` entry out (§2). | The difference between a frontend and an importer is what happens next. A @@ -147,7 +178,7 @@ decided (§7). Built-in frontends, supervisor renderers and importers are in tree, are to be found through a static import table and never through entry points (planned, §4: no table exists today), and their names are reserved -against third-party entry points (§4). The +against third-party entry points should those be built (deferred, §4). The Python interface a plugin implements, and the table's format, are not specified yet; they are to be settled when the split is done (§5, step 4). @@ -787,7 +818,13 @@ the preview diff is **advisory**. The rule: **Activation: a plugin is selected only if site-private names it** (the loader is **planned**, restructure step 4, and Step 6 for the release -checks; no loader exists today). The steps run in this order: +checks; no loader exists today). The steps run in this order. +**Deferral (operator ruling, 2026-11-14, Smaller 5, "1. Defer out-of-tree +discovery"):** the deliverable is steps 1, 3 (for in-tree plugins), 4, 6, 7 +and 8 over the static import table. Step 2 and the third-party parts of +steps 3 and 5 describe out-of-tree discovery, which is deferred until a +user needs it and out-of-tree plugins can be pinned (#47); they are kept +as the deferred design. 1. **In-tree plugins come from a static import table.** A plugin is in-tree when its module's realpath, with symlinks resolved, sits under @@ -807,8 +844,10 @@ checks; no loader exists today). The steps run in this order: resolves each table entry to a file, checks that file's realpath, and only then executes it by file location, the way `load_projector` in `compiler/nix2cf/cli.py` already loads the projector. -2. **Entry points are read only for third-party plugins**, and only after - [#47](https://github.com/frdminc/tendcf/issues/47) exists. The loader +2. **Deferred: entry points are read only for third-party plugins**, and + only after [#47](https://github.com/frdminc/tendcf/issues/47) exists + (until then they are not read at all, so there is no loader code for + this step). The loader lists every entry point, with no deduplication by distribution name (`importlib.metadata.entry_points()` drops a second distribution with the same name, so "a duplicate name is a compile error" could never @@ -835,9 +874,9 @@ checks; no loader exists today). The steps run in this order: 4. **Importers follow the same rules as frontends**: an importer runs only if it is named and pinned. Which importers an operator may run is exactly the set site-private names. -5. **Until out-of-tree pinning exists** - ([#47](https://github.com/frdminc/tendcf/issues/47)), a release build - loads in-tree plugins only (`plugins/` and `contrib/`, at the pinned +5. **Until out-of-tree pinning exists** (and entry-point discovery, which + is deferred with it; [#47](https://github.com/frdminc/tendcf/issues/47)), + a release build loads in-tree plugins only (`plugins/` and `contrib/`, at the pinned tendcf rev). That way the tendcf pin identifies the source of the compiler and of every plugin a release loads. Reproducing a release byte for byte also needs a fixed dependency and toolchain closure and @@ -865,7 +904,8 @@ checks; no loader exists today). The steps run in this order: How an out-of-tree plugin earns trust (an OpenPGP web of trust) and how a site manages its plugins (a `tendcf plugin` command) is -[#47](https://github.com/frdminc/tendcf/issues/47). +[#47](https://github.com/frdminc/tendcf/issues/47); it is deferred with +out-of-tree discovery (Smaller 5, 2026-11-14). **Current schema version only.** The compiler renders only the current `schema_version`. Its ability to render older versions (today nix2cf's @@ -884,12 +924,13 @@ and the multi-version render returns with it. into the repository with a lower bar. The lower bar waives support and maintenance promises only: the project does not promise to fix, keep or port a contrib plugin. It never waives the standing review rule - (root `AGENTS.md`: every pull request gets a cross-model frontier - review), because contrib code runs in the release pipeline with the + (root `AGENTS.md` rule 3: contrib code is neither docs, a spike note nor + device code, so it keeps at least one cross-model frontier review), because contrib code runs in the release pipeline with the same privilege as everything else. A contrib plugin is off unless site-private names it, like any other. -3. **Out of tree.** A pip package that registers under `tendcf.frontends` - or `tendcf.importers`, the way Salt extensions and Ansible collections +3. **Out of tree (deferred, Smaller 5, 2026-11-14: not built until a user + needs it and out-of-tree plugins can be pinned).** A pip package that + registers under `tendcf.frontends` or `tendcf.importers`, the way Salt extensions and Ansible collections are shipped apart from Salt and Ansible. tendcf does not review it. Its output passes the same release gates as any plugin's, which bound its shape, not its faithfulness (above). A release build does not load @@ -903,7 +944,7 @@ and the multi-version render returns with it. | 1 | This documentation: the guide, the paper, the map (D46), the change process, the Linux targets plan, the glossary, this file; and the rename of the illustrative `nix2cf_*` keys (§6). Moves no files and changes no code or schema. | this change | | 2 | Import `frdminc/nix2cf` with full history under `compiler/`; the root `README.md` follows. | done: [#45](https://github.com/frdminc/tendcf/pull/45), merged 2026-11-13 (`ca4fa90`) | | 3 | Archive `frdminc/nix2cf`. | done 2026-11-13, right after #45 merged (README points here) | -| 4 | The restructure, one pull request: `bin/` → `tools/`; the Python package renamed `tendcf`; the compiler split into `compiler/` and `plugins/` with the static import table for in-tree plugins (§4) and the two public entry-point groups, which are not read until #47; `tendcf compile` replaces `nix2cf buildfile`; older-version rendering removed; the device-boundary import check (§4). No alias, symlink or wrapper. Waits until open PRs #41 and #42 merge. | planned | +| 4 | The restructure, one pull request: `bin/` → `tools/`; the Python package renamed `tendcf`; the compiler split into `compiler/` and `plugins/` with the static import table for in-tree plugins (§4), which is the deliverable (~~and the two public entry-point groups, which are not read until #47~~: the groups are deferred, not part of this step, until a user needs out-of-tree plugins and they can be pinned; operator ruling, 2026-11-14, Smaller 5); `tendcf compile` replaces `nix2cf buildfile`; older-version rendering removed; the device-boundary import check (§4). No alias, symlink or wrapper. PRs #41 and #42 are merged. | planned | | 5 (map's Step 6) | The release pipeline (Step 6, [`change-process.md`](change-process.md) §10) and the §4 properties that depend on it: the plugin loader's activation steps; the two-job split and its signer backends; promotion of the pull request's artifacts and branch protection on site-private; the privileged-change checks of gate 5; the import step for external recipes with the Nix limits; the projection lint's cross-host check. None is built. The two numberings differ: this table's step 5 is the map's Step 6. | planned | Step 4 rewrites every path reference in every file, dated records @@ -998,8 +1039,9 @@ change, because the list moves: `external_import.without_ai` (§4, frontend inputs) lives in this file, so the file's format decides how that setting is written; TOML unless decided otherwise. -- Out-of-tree pinning and trust establishment, after which a release - build may load an out-of-tree plugin +- Out-of-tree pinning and trust establishment, after which (and only when + a user needs one: Smaller 5, 2026-11-14) entry-point discovery of an + out-of-tree plugin may be built and a release build may load one ([#47](https://github.com/frdminc/tendcf/issues/47)). - Compile-step network access: job A's egress is unrestricted for now (operator ruling, §4), and a future restriction stays open below. Still diff --git a/docs/architecture/tendcf-validate-proposal-2026-11-03.md b/docs/architecture/tendcf-validate-proposal-2026-11-03.md index 83df1d7..6168dff 100644 --- a/docs/architecture/tendcf-validate-proposal-2026-11-03.md +++ b/docs/architecture/tendcf-validate-proposal-2026-11-03.md @@ -1225,7 +1225,8 @@ The fork-side all-or-nothing loader (PR #41) and this check hold each without the other: with the loader failing closed, the file's keys are not loaded and the check refuses and reports it, which is correct and louder. The independence is limited, not complete: the loader's strict parse (a repeated member or -trailing input refuses the file; fork `4443504`) belongs to the CMDB loader +trailing input refuses the file; fork `4443504`, the pin moved by PR #61, merged +2026-11-15T00:12:15Z, `401e0f6`) belongs to the CMDB loader only, while this check's `readjson` stays lenient and sees the last of a repeated member or `vars` section, so an earlier container the loader refused is not named by the check. The check reports a refusal when that lenient view diff --git a/docs/architecture/upstream-overlay.md b/docs/architecture/upstream-overlay.md index 5ea36ab..58ff2ea 100644 --- a/docs/architecture/upstream-overlay.md +++ b/docs/architecture/upstream-overlay.md @@ -226,10 +226,15 @@ CMDB loader that replaces B-5b's per-entry skip (a skipped interlock leaves the services it guards unguarded). The manifest entry still reproduces `8f0076b81` and carries a `superseded_on_fork` note; the table above is the 2026-10-09 state and is not updated. Upstream plus this overlay skips a bad entry; the -pinned fork installs nothing from the file. The operator ruled on 2026-11-14 -to replace the patch: a later, separate PR makes the overlay carry the -all-or-nothing loader in its place ([`upstream-register.md`](upstream-register.md) -B-5b note). +pinned fork installs nothing from the file. Operator ruling, 2026-11-14, B11 +round 2 item 1 (adversary D5, Astra C2): "1. Replace". The overlay carries the +all-or-nothing CMDB loader (R13) instead of B-5b's per-entry skip, so +upstream-plus-overlay builds match the pinned fork; if the overlay cannot patch +libntech it carries the core part only (no strict parse). `8f0076b81` (fork PR +59) is retired, never offered upstream. Status: ruled; implementation pending +in a follow-up PR (overlay phase B), because it changes what the overlay +reproduces ([`upstream-register.md`](upstream-register.md), "Operator rulings of +2026-11-14 on the queue and the fork", item 2). So the overlay reproduces exactly the inputs whose build was verified on 2026-08-19, from this repository alone, and would still apply to a build diff --git a/docs/architecture/upstream-register.md b/docs/architecture/upstream-register.md index 5dc08d2..ac68107 100644 --- a/docs/architecture/upstream-register.md +++ b/docs/architecture/upstream-register.md @@ -350,7 +350,8 @@ tendcf that is fail-open: an interlock entry dropped at load leaves the services it guards actuated unguarded. `tendcf-integration` now carries `cmdb-fail-closed` (`a750b1dfe`, `dbf9dede6`, `61065e551`, `736becc07`, merged `d32cade13`; hardened by djbclark/core PR #98 and a strict libntech JSON parse, -fork PR 99 moved the CMDB test seam under `TEST_UNIT_TEST`; the pin now `4443504`): `LoadCMDBData()` validates every entry of +fork PR 99 moved the CMDB test seam under `TEST_UNIT_TEST`; the pin now `4443504`, +moved by PR #61, merged 2026-11-15T00:12:15Z, `401e0f6`): `LoadCMDBData()` validates every entry of `vars`/`variables`/`classes` first and installs nothing from `host_specific.json` if any one is invalid (also an unknown top-level key, a null section, a key with index brackets, a frame-dependent special scope, two @@ -369,7 +370,67 @@ a `superseded_on_fork` note saying so, and overlay keeps, retires or replaces that patch was ruled on 2026-11-14 (Replace: the overlay will carry the all-or-nothing loader instead of the per-entry skip), and is done in a later, separate PR because it changes what the overlay -reproduces. +reproduces. The ruling is recorded in full under "Operator rulings of +2026-11-14 on the queue and the fork" below. + +### Operator rulings of 2026-11-14 on the queue and the fork + +Ruled, one item per line. Quotes are the operator's chosen options, exactly. + +1. **PR queue (B11).** Operator ruling, 2026-11-14, B11: "1. Review+merge #42, + then #41; park s5". Frontier plus adversary review of #42, then merge it; + rebase #41, fix its two stale statements and its stale pin hash, review it, + merge it. The two 2026-11-02 rulings are recorded with #41 (the fork's + all-or-nothing loader, R13, in the B-5b note above), without duplicating + #42's own paragraph, which records the other (Q10, "Implemented + 2026-11-06"; V-§13-11, C9). `s5-design` (the report-only systemd/dpkg + detector, 54 commits behind) is parked and the branch kept. Queued by the + lead; at the time of the ruling the reviews and merges were not yet done + (historical). Outcome, 2026-11-14: #42 merged (`acec5b5`), then #41 + (`daa4530`), in the ruled order; `s5-design` stays parked. +2. **B-5b: overlay carries the all-or-nothing loader.** Operator ruling, + 2026-11-14, B11 round 2 item 1 (adversary D5, Astra C2, upstream queue C2): + "1. Replace". The overlay carries the all-or-nothing CMDB loader (R13) + instead of B-5b's per-entry skip, so upstream-plus-overlay builds match + the pinned fork. If the overlay cannot patch libntech, it carries the core + part only (no strict parse). Upstream is later offered the core + all-or-nothing series (queue item 7 of e0d15d93's upstream queue, still + gated on D1/D2 and on libntech item 6). `8f0076b81` (fork PR 59) is + retired and never offered upstream. Status: ruled; implementation pending + in a follow-up PR (overlay phase B); queued as build work. The overlay + side is in [`upstream-overlay.md`](upstream-overlay.md) section 7. +3. **Fork-only assertions in `tests/policy/run.sh`.** Operator ruling, + 2026-11-14, B11 round 2 item 2 (adversary D1, Astra r2 B3): "1. Keep Mac, + SKIPs". The Mac dev build stays a `run.sh` target and prints an explicit + SKIP for each fork-only assertion; Linux CI sets + `TENDCF_REQUIRE_FORK_LOADER=1` and fails on any SKIP. Follow-up (Astra r2 + B3): assertions that hold only with the strict loader (the `strict_case` + policy refusals) are gated the same way, so a non-fork run passes with + SKIPs rather than failing (done in the base: the `strict_case` calls with + POLICY `fork` go through `fork_only` in `tests/policy/run.sh`; not yet run + on the Mac). How the script behaves is in `AGENTS.md` + ("Verifying policy and the CFEngine build"). +4. **Upstream queue order.** Operator ruling, 2026-11-14, B11 round 2 item 3: + "1. Leave order as is". The libntech strict parse stays queue item 6, + after the four `--simulate-json` PRs. +5. **`.gitmodules` in the fork's core.** Operator ruling, 2026-11-14, B11 + round 2 item 4 (adversary r2 I3): "1. Bundle with next pin move". A + one-line `.gitmodules` change pointing libntech at + `https://github.com/djbclark/libntech` lands on `djbclark/core` + `tendcf-integration` together with the next real engine change (for + example the `CMDBTestFailInsertion` test-hook removal). PR #41 merges at + `6505f48` without it. Upstream PRs keep upstream's URL. Status: the + `.gitmodules` change is in place at the pin `4443504` (checked in + `djbclark/core`: `libntech` points at `https://github.com/djbclark/libntech`); + that pin move is PR #61, merged 2026-11-15T00:12:15Z, `401e0f6`. +6. **`--simulate-json` upstream (Smaller 7).** Operator ruling, 2026-11-14, + Smaller 7: "Talk to 2d776056-3ea2-4fe5-a8d6-b59574dc427f about this and + let it lead and ask me any questions; you monitor and get the final + decision/state." Outcome, via 2d776056 (2026-11-14): the operator chose + "Prepare the PR". It is **not sent**: the cfengine worker 7d55e815 is + preparing it, and the operator's review gates sending. Nothing is posted + upstream until that review (the standing rule that nothing is re-sent + without the operator stands). B-2 through B-7 are described, measured and sourced in [`cfengine-upstream-candidates-2026-08-16.md`](cfengine-upstream-candidates-2026-08-16.md); diff --git a/docs/review-2026-11-13/00-goal-definition.md b/docs/review-2026-11-13/00-goal-definition.md new file mode 100644 index 0000000..6f90418 --- /dev/null +++ b/docs/review-2026-11-13/00-goal-definition.md @@ -0,0 +1,133 @@ +# tendcf goal definition (agreed 2026-11-13) + +Status: agreed between djbclark and the reviewing session on 2026-11-13, in an +eight-question walk; amended by the operator's rulings of 2026-11-14 (see +"Later rulings" below). This file is new. No original document was changed. The +review documents beside it measure everything against paragraphs G1 to G9. + +Base commit for every anchor in this directory: `eefea3c` (master). + +## The goal + +**G1. Aim.** tendcf is free software that gives people control of their own +computing devices as they see fit. It is a configuration management system that +other people adopt. It is used through an AI or directly at the code level, +whichever the user prefers at any moment. Through an AI, a person says what +they want; the AI writes it as configuration and explains or warns when a +request looks unwise. The first adopters are sysadmins who already share +configs in Nix. The long-run user is a person with no admin skill at all. + +**G2. Authoring.** Config is written in the real Nix language, with +NixOS-style options, so existing NixOS and nix-darwin configs carry over. +Plain YAML/JSON sits beneath it as the data form Nix evaluates to, and can be +written by hand. What a person is shown reads clearly without manuals. + +**G3. Shape.** Every device is self-sufficient: it converges on its own, there +is no control node, and it accepts updates from any other device that +completes the correct cryptographic handshake. "Server" means only a machine +that provides services to others, such as receiving and archiving logs and +monitoring. "Client" means a device that uses them. The architecture is not +changed by these words. + +**G4. Safety.** Nothing changes a device except as an exact, mechanically +checked difference that the device's owner can see and refuse. Each difference +is also scanned for likely safety in several ways, AI among them. The owner is +shown a safety score from 0 to 100, set as a ceiling by mechanical checks that +AI review can lower but never raise, with an explanation of each part of it, +its measured hit rate once a test corpus exists, and the questionable code +highlighted more dramatically the less safe it looks. This is offered in a command-line mode and a TUI mode. The TUI is +built on a scaffold borrowed from another project. + +**G5. Platforms, in order.** + +1. macOS as server +2. Android as client +3. macOS as client +4. Linux as server +5. Linux as client + +Android is the main differentiator: comprehensive configuration management +that works with Island/Insular profiles and with user-space ShizukuPlus, which +the operator believes nothing else offers. + +**G6. Premise.** That AIs write the configuration is the premise of the +project. It is not a hypothesis the project sets out to test. + +**G7. Instruments.** CFEngine, the CFEngine fork, the Site Model and the +compiler are instruments. They are open to challenge, and nothing about them +changes without the operator's ruling. + +**G8. Finish line.** Three states. Each is reached in this order, but work toward state 3 may start once state 1 holds. + +1. One of the operator's Macs and one of his Android devices converge from + Nix-authored config, with updates accepted only after the cryptographic + handshake and logs archived on the Mac. +2. The operator's whole fleet runs on tendcf and the `~/ops` suite is retired. +3. A person the operator has not helped installs it from the public docs with + their own AI and keeps using it. From state 1 on, a clean machine with a + fresh AI session that has only the public docs rehearses this in CI. + +**G9. Later.** Free-software branch management, built as an extension of the +platform's existing patch patterns, so that non-technical users can maintain +forks of projects, or of plugins to projects, without knowing about merging, +rebasing or compiling. + +Whether tendcf becomes a product is undecided. If it does, it stays free +software. + +## Rulings behind it + +Each row is one question and the operator's answer. Quoted text is his. + +| # | Question | Answer | +|---|---|---| +| 1 | Primary aim | Adoptable tool. "we eventually want to get to the point that non-sysadmin users, even clueless people, could use the tool via only via AI, with the AI translating the user's wishes into action, and teaching the user if a request looks maybe bad" | +| 2 | First adopter | Nobody named yet. | +| 3 | CFEngine | Instrument, open to challenge. | +| 4 | Nix authoring | Real Nix first, YAML beneath. | +| 5 | AI-only use | Taken as given; no experiment asked for. | +| 6 | Platforms | "The first platforms should be MacOS as server and Android as client, followed by MacOS as client, followed by linux server, followed by linux client. Android is one of the most important pieces as it will be the major marketplace differentiator" | +| 6b | Server and client | "I am not trying to change the architecture; client and server are not entirely meaningful here as each device will be self-sufficient and able to take updates from any other device that uses the correct crytoographic handshake. So when I say server I am refering only to the machines that are a server for services like recieving and archiving logs and doing monitoring of other machines." | +| 7 | Finish line | The ladder of three states in G8. | +| 8 | Wording | Agreed, with two changes to the draft. G1: "it is used through an AI or at the code level depending on the user's preference at any point in time." G4: "the diffs are also scanned in various ways including using AI for likely safety, and the user gets to see safety confidence out of 100% as well as an explanation of why that percentage was choosen and the code that is questionable should be hilighted in increasingly dramatic ways depending on safety (we should borrow a TUI scaffold from another project, and have both command-line and TUI modes)." Framing: "focus on the user's freedom to control their own computing devices as they see fit." G9 added. | + +## Later rulings (2026-11-14) + +The goal text above changed in three places, all from the 2026-11-14 walk of +`14-synthesis-and-rulings.md` section B: the G4 figure sentence (B13 items 2 +and 3, settled by B8), the G8 lead sentence (B13 item 4) and G8 item 3 (B13 +item 5). Everything else below is a reading, recorded here so no reader has to +open the review to learn it. +Every quotation is the operator's chosen option; each is cited as +`operator ruling, 2026-11-14, `. + +1. **G3 and G8.1, the handshake (B1; B13 item 1).** B13 item 1: "1. Keep text; B1 is the reading". The goal text is unchanged. "The correct cryptographic handshake" means B1's content checks: B1: "1. Content checks; v0 first". An update is accepted only if it is signed by keys the device trusts, fresh, names this device, and carries the owner's approval; transport authentication decides only who may talk. First build: SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter); the map's 2-of-3 offline-root floor may lag until TUF. +2. **G4, the figure (B8; B13 items 2 and 3).** B13 items 2 and 3 are settled by B8: "1. Capped 0-100 score". The reading is wording 3: "score from 0 to 100", mechanical checks set a ceiling that AI review can lower but never raise, an explanation of each part, and a measured hit rate once a corpus exists (B13 wording 3, X-pm-03). G4 above carries it: the sentence beginning "The owner is shown" now reads as wording 3, with the highlighting clause kept (B13 wording 3 as written omits it; the operator's row-8 wording requires it). Ruled (operator ruling, 2026-11-14, PR 62 review Q5, record line L61): "1. Yes, keep it". This composite, wording 3 plus the kept highlighting clause, is the ruled sentence. (The two PR 62 reviewers had differed: one called it faithful, one asked for confirmation.) The operator's verbatim words stay in row 8 of the table. The cap values are B8 sub 1, "1. 09's table, top 95" (`03-response-map.md` M-§9-03). The owner-set auto-refuse floor is B8 sub 2, "1. Allowed, off by default" (`02-response-guide.md` G-§7-01). G4 stays whole in state 1: B8 sub 3, "1. Build order, not scope" (the CLI diff and `y/N` is built first, state 1 is declared only once score, explanation, highlighting and TUI land, and there is no "state 1.5"). The TUI scaffold is B12, "2. Borrow both freely; raise Python" (Toad and textual-diff-view; the review TUI becomes AGPL-3.0-only and moves to Python >=3.14). +3. **G5, platforms and "comprehensive" (B9; B13 item 6).** B9: "1. Keep G5; word public claim". G5 is unchanged. Public docs use "we know of no other tool that converges an owner's own unrooted phone, including its Island/Insular work profile, from a signed goal file, without MDM enrollment or root" and state the developer-verification terms (ADB exempt; advanced flow one-day wait; limited distribution 20 against 50 devices discrepancy). B13 item 6 is settled by B9. +4. **G2, "carry over" (B7; B13 item 7).** B7: "1. Importer + matching names": a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin and NixOS where the meaning is the same. No G2 text was proposed, so none changed (B13 item 7). +5. **G8, order and rehearsal (B13 items 4 and 5).** B13 item 4: "1. Adopt the clarification". B13 item 5: "1. Add the rehearsal sentence". Both are applied in G8 above. +6. **G3 and G8.1, the `monitor` role (B4 rider).** "1. State 2": state 1 needs only the log archive (G8.1). +7. **G8, Android and Mac in state 1 (B3, B6).** B3: "3. Termux CFEngine + thin Kotlin". B6: "1. Plain Mac, launchd by tendcf", with sub 1 "1. macOS VM on bigmac" (state 1's Mac is an Apple Silicon macOS VM, a client and not an always-on server, that is also the log-archive server while bigmac is awake). Details are in `14-synthesis-and-rulings.md` section B. B3's ruling is about trust, consent and Termux; the Android log and index afterwards is ruled separately (operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role"): "only" is about decisions; the thin Kotlin agent still writes the device JSONL and index as a support role; map and D18 stand. + +## Where this differs from the documents at `eefea3c` + +These are the differences the review starts from. Each is taken up in the +response documents. + +1. **Platform order.** The documents follow the 2026-10-29 order: Linux first, + Android deferred. G5 puts macOS and Android first and Linux fourth and + fifth. Every live host today is Linux. +2. **Nix and YAML.** D12 makes them equal frontends. G2 puts Nix first. +3. **Primary aim.** The map says "the trust/consent layer is the point". G1 + makes adoption the aim and G4 makes see-and-refuse the safety mechanism. +4. **Safety scoring.** The 0 to 100 confidence, its explanation, graded + highlighting and the TUI are new. No document describes them. +5. **Peer updates.** "Updates from any other device that completes the + correct cryptographic handshake" is firmer than the documents' open + transport questions. +6. **Servers.** Log archive and monitoring as services other devices use are + not in the build order. +7. **Finish line.** No document states one. +8. **Branch management (G9).** New. +9. **AI authorship.** The paper lists it among open questions. G6 fixes it as + the premise. diff --git a/docs/review-2026-11-13/01-response-paper.md b/docs/review-2026-11-13/01-response-paper.md new file mode 100644 index 0000000..23c60eb --- /dev/null +++ b/docs/review-2026-11-13/01-response-paper.md @@ -0,0 +1,1419 @@ +# Response: the research paper against the 2026-11-13 goal + +**Target:** `docs/paper/tendcf-architecture-paper.md` (2,056 lines, all read). +**Base commit:** eefea3c +**How this was produced:** one reviewing agent (Claude Opus), then an +independent checking agent that tried to refute each finding; nothing was +executed unless an item says so. +**Item counts by Weight, after corrections:** 57 items: blocks-goal 16, +misleads 17, improves 24; plus 12 nits in the table. None was withdrawn. +P-§1.1-02 and P-§2.3-02 moved from misleads to improves on checking. + +**Reviewer:** Opus 5.5, high effort, read-only, on a worktree of this +repository at `eefea3c`. No repository file changed. + +Sources consulted: firecrawl search for ShizukuPlus +(https://github.com/thejaustin/ShizukuPlus: an "enhanced version of Shizuku"; +privileged process started "with adb or root"), and for Island/Insular +(https://github.com/proletarius101/Insular; a work profile is a secondary +Android user, "usually user 10", +https://filepathgeek.com/posts/insular-data-location/). A search for the Bcfg2 +Actions semantics returned nothing useful, so that is left to the +sources reviewer. + +There are 57 items, more than the 25-45 asked for, because one change per +item splits the §9 additions. Where this response and the sources check +(`06-sources-check.md`) treat the same passage, this one follows the +sources check's verdict and names its item. + +--- + +## Front matter and abstract + +### P-§0-01: Title and header describe the August paper, not the goal + +**Target:** `docs/paper/tendcf-architecture-paper.md` title and header, at "A Configuration Management Architecture for AI-Authored Configuration" and "facts re-checked against the vetted current-state guide and against the repository on 2026-08-18" +**Kind:** reword +**Goal:** G1, G6 +**Weight:** improves +**Finding:** The title puts AI authorship first. Under G1 the aim is owner control and adoption, and under G6 AI authorship is the premise, not the subject. The header says facts were re-checked on 2026-08-18. Eight commits touched the paper on 2026-11-13 alone, so readers cannot tell which facts are current. +**Evidence:** `git log -- docs/paper/tendcf-architecture-paper.md` shows a13e892, fd43679, b315772, 74967fc, b47960b, e99db28 and 1ce21a8, all on 2026-11-13. +**Proposed text:** + +> # tendcf: Owner-Controlled Configuration Management, Written in Nix by the Owner's AI +> +> Drafted 2026-08-13; restructured against the goal agreed 2026-11-13 +> (`docs/review-2026-11-13/00-goal-definition.md`). Facts re-checked against +> the repository at commit `` on ``. + +**Merge:** replace the title and the header's second sentence +**Checked:** verified (git log); independently checked 2026-11-13: confirmed + +### P-Abs-01: The abstract says the defect fixes are open upstream + +**Target:** Abstract, at "Twenty-three defect fixes are now open as pull requests against `cfengine/core`" +**Kind:** correct +**Goal:** G7 +**Weight:** misleads +**Finding:** §7.1 of the same paper says upstream closed all twenty-six PRs on 2026-08-19 and that "the open count upstream is zero". The abstract still says they are open. It is the first factual claim a reader checks. +**Evidence:** paper lines 49-50 against 1544-1554; inventory §E (closed 08-19; "the fork is the destination", 08-22). +**Proposed text:** see P-Abs-03, which replaces the whole abstract. As a stand-alone fix: + +> Building on that layer surfaced twenty-three defects, ten of them in that +> data layer, three of which stop the run before a single promise is +> evaluated (§7). Upstream closed the submissions on volume grounds; the +> fixes now live on our CFEngine fork. + +**Merge:** replace that sentence (or take P-Abs-03) +**Checked:** verified (read both passages; inventory); independently checked 2026-11-13: confirmed + +### P-Abs-02: The abstract describes the withdrawn "typed operation plan" + +**Target:** Abstract, at "signed release carrying a typed operation plan that the on-device executor mechanically refuses to exceed" +**Kind:** correct +**Goal:** G4 +**Weight:** misleads +**Finding:** §2.5 withdraws exactly this design ("It is withdrawn") and replaces it with a goal-file diff checked by a validator. The abstract and §10 ("a signed plan the executor may not exceed") still describe the old design. +**Evidence:** paper lines 36-38 and 1916-1917 against 461-468. +**Proposed text:** see P-Abs-03. As a stand-alone fix: + +> a signed release carrying each host's complete goal file, of which the +> device applies only the difference its owner approved + +**Merge:** replace that phrase (or take P-Abs-03) +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### P-Abs-03: Full replacement abstract + +**Target:** Abstract, all three paragraphs, from "We describe the architecture of `tendcf`" to "a list of the places we think it is weakest." +**Kind:** reword +**Goal:** G1, G2, G3, G4, G5, G6, G7, G8 +**Weight:** blocks-goal +**Finding:** The abstract leaves out the aim (G1), Nix authoring (G2), the peer handshake (G3), see-and-refuse with safety scoring (G4) and the platform order with Android as the differentiator (G5). It frames CFEngine as the design's bet rather than an instrument (G7), and it says nothing about the finish line (G8). It also carries the two errors above. The replacement keeps the paper's habit of saying first what is not built. +**Evidence:** paper lines 20-56; goal G1-G8. +**Proposed text:** + +> We describe `tendcf`, free software for configuration management whose aim +> is that people control their own computing devices as they see fit. A +> person uses it through an AI or directly at the code level, whichever they +> prefer at the moment. Through an AI, they say what they want; the AI writes +> it as configuration, and explains or warns when a request looks unwise. +> Configuration is written in the Nix language with NixOS-style options, so +> existing NixOS and nix-darwin configurations carry over. It evaluates to +> plain JSON, which is what gets schema-checked and compiled. We take it as a +> premise, not a hypothesis, that AI agents write most of this configuration. +> From that we derive a design rule: prefer designs whose correctness follows +> from information *local* to the file being edited over designs that need +> *global* knowledge of what everyone else declared. +> +> Every device converges on its own. There is no control node. A device +> accepts an update from any other device that completes the correct +> cryptographic handshake, and a "server" is only a device that provides +> services, such as log archiving and monitoring, to others. Nothing changes a +> device except as an exact, mechanically checked difference between the goal +> file it has approved and the one proposed, and the device's owner can see +> that difference and refuse it. Each difference is also scanned for likely +> safety in several ways, AI among them. The owner sees a confidence figure +> out of 100%, the reasons for it, and the questionable entries highlighted +> more strongly the less safe they look, in a command-line mode or a TUI. The +> first platforms are macOS as a server and Android as a client. We know of +> no comparable tool for Android that works across Island and Insular work +> profiles and with ShizukuPlus's user-space privilege. Today the substrate +> is a fork of CFEngine, driven through its JSON data layer. Bcfg2 supplies +> `` load-bearing ideas (§6). +> +> Little of this is built. A compiler renders per-host goal files, with +> service units for launchd only, and a reference projector and a generic +> CFEngine bundle exist. One canary service has been enforced on one Linux +> operator host since 2026-10-31. No Mac or Android device runs tendcf. The review surface, +> the handshake and the Android agent are designs. Our one empirical result +> is about the substrate: putting real weight on CFEngine's data layer +> surfaced twenty-three defects, ten of them in that layer (§7). The paper is +> written for an expert reader who will find the holes; §9 lists where we +> think it is weakest. + +**Merge:** replace the abstract; `` takes the Bcfg2 idea count settled under 06 P-refs-s16 (four in the paper, six in the guide; the same count in both documents) +**Checked:** verified, for the status claims: compiler launchd-only (inventory §A, `RENDERED_SUPERVISORS`); canary since 2026-10-31 (`docs/architecture/linux-targets.md:39`); no Mac or Android deployment (inventory §G4); independently checked 2026-11-13: weakened, corrected (the Android sentence reworded; the compiler limit narrowed to service units, `compiler/nix2cf/compile.py:95`; the idea count deferred to 06 P-refs-s16) + +--- + +## §1 Motivation + +### P-§1-01: The motivation predates the aim + +**Target:** §1 "Motivation", first paragraph, from "The site is heterogeneous rather than uniform" to "or see the conversation." +**Kind:** ruling-drift +**Goal:** G1, G5 +**Weight:** blocks-goal +**Finding:** §1 motivates the design from one heterogeneous site "held by more than one trusted operator". G1 motivates it from people who should control their own devices, with named first adopters (sysadmins who share configs in Nix) and a long-run user with no admin skill. The paragraph never mentions adoption, the platform order or Android's role. It does keep the right point about the user's own AI. +**Evidence:** paper lines 62-71; goal G1, G5; ruling 1 ("non-sysadmin users, even clueless people, could use the tool via only via AI"). +**Proposed text:** + +> The aim is that people control their own computing devices as they see +> fit, and that they can do so without becoming administrators. tendcf is a +> configuration management system meant to be adopted by others. A person +> uses it through an AI or directly at the code level, whichever they prefer +> at the moment. Through an AI, they say what they want; the AI writes it as +> configuration, and explains or warns when a request looks unwise. That AI +> is **theirs**, not ours: we never run their model, see their prompt, or see +> the conversation. We expect the first adopters to be sysadmins who already +> share configurations in Nix. The user we are building toward has no admin +> skill at all. +> +> The platforms come in a fixed order: macOS as a server, Android as a +> client, macOS as a client, Linux as a server, then Linux as a client. +> Android is the one we think nobody else serves. Comprehensive configuration +> management that works across Island/Insular work profiles and with the +> user-space privilege of ShizukuPlus is, as far as we know, not offered +> anywhere else (§2.8). + +**Merge:** replace the paragraph +**Checked:** verified (read §1 against G1/G5); independently checked 2026-11-13: confirmed + +### P-§1-02: "The unusual requirement" omits the two ways of use + +**Target:** §1, paragraph beginning "**The unusual requirement is who writes the configuration.**" +**Kind:** add +**Goal:** G1, G2, G6 +**Weight:** improves +**Finding:** The paragraph states the premise in a way consistent with G6 ("not a prediction... the operating assumption"). It leaves out G1's other half: the same person may edit the code directly at any moment. That makes human readability of the Nix source and of the diff a requirement too (G2: "reads clearly without manuals"). Without it, the local-knowledge rule could be read as licence to optimise only for machine authors. +**Evidence:** paper lines 76-82; goal G1, G2. +**Proposed text:** + +> The same person may also stop using the AI at any moment and edit the +> configuration directly. So whatever the AI writes must remain ordinary +> Nix that a person can read and change, and whatever a person is shown, the +> diff above all, must read clearly without a manual. Machine authorship +> sets the cost structure; human legibility is a constraint on it, not a +> casualty of it. + +**Merge:** insert after the paragraph +**Checked:** verified (read) + +### P-§1.1-01: The device-local trust root is now required, not a fix "until" + +**Target:** §1.1 "Scope, and where it stops applying", bullet beginning "**The consent gate does not yet mean what §2.5 says it means.**", at "Until that exists, a site that needs the property §2.5 describes needs a different trust architecture" +**Kind:** ruling-drift +**Goal:** G3, G4 +**Weight:** blocks-goal +**Finding:** The bullet treats a device-local trust root as an optional remedy for sites that need real consent. G3 requires that every device accept updates from *any* other device that completes the correct handshake. That works only if the device holds, locally, what a correct handshake is, beyond the reach of the release path. G8 state 1 requires it on the first Mac and Android device. The limit has become a requirement on the first milestone. That "required" is an inference: a TUF root is already enrolled out of band (paper lines 475-477), and G3/G4 imply only that the handshake's anchors and the consent policy sit beyond the release path's reach. +**Evidence:** paper lines 126-138; goal G3, G8.1; inventory §H ("Device-local trust root | schema only"). +**Proposed text:** + +> Until that exists the gate is an audit trail, not a boundary. Because +> every device must accept updates from any peer that completes the +> handshake (§2.3), what that handshake trusts, and the consent policy, must +> sit beyond the release path's reach; whether that takes a separate +> device-local root is open (§9.15). + +**Merge:** needs the operator's ruling first (whether a device-local trust root is a requirement of G3/G4 or one design among several); then replace the final sentence of the bullet +**Checked:** verified (read; inventory); independently checked 2026-11-13: weakened, corrected + +### P-§1.1-02: "§1 promises more than one" operator: adoption is many sites, not one shared root + +**Target:** §1.1, bullet beginning "**The signing model is sized for one operator, and §1 promises more than one.**" +**Kind:** reword +**Goal:** G1, G3 +**Weight:** improves +**Finding:** Under G1, adoption means many independent owners, each with their own site, sharing configuration as inputs (Nix-style). That is many single-root sites, not one multi-operator site, and it needs no threshold signing. The multi-operator limit still applies inside one household or lab that shares a root. That is a narrower case, and the bullet should say so rather than imply the product needs threshold signing to be adopted. +**Evidence:** paper lines 145-149; §2.1 layers at lines 189-212; goal G1. +**Proposed text:** + +> - **The signing model is sized for one owner per site.** Adoption does not +> strain it: each adopter is the owner of their own site and takes other +> people's configuration as pinned, namespaced inputs (§2.1), not as a +> shared signing key. The limit is a site with several co-equal owners, a +> household or a lab, where a second owner must author a release without +> the first's key. Threshold signing, delegation, per-role scoping and +> co-owner revocation are a different trust architecture, and we do not +> have one. + +**Merge:** only if P-§1-01 removes "more than one trusted operator"; otherwise no change (the bullet ties threshold signing to §1's multi-operator site, not to adoption) +**Checked:** inferred (reading of G1 against §2.1); independently checked 2026-11-13: weakened, corrected + +### P-§1.1-03: The "refusal is offered, not exercised" limit now has a planned answer, G9 + +**Target:** §1.1, bullet beginning "**Refusal is offered, not exercised.**" +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** The bullet says there is no path for a person's divergence to persist. G9 names the path, later: branch management built on the platform's existing patch patterns, so that non-technical users can keep forks without merging or rebasing. The repo already runs that pattern for CFEngine (`overlay/`: six patches checked weekly for drift). Saying so turns a dead-end limit into a stated direction. +**Evidence:** paper lines 139-144; inventory §E (overlay.json, 6 patches, weekly drift job); goal G9. +**Proposed text:** + +> The direction we intend, later, is to make a refusal the start of a branch +> rather than the end of a conversation. A person who keeps a change of +> their own carries it as a patch over the shared configuration. The device +> checks that patch against each new release the way this project already +> checks its own patches against upstream CFEngine (§11). The person never +> has to know about merging, rebasing or compiling. + +**Merge:** insert at the end of the bullet +**Checked:** verified (overlay/ per inventory §E; §11 is the new section in P-§S-01); independently checked 2026-11-13: confirmed + +### P-§1.1-04: The "much smaller system" boundary should be argued from G4 + +**Target:** §1.1, bullet beginning "**Below some engineering budget, a much smaller system delivers most of this.**" +**Kind:** reword +**Goal:** G4 +**Weight:** improves +**Finding:** The bullet concedes that a signed tarball plus a convergent applier delivers most of the value. Under G4 it does not: it has no exact difference an owner can see and refuse, and nothing to scan. Stating that turns a vague budget concession into a concrete line, which is what an adopter deciding between the two needs. +**Evidence:** paper lines 163-168; goal G4. +**Proposed text:** + +> - **Below some engineering budget, a much smaller system delivers most of +> this, for a fleet whose owner is its only author.** A signed tarball of +> rendered per-host state plus a convergent applier keeps devices +> converged at a fraction of the cost. What it cannot give is the one thing +> this design exists for: an exact difference the device's owner sees, +> gets a reasoned safety reading on, and can refuse. A reader who does not +> need that should take the tarball. + +**Merge:** replace the bullet +**Checked:** inferred + +--- + +## §2 Architecture + +### P-§2.1-01: Nix is "may", G2 makes it the authoring language + +**Target:** §2.1 "The Site Model: facts in layers, behavior in tendcf", paragraph beginning "The Site Model *may* be authored in the Nix module system" +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** The paragraph makes Nix optional and promises that an adopter "is never required to know Nix". G2 puts real Nix with NixOS-style options first, with YAML/JSON beneath it as the data form it evaluates to, still writable by hand. The paragraph also omits the reason G2 gives: existing NixOS and nix-darwin configs carry over. The fact that the JSON, not the Nix, is what is validated and signed survives, and should stay. +**Evidence:** paper lines 243-251; goal G2, difference 2; `compiler/nix2cf/cli.py:203` (`eval-nix` exists, thin); inventory §A ("the Nix module frontend of D12 ... is not built"). +**Proposed text:** + +> The Site Model is written in the Nix language, using the module system as +> NixOS does: `mkOption`, `types.*`, `mkIf`/`mkDefault`/`mkMerge`, and +> option names in NixOS's style. The point is that configuration people +> already have carries over: a host already running NixOS or nix-darwin +> keeps its configuration unchanged through passthrough (linux-targets §5), +> and elsewhere a person who knows Nix writes the configuration for a Mac or +> an Android phone the way they would write it for NixOS. Beneath the Nix sits plain JSON/YAML, the data form the +> evaluation produces. That data is what is schema-validated, compiled, +> signed and diffed, and a person may write it by hand. We use the Nix +> *language* and module system, not the Nix *build system* (but see §9 on +> `pkgs`). Today only a thin evaluator exists (`nix2cf eval-nix`, a wrapper +> around `nix-instantiate --eval --strict --json`); the module frontend +> that will carry the name `nix2cf` is not built (§8). + +**Merge:** replace the paragraph +**Checked:** verified (cli.py:203; inventory §A); independently checked 2026-11-13: confirmed (proposed text corrected for passthrough on NixOS/nix-darwin hosts) + +### P-§2.1-02: "Carry over" collides with "not the Nix build system" + +**Target:** §2.1, sentence beginning "We use the Nix *language* and not the Nix *build system*" +**Kind:** question +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** Real NixOS and nix-darwin configs are mostly settings of option trees that nixpkgs and nix-darwin declare (`services.caddy.enable`, `launchd.daemons.*`), and they name packages as derivations (`pkgs.caddy`). Carrying them over means one of three things: evaluate nixpkgs/nix-darwin's own modules and translate their result, which needs nixpkgs at authoring time; re-declare a compatible subset of their option names in tendcf's own modules; or carry only the module *style*, not the configs. The three differ in cost by an order of magnitude, and each needs an answer for what `pkgs.x` means on macOS and Android. The paper should not claim carry-over until one is chosen. On NixOS and nix-darwin hosts the ruling of 2026-10-29 already settles it (passthrough, `docs/architecture/linux-targets.md:63-99`); what is open is a host without Nix. +**Evidence:** paper lines 248-251; goal G2; `docs/architecture/linux-targets.md:65-94` (the 2026-10-29 "verbatim" wording, per digest-current-plan B4). +**Proposed text:** + +> Part of "carries over" is settled: on NixOS and nix-darwin hosts the +> existing configuration is used unchanged through passthrough (ruling of +> 2026-10-29, linux-targets §5). What is open is what carries over to a +> host without Nix: a Mac without nix-darwin, or an Android phone. Evaluating nixpkgs' and +> nix-darwin's own modules gives the most faithful carry-over but brings +> nixpkgs onto every authoring machine. Re-declaring a compatible subset of +> their option names in tendcf's modules is cheaper and covers only what we +> declare. Carrying the module style without the configs is cheapest and +> carries nothing. In each case a package reference (`pkgs.caddy`) needs a +> meaning on hosts where nothing is built by Nix. The open question on what carries over asks it. + +**Merge:** needs the operator's ruling first (what G2's carry-over means on non-Nix hosts); insert after the sentence once ruled +**Checked:** inferred (standard NixOS module structure; not checked against a real carry-over attempt); independently checked 2026-11-13: weakened, corrected + +### P-§2.1-03: Foreign inputs should be named as what Nix sharers already use + +**Target:** §2.1, paragraph beginning "Site-private holds a lockfile (flake-style inputs)" +**Kind:** add +**Goal:** G1, G2 +**Weight:** improves +**Finding:** G1's first adopters already share configs in Nix, which today usually means flakes and their `flake.lock`. The layer model (site-shared, foreign site-shared, lockfile) is the right shape. The paper says "flake-style" without saying whether a foreign site-shared input *is* a flake. If it is, an adopter's existing sharing works unchanged and that is a selling point. If it is not, the paper should say why. +**Evidence:** paper lines 193-212; change-process `site.lock` (digest-current-plan A4). +**Proposed text:** + +> For the adopters we expect first, who already share configuration as Nix +> flakes, the intent is that a site-shared input is a flake and the lockfile +> pins it the way `flake.lock` does, so what they already publish is +> already a tendcf input. Whether the lockfile is `flake.lock` itself or a +> `site.lock` beside it is open. + +**Merge:** insert after the paragraph; needs the operator's ruling on flake-as-input +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### P-§2.2-01: `tendcf compile` is presented as the command that exists + +**Target:** §2.2 "The compiler: a pure function into CFEngine's own data layer", at "A compiler, `tendcf compile`, reads the Site Model and renders a per-host goal file" +**Kind:** correct +**Goal:** G2 +**Weight:** misleads +**Finding:** The command today is `nix2cf buildfile`, with `eval-nix` beside it. `tendcf compile` is the name D46 plans for a later restructure. The second paragraph of §2.2 says so, but the section opens in the present tense with the planned name, and §2.1 does the same ("The compiler (`tendcf compile`, §2.2) is a tool"). +**Evidence:** `compiler/pyproject.toml:18` (`nix2cf = "nix2cf.cli:main"`); `compiler/nix2cf/cli.py:179,203`; paper lines 255, 238. +**Proposed text:** + +> A compiler reads the Site Model and renders a per-host goal file. Today +> it is invoked as `nix2cf buildfile`; it becomes `tendcf compile` in the +> planned restructure. + +**Merge:** replace that sentence (and the parenthesis in §2.1 at "The compiler (`tendcf compile`, §2.2) is a tool") +**Checked:** verified (pyproject.toml, cli.py); independently checked 2026-11-13: confirmed + +### P-§2.2-02: The bundle is no longer launchd-only + +**Target:** §2.2, at "A first version of that bundle now exists and runs (§8); it is launchd-only, which is a real limit and not a placeholder." +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** §8 of the same paper says the bundle gained a systemd branch on 2026-10-31, and that branch is enforced on pastebin. Only the *compiler* is launchd-only. The two have been conflated, here and again in §2.6 (P-§2.6-02). +**Evidence:** paper line 314 against 1727-1728; inventory §A ("systemd: unit rendered ... enforced on pastebin"; compiler `RENDERED_SUPERVISORS` launchd only). +**Proposed text:** + +> A first version of that bundle now exists and runs (§8), with a launchd +> branch and a systemd branch. The compiler renders services for launchd +> hosts only, so a systemd host's goal file is today written outside it. + +**Merge:** replace that sentence +**Checked:** verified (read; inventory); independently checked 2026-11-13: confirmed + +### P-§2.2-03: nix-darwin is a source of configuration, not just optional "substrate" + +**Target:** §2.2, at "NixOS / nix-darwin remain optional Mac *substrate*, Step 7, not a runtime dependency of the compiler." +**Kind:** ruling-drift +**Goal:** G2, G5 +**Weight:** misleads +**Finding:** Under G2, nix-darwin configs are an input that should carry over, and under G5 macOS is the first platform. Calling nix-darwin "optional Mac substrate, Step 7" puts it late and on the wrong side of the compiler. Whether a nix-darwin Mac is managed through nix-darwin (as NixOS hosts pass through today) or through CFEngine with the config carried over is a real choice. The paper should state it as such. +**Evidence:** paper lines 352-353; goal G2, G5.1; `docs/architecture/nixos-passthrough-plan.md` (Nix hosts report and refuse; digest-current-plan B6). +**Proposed text:** + +> nix-darwin matters twice. Its configurations are input that should carry +> over (§2.1), and on a Mac that already runs it, it could instead be the +> enforcing layer, as NixOS is on NixOS hosts today. On a Mac that runs +> nix-darwin, passthrough is the path (linux-targets §5: the adapter "is +> required either way"); whether the first Mac runs nix-darwin is open +> (the open question on what carries over). Neither is a runtime dependency of the compiler. + +**Merge:** replace that sentence +**Checked:** inferred; independently checked 2026-11-13: weakened, corrected (`docs/architecture/linux-targets.md:99`: "The nix-darwin passthrough adapter is required either way") + +### P-§2.2-04: "because of Promise Theory" treats CFEngine as the design rather than an instrument + +**Target:** §2.2, at "The pairing here is Site Model (YAML/JSON, or an optional Nix frontend) into CFEngine Augments, because of Promise Theory and disconnected multi-owner operation (§2.3)" +**Kind:** reword +**Goal:** G2, G7 +**Weight:** improves +**Finding:** G7 makes CFEngine, the fork, the Site Model and the compiler instruments, open to challenge. The sentence makes CFEngine Augments part of the design's identity and keeps Nix as "optional". The stable contract the design actually depends on is the goal file and the device's diff, not augments. +**Evidence:** paper lines 349-353; goal G7. +**Proposed text:** + +> The pairing here is Nix-authored Site Model into a per-host goal file, +> applied today through CFEngine's augments. CFEngine is the current engine +> because it already runs autonomous agents with no control node (§2.3). It +> is an instrument, not the design: the contract is the goal file and the +> difference a device computes from it, and another engine that can apply +> that difference could replace CFEngine without changing it. + +**Merge:** replace that sentence +**Checked:** verified (read against G7) + +### P-§2.3-01: "Every host runs its own `cf-serverd`" is not what deployed hosts do, and G3 is firmer + +**Target:** §2.3 "Deployment shape: no policy server, push and pull as one mechanism", first paragraph, from "Every host runs its own `cf-serverd` and reads policy synced via git" to "Push and pull are two modes of the same mechanism." +**Kind:** correct +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** The one enforced host runs a root `cf-execd` and an installer-copied policy. Neither the deploy tree nor linux-targets mentions `cf-serverd` at all, and nothing is synced via git. G3 states the shape firmly: every device is self-sufficient, there is no control node, and it accepts updates from any device that completes the correct handshake. The paragraph should state that as the requirement and say what exists. Which handshake is unsettled (P-§2.5-03). +**Evidence:** `rg -c cf-serverd deploy/ docs/architecture/linux-targets.md` gave no hits; `docs/architecture/linux-targets.md:39` ("No masterfiles framework: the installer copies the policy in as root"); goal G3, difference 5. +**Proposed text:** + +> Every device is self-sufficient: it converges on its own schedule from the +> last release it approved, and there is no control node. A device accepts +> an update from *any* other device that completes the correct cryptographic +> handshake. A peer may carry a release; only the handshake makes it +> acceptable. A device that holds a deploy role may also ask another to +> converge now rather than at its next cycle; that is a request, and the +> target still applies only what it would have accepted anyway. "Server" in +> this paper means only a device that provides services to others, such as +> receiving and archiving logs or monitoring (§2.5). "Client" means a device +> that uses them. Neither word changes the architecture. Today the one +> enforced host runs a root `cf-execd` with an installer-copied policy; no +> `cf-serverd`, git sync or peer transport is built. + +**Merge:** replace the paragraph +**Checked:** verified (rg; linux-targets:39); independently checked 2026-11-13: confirmed + +### P-§2.3-02: The Promise Theory claim is overstated + +**Target:** §2.3, at "Promise Theory was formalized as a model of autonomous agents specifically to rule out client-server protocols that push data to a controller [6]; nothing about "no control node" is this paper's invention, and it is the actual reason §2 chooses CFEngine over the alternatives." +**Kind:** correct +**Goal:** G7 +**Weight:** improves +**Finding:** (c) Promise Theory models autonomous agents that can only promise their own behaviour, so cooperation is voluntary. That makes push-imposed obligations inexpressible. It was not formalised "specifically to rule out client-server protocols that push data to a controller": that purpose claim is refuted by the book and by Burgess 2005 (see 06 T27 and R2c in `checks/v7-refetch.md`). Burgess's 2005 DSOM paper introduced the promise as a measure of voluntary cooperation, and the book says Promise Theory "is not about protocol modeling" (checked against the book and the 2005 paper, 2026-11-13). Burgess 2005 even builds client-server interactions from promises, so the theory does not rule them out. The 2014 book [6] is the later full formalisation of that 2005 motivation. The sources check treats the same sentence as 06 P-§2.3-s21 (weight `improves`); this item follows it, and the two now agree and merge as one text. +**Evidence:** paper lines 379-383; reference [6] at line 1969. Checked against the book (Burgess and Bergstra, *Promise Theory: Principles and Applications*, 2014, ch. 1 and 17: "originally invented to discuss the issues surrounding this autonomous operation, and voluntary cooperation"; "It is not about protocol modeling") and against Burgess, DSOM 2005, LNCS 3775 (no external agent can tell an agent what to do "without its consent"; promises rebuild "client-server interactions, dependencies and access control"), both read 2026-11-13. The book and the paper support "no other agent can impose a promise on it", not "cannot be obliged". The markburgess.org FAQ says Promise Theory "emerged from the software CFEngine"; the promises page states no "specifically to rule out" purpose (06 T27). +**Proposed text:** + +> In Promise Theory, which was developed to describe CFEngine's +> decentralised mode of operation, an agent can promise only its own +> behaviour and no other agent can impose a promise on it [6]. A design with no +> control node is the natural reading of that model, not this paper's +> invention, and it is one reason CFEngine is the current engine (§2.2). + +**Merge:** replace that sentence, as one merged edit with 06 P-§2.3-s21; [6] and Burgess 2005 are now checked (see Finding); consider citing Burgess 2005 +**Checked:** verified (the book, ch. 1 and 17, and Burgess 2005 read 2026-11-13); independently checked 2026-11-13: weakened, corrected; sources re-fetched 2026-11-13: corrected + +### P-§2.3-03: "No equivalent to phone home to" is false once logs are archived + +**Target:** §2.3, at "it is centralized, and devices phone home to it; this design has no equivalent to phone home to at all." +**Kind:** ruling-drift +**Goal:** G3, G8 +**Weight:** misleads +**Finding:** G8 state 1 needs logs archived on the Mac, and G3 names log archiving and monitoring as services other devices use. Devices will send something to a server. The real difference from balenaCloud is that nothing a device *needs* in order to converge or accept an update lives on that server. +**Evidence:** paper lines 396-400; goal G3, G8.1, difference 6. +**Proposed text:** + +> it is centralized, and devices depend on it. Devices here also send their +> logs to a server, but only as a service: nothing a device needs in order +> to converge, or to accept an update, lives there, and a device that +> cannot reach it keeps working and keeps its own record. + +**Merge:** replace that clause +**Checked:** verified (read against G3/G8); independently checked 2026-11-13: confirmed + +### P-§2.4-01: The Android paragraph is about Termux; G5 is about profiles and ShizukuPlus + +**Target:** §2.4 "The record of truth is local", paragraph beginning "On Android, Termux and tendcf-agent are different UIDs" +**Kind:** ruling-drift +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** The only Android-specific architecture in the paper is a storage note about Termux UIDs. G5 makes Android the main differentiator and names what it must handle: Island/Insular work profiles (secondary Android users, typically user 10) and user-space ShizukuPlus. Neither appears anywhere in the paper. How CFEngine's agent runs on Android is also unsettled: the map keeps CFEngine there (R4), D45 makes only tendcf-agent Android-only, and the compiler does not yet offer an `android` platform. This needs a section, not a paragraph (P-§S-01, new §2.8). +**Evidence:** paper lines 423-427; `rg -n -i 'island|insular|shizukuplus'` over the paper gave no hits (Shizuku appears only as "a forked Shizuku" and "Shizuku"); digest-current-plan D6; Insular README, https://github.com/proletarius101/Insular. +**Proposed text:** + +> On Android the agent is tendcf-agent, and it owns the JSONL capture and +> the SQLite index in its app-private storage. A device with a work profile +> (Island, Insular) is several Android users, each with its own apps and +> private storage. The agent records every profile's outcomes in one +> capture, and reaches the other profiles through ShizukuPlus's privileged +> process rather than by reading their files (§2.8). How CFEngine's agent +> runs on Android, as a native helper or behind a Termux reporter, is open +> (§2.4; the compiler does not yet offer an `android` platform). + +**Ruled:** "3. Termux CFEngine + thin Kotlin" (operator ruling, 2026-11-14, B3): state 1 on Android is Termux CFEngine fed tendcf projections, and the Kotlin agent holds trust and consent only (05 Idea 4). So "as a native helper or behind a Termux reporter" is answered for state 1: CFEngine runs in Termux. Also "1. Field on entries" (B3 sub 1, X-android-05): one host per phone, each Android promise names its target user and the work profile's owner app. Ruled; implementation pending. The proposed text's sentence that tendcf-agent "owns the JSONL capture and the SQLite index" stands as a support role (operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role"): "only" is about decisions; the thin Kotlin agent still writes the device JSONL and index; map and D18 stand. + +**Merge:** replace the paragraph; the question on how cf-agent runs on Android is ruled (map R4; `compiler/nix2cf/cli.py` --platform) +**Checked:** verified (rg over paper); not checked: ShizukuPlus's cross-user behaviour on a real device, and the clause "reaches the other profiles through ShizukuPlus's privileged process" (the ShizukuPlus README, https://github.com/thejaustin/ShizukuPlus, describes "a privileged process started with adb or root" and says nothing about work profiles); independently checked 2026-11-13: weakened, corrected (no D45/R4 conflict: `docs/architecture/architecture-DEFINITIVE-v3.md:105-115`) + +### P-§2.4-02: "Any central or shared view is optional" against a required archive + +**Target:** §2.4, at "Any central or shared view is optional and eventually consistent." +**Kind:** reword +**Goal:** G3, G8 +**Weight:** improves +**Finding:** The archive on the Mac is part of G8 state 1, so it is not optional for the first milestone. It can still be non-authoritative and eventually consistent, which keeps the local-first argument intact. +**Evidence:** paper line 411-412; goal G8.1. +**Proposed text:** + +> A log archive on a server device is part of the design (§2.5); it is +> eventually consistent and never authoritative. The device's own capture +> is the record. + +**Merge:** replace that sentence +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### P-§2.5-01: The safety review G4 asks for is missing + +**Target:** §2.5 "Releases carry a goal file; the device applies only an approved diff", paragraph beginning "Layered on the verifiable plan is a *semantic* layer" +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** The paper has a semantic briefing and an `accept | reject` slot. G4 adds a scan of each difference in several ways, AI among them, a confidence figure out of 100% with an explanation, graded highlighting of questionable entries, and CLI and TUI modes. None of this is in any document (difference 4). The paper's own §3.2 item 5 names the risk: a generated summary that cannot authorize can still mislead. The score is the strongest such summary. The design must keep it from becoming the authority by persuasion. +**Evidence:** paper lines 485-491, 1101-1121; goal G4; inventory §H (nothing for scoring). +**Proposed text:** + +> Beside the briefing sits a **safety reading**. Each difference is scanned +> in several ways. Mechanical scanners check what the schema already knows: +> a privileged region touched, a domain's coverage withdrawn, a new +> listening port, a secret newly referenced, a removal, an interlock +> changed. Provenance counts who signed the release and how many trusted +> devices already applied it. An AI reviewer, the owner's choice of model, +> reads the difference with the Site Model behind it. The owner is shown +> one figure out of 100%, the reasons for it, each pointing at the entries +> that produced it, and the questionable entries highlighted more +> dramatically the less safe they look. Mechanical findings set a ceiling +> the AI reading can lower but never raise. The reading is offered on the +> command line and in a TUI. Like the briefing, it never authorizes: the +> owner's yes does, against the exact difference, and refusing is always +> one keystroke (§2.7). + +**Ruled:** "1. Capped 0-100 score" (operator ruling, 2026-11-14, B8): "score from 0 to 100", mechanical checks set a ceiling that AI review can lower but never raise, an explanation of each part, a measured hit rate once a corpus exists (B13 wording 3 / X-pm-03). So "one figure out of 100%" in the proposed text above reads "a safety score from 0 to 100". The values are "1. 09's table, top 95" (B8 sub 1): base 95, never 100; the table is in 09 Q3. Ruled; implementation pending. + +**Merge:** the score computation is ruled (the mechanical ceiling and never showing 100 are in the B8 rulings); insert after the paragraph (and see P-§S-01 for the full section) +**Checked:** verified (no scoring in docs per goal difference 4; the ceiling rule is a proposal); independently checked 2026-11-13: confirmed + +### P-§2.5-02: The owner's AI may be both author and advisor + +**Target:** §2.5, at "The proposing side and the consenting side are different programs." +**Kind:** question +**Goal:** G1, G4, G6 +**Weight:** blocks-goal +**Finding:** Under G1 the owner's AI writes the configuration and also warns when a request looks unwise. Under G4 an AI scans the difference. If one AI does both, the "different programs" separation and §1.1's compromised-authoring-agent limit collapse into one model checking its own output. The project's own review rule already forbids that for code ("No PR merges on a review by the model family that wrote the change"). The paper should say whether the scanning AI must differ from the authoring AI, and who enforces that. +**Evidence:** paper lines 505-506, 156-162; `AGENTS.md` standing rule 3 (cross-model review); goal G1, G4. +**Proposed text:** + +> The owner's AI may well be the author of the change it is asked to +> review. We therefore require the AI reading of §2.5's safety review to +> come from a different model, or at least a fresh context with no memory +> of authoring it, and say which on the screen. A reading from the author's +> own model is shown as such and cannot lift the figure above the +> mechanical ceiling. + +**Ruled:** "2. Should not (as written)" (operator ruling, 2026-11-14, B8 sub 4, X-safety-06 / v6 C6). X-safety-06's text is adopted: the scanning AI SHOULD NOT be the authoring model; it sees only the canonical diff as quoted data, never the author's prose; the diff is hostile input; two model families where the owner has them, and their disagreement caps the score (70). The same model is allowed with no extra cap. So the proposed text above, which asks for "a different model, or at least a fresh context" and says which on the screen, is superseded by X-safety-06's text in 09. The citation (arXiv:2404.13076) was fetched and verified on 2026-11-14. Ruled; implementation pending. + +**Merge:** ruled; insert after that sentence, in X-safety-06's wording +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### P-§2.5-03: "The correct cryptographic handshake" is undefined against the TUF text + +**Target:** §2.5, paragraph beginning "The distinction we are drawing is between", at "Signing itself is an unremarkable TUF [26] subset sized for one operator" +**Kind:** question +**Goal:** G3, G8 +**Weight:** blocks-goal +**Finding:** The paper's model is a TUF-signed release from one site root, which says nothing about how a release travels. G3 says "updates from any other device that completes the correct cryptographic handshake". That could mean (a) any device may relay a release and the release's signature is the handshake, (b) a mutual device-key handshake on the channel, as CFEngine's own `cf-serverd` key trust does, or (c) both. Under (a), TUF's mirror model already fits: any peer is a mirror. (b) alone would make a device's key, not the site root, the authority. G8 state 1 needs the choice made. +**Evidence:** paper lines 473-483; goal G3, difference 5; inventory §H ("Pull / self-update | nothing"; "Signed release / TUF | prose only"). +**Proposed text (for reading (c), pending ruling):** + +> Signing is an unremarkable TUF [26] subset sized for one owner. TUF +> separates who signs from who serves, so any device may serve a release +> to any other, as a mirror. The handshake a device requires is two checks. +> The release verifies against the root this device enrolled. The peer +> carrying it authenticates with a device key this device lists. The first +> decides whether a change is acceptable; the second only decides who may +> talk to it. + +**Ruled:** "1. Content checks; v0 first" (operator ruling, 2026-11-14, B1): G3's handshake means content checks (signed by trusted keys, fresh, names this device, owner approval); transport auth decides only who may talk. This is reading (c)'s split, with the content checks as the handshake. First build: SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter); the map's 2-of-3 offline-root floor may lag until TUF. Ruled; implementation pending. + +**Merge:** ruled (which of (a), (b), (c) "the correct cryptographic handshake" means) +**Checked:** inferred (TUF mirrors: general knowledge, not re-fetched); independently checked 2026-11-13: confirmed + +### P-§2.6-01: The Nix illustration is not NixOS style + +**Target:** §2.6 "Three worked examples", the `nix` block beginning "# site/services/edge-http.nix — the same caddy record via the Nix authoring" +**Kind:** correct +**Goal:** G2 +**Weight:** misleads +**Finding:** The example *declares options* (`options.siteModel.services.caddy.description = mkOption {... default = ...}`) and puts the record's values in their defaults. NixOS users do not write configuration that way: tendcf would declare the options once, and a user's module *sets* them (`tendcf.services.caddy = {...};`). As shown, a Nix user would conclude that every service needs its own option declarations, the opposite of "existing configs carry over". It is the only Nix in the paper, so it sets the reader's picture of G2. +**Evidence:** paper lines 598-640; goal G2. +**Proposed text:** + +> ```nix +> # site/services/edge-http.nix — the same caddy record as a NixOS-style +> # module. tendcf declares the options once (types, defaults, docs); a site +> # only sets them. ILLUSTRATIVE — the module frontend is unbuilt (§8). +> { ... }: +> { +> tendcf.services.caddy = { +> description = "Site reverse proxy and HTTPS terminator"; +> domain = "macos-launchd-services"; +> bundle = "edge-http"; +> platform = "macos"; +> runsAs = "djbclark"; +> command = [ "/opt/homebrew/bin/caddy" "run" "--config" "/etc/caddy/Caddyfile" ]; +> launchd = { label = "com.djbclark.caddy"; runAtLoad = true; keepAlive = true; }; +> # provides/requires are typed the same way regardless of frontend: +> # local knowledge lives in the option, not in which language declared it. +> provides = [ "service:caddy" "port:443" "port:80" ]; +> requires = [ "path:/etc/caddy/Caddyfile" "service:tailscaled" ]; +> }; +> } +> ``` +> +> The option declarations behind `tendcf.services.` live once, in +> tendcf, where `mkOption`/`types.*` give each field its type and +> documentation. That is also where a NixOS-compatible name such as +> `services.caddy.enable` would be mapped, if §2.1's carry-over is taken +> that far. + +**Merge:** replace the code block and the sentence before it ("but it shows what `caddy`'s record above would look like as typed options") +**Checked:** verified (read the block); option naming `tendcf.services` is a proposal; independently checked 2026-11-13: confirmed + +### P-§2.6-02: Example C's "launchd-only" limit is stale + +**Target:** §2.6, Example C, at "It is **launchd-only**: systemd, runit and Jobber are unwritten, so "supervisors are adapters" (§2.3) remains a claim about a design and not about running code." +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** The bundle has had a systemd branch since 2026-10-31, enforced on pastebin and run as root in CI on three Ubuntu VMs. runit is refused by name. "Supervisors are adapters" is now true of two adapters in the bundle, and of one in the compiler. +**Evidence:** inventory §A (policy: systemd branch, runit refused), §F (linux.yml VM matrix); paper line 1727-1728. +**Proposed text:** + +> It covers **launchd and systemd**. runit is refused by name and Jobber is +> unwritten, and the compiler renders launchd services only, so "supervisors +> are adapters" (§2.3) holds for two adapters in the bundle and one in the +> compiler. + +**Merge:** replace that sentence +**Checked:** verified (inventory; paper §8); independently checked 2026-11-13: confirmed + +### P-§2.6-03: "The only place in this paper where a mechanism is demonstrated" is stale + +**Target:** §2.6, at "That is a small result, and it is the only place in this paper where a mechanism is demonstrated rather than argued." (and §6.1, at "It is the only claim in this paper that has been demonstrated rather than argued.") +**Kind:** correct +**Goal:** G8 +**Weight:** misleads +**Finding:** A root `cf-execd` on pastebin restored the enforced canary within three minutes of a manual stop on 2026-10-31. CI runs the systemd lifecycle as root on every push. Those are demonstrated mechanisms (convergence, tombstone-guarded teardown) and the paper does not report them. A Bcfg2 author will value an enforcement result more than an interlock skip. +**Evidence:** `docs/architecture/linux-targets.md:39` ("a root `cf-execd` (`tendcf-execd.service`) restored the canary within 3 minutes of a manual stop"); inventory §F. +**Proposed text:** + +> That is a small result. It has one companion: on one Linux operator host, +> a root `cf-execd` running this bundle has enforced a canary service since +> 2026-10-31, and restored it within three minutes of a manual stop (§8). +> Everything else in this paper is argued, not demonstrated. + +**Merge:** replace that sentence; make the matching change in §6.1 +**Checked:** verified (linux-targets:39); independently checked 2026-11-13: confirmed + +### P-§2.7-01: The peer-action example is ShizukuPlus; say so + +**Target:** §2.7 "Peer actions: help without a global lock", at "Example from our last system: a device that cannot start its privileged helper itself; any healthy peer in its allowlist may do it over ADB" +**Kind:** reword +**Goal:** G3, G5 +**Weight:** improves +**Finding:** The example is a Shizuku-family helper, which on a non-rooted phone must be restarted over ADB after reboot. Under G5 this is the central Android mechanism, not an anecdote from "our last system". Naming it also separates a peer *action* (help) from a peer *update* (G3's handshake). A reader could easily conflate the two. +**Evidence:** paper lines 890-893; ShizukuPlus README ("privileged process started with adb or root"), https://github.com/thejaustin/ShizukuPlus. +**Proposed text:** + +> The example that matters most is Android's. Without root, ShizukuPlus's +> privileged process must be started over ADB, and a reboot stops it, which +> leaves the phone unable to converge anything that needs it. Any healthy +> peer in that phone's allowlist may restart it over wireless ADB. If every +> helper is down, **only that phone waits**. A peer action is help with an +> operation; it is not a peer update (§2.3), and it carries no +> configuration. + +**Merge:** replace those sentences +**Checked:** not checked: the item rests on the ShizukuPlus README (via search snippet); it needs a test on a real device that a peer can restart ShizukuPlus's privileged process over wireless ADB after a reboot, and whether that needs on-device confirmation on current Android + +### P-§2.8-01: The `managed` tier lets someone other than the owner waive see-and-refuse + +**Target:** §2.8 "Per-device trust", table row "**Consent** | Do I also need a local yes? | `operator`: no. `consented`: yes (advisor key). `managed`: operator-chosen" +**Kind:** ruling-drift +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4: "Nothing changes a device except as an exact, mechanically checked difference that the device's owner can see and refuse." A `managed` device whose consent rule is "operator-chosen" lets a non-owner decide that the owner is not asked. Even `operator: no` means there is no per-change yes. That is fine if the owner chose a standing accept and can still see every difference and withdraw that choice. The table should say that, and say who may set it. +**Evidence:** paper lines 917-923; goal G4. +**Proposed text:** + +> | **Consent** | Do I also need a local yes? | Every change is an exact difference the owner can see and refuse. `consented`: a yes per change (advisor key). `operator` and `managed`: the owner may set a standing accept, which only the owner can set or withdraw, and every applied difference stays visible | + +**Merge:** needs the operator's ruling first (whether a standing accept satisfies G4's "can see and refuse"); replace the row once ruled +**Checked:** verified (read against G4); independently checked 2026-11-13: confirmed + +### P-§2.8-02: The release axis should name the handshake, not only the TUF root + +**Target:** §2.8, table row "**Release** | Whose signatures may change me? | Site TUF root enrolled at the first-run ceremony" +**Kind:** reword +**Goal:** G3 +**Weight:** improves +**Finding:** This is the row G3 changes. It should point at the handshake decided in P-§2.5-03, and say that the carrier of a release is irrelevant to whether it is accepted. +**Evidence:** paper line 919; goal G3. +**Proposed text:** + +> | **Release** | What may change me, and who may hand it to me? | A release that verifies against the root enrolled at first run, from any peer that completes the handshake (§2.5) | + +**Merge:** replace the row after P-§2.5-03 is ruled +**Checked:** inferred + +--- + +## §3 The design rule + +### P-§3-01: "Adopting and testing" should separate the premise from the rule + +**Target:** §3 "The design rule", at "a rule we are adopting and testing, not one we consider settled" +**Kind:** reword +**Goal:** G6 +**Weight:** improves +**Finding:** The sentence is consistent with G6 only if the reader sees that the *rule* is under test and the *premise* is not. As written, a reader could take "testing" to cover machine authorship itself, which §9.2 and §9.9 then seem to confirm. One clause fixes it. +**Evidence:** paper lines 953-955; goal G6, difference 9. +**Proposed text:** + +> The premise is fixed: most configuration here is machine-authored, and we +> do not set out to test that. The rule we derive from it is not fixed; it +> is one we are adopting and testing: + +**Merge:** replace the paragraph's first two sentences +**Checked:** verified (read) + +### P-§3.2-01: Item 3 critiques a warning the map no longer carries + +**Target:** §3.2 "Nine concrete instances", item 3, at "carries, at its own top, an instruction telling any AI agent reading it not to modify the document without a human's explicit approval" +**Kind:** correct +**Goal:** — +**Weight:** misleads +**Finding:** The map's header now reads "It is freely editable: keep it current rather than proposing changes elsewhere." The protection was lifted on 2026-08-15. The item's central irony ("the rule caught a document failing to apply the rule to itself") no longer has an object. +**Evidence:** `docs/architecture/architecture-DEFINITIVE-v3.md:3-4`; digest-project-history C7 ("Protected documents. All made mutable 08-15"). +**Proposed text:** + +> **3. A document's warning about itself should be a check, not prose.** +> The architecture document once carried, at its own top, an instruction +> telling any AI agent not to modify it without a human's explicit +> approval, with nothing enforcing it. The project resolved that by lifting +> the protection rather than mechanising it. The general point stands: an +> instruction a reader must remember, with nothing checking it, is the +> shape §3's second clause warns about. + +**Merge:** replace item 3 (or cut it with the rest of §3.2, P-§S-03) +**Checked:** verified (map:3-4); independently checked 2026-11-13: confirmed + +### P-§3.2-02: Item 5 makes a literature claim with no citation + +**Target:** §3.2, item 5, at "a broader body of work on grounding generated text in retrieved or cited source material, which finds that requiring a generated claim to point at the specific fact it summarizes measurably reduces unsupported claims" +**Kind:** correct +**Goal:** G4 +**Weight:** misleads +**Finding:** (c) Every other item that reports an outside finding carries a numbered reference; this one asserts a measured finding ("measurably reduces") with none. Under G4 it becomes the main justification for how the safety explanation is built, so it needs a source or a softer verb. +**Evidence:** paper lines 1112-1116. +**Proposed text:** + +> which reports that requiring a generated claim to point at the specific +> fact it summarizes reduces unsupported claims relative to generating +> freely from the same facts [N]. + +**Merge:** replace that clause and add reference [N]; the sources reviewer should supply it +**Checked:** verified (no citation present); source not checked; independently checked 2026-11-13: weakened, corrected (item 3 has no citation either) + +### P-§3.2-03: Item 4's percentages need checking against [13] + +**Target:** §3.2, item 4, at "at roughly two-thirds of all technical errors; errors of simple omission are the second-largest, at roughly a quarter; syntax and structural errors ... are the smallest, at under two percent" +**Kind:** question +**Goal:** — +**Weight:** improves +**Finding:** (c) These three figures carry a design conclusion (invest in reference checks, not structure). They are attributed to [13] without a table or section number. A paper aimed at an expert reader should cite the table. The sources check has confirmed them (06 T34: [13] Table 6 gives 65.0%, 26.5% and 1.5%), so the item closes with the locator. +**Evidence:** paper lines 1083-1087; reference [13] arXiv:2512.14792, Table 6 (https://arxiv.org/html/2512.14792). +**Proposed text:** + +> (... [13, Table 6]) + +**Merge:** insert the table locator after the figures; the check is done (06 T34) +**Checked:** verified by the sources check (06 T34, [13] Table 6: 65.0 / 26.5 / 1.5%); independently checked 2026-11-13: confirmed, resolved + +--- + +## §4 Two places the rule shows up + +### P-§4.2-01: Comprehensiveness on an owner's device: the owner's own change is not drift + +**Target:** §4.2 "Comprehensiveness, default-on with a reasoned opt-out", at "AI-authored drift is exactly what extra-entry detection catches, so the safe default belongs on the detecting side." +**Kind:** add +**Goal:** G1, G5 +**Weight:** improves +**Finding:** On a phone (G5's client) the owner installs apps and changes settings by hand all the time. Default-on comprehensiveness reports every such change as an extra entry. G1's freedom to control one's device as one sees fit means the owner's own change must have a first-class path: adopt it into the configuration (through their AI) or mark it theirs. Otherwise the tool punishes direct use, and the `not-yet-migrated` count never falls (§9.3). +**Evidence:** paper lines 1268-1273, 1798-1803; goal G1, G5. +**Proposed text:** + +> On a device its owner uses by hand, most extra entries are not drift but +> the owner's own choices. For those the report is an offer: the owner, or +> their AI, can adopt the entry into the configuration as written, or mark +> the domain theirs. Either is one exact difference, seen and approved like +> any other. Extra-entry detection exists to catch what nobody chose, not to +> argue with what the owner did. + +**Merge:** insert after that paragraph +**Checked:** inferred + +--- + +## §5 Where this departs from Bcfg2 + +### P-§5.3-01: "No consumer for a central copy" is no longer true + +**Target:** §5.3 "Local-first record, where the papers centralized statistics", at "the honest summary is that we currently have *no consumer* for a central copy" +**Kind:** ruling-drift +**Goal:** G3, G8 +**Weight:** misleads +**Finding:** G8 state 1 requires logs archived on the Mac, and G3 names monitoring as a server service. Both consume a central copy. The paper's local-first argument survives (the archive is a service, not the record), but its admission that the Bcfg2 advice to build reporting early might be right is now partly answered in Bcfg2's favour: reporting arrives early. That advice is the 2008 booklet's deployment tip [4, §8.1], not LISA '05's; this item follows the sources check on that (06 P-§5.3-s10, T14). Desai will notice. +**Evidence:** paper lines 1371-1384; goal G3, G8.1; 06 T14 (booklet §8.1 "Set up the reporting system early"). +**Proposed text:** + +> We now have a consumer: the first milestone archives every device's logs +> on the Mac (G8.1), and the server role includes monitoring other devices +> (G3). That moves us toward the booklet's advice to set up reporting early +> [4, §8.1]. What we keep is the other +> half: the archive is fed from each device's own capture, is eventually +> consistent, and is never the record of truth. + +**Merge:** replace from "the honest summary" to "not that one is unbuildable."; coordinate with 06 P-§5.3-s10, which corrects the attribution in the next sentence of §5.3 +**Checked:** verified (read against G8); independently checked 2026-11-13: weakened, corrected + +--- + +## §6 What we took from Bcfg2 + +### P-§6.4-01: "Dry-run the standing posture for ... the primary workstation" is neither what happened nor what G5 orders + +**Target:** §6.4 "Deploy reporting early, and dry-run as the default posture", at "we make dry-run the standing posture for the first platform class brought under management: the primary workstation" +**Kind:** correct +**Goal:** G5, G8 +**Weight:** misleads +**Finding:** The first platform actually brought under management was a Linux server, enforced, not dry-run. G5 puts macOS as a server first and Android as a client second. A Mac that serves logs is still the machine that is hard to reimage, so the LISA '05 practice applies to it. The paper should say where it applies now, and admit the Linux canary went to enforce after a two-day dry run. +**Evidence:** paper lines 1488-1493; `docs/architecture/linux-targets.md:39` (dry-run 10-29, enforced 10-31); goal G5. +**Proposed text:** + +> we make dry-run the standing posture for the first Mac, which is both the +> first server and a machine that cannot easily be reimaged, and for the +> first phone. The one Linux host enforced so far went from a dry run on +> 2026-10-29 to enforcement on 2026-10-31 of a single canary service, which +> is the narrowest form of this practice. + +**Merge:** replace that clause; merge with 06 P-§6.4-s13 into one edit of that sentence +**Checked:** verified (linux-targets:39); independently checked 2026-11-13: weakened, corrected + +--- + +## §7 Building on CFEngine + +### P-§7.3-01: The fork bullet and the channel bullet are stale + +**Target:** §7.3 "What this does to the argument", bullets beginning "**The design currently depends on a fork.**" and "**The channel is open but slow.**" +**Kind:** correct +**Goal:** G7 +**Weight:** misleads +**Finding:** "If none of them merge ... permanently rather than temporarily" and "Neither has merged anything yet" were written on 2026-08-18. Since then: upstream closed all twenty-six on 08-19 (as §7.1 says), the operator ruled on 08-22 that the fork is the destination, and core#6332 (CFE-4742) merged on 09-02. The section contradicts §7.1 and the project's own decision. +**Evidence:** paper lines 1638-1646 against 1544-1554; `docs/architecture/upstream-register.md:15-18` ("PR1 MERGED 2026-09-02 ... cfengine/core#6332"); inventory §E. +**Proposed text:** + +> - **The design depends on a fork, by decision.** Our builds come from a +> fork branch that merges every fix and the `--simulate-json` series. We +> chose on 2026-08-22 to maintain that fork rather than wait on upstream, +> which makes it a permanent maintenance liability, and one more reason +> (G7) to keep CFEngine replaceable behind the goal file. +> - **The channel is narrow but not closed.** After the August closures, one +> small pull request (core#6332, CFE-4742) was merged on 2026-09-02, and +> on 2026-09-23 a maintainer invited `--simulate-json` back if split into +> logical parts. + +**Merge:** replace both bullets +**Checked:** verified (upstream-register:15-18; inventory; the 2026-09-23 invitation: `docs/handoffs/HANDOFF_standalone-3fd9_simulate-json-three-prs_2026-10-08_fab1.md:18-20`, larsewi on core#6332); independently checked 2026-11-13: weakened, corrected (dropped the unsupported "We send upstream only what the design cannot do without") + +### P-§7-01: §7 is the paper's best-evidenced section but the wrong centre of gravity + +**Target:** §7 "Building on CFEngine: what the substrate cost", whole section +**Kind:** move +**Goal:** G7 +**Weight:** improves +**Finding:** At 185 lines, §7 is the paper's only measured result, and the conclusion calls it the transferable finding. Under G7 the substrate is an instrument. A paper about an adoptable, owner-controlled tool should not have a CFEngine bug report as its main result. Keep §7.2 (the self-inverse codec lesson) and §7.4 (who wrote the fixes, relevant under G6) in a condensed appendix, and leave a five-line summary in the body. +**Evidence:** paper lines 1524-1705, 1923-1931. +**Proposed text (body summary):** + +> ### 7. The substrate, briefly +> +> Putting real weight on CFEngine's JSON data layer surfaced twenty-three +> defects, ten in that layer and three fatal before any promise runs. We +> now carry the fixes on a fork. The lesson that transfers is in Appendix +> B: a codec tested only against itself cannot see a fault its two halves +> share, and a design that routes traffic differently from the tool's own +> deployment is in effect a new test suite. + +**Merge:** move §7.1-§7.5 to Appendix B and insert the summary in their place +**Checked:** verified (line counts by reading); independently checked 2026-11-13: weakened, corrected (185 lines, not 180) + +--- + +## §8 Status and validation + +### P-§8-01: Add status against the finish line + +**Target:** §8 "Status and validation", new opening paragraph before "**Implemented.**" +**Kind:** add +**Goal:** G8 +**Weight:** blocks-goal +**Finding:** No document states a finish line (difference 7), and §8 measures progress against Bcfg2's deployment numbers rather than against the project's own target. G8 gives a three-state ladder. Measured against state 1, almost nothing exists: no Mac or Android device runs tendcf, no handshake, no archive service, and no Nix module frontend. +**Evidence:** goal G8; inventory §G4 ("Android and Mac: nothing tendcf runs there"), §H (Pull, Push, Peer, Android agent: nothing). +**Proposed text:** + +> **The finish line.** We will call this working in three steps. First, one +> of the operator's Macs and one of his Android devices converge from +> Nix-authored configuration, accept updates only after the handshake, and +> archive their logs on the Mac. Second, the operator's whole fleet runs on +> tendcf and the system it replaces is retired. Third, a person we have not +> helped installs it from the public documents with their own AI and keeps +> using it. Against the first step today: neither device runs tendcf; the +> compiler renders launchd services but has no Nix module frontend; the +> handshake, the update path, the archive service, the safety review and +> the Android agent are designs only. + +**Merge:** insert at the start of §8 +**Checked:** verified (inventory §G, §H); independently checked 2026-11-13: confirmed + +### P-§8-02: "Nothing is deployed beyond that one operator-host canary" should say what that canary lacks + +**Target:** §8, at "**Nothing is deployed** beyond that one operator-host canary." +**Kind:** reword +**Goal:** G4, G5 +**Weight:** misleads +**Finding:** The canary is on Linux, G5's fourth platform. It was brought up with CMDB data "installed by hand", carrying fixture trust content, and no approved goal file is stored on any host. It therefore changes a device without the exact, owner-visible, refusable difference G4 requires. That is acceptable for an operator canary, and the paper should state it plainly. The sentence also omits that the fork is installed, unscheduled, on a NixOS host. +**Evidence:** digest-current-plan C1c, C2; inventory §G ("No approved goal file is stored on any host"). +**Proposed text:** + +> **Little is deployed.** On one Linux operator host a root `cf-execd` +> enforces one canary service. Its data was installed by hand from a +> schema-valid goal file with fixture trust keys, so it runs without the +> see-and-refuse difference this paper is about. On one NixOS host the +> CFEngine fork is installed and nothing is scheduled. + +**Merge:** replace that sentence +**Checked:** verified (digests; not checked live); independently checked 2026-11-13: confirmed + +### P-§8-03: The "not implemented" list omits what the goal added + +**Target:** §8, paragraph beginning "**Not implemented, and this is still most of it:**" +**Kind:** add +**Goal:** G3, G4, G5 +**Weight:** improves +**Finding:** The list predates G3-G5. It should name the safety review and its CLI/TUI, the handshake and peer update path, the log archive and monitoring services, and the Android agent's profile handling. The "Remaining Step 0 work" list refers to the August build order and should be checked against tracker #1 or dropped. +**Evidence:** paper lines 1755-1763; inventory §D (#1 last updated 10-09). +**Proposed text:** + +> ... the peer-action runtime; the handshake and the peer update path; the +> log archive and monitoring services; the safety review, its scanners, and +> its command-line and TUI modes; and tendcf-agent on Android, including +> work-profile handling through ShizukuPlus. + +**Merge:** insert into the list; delete "Remaining Step 0 work: ..." unless re-checked against tracker #1 +**Checked:** verified (inventory) + +--- + +## §9 Open questions + +Disposition of the existing sixteen, under the goal: + +| Q | Status under the goal | Action | +|---|---|---| +| 9.1 inference vs fixpoint | remains | keep | +| 9.2 argument or hypothesis | premise answered by G6; rule remains | reword (P-§9-01) | +| 9.3 `not-yet-migrated` grind | remains, sharper for a non-admin owner | keep; link P-§4.2-01 | +| 9.4 per-domain granularity | remains; Android profiles are natural domains | keep | +| 9.5 local-first | partly answered by G3/G8 (archive is a consumer) | reword (P-§9-02) | +| 9.6 global question | remains; monitoring service narrows it | keep, cite §2.5 | +| 9.7 spurious-edge provenance | remains | keep | +| 9.8 schema keeps up | remains | fix "8.3" to "9.3" | +| 9.9 premise wrong shape | premise answered by G6; "wrong surface" remains | reword (P-§9-01) | +| 9.10 is a diff consentable | G4 commits to a mechanism; whether it works remains | reword (P-§9-03) | +| 9.11 total-diff events | remains | keep | +| 9.12 refusal cost | remains; G9 gives refusal a future | keep, cite §11 | +| 9.13 baseline protection | remains; "Termux" is the wrong awkward case | reword (P-§9-04) | +| 9.14 policy tree in reviewed state | remains | keep | +| 9.15 device-local trust root | now a requirement (G3); buildability remains | reword (P-§9-05) | +| 9.16 confirming effect | remains | keep | + +### P-§9-01: 9.2 and 9.9 question the premise G6 fixes + +**Target:** §9 "Open questions", items "**9.2 Is the writing rule an argument or a hypothesis?**" and "**9.9 Is the whole premise the wrong shape?**" +**Kind:** reword +**Goal:** G6 +**Weight:** misleads +**Finding:** 9.9's title and first sentence ("on the assumption that they are the primary authors") put the premise itself up for attack, which G6 rules out. Its real question, whether bounded context is the weakness worth hardening against, is legitimate and should stay. 9.2 is already about the rule; it needs only a clause. The sentence G6 directs (difference 9) is this one. +**Evidence:** paper lines 1791-1796, 1834-1841; goal G6. +**Proposed text (9.9):** + +> **9.9 Have we hardened the right surface?** That AI agents write most of +> this configuration is the project's premise, not a question here. What is +> open is our account of their weakness. We assume it is bounded context. +> If it is instead plausible-looking output that type systems do not catch, +> the schemas guard the wrong place. §7.4 is one reason to take this +> seriously: none of the ten data-layer defects would have been caught by +> any schema at our layer. The safety review (§2.5) is our second line +> there. + +**Merge:** replace 9.9; in 9.2, insert "The premise is fixed; the rule is not." after the title +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### P-§9-02: 9.5 is partly answered + +**Target:** §9, item "**9.5 Is local-first the wrong call?**" +**Kind:** reword +**Goal:** G3, G8 +**Weight:** improves +**Finding:** With a log archive in the first milestone, the question is no longer whether to have a central copy. It is whether the device or the archive is authoritative when they disagree, and whether an owner can refuse to export logs at all. +**Evidence:** paper lines 1810-1812; goal G8.1. +**Proposed text:** + +> **9.5 Which copy wins?** The first milestone archives logs on a server +> device, so a central copy exists. We hold that the device's own capture +> is the record and the archive a service fed from it. Is that right when +> they disagree, and is exporting a device's logs itself a difference its +> owner must approve? + +**Merge:** replace 9.5, as one edit with 06 P-§6.4-s11, which corrects the same item's "precisely the reasoning LISA '05 warns against" to the booklet [4, §8.1]; if the replacement names where the "report early" advice comes from, it carries that booklet attribution +**Checked:** inferred + +### P-§9-03: 9.10 now has a proposed mechanism + +**Target:** §9, item "**9.10 Is a diff something a person can actually consent to?**" +**Kind:** reword +**Goal:** G4 +**Weight:** improves +**Finding:** G4 commits to a mechanism for making a large diff holdable: a scored reading with reasons and graded highlighting. The open question becomes whether that mechanism works, and whether a high score trains people to stop reading. That is 9.11's rubber-stamp worry moved one level up. +**Evidence:** paper lines 1843-1851; goal G4. +**Proposed text:** + +> **9.10 Does the safety reading make a diff consentable, or replace +> reading it?** Our answer to "forty-one entries changed" is the safety +> review: a figure, its reasons, and the questionable entries highlighted +> (§2.5). If it works, a person reads the few entries that matter. If it +> works too well, a person reads the figure and nothing else, and a +> high-scoring malicious change is the cheapest attack left. The test is +> countable once real diffs exist: how often an owner opens an entry the +> reading did not highlight. + +**Merge:** replace 9.10 +**Checked:** inferred + +### P-§9-04: 9.13's awkward case is Android profiles, not Termux + +**Target:** §9, item 9.13, at "and Android under Termux is the awkward case." +**Kind:** reword +**Goal:** G5 +**Weight:** improves +**Finding:** With tendcf-agent as the Android component and work profiles in scope, the baseline lives in app-private storage. The awkward case is protecting it from a process holding ShizukuPlus's shell-level privilege, which is the same process tendcf needs in order to act. +**Evidence:** paper lines 1871-1873; digest-current-plan B10 (D45). +**Proposed text:** + +> and Android is the awkward case: the baseline sits in tendcf-agent's +> private storage, on a device where ShizukuPlus's privileged process, which +> tendcf itself relies on, can reach more than any one app should. + +**Merge:** replace that clause +**Checked:** not checked: reasoning from G5 with no source; it needs a device test of what ShizukuPlus's privileged process can reach in another app's private storage (Shizuku's shell-uid scope is general knowledge, not tested) + +### P-§9-05: 9.15 is a requirement now + +**Target:** §9, item "**9.15 Can the consent gate be made to mean what it says?**" +**Kind:** ruling-drift +**Goal:** G3 +**Weight:** misleads +**Finding:** G3's peer updates make a device-local trust root mandatory (P-§1.1-01). What remains open is how to build it on macOS and Android first, not whether to. As in P-§1.1-01, "mandatory" is an inference: G3/G4 imply only that the handshake's anchors and the consent policy sit beyond the release path's reach. +**Evidence:** paper lines 1883-1886; goal G3, G5. +**Proposed text:** + +> **9.15 How is the device-local trust root built?** Every device must hold, +> out of the release path's reach, what a correct handshake is (§1.1, +> §2.5). How that is stored on a Mac (Keychain, a root-owned file, the +> Secure Enclave) and on a phone (Android Keystore inside tendcf-agent) is +> open, and the rest of the gate rests on it. + +**Merge:** needs the operator's ruling first (whether a device-local trust root is a requirement of G3/G4 or one design among several); replace 9.15 once ruled +**Checked:** inferred (storage options are suggestions); independently checked 2026-11-13: weakened, corrected + +### P-§9-06: New question from G3: what is the handshake, and who may originate an update? + +**Target:** §9, new item after 9.16 +**Kind:** add +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** "Any other device that completes the correct cryptographic handshake" leaves open whether any device may *originate* an update or only relay one, and what happens when a phone holding a deploy key is lost. These are the first design decisions G8 state 1 needs. +**Evidence:** goal G3, difference 5. +**Proposed text:** + +> **9.17 What does a peer's handshake authorize?** If any device may carry a +> release, the signature decides and the carrier is irrelevant. If a device +> may also *originate* one, every device that can is a signer, and losing a +> phone is a key compromise. Which devices may originate, how a lost one is +> revoked by peers that never meet the owner's root, and whether a device +> may refuse a valid update from a peer it has never seen are open. + +**Merge:** insert after 9.16 +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### P-§9-07: New question from G4: what does "safety confidence out of 100%" mean? + +**Target:** §9, new item +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** A percentage invites a probability reading ("97% safe"). Nothing is calibrated against, the scanners disagree in kind, and the AI component is non-deterministic. The paper needs to say what the number is, how it is combined, whether the same difference always gets the same figure, and what it may never be (100%). +**Evidence:** goal G4, difference 4. +**Proposed text:** + +> **9.18 What is the confidence figure a measure of?** It is shown as a +> percentage, but nothing yet calibrates it. Which scanners contribute and +> how, whether one difference always gets the same figure when an AI is +> among them, and how an owner is kept from reading 95% as "safe" are +> open. Our provisional answers: mechanical findings cap it, it never +> shows 100%, and the reasons are shown before the figure. + +**Ruled:** "1. Capped 0-100 score" (operator ruling, 2026-11-14, B8) and "1. 09's table, top 95" (B8 sub 1): the provisional answers in the proposed text are adopted. The figure is a score from 0 to 100, never 100 (base 95), capped by mechanical findings that AI review can lower but never raise, with an explanation of each part and a measured hit rate once a corpus exists. The item's title and "percentage" wording then read "score from 0 to 100". Ruled; implementation pending. + +**Merge:** the score computation is ruled; insert as a new item, worded as the ruling +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### P-§9-08: New question from G2: what carries over? + +**Target:** §9, new item +**Kind:** add +**Goal:** G2 +**Weight:** improves +**Finding:** The question P-§2.1-02 and P-§2.2-03 defer to. Without a test corpus, "carries over" cannot be checked. +**Evidence:** goal G2. +**Proposed text:** + +> **9.19 Which NixOS and nix-darwin configurations carry over, and how +> would we know?** The honest test is a corpus: real, public NixOS and +> nix-darwin configurations, compiled for a Mac and a phone, counting what +> carries over unchanged, what needs a rename, and what has no meaning off +> NixOS. We have not built the corpus or chosen how faithful carry-over must +> be (§2.1). + +**Merge:** insert as a new item +**Checked:** inferred + +### P-§9-09: New question from G5: one agent per phone, or one per profile? + +**Target:** §9, new item +**Kind:** add +**Goal:** G5 +**Weight:** improves +**Finding:** A phone with a work profile is several Android users. The agent could be one install in the main profile acting on others through ShizukuPlus, or one per profile, each with its own baseline and its own owner yes. The second matches G4 better if a profile can have a different owner (an employer). The first is simpler. +**Evidence:** Insular: work profile as secondary user (https://filepathgeek.com/posts/insular-data-location/); goal G5. +**Proposed text:** + +> **9.20 Is a work profile a device?** An Island or Insular profile is a +> separate Android user with its own apps and storage. tendcf can manage it +> from one agent in the main profile, through ShizukuPlus, or treat each +> profile as its own device with its own goal file, baseline and approval. +> The first is simpler. The second is right if a profile's owner can +> differ from the phone's. We have not decided. + +**Ruled:** "1. Field on entries" (operator ruling, 2026-11-14, B3 sub 1, Q20 / M-§12-04 / X-android-05): one host per phone (one key, baseline, review); each Android promise names its target user (owner/work/private) and the work profile's owner app (island/insular/none); an unreachable profile reports `not_kept`. So a work profile is not a device: the question is answered "one agent per phone". The schema bump is a design ruling (two frontier reviews) and rides the same bump as the agent id (M-§12-05 item 4). That bump is the next unused schema version (v7 or later; shipped v6 is C-policy-01, PR 52); whether the standing-modes approval record shares it is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. Ruled; implementation pending. + +**Merge:** insert as a new item, with the answer above +**Checked:** not checked: reasoning from G5 with no source to check (the Android multi-user model comes from a search snippet); it needs a device test of Island/Insular profiles with ShizukuPlus + +### P-§9-10: New question from G9: can a non-technical person keep a fork? + +**Target:** §9, new item +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** G9 is "later", but it constrains choices made now: patch formats, how a conflict is presented, and whether a refused change can become a kept patch (P-§1.1-03). Stating the question now stops early decisions from closing it off. +**Evidence:** goal G9; `overlay/` (6 patches, weekly drift check; inventory §E). +**Proposed text:** + +> **9.21 Can someone who has never merged anything keep a fork?** We +> intend, later, to let a person maintain their own changes to a project, +> or to a plugin of one, as patches over its releases, extending the +> pattern this project already uses for its CFEngine fork (§11). What a +> conflict looks like to such a person, whether their AI may resolve it, +> and whether each resolution is itself a difference they approve are +> open. + +**Merge:** insert as a new item +**Checked:** inferred + +--- + +## §10 Conclusion + +### P-§10-01: Full replacement conclusion + +**Target:** §10 "Conclusion", all three paragraphs, from "We have described a configuration management architecture" to "than after a fleet is running on it." +**Kind:** reword +**Goal:** G1, G2, G3, G4, G6, G7, G8 +**Weight:** blocks-goal +**Finding:** The conclusion repeats the withdrawn "signed plan the executor may not exceed". It calls the CFEngine defect count the paper's transferable finding, which G7 makes a side result. It says "the schemas are days old and nothing is deployed": they date from 2026-08-15 and are at version 5, and a canary is enforced. And it does not state the aim or the finish line. +**Evidence:** paper lines 1903-1935; inventory §A (schema_version 5); goal G1-G8. +**Proposed text:** + +> We have described a configuration management system whose aim is that +> people control their own devices, on the premise that an AI, usually the +> owner's own, writes most of the configuration. Three commitments carry +> the design. Configuration is written in Nix with NixOS-style options and +> evaluates to plain data, so the people likely to adopt it first bring +> the language and module style they already use. Every device is self-sufficient and accepts only +> updates that complete its handshake, so there is no control node to fail +> or to trust. And nothing changes a device except as an exact difference +> its owner can see and refuse, with a safety reading that shows its +> reasons, so the owner decides with the evidence in front of them rather +> than on trust in whoever proposed the change. +> +> The local-knowledge rule of §3 is not new. It is a +> configuration-management instance of local reasoning about global +> properties [9], argued independently for AI-generated code by Tratt +> [10]. What we claim is the composition, and one uncommon choice inside +> it: compiling into an existing engine's native data layer rather than +> shipping a new client, with that engine treated as an instrument we can +> replace. The one measured result so far concerns that choice: routing +> heavy traffic through a path the engine's own deployment uses lightly +> found twenty-three defects in the engine, ten of them in that path +> (Appendix B). +> +> The first test is concrete: one Mac and one Android phone converging +> from Nix-authored configuration, accepting updates only after the +> handshake, with their logs archived on the Mac. The last is that someone +> we have not helped installs tendcf from the public documents with their +> own AI and keeps using it. Neither has happened. We would rather be told +> where the design is wrong now, while it is mostly on paper, than after a +> fleet depends on it. + +**Merge:** replace §10 +**Checked:** verified (stale claims against inventory); independently checked 2026-11-13: confirmed (proposed text corrected: the defect count matches paper lines 49-50 and 1924-1925) + +--- + +## Whole-paper structure + +### P-§S-01: Proposed outline for the paper under the goal + +**Target:** the whole paper, section order §1-§10 +**Kind:** move +**Goal:** G1, G2, G3, G4, G5, G9 +**Weight:** blocks-goal +**Finding:** The paper is organised as a dialogue with Bcfg2 about an AI-authorship design rule, with a CFEngine experience report as its result. The goal's distinctive parts have no home: Nix authoring (G2), peer updates (G3), the safety review (G4), Android (G5) and branch management (G9). Keep the Bcfg2 dialogue: it is what the first reader, Desai, can judge best. Add the five sections, move process advice and the substrate report to appendices, and put status against the finish line. +**Evidence:** paper section list (lines 60-1901); goal G1-G9. +**Proposed text (outline):** + +> 0. Abstract (P-Abs-03) +> 1. Motivation: owner control, who adopts, AI or code, platform order (P-§1-01, P-§1-02) +> 1.1 Scope and limits (P-§1.1-01 to -04) +> 2. Architecture +> 2.1 The Site Model and its layers (old 2.1, minus the Nix paragraph) +> 2.2 **Authoring in Nix** (new). NixOS-style options declared once by +> tendcf, set by sites; JSON/YAML beneath and writable by hand; what +> carries over (P-§2.1-02); flakes as shared inputs (P-§2.1-03); the +> evaluation boundary: where Nix runs, and that no device evaluates. +> 2.3 The compiler (old 2.2) +> 2.4 **Every device self-sufficient** (old 2.3 rewritten, P-§2.3-01). +> The handshake (P-§2.5-03), relay and origination, push as request. +> 2.5 **Servers are services** (new). Log archive and monitoring on the +> first Mac; fed from device capture; never authoritative; owner +> approves log export. +> 2.6 Releases, goal files and the difference the owner sees (old 2.5) +> 2.7 **The safety review** (new, P-§2.5-01). Scanners (mechanical, +> provenance, AI from a different model), the figure and its +> ceiling, reasons citing entries, graded highlighting, CLI for +> scripts and AIs, TUI on a borrowed scaffold, refusal always one +> step. +> 2.8 **Android** (new). What is managed per profile (apps, enabled +> state, permissions and app ops, settings, default apps, always-on +> VPN); ShizukuPlus as the user-space privilege, and its loss on +> reboot; Island/Insular profiles (P-§9-09); tendcf-agent's capture +> and baseline; where, if anywhere, CFEngine runs; the owner's +> review on the phone itself. +> 2.9 Worked examples (old 2.6, Nix block fixed per P-§2.6-01, plus an +> Example D: one app installed in a work profile, from Nix to the +> difference the owner sees, scored) +> 2.10 Peer actions (old 2.7, P-§2.7-01); 2.11 Per-device trust (old +> 2.8); 2.12 Token discovery (old 2.9) +> 3. The design rule (old 3 and 3.1; premise fixed, P-§3-01) +> 4. Two places the rule shows up (old 4, plus P-§4.2-01) +> 5. Where this departs from Bcfg2 (old 5) +> 6. What we took from Bcfg2 (old 6) +> 7. The substrate, briefly (P-§7-01) +> 8. Status against the finish line (old 8, P-§8-01 to -03) +> 9. Open questions (old 9 reworded, plus 9.17-9.21) +> 10. Conclusion (P-§10-01) +> 11. **Later: branch management for everyone** (new, G9). Refusal becomes a +> kept patch; the overlay pattern (`overlay/`, drift checked weekly) +> generalised to any project or plugin; the person's AI presents +> conflicts as differences to approve; no merging, rebasing or +> compiling asked of them. +> Appendix A. Nine instances of the rule (old 3.2) +> Appendix B. Building on CFEngine (old 7.1-7.5) + +**Merge:** needs the operator's ruling first (accept the outline, or name sections to keep as they are) +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### P-§S-02: Two documents, not one + +**Target:** the whole paper, header paragraph "The vetted current-state description is ... Where this paper and the guide disagree on the current design, the guide wins." +**Kind:** question +**Goal:** G1, G8 +**Weight:** improves +**Finding:** The paper serves two audiences: Desai, who will judge the Bcfg2 dialogue and the consent design, and "the public". G8 state 3 adds a third: a person installing from the public docs with their own AI. That person needs a short "what it does for you" document, not a 2,000-line paper. Naming the paper's audience as Desai and expert readers, and pointing the public at an adopter's introduction, stops the paper being bent to serve both. +**Evidence:** paper lines 11-16, 53-56; digest-project-history B1.7 ("he is the primary target"); goal G8.3. +**Proposed text:** + +> This paper is written for readers who build configuration management +> systems, and first for the author of Bcfg2. A person deciding whether to +> use tendcf should start with ``, which this paper +> does not replace. + +**Merge:** needs the operator's ruling first (whether an adopter introduction is wanted, and where it lives) +**Checked:** inferred + +### P-§S-03: Move §3.2 to an appendix + +**Target:** §3.2 "Nine concrete instances", whole subsection +**Kind:** move +**Goal:** G1 +**Weight:** improves +**Finding:** §3.2 is 180 lines of repository practice: lookup CLIs, schema-example pairing, a document's self-warning, YAML round-trips, AGENTS.md files. It reads as an internal memo inside the paper's argument and delays the architecture for the reader. Items 5 (grounded explanations) and 6 (constrained decoding) bear on the safety review and should be cited from §2.7. The rest belongs in Appendix A. +**Evidence:** paper lines 1023-1201. +**Proposed text:** + +> §3.1's rule has concrete consequences for the repository as well as the +> design; Appendix A lists nine, each checked against its source. Two bear +> on the safety review (§2.7): an explanation must cite the entries it +> summarises, and where a grammar can constrain what an AI writes, it +> should. + +**Merge:** move §3.2 to Appendix A and insert this paragraph in its place +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +--- + +## Nits + +| ID | Where (quoted) | Fix | +|---|---|---| +| P-N-01 | §2.2 "That is the §3.2-item-1 problem in its natural habitat" | §3.2 item 1 is the targeted lookup; the silent-scope bug matches §3's "violate confidently and plausibly". Cite §3. | +| P-N-02 | §2.6 "do not exist yet (§6.5, §8)" and the Nix block's "the frontend is unbuilt (§6.5)" | §6.5 is "What did not transfer". Cite §8. | +| P-N-03 | §9.8 "That is question 8.3 wearing a different hat." | Should be 9.3. | +| P-N-04 | References [2], [3], [5], [7], [8], [29] | Never cited by number in the body (LISA '05/'06 are named only). Cite them where named, or drop [5], [7], [8]. Verified by `rg -F "[n]"` over lines < 1940. | +| P-N-05 | §2.1 "tool forks (optional) — sudo-secretspec, Shizuku" | "ShizukuPlus (our fork, ShizukuTendCF)". | +| P-N-06 | §1 "Android devices reached through Termux, a forked Shizuku, and a local agent" | Superseded by P-§1-01; if kept, "ShizukuPlus". | +| P-N-07 | §4.1 "The site's existing Android deploy chain hand-orders" | "Our predecessor system's Android deploy chain"; Ansible was removed 2026-08-13. | +| P-N-08 | §5.4 "all fourteen service-owning roles across the site ... single-role plays" | Say these were the predecessor's Ansible roles. | +| P-N-09 | §6.5 "Termux's `$PREFIX`-relative layout against Linux and macOS absolutes" | Add Android's per-user paths (`/data/user//`) as the same `altsrc` problem. | +| P-N-10 | §7.5 "who responds to every defect by fixing it upstream" | "by fixing it in the substrate". | +| P-N-11 | §2.6 "**Three worked examples**" then "on two concrete Site Model records" | Fine as written; if Example D (P-§S-01) is added, make it "Four". | +| P-N-12 | §8 Bcfg2 figures "four months, one person, roughly three FTE ... a third and a half of an FTE ... about two hundred people", and §6.4 "about four months" | (c) For the sources reviewer: give the LISA '05 section for each figure. | + +Also for the sources reviewer, not itemised: §2.2 "3.7.3 back-ported `def.json` parsing into the core agent"; §2.2 cdktf "deprecated ... December 2025 [21]"; §3.1 Tratt [10] "July 2026"; §3.2 item 9 "[17] ... inference cost rose by more than a fifth"; §6.1's quoted Bcfg2 Actions sentence [4, §A.2.1]. I did not check any of them. + +--- + +## Ideas and risks + +1. **The figure becomes the authority.** A well-calibrated 96% will be read as "safe", and the cheapest attack left on G4 is a malicious change that scores high. Show the reasons before the figure, never show 100%, and let mechanical findings cap what the AI can award. Measure how often owners open un-highlighted entries. **Ruled:** "1. 09's table, top 95" (operator ruling, 2026-11-14, B8 sub 1): base 95, never 100; penalties lockout 60, privilege 50, management 45, data-loss 40, reversible 10, notice 3; the AI reviewer subtracts up to 30 (findings that cite a key path only; whether per reviewer or in total is open: deferred to the schema design review (operator ruling, 2026-11-14, PR 62 review Q7)); caps: lockout, privilege or management finding 40, a check not run or failed (including AI reviewer unavailable) 60, uncovered hunk kind 70, AI families disagree on a tier 70, touched domain not comprehensive 80, integrity flag 0; bands 0-39 danger, 40-69 caution, 70-89 notice, 90-95 plain. The values are fixed in the schema, changed only by a ruling, later backed by a labelled corpus (table in 09 Q3). + +2. **Use the project's own review rule on owners' devices.** The repo already forbids a model family from reviewing its own work. Applying the same rule to the safety reading (a different model from the author's, or a disclosed fallback) is a real differentiator, and it costs a configuration option, not a new system. **Ruled:** "2. Should not (as written)" (operator ruling, 2026-11-14, B8 sub 4, X-safety-06): "should not", with two model families where the owner has them and their disagreement capping the score (70); the same model is allowed with no extra cap. + +3. **Android rests on a third-party fork.** ShizukuPlus is one person's fork of a fork (thejaustin over thedjchi over RikkaApps), and ShizukuTendCF forks it again, last touched 2026-10-22. Android releases have repeatedly narrowed wireless debugging. The paper should name this dependency as the platform's largest risk, and the Android section should say what degrades when the privileged process cannot be started. + +4. **"Carries over" needs a number.** A corpus of public NixOS and nix-darwin configs compiled for a Mac target, with the share that carries over unchanged, would turn G2 from a slogan into a measurement. It is also the cheapest result to show Nix-sharing sysadmins, G1's first adopters. + +5. **TUF already permits relay.** TUF separates signers from mirrors, so "any device may carry an update" costs little if the handshake is the release signature. A phone can carry a release to a sleeping Mac. Much of G3 may be cheaper than the documents' open transport questions suggest. + +6. **The log archive is the first thing that leaves a device.** On a household fleet, an owner's phone logs arriving on someone else's Mac is the very kind of change G4 is about. Make log export an entry in the goal file, seen and refused like any other. + +7. **Profiles may be the cleanest unit of ownership.** If an Island/Insular profile is a device in the goal-file sense, one phone can host a personal profile under its owner and a work profile under someone else, each with its own see-and-refuse. That would be a strong, demonstrable Android story, and it fits the existing per-device trust table without new concepts. + +8. **Refusal and G9 are one feature.** A refused change that the owner wants to keep their own version of is a branch. Designing the refusal record now so it can later become a kept patch costs little and avoids a second mechanism. + +9. **The paper can absorb effort the milestone needs.** Docs hold 70,142 added lines against 5,301 for the compiler (inventory §B), and two prior reviews warned of "a paper that had a repo". Rewriting this paper before G8 state 1 exists repeats that pattern. Take the factual corrections now and defer the restructure (P-§S-01) until the Mac and the phone converge. + +10. **Desai is a test reader for G4, not only for Bcfg2.** He spent LISA '05 learning that administrator trust is about information presentation. A one-page mock of the CLI review screen for a real difference, with score and highlighting, would draw sharper comment from him than any further prose about consent. + +Last search run: exempt: a document review; the two searches above (ShizukuPlus, Insular) were the only facts where current web state could change an item, and they were run before writing. + +--- + +## Withdrawn after checking + +None. The independent check refuted no item in this response. diff --git a/docs/review-2026-11-13/02-response-guide.md b/docs/review-2026-11-13/02-response-guide.md new file mode 100644 index 0000000..d8dd461 --- /dev/null +++ b/docs/review-2026-11-13/02-response-guide.md @@ -0,0 +1,1241 @@ +# Response: `docs/paper/tendcf-architecture-guide.md` against the goal of 2026-11-13 + +Target: `docs/paper/tendcf-architecture-guide.md` (1,676 lines, read in full) + +Base commit: eefea3c + +How this was produced: one reviewing agent (Claude Opus), then an independent checking agent that tried to refute each finding; nothing was executed unless an item says so. + +Item counts by Weight after corrections: 45 full items and 10 table nits; blocks-goal 12, misleads 9, improves 21, nit 13 (3 full, 10 in the table). Checking: 32 items checked (25 confirmed, 7 weakened and corrected, 0 withdrawn); the other 13 full items and the nit table were not sampled and stand as written. + +Measured against `docs/review-2026-11-13/00-goal-definition.md` G1–G9 and its nine differences (cited as "diff N"). Item format per `docs/review-2026-11-13/README.md`. All anchors are guide `file:line` at `eefea3c` unless named. + +Sources consulted: firecrawl_search for ShizukuPlus (found https://github.com/thejaustin/ShizukuPlus), Insular/Island (https://f-droid.org/packages/com.oasisfeng.island.fdroid/, https://github.com/proletarius101/Insular), nix-darwin launchd options (https://nix-darwin.github.io/nix-darwin/manual/, https://mynixos.com/nix-darwin/option/launchd.agents.%3Cname%3E.serviceConfig), Python TUI frameworks (https://www.michaelblaess.de/en/blog/tui-vergleich/). + +--- + +## Front matter + +### G-§0-01: The goal, not the guide, says what the design is for + +**Target:** front matter, at the sentence beginning "Where any other living document disagrees" +**Kind:** add +**Goal:** G1–G9 +**Weight:** blocks-goal +**Finding:** The guide makes itself the winner on every conflict over the current design. It has no higher reference that says what the design is *for*, so a design choice can only be checked against other design choices. The agreed goal should sit above it: the guide wins over other design documents, and the goal wins over the guide. +**Evidence:** guide:8-16; `docs/review-2026-11-13/00-goal-definition.md:1-7`. +**Proposed text:** + +> What the system is for is fixed by the goal definition +> ([`00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md), +> agreed 2026-11-13, G1–G9). Where this guide's design conflicts with that +> goal, the guide is wrong and is amended. Below the goal, the order is as +> follows. + +**Merge:** insert before "Where any other living document disagrees" (and move the goal file to a permanent path, e.g. `docs/GOAL.md`, first: needs the operator's ruling on where it lives) +**Checked:** verified (read both files); independently checked 2026-11-13: confirmed + +### G-§0-02: "Nothing described here is deployed" undercounts the live state + +**Target:** front matter, at "**Nothing described here is deployed**, apart from a canary service on one operator host (§4)" +**Kind:** correct +**Goal:** G4 +**Weight:** misleads +**Finding:** The sentence names the canary but not what runs it, and leaves two things out. pastebin runs a scheduled root `cf-execd` over a projection installed with `tendcf-install.sh install --data`, and the interlock path there has a documented fail-open. get.sipb.cloud has the fork installed as a NixOS module, with nothing scheduled. The operator's NixOS host repos have consent CI. Under G4 a reader needs to know that a root agent changes a host today with no device-side diff. +**Evidence:** `docs/architecture/tendcf-validate-proposal-2026-11-03.md:1017-1026` ("fail-open in the live design ... applies to pastebin today"); `CLAUDE.md` ("pastebin (root install, canary enforced), get.sipb.cloud (module installed, nothing scheduled)"); inventory report §G. +**Proposed text:** + +> **Almost nothing described here is deployed.** One operator Linux host +> (pastebin) runs the fork as root under a scheduled `cf-execd` and enforces +> one canary service, from a projection installed by hand: no device there +> computes a diff or holds an approved baseline, and the interlock path has a +> known fail-open (§16.C). A second host (get.sipb.cloud) has the fork +> installed and nothing scheduled. No Mac or Android device runs any of it. + +**Merge:** replace that sentence +**Checked:** verified (read validate proposal §13 and CLAUDE.md); live hosts not contacted; independently checked 2026-11-13: weakened, corrected + +--- + +## §1 What this is + +### G-§1-01: Replace §1 with the agreed goal + +**Target:** §1 "What this is", whole section +**Kind:** correct +**Goal:** G1, G2, G3, G4, G5, G6, G8, G9 +**Weight:** blocks-goal +**Finding:** §1 describes a fleet-keeping design for the operator's mixed fleet. It has no adoption aim, names an ordinary Linux distribution as a goal and reaches Android only through Termux (no ShizukuPlus, no Island/Insular), makes Nix one of two equal languages (diff 2), and has no finish line (diff 7). Its "more than one trusted person can act" is the claim §17 says the signing model cannot meet (guide:1257-1261; also the 2026-08-15 skeptical review, per the review-record digest A8). Below is a full replacement in the guide's voice. It drops the multi-operator claim and narrows "no central server" to what G3 says. +**Evidence:** guide:45-67; goal G1–G9. +**Proposed text:** + +> ## 1. What this is +> +> `tendcf` is free software that gives people control of their own +> computers, phones and tablets, as they see fit. It is a configuration +> management system meant to be adopted by people other than its author. +> +> A person uses it through an AI or directly at the code level, and can +> switch between the two at any moment. Through an AI, they say what they +> want; the AI writes it as configuration, and explains or warns when a +> request looks unwise. The first adopters are expected to be sysadmins who +> already share configurations in [Nix](https://nixos.org/). The long-run +> user has no admin skill at all. +> +> That AI agents write the configuration is the premise, not a hypothesis +> this project tests. The design's job is to make that safe. +> +> - **Authoring.** Configuration is written in the real Nix language with +> NixOS-style options, so existing NixOS and nix-darwin configuration +> carries over (§3). Plain YAML/JSON sits beneath it as the data Nix +> evaluates to, and can be written by hand. Nix runs where configuration +> is written; on a managed device it runs only where it is already that +> host's configuration system (NixOS, nix-darwin), or as the owner's +> authoring tool (§4). +> - **Shape.** Every device converges on its own. There is no control node. +> A device accepts an update from any other device that completes the +> correct cryptographic handshake (§5, §7). A "server" is only a device +> that provides services to others, such as receiving and archiving logs +> or monitoring; a "client" is a device that uses them. Neither word +> changes the architecture. +> - **Safety.** Nothing changes a device except as an exact, mechanically +> checked difference its owner can see and refuse (§7). Each difference is +> also scanned for likely safety in several ways, AI among them, and the +> owner is shown a confidence out of 100%, why that figure was chosen, and +> the questionable parts highlighted more dramatically the less safe they +> look, at the command line or in a TUI (§8). +> - **Platforms, in order:** macOS as server, Android as client, macOS as +> client, Linux as server, Linux as client. Android is the differentiator: +> comprehensive configuration management that works with Island/Insular +> work profiles and with user-space ShizukuPlus (§6, §13). +> +> **Finish line.** Three states, in order. (1) One Mac and one Android device +> converge from Nix-authored configuration, accept updates only after the +> handshake, and archive their logs on the Mac. (2) The author's whole fleet +> runs on tendcf and the configuration stack it replaces is retired. (3) +> Someone the author has not helped installs it from the public +> documentation with their own AI, and keeps using it. §18 is ordered by +> these states. +> +> **Later.** Free-software branch management built on the same patch +> patterns (§18, `overlay/`), so that a person with no technical skill can +> keep a fork of a project, or of a plugin to one, without knowing about +> merging, rebasing or compiling. +> +> CFEngine, the CFEngine fork, the Site Model and the compiler are the +> instruments chosen to reach this. They are open to challenge, and none of +> them changes without the operator's ruling. + +**Merge:** replace §1 (the "previous configuration stack" paragraph at guide:39-41 stays in the front matter; G8 state 2 names `~/ops` in private docs only, so the public text says "the configuration stack it replaces") +**Checked:** verified (read §1 and the goal); independently checked 2026-11-13: weakened, corrected + +--- + +## §2 The picture + +### G-§2-01: The picture has no server services and no review surface + +**Target:** §2 "The picture", the diagram +**Kind:** add +**Goal:** G2, G3, G4 +**Weight:** improves +**Finding:** The diagram ends at "JSONL log / SQLite index". It shows no log archive or monitoring service (G3, diff 6) and no place where the owner sees, scores and refuses a diff (G4, diff 4). It lists the frontend as "YAML, or Nix", the opposite of G2's order. +**Evidence:** guide:73-113. +**Proposed text:** + +> ``` +> tendcf compile compiler, in tendcf: frontend (Nix modules via +> (tool) the nix2cf plugin; or YAML/JSON, the data Nix +> evaluates to) → merge → conflict check → +> per-host goal file. +> ... +> ▼ +> Device-side review the device computes the diff from its approved +> (CLI or TUI) baseline; scanners score it 0–100 with reasons; +> the owner sees it, highlighted, and accepts or +> refuses (§7, §8) +> ... +> ▼ +> JSONL log (capture) append-only; the durable record, on the device +> SQLite (index) rebuildable from JSONL +> ┆ best-effort copy +> ▼ +> Server services any device holding the role: log archive, +> (a role, not a tier) monitoring. Never the record of truth (§6). +> ``` + +**Merge:** replace the frontend box, and insert the two new boxes in place +**Checked:** verified (read diagram) + +--- + +## §3 Facts live in layers + +### G-§3-01: Nix first, YAML beneath, not "two equal authoring frontends" + +**Target:** §3, at "The Site Model has two equal authoring frontends" +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** The paragraph states D12 as amended 2026-10-29: two equal frontends, and "Nobody adopting the project has to know Nix". G2 makes Nix the authoring language and YAML/JSON the data layer beneath it, which can still be written by hand. The compiler today has only an `eval-nix` wrapper over `nix-instantiate`, and `site.nix` is a plain attribute set, not a module system. So the guide's "not built yet" stands, but the frontend it should promise first is the Nix one. +**Evidence:** guide:189-198; `compiler/nix2cf/cli.py:150-171,203`; `compiler/examples/site/site.nix`; inventory report §A ("the Nix module frontend of D12 ... is not built"). +**Proposed text:** + +> Site Model configuration is written in Nix, with the module system +> (`mkOption`, `mkIf`, `mkDefault`) and NixOS-style option names. It +> evaluates to plain YAML/JSON, the data everything else consumes and the +> form the schemas check. That data form is public and stable, so it can +> also be written by hand, by a person or a tool that does not use Nix. +> A Nix-authored site renders for a Mac or a Debian box that has no Nix at +> all; and a host that already runs NixOS or nix-darwin keeps its +> configuration verbatim, tendcf adding only distribution, consent and +> reporting around it. The Nix module frontend, which will carry the name +> `nix2cf` (§4), is not built yet: today `nix2cf eval-nix` evaluates a +> plain Nix attribute set to the same JSON, and the fixtures are YAML. + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`) adopts D49, which amends D12 (Nix first, not two equal frontends). Ruled; merged into the map's D49 and D12 (decision register) on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. Whether `schema/` or the Nix module options is the schema authority (Q23) and whether the YAML twin stays as a test remain open. + +**Merge:** replace the paragraph; D12 is amended at the same time in the map (the map's orientation section, item 2, and D12 say "equal"); ruled (operator ruling, 2026-11-14, B4: D49 adopted) +**Checked:** verified (read cli.py and the guide); independently checked 2026-11-13: confirmed + +### G-§3-02: "Configs carry over": say which options, and borrow nix-darwin's names + +**Target:** §3, same paragraph (follows G-§3-01) +**Kind:** question +**Goal:** G2 +**Weight:** improves +**Finding:** G2 says existing NixOS and nix-darwin configuration "carries over". For a host that keeps NixOS or nix-darwin this is passthrough. For a non-Nix host it is open how much carries: a NixOS option such as `services.caddy.enable` means whatever the NixOS module implements, and tendcf would have to reimplement it. A cheap, honest first scope is the supervisor-level options, which map almost one to one onto the service record: nix-darwin's `launchd.daemons..serviceConfig` and NixOS's `systemd.services.`. Higher-level `services.*` modules would need a ruling. +**Evidence:** guide:189-198; https://nix-darwin.github.io/nix-darwin/manual/ and https://mynixos.com/nix-darwin/option/launchd.agents.%3Cname%3E.serviceConfig ("Each attribute in this set specifies an option for a key in the plist"). +**Proposed text:** + +> What carries over from an existing NixOS or nix-darwin configuration to a +> host without Nix is, first, its supervisor-level service declarations: +> tendcf's Nix options for services use the names nix-darwin +> (`launchd.daemons.`) and NixOS (`systemd.services.`) already +> use, so those blocks move with no rewrite. Higher-level modules +> (`services..enable`) carry over only where tendcf supplies an +> implementation; an option it does not implement is a compile error that +> names it, never a silent no-op. + +**Ruled:** B7: "1. Importer + matching names" (`operator ruling, 2026-11-14, B7`): a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin/NixOS where the meaning is the same. Ruled; merged into the map's §5 and D49 (decision register) on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. G2 gets no new text (B13 item 7: B7 supplies the meaning). + +**Merge:** ruled (operator ruling, 2026-11-14, B7: "1. Importer + matching names") +**Checked:** verified (nix-darwin option via search results); NixOS option set not checked + +--- + +## §4 A compiler turns facts into CFEngine data + +### G-§4-01: Cut the third-party plugin entry points until someone asks + +**Target:** §4 "Name and home", at "Frontends and importers are found through Python entry points, so a third party can ship one as an ordinary package" +**Kind:** cut +**Goal:** G2, G8 +**Weight:** improves +**Finding:** Entry-point discovery, out-of-tree plugins, and importers from other tools (Ansible, Salt per plugin-layout) serve an ecosystem that does not exist. G2 names one frontend (Nix) with data beneath it. None of G8's three states needs a third-party frontend. The guide's own next paragraph says out-of-tree plugins cannot be pinned yet, so the release loads only in-tree ones anyway. +**Evidence:** guide:234-253; `docs/architecture/plugin-layout.md` (D46), via the plan-docs digest A3, E2; issue #47 (inventory D). +**Proposed text:** + +> Frontends, supervisor renderers and one-shot importers are plugins, and +> all of them live in tree. Plugins run only at compile time, never on a +> device. Discovery of out-of-tree plugins (Python entry points) is deferred +> until a user needs one and out-of-tree plugins can be pinned. + +**Ruled:** Smaller 5: "1. Defer out-of-tree discovery" (`operator ruling, 2026-11-14, Smaller 5, G-§4-01 / map Step 0 / v2 C3`): amend D46 with this item's text: all plugins in tree, compile-time only, never on a device; Python entry-point discovery is deferred until a user needs one and out-of-tree plugins can be pinned. The proposed text above is adopted as written. The same ruling covers the map's Step 0 (`03-response-map.md` M-§13-01, which does the D46 restructure as decided). Ruled; merged into the map's D46 amendment (§5 and decision register) on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** replace "Frontends, supervisor renderers and one-shot importers ... never on a device." Ruled (operator ruling, 2026-11-14, Smaller 5); amends D46. +**Checked:** verified (read §4); plugin-layout.md not re-read; independently checked 2026-11-13: confirmed + +### G-§4-02: The Mac is both the authoring machine and a managed device + +**Target:** §4, at "**Where it runs:** operator machine or CI." +**Kind:** add +**Goal:** G2, G5, G8 +**Weight:** improves +**Finding:** At G8 state 1 one Mac holds server roles, is managed, and is very likely where configuration is written. So it is both an authoring machine (Nix installed to evaluate) and a managed device (where §4 says Nix runs only as the host's configuration system). The text should say that Nix-as-authoring-tool on a managed Mac is allowed and is not passthrough. It should also say that the compile step on that Mac must not hold the release signing key. Checked on one of the operator's Macs: no `nix`, no nix-darwin, and Homebrew's upstream CFEngine 3.29.0, not the fork. +**Evidence:** guide:321-324, 248-252; `command -v nix` printed nothing; `/run/current-system` absent; `/opt/homebrew/bin/cf-agent --version` → `CFEngine Core 3.29.0`. +**Proposed text:** + +> A device may also be where configuration is written: the Mac that holds +> server roles is usually the author's own machine. Nix installed there to +> evaluate configuration is an authoring tool. It is not that Mac's +> configuration system, so the Mac is a managed, non-Nix host, not a +> passthrough one. The compile step on such a machine still holds no +> signing key (above). + +**Merge:** insert after "...(NixOS, nix-darwin)." +**Checked:** verified on this Mac (commands above); whether this is the Mac the operator means for state 1 is not checked; independently checked 2026-11-13: confirmed + +--- + +## §5 Every device runs its own agent + +### G-§5-01: Updates come from any peer that completes the handshake, not "synced via git" + +**Target:** §5, at "reads policy that arrived as part of the ordinary signed-release path, synced via git" +**Kind:** ruling-drift +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** G3 says a device accepts updates from *any other device* that completes the correct cryptographic handshake (diff 5). The guide names git as the sync channel and keeps push for "a host that currently holds a deploy role". TUF-style signing already makes the carrier irrelevant to authenticity, so any peer can relay. That is what G3 needs, but the guide never says it. "Handshake" is ambiguous: it could mean release-signature verification, peer mutual authentication, or both. That decides whether a stranger's device can relay, so it needs a ruling. +**Evidence:** guide:330-338; goal G3 and ruling 6b. +**Proposed text:** + +> Each computer runs CFEngine and converges on the last release it +> approved. A release reaches it from any other device: whichever peer has +> it can hand it over, and the device accepts it only after the +> cryptographic handshake [what the handshake covers is open: checking the +> release's signatures against the device's enrolled root (§7), +> authenticating the sending device against its peer allowlist (§14), or +> both — operator's ruling]. The carrier, whether a +> peer, a git remote or a file on a USB stick, adds no trust. There is no +> dedicated central policy host, no SSH requirement, and no requirement to +> push. + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): G3's handshake means content checks (signed by trusted keys, fresh, names this device, owner approval); transport auth decides only who may talk. The release is what is authenticated (not the sender). First build: SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter); the 2-of-3 offline-root floor may lag until TUF. Ruled; merged into the map's §9.11 ("The handshake is content checks (D50)") and D50 on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** replace the first paragraph of §5; ruled (operator ruling, 2026-11-14, B1): content checks +**Checked:** verified (read §5, §7, §14); independently checked 2026-11-13: confirmed + +### G-§5-02: "Its own `cf-serverd`" is true of neither live host, and may be the handshake + +**Target:** §5, at "Each computer runs CFEngine, including its own `cf-serverd`" +**Kind:** question +**Goal:** G3, G7 +**Weight:** misleads +**Finding:** The installer on pastebin installs and schedules `cf-execd` only. It does not mention `cf-serverd`. If cf-serverd stays in the design, it is the natural peer-to-peer carrier for G3: CFEngine's own protocol already does a key-based mutual-authentication handshake, through `cf-key` and `ppkeys`. That would cover the transport half of the handshake, with TUF signatures as the content half. Whether to use it is a G7 instrument ruling. +**Evidence:** `rg -n "serverd" deploy/linux/tendcf-install.sh` → no hits; guide:330. +**Proposed text:** + +> Each computer runs CFEngine. A device that relays releases to peers runs +> `cf-serverd` [whether the handshake includes peer authentication is open, +> operator's ruling; if it does, `cf-serverd`'s key-authenticated +> connection would be its transport half and the release's signatures (§7) +> its content half, neither substituting for the other]. (Today pastebin +> runs `cf-execd` only, and get.sipb.cloud schedules nothing.) + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`) answers what the handshake covers. Whether `cf-serverd` is the peer transport (G7) is not ruled by the 2026-11-14 rulings and stays open. + +**Merge:** needs the operator's ruling first (G7: is cf-serverd the peer transport; and what the handshake covers, ruled in G-§5-01: B1) +**Checked:** verified (grep of the installer); independently checked 2026-11-13: weakened, corrected + +### G-§5-03: Trim the supervisor list to what the platform order needs + +**Target:** §5, at "[Jobber](https://dshearer.github.io/jobber/), OpenRC / s6 / dinit when a real host needs one" +**Kind:** cut +**Goal:** G5 +**Weight:** nit +**Finding:** G5 needs launchd (macOS), runit through termux-services (Android), and systemd (Linux, which already exists). Jobber, OpenRC, s6 and dinit have no host in any G8 state. The guide already hedges them with "when a real host needs one". Dropping them from §2, §3 and §5 shrinks the claims that §4 has to label "still a design claim". +**Evidence:** guide:106, 170-172, 355-358, 276-280. +**Proposed text:** + +> [systemd](https://systemd.io/), launchd, and +> [runit](http://smarden.org/runit/) via +> [termux-services](https://github.com/termux/termux-services) on Android. +> Another supervisor is added when a real host needs one. + +**Merge:** replace the list in §5, and the same list in §2 and §3 "Services"/"Unit writers" +**Checked:** verified (read) + +--- + +## §6 Each device keeps its own record + +### G-§6-01: The log archive is a server service; the device stays the record + +**Target:** §6, at "A path to a fleet-wide view already exists and costs nothing new to stand up" +**Kind:** add +**Goal:** G3, G8 +**Weight:** blocks-goal +**Finding:** G8 state 1 requires logs archived on the Mac, and G3 names log archiving as the defining server service (diff 6). The guide has only a best-effort push into an observability stack and no archive role. Nothing in the guide conflicts with an archive, as long as it stays a copy. The guide should say that, name the role, and say how a mostly offline Android device feeds it. +**Evidence:** guide:409-417; goal G3, G8.1. +**Proposed text:** + +> **Log archive is a server service.** A device holding the `log-archive` +> role receives other devices' JSONL capture and keeps it. Each device ships +> its own lines when it can reach a holder, resumes from the last line the +> archive acknowledged, and keeps its local capture until then, so an +> archive that is asleep or unreachable costs delay, never history. The +> archive is a copy: the device's own capture stays the record of truth, +> and a question that needs a real yes or no is still asked of the device. +> Who may write into an archive is the archive host's peer allowlist (§14), +> and each line carries the release and the device key that produced it. + +**Merge:** insert before "A path to a fleet-wide view" +**Checked:** inferred (design text; nothing in the repo ships logs: inventory §A, no "jsonl" hits in code); independently checked 2026-11-13: confirmed + +### G-§6-02: Monitoring is a server service that reports "unknown", not "down" + +**Target:** §6, after G-§6-01 +**Kind:** add +**Goal:** G3 +**Weight:** improves +**Finding:** G3 names monitoring of other machines as the second server service. The guide's rule that unreachable devices are "unknown, not a stale aggregate" already fits a monitor, but it is written only for one-off fleet queries. For phones, which are routinely offline, a monitor that reports "down" would be wrong most of the time. +**Evidence:** guide:409-414; goal G3. +**Proposed text:** + +> **Monitoring is the other server service.** A device holding the +> `monitor` role shows, per device: last contact, the release it last +> reported converged, its extra-entry and `not-yet-migrated` counts, and +> any refusal outstanding. A device not heard from is shown as unknown since +> a time, never as down or as converged. + +**Merge:** insert after G-§6-01's paragraph +**Checked:** inferred + +### G-§6-03: Android section omits Island/Insular and ShizukuPlus, the differentiator + +**Target:** §6, at "**Android:** Termux (`com.termux`) and tendcf-agent are different UIDs." +**Kind:** add +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** G5 calls Android with Island/Insular work profiles and user-space ShizukuPlus the main differentiator. The guide and the architecture docs never mention Island, Insular or work profiles (searched). A work profile is a separate Android user, so the guide's UID reasoning applies once per profile: Termux, CFEngine and the agent may exist twice, and "the app list on this device" is two domains. The tool fork the repo has (`frdminc/ShizukuTendCF`) is a fork of ShizukuPlus. The guide still says "Shizuku". +**Evidence:** `rg -n "Island|Insular|work profile" docs/architecture/*.md` → no hits; guide:88-89, 396-402; https://github.com/thejaustin/ShizukuPlus; https://f-droid.org/packages/com.oasisfeng.island.fdroid/ ("Insular is a FLOSS fork of Island"); inventory §C (ShizukuTendCF "a fork of ShizukuPlus"). +**Proposed text:** + +> **Work profiles.** Android with [Island](https://island.oasisfeng.com/) +> or its free fork [Insular](https://github.com/proletarius101/Insular) +> runs a second Android user, the work profile, beside the personal one. +> Each profile is its own set of UIDs and its own app list, so each is its +> own set of domains in the Site Model (`android-apps@personal`, +> `android-apps@work`), and anything the agent does across the boundary goes +> through the profile owner's APIs, never by reading the other profile's +> storage. Privileged operations go through +> [ShizukuPlus](https://github.com/thejaustin/ShizukuPlus) running in user +> space (our fork, `frdminc/ShizukuTendCF`); where it cannot start itself, +> a peer starts it (§13). + +**Ruled:** B3 sub 1: "1. Field on entries" (`operator ruling, 2026-11-14, B3 sub 1`): one host per phone; each Android promise names its target user (owner/work/private) and the work profile's owner app (island/insular/none); an unreachable profile reports `not_kept`. B3 sub 3: "1. Never" (`operator ruling, 2026-11-14, B3 sub 3`): tendcf never holds a DPC slot (profile owner or device owner), works with Island/Insular through shell (`--user N`) and the owner app's API, and never requires MDM enrolment. B3: "3. Termux CFEngine + thin Kotlin" (`operator ruling, 2026-11-14, B3`). Ruled; the schema bump is pending (SCHEMA-TOUCHING). + +**Merge:** insert after the Android paragraph; the profile naming is ruled (operator ruling, 2026-11-14, B3 sub 1: a field on entries) +**Checked:** verified (grep; URLs from search; island.oasisfeng.com URL not fetched); independently checked 2026-11-13: confirmed + +--- + +## §7 Changes arrive as signed plans + +### G-§7-01: Add the safety-scoring layer, advisory and owner-side + +**Target:** §7, after the paragraph beginning "On top of the verifiable diff sits a *semantic* layer" +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4's confidence out of 100, the explanation, and the graded highlighting are absent from every document (diff 4). The guide already has the right slot: an advisory layer above the diff that "never authorizes". The new layer should follow the same rules. It should also be computed on the owner's side, against the diff the device computed. A score computed by the proposer is the same-party problem §17 names for the briefing. One consequence follows from §7's own "Emergency vs consent" rule: a score may tighten (refuse automatically below an owner-set floor, ruled "1. Allowed, off by default") but may never loosen (a high score never skips the owner's look). +**Evidence:** guide:562-573, 568-582, 1231-1246; goal G4. +**Proposed text:** + +> **Every diff is scanned for likely safety, and the owner sees the +> result.** Several scanners read the device-computed diff: fixed rules +> (a privileged region touched, a removal, a new command or listening +> port, a secret name newly bound, a `--simulate-json` effect outside the +> diff), and one or more AI reviewers chosen by the owner. They produce one +> **safety score from 0 to 100**, an explanation of each part of it and why +> that figure and not another, and a weight per entry that sets how +> dramatically it is highlighted. Like the briefing, the score **never +> authorizes**. It can only tighten. A fixed rule's finding sets a ceiling; +> an AI reviewer can lower the score, never raise it past a ceiling. The +> base is 95, so 100 is never shown; the values are fixed in the schema. +> **Owner-set floor.** An owner may set a floor, which is off by default +> (there is no default floor). A bundle whose score is below the floor is +> refused automatically, the refusal is logged, and the owner is notified +> with the diff. The floor only tightens: no score, however high, applies a +> diff the owner has not been shown, and no score ever accepts. The owner +> can re-request a refused bundle and accept it. The scan runs on the +> owner's side, against the diff the device computed, because a score the +> proposer computes is a claim the device cannot check. + +**Ruled:** B8 sub 2: "1. Allowed, off by default" (`operator ruling, 2026-11-14, B8 sub 2, G-§7-01 v2`): an owner may set a floor; a bundle below it is refused automatically, logged, and the owner notified with the diff; no default floor; tighten-only (no score ever auto-accepts); the owner can re-request and accept a refused bundle. B8: "1. Capped 0-100 score" (`operator ruling, 2026-11-14, B8`): "score from 0 to 100", mechanical checks set a ceiling that AI review can lower but never raise, an explanation of each part, and a measured hit rate once a corpus exists. B8 sub 1: "1. 09's table, top 95" (`operator ruling, 2026-11-14, B8 sub 1`): the cap values are in `03-response-map.md` M-§9-03. B8 sub 4: "2. Should not (as written)" (`operator ruling, 2026-11-14, B8 sub 4`), X-safety-06's text in `09-safety-score-and-tui.md`. The proposed text above is rewritten to carry the floor inside it. Ruled; merged into the map's §9.12 on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** insert after the semantic-layer paragraph. Ruled (operator ruling, 2026-11-14, B8, B8 sub 1, B8 sub 2, B8 sub 4). +**Checked:** inferred (design); verified that no document describes scoring (goal diff 4; grep for "TUI" in docs found only the goal file and deprecated tooling notes); independently checked 2026-11-13: confirmed + +### G-§7-02: "Operator: no local yes" conflicts with "the owner can see and refuse" + +**Target:** §7, at "where the device's tier requires a local yes (§14)"; also §4 "(An operator host applies without a local yes, so there the pull request's preview diff is the only human check.)" and the §14 table row "Consent" +**Kind:** ruling-drift +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 says *nothing* changes a device except as a difference its owner can see and refuse. The guide exempts operator-tier hosts, which are every device in G8 states 1 and 2, and lets the proposer's PR preview stand in for the device-computed diff. That preview is computed from the proposer's idea of the baseline, not the device's (§7's own seven-releases-behind argument). Either the operator tier also sees the device-computed diff (possibly once, on the Mac, for all his devices), or G4 has an operator exception. That is a ruling. +**Evidence:** guide:245-246, 444-450, 846; goal G4. +**Proposed text:** + +> Every device shows its owner the difference it computed itself, and +> applies nothing the owner refused. Tiers differ only in *where* and *how* +> that is done: on an `operator` device the owner may accept, from one +> place, the diffs every one of his devices computed, and the device checks +> that the acceptance names its own diff; on a `consented` device the yes is +> local, signed by the enrolled advisor key and bound to a nonce the device +> issued. + +**Ruled:** B2: "3 but also the existance of standing wait for user and standing refusal" (`operator ruling, 2026-11-14, B2`). The operator chose option 3, not option 1 (which this proposed text carries): a hold window, or an owner-enrolled standing approval, shown and refusable before apply, with a new approval-record shape without a per-change nonce (a schema bump), plus two further standing modes: a standing "wait for user" (hold until the owner answers) and a standing refusal. The `operator`-tier sentence above is therefore superseded as follows, and the `consented` sentence stands: + +> On an `operator` device the owner may enrol a hold window or a standing approval, shown and refusable before apply; may set a standing "wait for user" (the device holds a change until the owner answers); and may set a standing refusal. + +Ruled; the schema bump is pending (SCHEMA-TOUCHING: an approval record without a per-change nonce). Q19 in the map is answered (`03-response-map.md` M-§10-01). The new shape takes the next unused schema version (v7 or later; shipped v6 is C-policy-01, PR 52, 83d7280), ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. + +A reading of the ruling (L5, B2), not part of it (lead decision, PR 62 round-3 review): a standing approval drops only the per-change nonce (DC-2's device nonce); it is signed by an owner-held trusted key and keeps B1's other content checks (signed by trusted keys, fresh, names this device) and the rest of DC-2 (per-target validity, monotonic-counter single use or high-water mark, persisted rejects); its ceremony class is still checked against the validator's derived requirement (§9.8); until the operator rules, a standing approval covers `ordinary` changes only; whether one may cover `privileged` or `baseline` changes is for the schema design review to propose and the operator to rule; it names its signer and algorithm only if X-trust-06 is adopted (proposed, not ruled); every standing mode (hold window, standing approval, standing "wait for user", standing refusal) is owner-enrolled and refusable, and none is a default; dropping any other check needs an operator ruling; the schema design review confirms the approval-record shape. + +**Merge:** replace the §7 clause, the §4 parenthesis, and the §14 "Consent" row, using the ruled sentence above. Ruled (operator ruling, 2026-11-14, B2). +**Checked:** verified (read the three places); independently checked 2026-11-13: confirmed + +### G-§7-03: `--simulate-json` is on the fork today, and is a scanner input + +**Target:** §7, at "Both are offered and neither has merged, so today this remains a manual check." +**Kind:** correct +**Goal:** G4, G7 +**Weight:** misleads +**Finding:** "Offered and not merged" describes upstream. The operator ruled on 2026-08-22 that the fork is the destination, and Linux CI builds the full fork, `--simulate-json` series included. So the feature is available in the build tendcf uses. Under G4 it becomes one of the "several ways" a diff is scanned: effects the run would make that the diff does not describe. +**Evidence:** guide:584-592; plan-docs digest B3 (`upstream-overlay.md:50-56`; `linux-targets.md:23-27`); inventory §E ("`tendcf-integration` is fork master plus every fix branch plus the `--simulate-json` series"). +**Proposed text:** + +> Both are in the fork tendcf builds (§19) and neither is upstream. Nothing +> calls them yet; when something does, a simulated change set that reaches +> beyond the approved diff is one of the safety scanners' findings (below). + +**Merge:** replace that sentence +**Checked:** verified from the digests' citations; fork branch not inspected; independently checked 2026-11-13: confirmed + +--- + +## §8 The person's own AI + +### G-§8-01: The owner is usually also the proposer + +**Target:** §8, at "We never run their model, see their prompt, or see the conversation. We offer a change and accept a signed yes/no." +**Kind:** reword +**Goal:** G1, G4 +**Weight:** misleads +**Finding:** §8 assumes two parties: "we" propose, "they" consent. G1 puts the person in charge of their own devices, working through their own AI or the code. In G8 states 1 and 3 the owner proposes changes to their own devices. In that case the AI that writes the change and the AI that warns are both the owner's, and the person to protect against is mostly the owner's own mistaken or manipulated agent. The two-party case (a household member's device) still exists, as the `consented` tier. +**Evidence:** guide:596-624, 835-849; goal G1, ruling 1. +**Proposed text:** + +> Usually the person who owns a device is also the person changing it. +> They say what they want, to their AI or in the code; their AI writes the +> configuration, and explains or warns when a request looks unwise. The +> device then shows them the exact difference, scored (§7), and applies it +> only if they accept. When someone else proposes the change, to a device +> on the `consented` tier, the shape is the same, and we still never run +> their model, see their prompt, or see the conversation: we offer a change +> and accept a signed yes/no, the same shape as a Kubernetes admission +> webhook. + +**Merge:** replace the first paragraph of §8 +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### G-§8-02: The review surface: command line and TUI + +**Target:** §8, at "None of this surface is built yet (§18)." +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 requires both a command-line mode and a TUI mode, with the TUI built on a scaffold borrowed from another project. The guide describes no surface at all. Since the compiler and the projector are Python, a Python TUI framework would keep one language. [Textual](https://textual.textualize.io/) is the obvious Python candidate and Ratatui the Rust one. Which project to borrow from is the operator's call. Highlighting "more dramatically" must not rely on colour alone. +**Evidence:** guide:624; goal G4; https://www.michaelblaess.de/en/blog/tui-vergleich/ (Ratatui, Textual, Terminal.Gui compared). +**Proposed text:** + +> The owner reviews a diff in one of two modes, which show the same thing: +> a command-line mode that prints the scored diff and takes `accept` or +> `refuse`, for scripts, SSH and an AI driving it; and a TUI, built on a +> scaffold borrowed from [named project], for reading a large diff with +> the questionable entries highlighted. Highlighting escalates in more than +> colour (weight, markers, ordering the least safe entries first, and +> requiring a keypress per entry below a threshold), so it survives a +> monochrome terminal and colour-blindness. None of this surface is built +> yet (§18). + +**Ruled:** B12: "2. Borrow both freely; raise Python" (`operator ruling, 2026-11-14, B12`): borrow Toad and textual-diff-view (AGPL-3.0) as needed; the review TUI becomes AGPL-3.0-only and moves to Python >=3.14. B3 sub 4: "1. Native screen + Termux" (`operator ruling, 2026-11-14, B3 sub 4, X-safety-08 / X-android-14`): one review document (R14) rendered three ways (CLI `--plain`/`--json`, Textual TUI including Termux and SSH, native screen in `tendcf-agent`); goldens hold all three; renderers compute nothing; the agent notification opens the native screen with Accept and Refuse; the Termux CLI/TUI is the operator's path; no answer means held; a refusal is logged. Ruled; merged into the map's §6 ("Review TUI borrows (B12)") and §12 ("Phone review surface") on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** replace "None of this surface is built yet (§18)."; the scaffold is ruled (operator ruling, 2026-11-14, B12) +**Checked:** not checked (which scaffold); Textual URL not fetched; independently checked 2026-11-13: confirmed + +### G-§8-03: Personal branches are where G9 starts + +**Target:** §8, at "Personal branch: theirs, applied under their consent; never auto-merges into anyone else's trust domain. Upstream-heal is a suggestion their agent evaluates." +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** G9 (diff 8) asks for branch management built on the platform's existing patch patterns. The repo already has one: `overlay/` with `bin/overlay.py`, which keeps patches against a pinned upstream with lint, drift and retirement checks. That is "keep a fork without merging" in mechanical form, and the CFEngine fork is its first user. The guide never connects personal branches to it. +**Evidence:** guide:620-622, 1333-1338; inventory §E (overlay: 6 patches, weekly drift check). +**Proposed text:** + +> A personal branch is kept the way this project keeps its own CFEngine +> changes (`overlay/`, §18): as a set of named patches against a pinned +> upstream, each checked for drift when upstream moves and retired when +> upstream absorbs it. Later (§18, after the finish line) the same pattern +> becomes a tool a person with no technical skill can use, through their +> AI, to keep a fork of a project or of a plugin to one. + +**Merge:** insert after "Upstream-heal is a suggestion their agent evaluates." +**Checked:** verified (read §18 bullet and inventory); independently checked 2026-11-13: confirmed + +--- + +## §9 The writing rule + +### G-§9-01: The premise is fixed; the writing rule is a hypothesis about serving it + +**Target:** §9, at "The rule is a working hypothesis, not a law. §20 asks what would count against it." +**Kind:** reword +**Goal:** G6 +**Weight:** improves +**Finding:** Under G6 AI authorship is the premise, and §9 should say so before it says what remains open. What stays a hypothesis is the *rule*: that local-knowledge designs are how to make AI authorship safe. That distinction is consistent with G6 and keeps §20 Q1 and Q2 legitimate. +**Evidence:** guide:630, 671-672; goal G6. +**Proposed text:** + +> That AI agents write the configuration is the premise of the project, not +> something it sets out to test. The writing rule is a working hypothesis +> about how to make that premise safe, not a law; §20 asks what would count +> against it, and a counter-example changes the rule, not the premise. + +**Merge:** replace those two sentences +**Checked:** verified (read) + +--- + +## §10 Ordering without a shared to-do list + +### G-§10-01: Take inference off the path to the finish line + +**Target:** §10, at "The primary authoring mechanism is `provides` / `requires`" +**Kind:** cut +**Goal:** G8 +**Weight:** improves +**Finding:** The guide itself doubts inference (§10's three ways it may fail; §20 Q1 and Q7), and the compiler marks it "NOT implemented". State 1 has a handful of services on two devices. Retry-until-stable plus explicit `depends_on` is enough, and `provides`/`requires` can stay as data that the conflict check and lookup use. Deferring inference removes a stage, the two-platform gate and its edge-origin machinery from every G8 state. +**Evidence:** guide:689-693, 701-723, 1533-1536, 1553-1554; `compiler/nix2cf/compile.py:11-22` (inventory §A: inference "NOT implemented"). +**Proposed text:** + +> Retry-until-stable is the substrate, and explicit `depends_on` wins +> where it exists. Records still state what they `provide` and `require`, +> because the conflict check and the lookup (§15) read them, but the +> compiler does not derive ordering edges from them until a real site shows +> retry-until-stable is not enough. Inference is demand-driven (§18). + +**Ruled:** B4 rider, D16: "1. Defer explicitly" (`operator ruling, 2026-11-14, B4 rider, D16`): record D16's ordering inference as deferred. Ruled; merged into the map's D16 amendment (decision register) on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** replace "This design uses all three ... seen the rest of the system."; needs the operator's ruling (G7: compiler scope) +**Checked:** verified (read §10, inventory); independently checked 2026-11-13: confirmed + +--- + +## §13 Peer actions + +### G-§13-01: Starting ShizukuPlus over ADB is on the path to state 1 + +**Target:** §13, at "a device that cannot start its privileged helper itself; any healthy peer in its allowlist may do it over ADB" +**Kind:** add +**Goal:** G5, G8 +**Weight:** improves +**Finding:** The guide's own example is the Android client's helper. Under G5 and G8 state 1 that example stops being an illustration and becomes a requirement: the Mac is the healthy peer, and ShizukuPlus is the helper. Non-root Shizuku-family helpers have to be started over ADB or wireless debugging after a reboot. The fork adds headless start/stop/status broadcasts and boot retry, which narrows the cases a peer must cover. The peer-action runtime is "nothing" in code today, so it belongs in the state-1 build order, not in "10+". +**Evidence:** guide:809-821; inventory §C (ShizukuTendCF features), §H ("Peer actions | nothing"); Shizuku's need for ADB after reboot comes from its own setup guide (https://shizuku.rikka.app/guide/setup/): for the wireless-debugging start, "the startup steps need to be performed again after each reboot"; a rooted start is different (read 2026-11-13). +**Proposed text:** + +> This is the first peer action tendcf will run. On an Android device +> without root, the privileged helper (ShizukuPlus, our fork) is started +> over ADB or wireless debugging, and after a reboot it may not be able to +> start itself; the device declares `start-helper` as a peer action, and the +> Mac holding the `helper` role does it. If no peer is reachable, only that +> device waits, and it reports why. + +**Merge:** insert after the first paragraph of §13 +**Checked:** verified (Shizuku start mechanics read in its setup guide 2026-11-13); independently checked 2026-11-13: confirmed; sources re-fetched 2026-11-13: confirmed + +--- + +## §14 Per-device trust + +### G-§14-01: Separate "who may relay" from "who may sign" + +**Target:** §14, the table, after the "Release" row +**Kind:** add +**Goal:** G3 +**Weight:** improves +**Finding:** G3's "any other device" makes the carrier of a release a separate question from its author. The table has "Release: whose signatures may change me" and "Peer: who may act on me" but no row for who may hand over a release or receive logs. Without one, a reader can take "Peer: nobody unless listed" to mean that only listed peers may relay, which contradicts G3. Follows G-§5-01. +**Evidence:** guide:843-849. +**Proposed text:** + +> | **Relay** | Who may hand me a release, or take my logs? | Release: [any device, if the handshake checks the release and not the carrier; only listed devices, if it also authenticates the sender: open, operator's ruling (G-§5-01)]. Logs: holders of the `log-archive` role on my allowlist | + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): content checks, so "who may relay" is any device and "who may sign" is the trusted keys; transport auth decides only who may talk. Ruled; merged into the map's §9.11 and D50 on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** insert after the "Release" row +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +--- + +## §16 Three walkthroughs + +### G-§16-01: "The compiler's render stage does not exist yet" is false since `buildfile` + +**Target:** §16 intro, at "the compiler's render stage does not exist yet, so nothing in those two except the YAML was produced mechanically" +**Kind:** correct +**Goal:** G2 +**Weight:** misleads +**Finding:** §4 and §18 say `buildfile` renders a goal file (launchd services, JCS bytes), and the projector produces `host_specific.json` from it. So the guide contradicts itself. What is still hand-authored in A is the edge list (no inference) and the `preview_*` nesting. In B, the CFEngine sketch is hand-authored, since the real bundle is generic. +**Evidence:** guide:891-895 vs guide:303-305, 1342-1347; inventory §A (`render_goal_file` compile.py L463). +**Proposed text:** + +> In **A** and **B** the outputs are hand-authored. Some of their shapes are +> now emitted by code: the compiler renders the goal file, +> `bin/projector.py` its projection, and the generic bundle the launchd +> plist. But nothing derives ordering edges (§10), and B's per-bundle +> promise sketch is illustrative: the generic bundle, not per-bundle +> CFEngine text, enforces interlocks (§16.C). + +**Merge:** replace that sentence +**Checked:** verified (read guide and inventory); independently checked 2026-11-13: weakened, corrected + +### G-§16-02: §16.C says "launchd-only"; the bundle has had systemd since 2026-10-31 + +**Target:** §16.C, at "It is **launchd-only**, and since 2026-10-29 it says so instead of pretending otherwise" +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** §4 and §18 report the systemd branch (2026-10-31), and the bundle's first line reads "launchd on darwin, systemd on Linux". §16.C still calls the bundle launchd-only. The flavour guard now refuses runit and NixOS-shaped hosts. +**Evidence:** guide:1163-1167 vs guide:273-280, 1329-1332; `policy/tendcf_services.cf:1,48-50`. +**Proposed text:** + +> It actuates **launchd on darwin and systemd on Linux only**, and says so +> instead of pretending otherwise: an entry of any other flavour (runit +> today), or a host whose `/etc/systemd/system` is a Nix store symlink, is +> refused and reported by name (the flavour guard). + +**Merge:** replace that sentence +**Checked:** verified (grep of the bundle); independently checked 2026-11-13: confirmed + +### G-§16-03: The interlock section omits the known container-drop fail-open + +**Target:** §16.C, at "dry-run stays fail-closed because a check that never ran defines nothing" +**Kind:** add +**Goal:** G4 +**Weight:** misleads +**Finding:** §16.C presents the interlock as fail-closed. The validate proposal records a fail-open that applies to pastebin today: if the CMDB loader installs `tendcf_service` but drops `tendcf_interlock`, every service runs ungated. Two open PRs address it (#41, the fail-closed loader on the fork; #42, a policy cross-check). Under G4 this belongs in the one section that claims a demonstrated safety mechanism. +**Evidence:** `docs/architecture/tendcf-validate-proposal-2026-11-03.md:1017-1030`; inventory §D (#41, #42 open). +**Proposed text:** + +> One path is still open, and it fails open: if CFEngine's loader installs +> the services container but drops the interlock container, the bundle sees +> no interlock and runs every service ungated. No known input does this +> today. Two fixes are open: a fail-closed loader in the fork +> ([#41](https://github.com/frdminc/tendcf/pull/41)) and a policy check +> that refuses to act when the loaded data differs from the file +> ([#42](https://github.com/frdminc/tendcf/pull/42)). + +**Status, 2026-11-14 (the proposed text above was written when both PRs were open):** both are merged, #42 at acec5b5 and #41 at daa4530, so "Two fixes are open" no longer holds; the paragraph would say that both fixes have merged, with the remaining fork-pin follow-ups tracked in `upstream-register.md`. + +**Merge:** insert after "...defines nothing." +**Checked:** verified (read proposal §13); PR state from the inventory, not re-queried; independently checked 2026-11-13: confirmed + +### G-§16-04: Show walkthrough A's input in Nix + +**Target:** §16.A, the YAML block beginning "- name: caddy" +**Kind:** add +**Goal:** G2 +**Weight:** improves +**Finding:** Under G2 the reader should see the authoring language first and the YAML as what it evaluates to. A short Nix module for `caddy`, shown beside the existing YAML as its evaluation, makes the G2 claim concrete. Here it is a target shape, labelled as such, because the module frontend is unbuilt. +**Evidence:** guide:905-941. +**Proposed text:** + +> ```nix +> # ILLUSTRATIVE — the Nix module frontend is not built (§3) +> { ... }: { +> tendcf.services.caddy = { +> bundle = "edge-http"; +> runsAs = "djbclark"; +> command = [ "/opt/homebrew/bin/caddy" "run" "--config" "/etc/caddy/Caddyfile" ]; +> launchd = { label = "com.djbclark.caddy"; runAtLoad = true; keepAlive = true; }; +> provides = [ "port:443" "port:80" ]; +> requires = [ "path:/etc/caddy/Caddyfile" "service:tailscaled" ]; +> }; +> } +> ``` +> +> It evaluates to the YAML below, which is also what a person writes who +> does not use Nix. + +**Merge:** insert before the YAML block; the option names depend on G-§3-02 +**Checked:** not checked (not evaluated; illustrative) + +--- + +## §17 Where a different design is a better fit + +### G-§17-01: "The part the implementer map's §0 calls the point" + +**Target:** §17 intro, at "the part the implementer map's §0 calls the point" +**Kind:** ruling-drift +**Goal:** G1, G4 +**Weight:** misleads +**Finding:** Diff 3: the map's orientation section, item 3, says "The trust/consent layer is the point". G1 makes adoption the aim, and G4 makes see-and-refuse the safety mechanism serving it. The sentence should point at the goal, and the map's orientation section, item 3, should change too (see the M-series response). +**Evidence:** guide:1189-1195; map:37-39. +**Proposed text:** + +> The rest bound the see-and-refuse layer — the part with no prior art, +> the safety mechanism the goal (G4) rests adoption on, and the part with +> the most to lose. + +**Ruled:** Smaller 3: "1. Yes, supersede D8's wording" (`operator ruling, 2026-11-14, Smaller 3`): D47 is ruled; adoption is the aim and G4 see-and-refuse is its safety mechanism; it supersedes D8 "Sovereignty is the point" and §0 items 1 and 3. Ruled; merged into the map's D47 and D8 (decision register) on 2026-11-14 (the rulings commit of this PR); this guide's own text is not otherwise rewritten. + +**Merge:** replace that clause; the map §0 item 3 change is ruled (operator ruling, 2026-11-14, Smaller 3) +**Checked:** verified (read both); independently checked 2026-11-13: confirmed + +### G-§17-02: The consent-gate limit mostly dissolves when the owner is the proposer + +**Target:** §17, bullet beginning "**The consent gate does not yet mean what §8 says it means" +**Kind:** reword +**Goal:** G1, G4 +**Weight:** improves +**Finding:** The limit is that every control is authored by the party it constrains. On a device whose owner is also the proposer (G1, G8 states 1 and 3), that party *is* the owner. The control's job is then to protect the owner from their own agent, and an owner-authored trust policy is correct. The limit still holds in full for the `consented` tier. Say which case it binds, so the limit is not read as fatal to the main use. +**Evidence:** guide:1231-1246; goal G1. +**Proposed text:** + +> **On a device the proposer does not own, the consent gate does not yet +> mean what §8 says it means.** (On a device whose owner writes its +> configuration, the usual case, the party the controls constrain is the +> owner's own agent, and owner-authored controls are what is wanted; the +> limit there is the next-but-two, the compromised authoring agent.) ... + +**Merge:** replace the bullet's first sentence; the rest of the bullet stands +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### G-§17-03: The one-operator signing limit is answered by "one owner per site" + +**Target:** §17, bullet beginning "**The signing model is sized for one operator and §1 promises more than one.**" +**Kind:** reword +**Goal:** G1, G3 +**Weight:** improves +**Finding:** With §1 replaced (G-§1-01), §1 no longer promises several operators. Each adopter is the one owner of their own site, which is the shape the signing model fits. The limit remains for a household where two people sign for one site. +**Evidence:** guide:1257-1261, 47-52. +**Proposed text:** + +> - **The signing model is sized for one owner per site.** That fits the +> goal: each adopter runs their own site. The limit is the second person +> who must sign releases for the *same* site without the first's key — +> a household sharing devices — which needs threshold signing, +> delegation, per-role scoping and co-signer revocation. That is a +> different trust architecture, not triggered by anything §1 promises. + +**Merge:** replace the bullet +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### G-§17-04: The compromised authoring agent is now the main threat, and G4 is a partial answer + +**Target:** §17, bullet beginning "**The threat model outgrows this design at the compromised authoring agent.**" +**Kind:** reword +**Goal:** G4, G6 +**Weight:** improves +**Finding:** Under G6, AI authorship is certain, so a manipulated authoring agent is the ordinary threat, not an outer limit. G4's independent scanners (fixed rules plus an AI the owner chose, different from the one that wrote the change) are a step toward the "two-party authoring review" this bullet says the design lacks. The bullet should credit that and keep what still stands: a scanner shares the reviewer's blind spots, and a score is not a proof. +**Evidence:** guide:1269-1276. +**Proposed text:** + +> ... is inside every control described here. The safety scan (§7) is the +> design's partial answer: rules that do not read prose, and an AI reviewer +> the owner chose, separate from the one that wrote the change. It narrows +> the gap and does not close it — two models can share a blind spot, and a +> crafted diff can be written to read as safe. Past that point the answer is +> an independent party reproducing the release from the Site Model, or +> n-of-m sign-off — neither of which is this design. + +**Merge:** replace from "is inside every control described here." to the end of the bullet +**Checked:** verified (read) + +### G-§17-05: The "AI-authorship premise" bullet: keep one side + +**Target:** §17, bullet beginning "**The AI-authorship premise bounds the design from both sides.**" +**Kind:** reword +**Goal:** G6 +**Weight:** improves +**Finding:** Consistent with G6 in substance, because the bullet bounds the *scaffolding*, not the premise. But "§20 asks this as a question" points at Q9, which as written asks whether "the whole premise" is the wrong shape. Reword both so that the premise is fixed and the defence is in question. The "worse than assumed" half is the live one, and G4's scanners and differential runs are its answer. +**Evidence:** guide:1283-1290, 1562-1565. +**Proposed text:** + +> - **AI authorship is the premise; what it bounds is the defence.** If +> agents become reliable over long contexts, the local-knowledge +> scaffolding is unnecessary and an ordinary catalog compiler wins. If +> they are worse than assumed — fluent, schema-conformant and +> semantically wrong — types are the wrong defence, and what is needed is +> the review-and-test loop: the safety scan (§7), property tests over +> rendered output, differential runs against the previous release. + +**Merge:** replace the bullet +**Checked:** verified (read) + +### G-§17-06: New limit: a score invites the rubber stamp it exists to prevent + +**Target:** §17, append to "The trust and consent layer" +**Kind:** add +**Goal:** G4 +**Weight:** improves +**Finding:** A visible "97%" on every routine release trains an owner to stop reading, which is the failure §20 Q10–Q11 describe, now with a number attached. The limit should be stated with something measurable, in the section's own style. +**Evidence:** guide:1566-1581; goal G4. +**Proposed text:** + +> - **A confidence figure can become the thing that is approved.** Once +> most diffs score high, a person reads the number and not the diff, and +> the scan becomes the authority it was designed never to be. The +> mitigation is structural — privileged regions and removals always need +> their own keypress, whatever the score — but whether people read past a +> high score is an observation, not a design. Measure time spent per +> accepted diff against its score, and how often a diff later reverted had +> scored above 90%. + +**Merge:** insert as the last bullet of "The trust and consent layer" +**Checked:** inferred + +### G-§17-07: Local-first reporting: G3's archive is the middle path + +**Target:** §17, bullet beginning "**Local-first reporting stops paying for itself" +**Kind:** reword +**Goal:** G3 +**Weight:** nit +**Finding:** The bullet offers only two shapes: per-device records, or a central statistics spine. G3's archive server (G-§6-01) is a third: a central copy fed by devices, never the record. The bullet should name it as the step before the spine. +**Evidence:** guide:1199-1208. +**Proposed text:** + +> ... the honest fix is a central statistics spine (the shape Bcfg2 already +> builds). The log archive (§6) is the step before it: it answers "what did +> device X report" without asking device X, but not "did the rollout land", +> which still needs the device. + +**Merge:** replace "the honest fix is a central statistics spine (the shape Bcfg2 already builds), not a federation layer retrofitted onto a local-first design." +**Checked:** verified (read) + +--- + +## §18 What is built, and what is next + +### G-§18-01: "Built today" omits the Linux work and the prototypes + +**Target:** §18 "Built today" +**Kind:** correct +**Goal:** G5, G8 +**Weight:** misleads +**Finding:** The list leaves out the pieces the new build order reuses most. These are: Linux CI building the pinned fork and running the bundle as root on three Ubuntu VMs and a `debian:13` container; the root installer and runbook (`deploy/linux/`); the enforced canary and its schema check; the read-only unit-namespace classifier (186 tests, not wired); the compiler's `eval-nix` and its NixOS service-free render; and the fact that macOS has no CI. +**Evidence:** inventory §A, §F; `CLAUDE.md` "Verifying policy and the CFEngine build"; guide:1296-1347. +**Proposed text:** + +> - **A root-owned Linux install** (`deploy/linux/tendcf-install.sh`, a +> runbook, and a canary goal file whose projection CI keeps +> byte-identical): the fork at `/opt/tendcf`, a root `cf-execd`, one +> canary service enforced on one operator host. +> - **CI that builds the pinned fork** and runs the bundle against it as +> root on ubuntu-24.04, 26.04 and 24.04-arm and a `debian:13` container, +> including the systemd lifecycle and the refusal on a NixOS-shaped host. +> There is no macOS CI: the launchd branch is tested on a Mac development +> build only. +> - **A read-only unit-namespace classifier** (`bin/unit_classifier.py`), +> the prototype of the extra-entry detector for Debian units; not wired +> into the bundle. +> - In the compiler, `nix2cf eval-nix`, which evaluates a plain Nix +> attribute set to Site Model JSON (not the module frontend), and a +> NixOS host rendered with no services. + +**Merge:** insert after the overlay bullet +**Checked:** verified (inventory with file references; CI not re-run); independently checked 2026-11-13: confirmed + +### G-§18-02: Replace the build order with one ordered by G8's states + +**Target:** §18 "Build order from here", the table and the two paragraphs after it +**Kind:** correct +**Goal:** G5, G8 (also G2, G3, G4) +**Weight:** blocks-goal +**Finding:** The table is the order from before 2026-10-29: macOS adapter, then Android, compiler, Linux, signing at Step 6 and consent at Step 9. It does not record D22's Android deferral, which the map's table does. G8 state 1 needs four things the table puts late or nowhere: signing with the handshake (Step 6), the device-side validator with see-and-refuse (Steps 6 and 9), the log archive (absent), and safety scoring (absent). It also needs two the table never schedules: the Nix module frontend and Android profiles. Below is a replacement ordered by state, with the reuse named per step. What the Linux work is worth: the root-install pattern, fork CI, the run.sh harness, the projector, the canary and the validate proposal all carry to macOS and Android almost unchanged. The systemd branch, schema v4/v5's dpkg claims, the unit classifier and the NixOS passthrough come later in the order, in state 2 (Steps 12–13; not paused, B4 rider "1. Order language"), where they are needed as built. Nothing is thrown away. +**Evidence:** guide:1359-1379; inventory §A, §C, §F, §H; goal G5, G8; `docs/architecture/PREMORTEM-BRIEF.md:20` (the Mac is a laptop that sleeps). +**Proposed text:** + +> **Build order from here**, by the three states of the finish line (§1). +> Each step leaves a coherent, describable system. +> +> *State 1: one Mac (server) and one Android device (client).* +> +> | Step | What | Reuses | +> | --- | --- | --- | +> | 0 | **Close the open work, and restructure.** Merge #42, then #41 (after their reviews; historical: both merged 2026-11-14, #42 at acec5b5 and #41 at daa4530); the D46 restructure (`tendcf compile`, `plugins/`), with all plugins in tree, compile-time only, never on a device (Python entry-point discovery deferred); the schema additions that have been ruled, at the next unused schema version (v7 or later; shipped v6 is C-policy-01, PR 52, 83d7280): the Android profile fields and the agent id share one bump (B3 sub 1), and whether the standing-modes approval record joins it is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. | PRs #41 and #42; `plugin-layout.md` (D46). | +> | 1 | **The fork on the Mac.** Build the pinned fork for macOS arm64 into `/opt/tendcf`, with a macOS CI job that builds the pin and runs `tests/policy/run.sh`; a root `cf-execd` under launchd on the state-1 Mac, which is a minimised macOS VM on bigmac (tart / Virtualization.framework); one canary launchd service enforced, everything else not yet named. bigmac itself runs dry-run only, as a user LaunchAgent. State 1 verifies the root launchd render path. | `overlay/fork.json` and the CI build action; `tendcf-install.sh` and the canary pattern, ported from systemd to launchd; the launchd branch of `policy/tendcf_services.cf`; `tests/policy/run.sh`. | +> | 2 | **Nix authoring, minimal.** A module system (`lib.evalModules`) with tendcf options for services, interlocks and roles, named after nix-darwin where one exists, evaluating to today's Site Model JSON; YAML twins stay as fixtures and must be byte-identical. | `nix2cf eval-nix`; `buildfile` (renamed `tendcf compile`); the schemas and lint unchanged. | +> | 3 | **`tendcf-validate`, first build.** Stored, integrity-checked baseline; the device computes the diff; the command-line review mode shows it and takes accept or refuse (a CLI diff and `y/N`, built first and used on the VM and dev devices before any TUI or score work); projection only after accept. Operator tier. | `bin/projector.py` (promoted, D45); `apply_diff` and `derive_ceremony_class` from `bin/schema_lint.py`; goal-diff and approval-record schemas; the validate proposal's options for trigger and atomic publication, which are platform-neutral. | +> | 4 | **Signed releases and the handshake.** The handshake is content checks (signed by trusted keys, fresh, names this device, owner approval); the first build is the SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter), and the TUF subset of §7 follows, with the 2-of-3 offline-root floor allowed to lag until then; any device may relay a release; the device verifies it before step 3 sees it. | `change-process.md` (lockfile, release, rollback, gates); `bin/overlay.py`'s pinning discipline. | +> | 5 | **Android client.** CFEngine in Termux fed tendcf projections; runit services via termux-services (a third bundle branch); the single Python `tendcf-validate` in Termux, with the Kotlin agent re-checking signature and high-water mark and keeping the trust anchor and approval record in app-private storage; Island/Insular work profiles as a field on entries, one host per phone; ShizukuPlus as the helper; the review is a native screen opened from the agent notification, with Termux CLI/TUI as the operator's path. | The `termux` flavour already in `services.schema.json` and the `android-termux-services` fixture; `frdminc/ShizukuTendCF`; the golden projections, which the Kotlin port must match (D45). | +> | 6 | **Peer actions and the archive.** The Mac starts ShizukuPlus over ADB when the phone cannot (§13); JSONL capture on both devices; the Mac's `log-archive` role (the `monitor` role is state 2), a service record rendered through launchd, with a fleet-wide SQLite index over every device while each device keeps its own index; the phone buffers while the Mac sleeps. | `report-row.schema.json`; the roles schema (`{main, backups[], peers[]}`). | +> | 7 | **Safety scan, then the TUI.** Fixed-rule scanners and an owner-chosen AI reviewer over the device-computed diff; the score, its explanation, graded highlighting; then the TUI on the borrowed scaffold (Toad and textual-diff-view). G4 stays whole in state 1. | The privileged-path list and ceremony classes already in the schemas; the fork's `--simulate-json`. | +> +> **State 1 is reached** when the Mac and the phone each converge from a +> Nix-authored site, each refuses a release that fails the handshake and a +> diff its owner refused, and both devices' logs are in the Mac's archive. +> State 1 is declared only once the score, explanation, highlighting and +> TUI (Step 7) have landed. There is no "state 1.5". +> +> *State 2: the whole fleet, and the old stack retired.* +> +> | Step | What | Reuses | +> | --- | --- | --- | +> | 8 | Pull: every device self-updates from any peer; roles move by editing data; the `monitor` role (state 2). | Steps 3–4. | +> | 9 | macOS as client: the other Macs. | Steps 1–3. | +> | 10 | Extra-entry reporting per domain, so the `not-yet-migrated` count measures what is left. | `bin/unit_classifier.py` and the s5 detector design (Debian units); new detectors for launchd and the Android app list. | +> | 11 | Migrate the old stack's services one domain at a time, then retire it. | Everything above. | +> | 12 | Linux as server: the existing Debian host, from canary to full. | The systemd branch, schema v5 package claims, the root installer, Linux CI. | +> | 13 | Linux as client, and NixOS/nix-darwin hosts as passthrough. | The NixOS refusal and passthrough stages already run on get.sipb.cloud. | +> +> *State 3: a stranger installs it from the public docs with their own AI.* +> +> | Step | What | +> | --- | --- | +> | 14 | The publishable layer extracted; install and first-run root ceremony a person with no admin skill can complete; the default advisor prompt; public documentation written for that person and their AI. | +> | 15 | The `consented` tier, for a device someone else proposes changes to. | +> +> *Later, demand-driven:* free-software branch management built on +> `overlay/` (§8, G9); ordering inference (§10; deferred explicitly); +> the builder/cache; reproducible APK provenance; web-of-trust as advisor +> tools; out-of-tree plugins (Python entry-point discovery). +> +> Linux is later in the order (Steps 12 and 13), not paused, and the +> pastebin canary stays the standing end-to-end proof. On bigmac, the +> daily driver, dry-run is the standing posture: tendcf computes and +> reports the diff, logs drift and applies nothing; the macOS VM is the only +> enforcing Mac in state 1. Reporting ("what changed, what is dirty, what release am I +> on") is an adoption requirement, not an observability extra. + +**Differences from the other proposal** (the map response's build order, M-§13-01, as corrected after checking; from the independent checker's comparison; the two proposals are kept separate so the owner can choose): +1. **First step.** Here the fork on the Mac comes first (1) and Nix authoring second (2); the map has the Nix frontend first and the Mac second. The checker notes the Mac today runs Homebrew upstream CFEngine 3.29.0 with the §19 data-path defects, which slightly favours the fork first; the two steps are otherwise independent. +2. **Step 0.** The map adds a Step 0: merge #41 and #42 (done 2026-11-14), the D46 restructure, and the ruled schema changes (the next unused version, v7 or later; grouping not ruled; the schema design review decides, operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"; see the table's Step 0). The proposal as first written had no schema step; the ruled order folds the map's Step 0 in (B4). The checker notes #41 and #42 touch only platform-neutral files, so they close the interlock fail-open on the Mac too. +3. **Validator and signing.** Here the validator (3) precedes signing and the handshake (4), flagged for a ruling. The map, as corrected, has the validator (3), owner review (4), then signed releases with signature and high-water verification (5). +4. **Safety scan and TUI.** Here all scanning, rules and AI, plus the TUI, is Step 7 inside state 1. The map has mechanical scanning and the CLI at Step 4 and the AI scanner and TUI at Step 8 ("1→2"), so its state 1 ships a partial G4. Ruled: B8 sub 3 "1. Build order, not scope" (`operator ruling, 2026-11-14`): G4 stays whole in state 1; the CLI diff and `y/N` is built first and used on the VM and dev devices before any TUI or score work; state 1 is declared only once score, explanation, highlighting and TUI land; no "state 1.5". +5. **Owner signature.** The map has an owner key sign at Step 4 (supersedes D39, needs that ruling); this Step 3 takes accept or refuse with no key specified. +6. **Peer actions.** Here ShizukuPlus start-over-ADB is a state-1 step (6); the map has no peer-action step. +7. **Monitoring.** Here the `monitor` role is in state 1 (Step 6); the map has it at Step 9, in state 2, which matches G8.1's literal text (log archive only). Ruled: "1. State 2" (`operator ruling, 2026-11-14, B4 rider, monitor role`): state 1 needs only the log archive (G8.1); the proposed table above moves `monitor` to state 2. +8. **Extra-entry reporting.** Here a separate step (10) with launchd and Android detectors precedes migration (11); the map has only the Linux unit-writer detector before retiring the old stack. +9. **Linux.** Both now keep G5's order 4 then 5 (here Steps 12 and 13; the map, as corrected, 10 and 10b). The map moves nix-darwin passthrough to its Step 9. +10. **Inference.** Both defer it with a ruling flagged: here to "Later" (G-§10-01), in the map, as corrected, to "13+ Demand". Ruled: "1. Defer explicitly" (`operator ruling, 2026-11-14, B4 rider, D16`): D16's ordering inference is recorded as deferred. +11. **macOS CI.** The map names a macOS CI job (ruling) in Step 2; this Step 1 says only "the CI build action" and leaves CI to Idea 6. Ruled: the ruled order folds in an explicit macOS CI step (B4); the table above now names it in Step 1. +12. **State 3.** Here the publishable layer and a root ceremony a novice can complete (14), then the `consented` tier (15); the map has public docs, the authoring guide, first non-operator enrolment, the TUF emergency role and advisor delegation. Complementary; the map's emergency-role deferral is a ruling this proposal does not make. +13. **When state 1 is reached.** Here each device must refuse both a release failing the handshake and a diff its owner refused; the map requires refusing an unsigned or unhandshaken update in a test. The checker finds this test closer to G4. +14. **Plugins.** The map's Step 0 does the D46 restructure as decided; G-§4-01 here cuts out-of-tree entry points (amends D46). One ruling covers both: "1. Defer out-of-tree discovery" (`operator ruling, 2026-11-14, Smaller 5`). + +**Ruled:** B4: "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`): adopt draft D47-D50 as corrected (M-§15-01..04), with this guide's build order as base "with the map's Step 0 and an explicit macOS CI step folded in". The proposed table above is rewritten accordingly (Step 0, the macOS CI step in Step 1) and is the adopted order. Riders, each dated 2026-11-14: Linux "1. Order language" (later in the order, not paused); canary "1. Keep it" (the pastebin canary stays the standing end-to-end proof); Nix on the release path "2. Allow on release path" with scope "1. Build-time only"; monitor role "1. State 2"; D16 "1. Defer explicitly". Rulings applied in the table: B8 sub 3 "1. Build order, not scope" (Steps 3, 7 and the state-1 test); B6 sub 1, sub 2 and sub 3 (Step 1: macOS VM on bigmac, dry-run only on bigmac, root daemon in the VM); B3 "3. Termux CFEngine + thin Kotlin" with sub 1 "1. Field on entries" and sub 2 "1. Termux + Kotlin trust check" (Step 5); B1 "1. Content checks; v0 first" (Step 4); Smaller 5 "1. Defer out-of-tree discovery" (Step 0); Smaller 6 "make that both" (Step 6). This supersedes D22 and the 2026-10-29 Linux-first ruling (`linux-targets.md`) and defers D16's inference. The question of whether signing (step 4) may follow the validator (step 3) is settled by the adopted order. Ruled; the map's §13 carries the adopted order as its stage table (2026-11-14, the rulings commit of this PR; `03-response-map.md` M-§13-01), and this guide's §18 original is not rewritten. Numbering: this table's Steps 0-15 and the map's Stages 0-16 are the same order. The map splits the macOS CI job out of Step 1 as its own Stage 2, so guide Step 0 and Step 1 are map Stage 0 and Stage 1, guide Steps 2-15 are map Stages 3-16 (Step N is Stage N+1), and "Step 8" or "Steps 3 and 7" in the other review documents use this guide numbering unless they say "Stage". Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): the VM may enforce early as an explicit, ruled exception like pastebin's: canary only, operator-authored data (its root `cf-execd` enforcement at the stage 1 / guide Step 1 VM stands as an exception to D45's "`tendcf-validate` before any further host is enforced"). The order is not changed. + +**Merge:** replace the section with the ruled table. Ruled (operator ruling, 2026-11-14, B4). +**Checked:** reuse claims verified against the inventory; feasibility of a macOS fork build and of CFEngine under Termux in a work profile not checked; independently checked 2026-11-13: weakened, corrected + +### G-§18-03: Step 4's distro default is Ubuntu; the first live host is Debian + +**Target:** §18 table, Step 4, "Ubuntu Server is the working default." +**Kind:** correct +**Goal:** G5 +**Weight:** nit +**Finding:** The only live Linux host is Debian 13, schema v5's package claims are dpkg-specific, and CI's root install runs on Ubuntu and Debian. Under the replacement (G-§18-02) the question moves to Step 12. If the old table stays, correct it. +**Evidence:** guide:1368; `docs/architecture/linux-targets.md:11-12`. +**Proposed text:** + +> | 4 | Linux reference path | A stock distro, not NixOS. The first live host is Debian 13 and the package claims are dpkg's; another family needs a schema bump. | + +**Merge:** replace the row (moot if G-§18-02 is merged) +**Checked:** verified (read) + +--- + +## §19 What we found underneath + +### G-§19-01: "This design bets everything on one thing": the instrument is open to challenge + +**Target:** §19, at "This design bets everything on one thing" +**Kind:** reword +**Goal:** G7 +**Weight:** improves +**Finding:** G7 makes CFEngine, the fork and the compile-to-Augments shape instruments, open to challenge. "Bets everything" frames the instrument as the project. The same section's costs (a permanent fork, time not spent building) are exactly the evidence an instrument challenge would weigh, so the opening should invite that challenge, not foreclose it. +**Evidence:** guide:1385-1390, 1469-1482; goal G7. +**Proposed text:** + +> The current instruments rest on one choice: that the right place to put +> a compiler's output is CFEngine's own JSON data layer, so the policy text +> stays generic and every site-specific fact arrives as data (§4). That +> choice is open to challenge, and changes only by the operator's ruling; +> what follows is the evidence any challenge would start from. + +**Merge:** replace the first paragraph's first sentence +**Checked:** verified (read) + +### G-§19-02: Move the upstream narrative out of the current-state guide + +**Target:** §19, subsections "Who wrote the fixes" and the upstream-history paragraphs +**Kind:** cut +**Goal:** G8 +**Weight:** improves +**Finding:** The front matter says the guide "does not recount how the design was reached", yet §19 runs about 140 lines of the August upstream episode. That story already lives in `upstream-register.md`. For a G8 state-3 reader, what matters is that tendcf ships against a patched fork, why, and what it costs. A 20-line §19 with a link keeps that and shrinks the guide by about 8%. +**Evidence:** guide:3-6, 1383-1525. +**Proposed text:** + +> tendcf runs on a fork of CFEngine (§18, `overlay/`). Pushing a whole +> site's facts through `def.json` and `host_specific.json` found ten +> defects in that data path — three of them stop a run before any promise +> is evaluated, dropping the host to failsafe, on input a correct compiler produces — and the fixes, each +> with a test shown to fail without it, live on the fork. Upstream declined +> the batch on review volume, not on substance. The cost is a fork to +> maintain; the record is [`upstream-register.md`](../architecture/upstream-register.md). + +**Merge:** replace §19 except "One last thing, and it cuts against §9", which stays; needs the operator's ruling (the paper keeps the long form) +**Checked:** verified (read); independently checked 2026-11-13: weakened, corrected + +--- + +## §20 Open questions + +### G-§20-01: Q9 asks about "the whole premise"; under G6 it asks about the defence + +**Target:** §20 Q9, "**Is the whole premise the wrong shape?**" +**Kind:** reword +**Goal:** G6 +**Weight:** improves +**Finding:** Diff 9. The question's substance, whether schemas defend the right wall, is legitimate under G6. Its title puts the premise in doubt. Q2 stands as written (it is about the rule). +**Evidence:** guide:1562-1565. +**Proposed text:** + +> 9. **Are the schemas defending the wrong wall?** The design hardens the +> surface where a machine author lacks global context. If the real +> weakness is plausible-looking output that type systems do not catch, +> the weight belongs on the safety scan and on testing rendered output +> (§7, §17), and the schemas are defending the wrong wall. + +**Merge:** replace Q9 +**Checked:** verified (read) + +### G-§20-02: Which questions the goal answers, which stand + +**Target:** §20, the list as a whole +**Kind:** add +**Goal:** G1–G9 +**Weight:** improves +**Finding:** Status of the existing 16 against the goal: +1. Q5 and Q6 (local-first) are **partly answered** by G3: the archive and monitor roles give a central copy that is not the record. +2. Q12 (does refusing cost the proposer) and Q15 (can the consent gate mean what it says) **narrow** to the `consented` tier once the owner is the usual proposer (G-§8-01, G-§17-02). +3. Q1 and Q7 (inference) **leave the critical path** if G-§10-01 is ruled. +4. Q2, Q3, Q4, Q8, Q10, Q11, Q13, Q14 and Q16 **stand**. Q10 and Q11 become sharper under G4, because a score now sits on top of the diff. Q13 (the baseline) is a state-1 blocker for Android. +5. Q9 is reworded (G-§20-01). +**Evidence:** guide:1533-1615. +**Proposed text:** + +> After the goal of 2026-11-13: questions 5 and 6 are partly answered by the +> archive and monitoring roles (§6); 12 and 15 bind only the `consented` +> tier, since an owner usually proposes their own changes (§8); 1 and 7 +> are off the path to the finish line while inference is deferred (§10). +> The rest stand, and 13 must be answered for Android before the first +> state of the finish line is reached. + +**Merge:** insert before question 1 +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### G-§20-03: New questions from G3 (peer updates, servers) + +**Target:** §20, append +**Kind:** add +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** G3 raises at least four open design questions that the guide does not ask: what the handshake authenticates; how an offline phone and a sleeping Mac meet; what happens to the archive when its only holder is lost; and whether a relaying peer can withhold releases (freeze) even though it cannot forge them. Mark them open; they gate state 1. +**Evidence:** goal G3, G8.1; (guide:550-552: the high-water mark rejects replay, freeze and downgrade; whether freeze detection works for a device that hears from one intermittent relay is the open part); `docs/architecture/PREMORTEM-BRIEF.md:20`. +**Proposed text:** + +> 17. **What does the handshake authenticate?** The release's signatures, +> the sending device, or both — and so whether a device outside the +> site may carry a release at all. +> 18. **How do a phone that is mostly offline and a laptop that sleeps +> meet?** The server is a role on a machine that is often unreachable; +> the archive and the relay have to work in the windows both are awake, +> and a client has to say how long it has gone unheard from. +> 19. **What survives losing the only server?** If the one Mac holding +> `log-archive` is lost, the devices still hold their own records; what +> has to be true for a second holder to take the role from data alone? +> 20. **Can a relay freeze a device by withholding?** A peer cannot forge a +> release, but if it is the only one a device hears from, it can stop +> passing them on. Freeze detection (§7) needs a clock or a second path. + +**Merge:** insert after question 16 +**Checked:** inferred; independently checked 2026-11-13: weakened, corrected + +### G-§20-04: New questions from G4 (score, highlighting, CLI and TUI) + +**Target:** §20, append +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** The score needs calibration and a defence against a diff written to manipulate the AI scanner. Configuration carries free text (descriptions, comments, command strings) that an AI reads as instructions. The explanation must not be AI-only either. Mark these open. +**Evidence:** goal G4; guide:1049-1062 (interlock `description` is free text inside the Site Model). +**Proposed text:** + +> 21. **What does 80% mean?** A confidence figure is only useful if it is +> calibrated: of diffs scored 80%, roughly how many turn out unsafe. +> Until there is a record to calibrate against, the figure is a ranking, +> and should say so. +> 22. **Can the diff talk the scanner round?** Descriptions, comments and +> command strings are text an AI scanner reads; a change can carry +> "this is a routine, safe update" inside itself. The AI scanner must +> read the diff as data, and its verdict can only lower the score a +> fixed rule allows (§7) — whether that is enough is untested. +> 23. **Does the explanation hold without AI?** If the owner's AI is +> unavailable, the fixed rules alone must still produce a score and a +> reason; how much lower that score is, and whether the owner can +> still accept, is open. +> 24. **Do the command-line and TUI modes stay equal?** An AI driving the +> command line must get everything the TUI shows a person, or the two +> modes are two different consent experiences. + +**Merge:** insert after question 20 +**Checked:** inferred; independently checked 2026-11-13: confirmed + +### G-§20-05: New questions from G1, G8.3 and G9 + +**Target:** §20, append +**Kind:** add +**Goal:** G1, G8, G9 +**Weight:** improves +**Finding:** The 2-of-3 offline root (§7), which the front matter makes a floor, is a key ceremony no person without admin skill will complete unaided. That collides with G1's long-run user and G8 state 3. G9 raises its own question: what a non-technical user does when an overlay patch stops applying. +**Evidence:** guide:9-12, 547-560; goal G1, G8.3, G9. +**Proposed text:** + +> 25. **Can a person with no admin skill hold the root?** The release root +> is offline and 2-of-3. For one owner of one site, what form of that +> ceremony can someone complete with only their AI's help, without +> relaxing the floor — or does the floor change for single-owner sites? +> 26. **What does a non-technical person do when their patch stops +> applying?** Branch management (§18, later) keeps a fork as patches +> against upstream. When upstream moves and a patch conflicts, the +> person's AI has to explain it and propose a fix they can refuse — +> the same see-and-refuse loop, applied to source rather than state. + +**Merge:** insert after question 24; question 25 needs the operator's ruling on whether the map's floor applies to single-owner sites +**Checked:** verified (read the floor statement); independently checked 2026-11-13: confirmed + +--- + +## Nits + +| ID | Where | Finding | Proposed fix | +|---|---|---|---| +| G-§0-03 | front matter "Prepared 2026-08-14; re-checked against the repository 2026-08-18." | Text carries 2026-11-13 edits; the date line is three months stale. | "Prepared 2026-08-14; last re-checked against the repository 2026-11-13." | +| G-§1-02 | §1 "Android devices reached through [Termux]" | Termux is one of three Android parts; G5 names ShizukuPlus and Island/Insular. | Covered by G-§1-01. | +| G-§2-02 | §2 "tool forks (optional) sudo-secretspec, Shizuku, …" | The fork is of ShizukuPlus (`frdminc/ShizukuTendCF`), and under G5 it is not optional for Android. | "ShizukuPlus (our fork, required on Android), sudo-secretspec, …" | +| G-§12-01 | §12 "This is the one mechanism in this guide that has been demonstrated" | The systemd lifecycle and tombstone teardown are also demonstrated (CI, pastebin). | "This is the one Site Model mechanism shown refusing for real;" | +| G-§18-04 | §18 Step 2, no "Deferred" | Map §13 Step 2 says Deferred (2026-10-29); the guide does not. Under G5 the guide is accidentally right and the map is wrong. | Fix the map, not the guide (M-series). | +| G-§18-05 | §18 Step 3 "Inference waits until types exist on two platforms." | Map Step 3 says "needs step 1 and a Linux systemd adapter"; both exist now, so the gate reads as open. | Moot under G-§10-01; otherwise "Types now exist for launchd and systemd." | +| G-§18-06 | §18 Step 6 note | Omits the map's "tendcf-validate built after schema v5 lands and before any further host is enforced" (map:1164); v5 landed 2026-11-02, validate is unbuilt. | Add the sentence, with "not yet built (2026-11-13)". | +| G-§map-01 | map §12 "First host: vps-primary." | linux-targets says vps-primary is not in the first milestone, and stage C ran on get.sipb.cloud. | M-series. | +| G-§map-02 | map §0 item 2 "reference target is a stock Linux distro" | Contradicts G5 (macOS first) as well as G2. | M-series. | +| G-§FR-01 | Further reading | No entry for Island/Insular, Shizuku/ShizukuPlus or nix-darwin, which the new §1, §3 and §6 lean on. | Add the three URLs from the items above. | + +## Ideas and risks + +1. **The server is a laptop.** The predecessor's named failure was "the control node was a Mac that sleeps", and the live Mac is a MacBook Air (`PREMORTEM-BRIEF.md:20`). G3's wording protects convergence. But the archive, relay and ShizukuPlus restart in state 1 all depend on the Mac being awake, so every server service must be designed around missed windows from day one, not retrofitted. +2. **Compute the score where the owner is.** A safety score computed by the proposer's pipeline repeats the §17 same-party problem with a number attached. Running the scanners against the device-computed diff, with an AI the owner chose, is what makes G4 more than display. +3. **Prompt injection through config text.** Free-text fields (descriptions, commands, comments in Nix) reach the AI scanner. The rule "AI may only lower the score below what fixed rules allow" is cheap and should be in the first scoring build, not added after an incident. +4. **Borrow nix-darwin's option names.** Using `launchd.daemons.` and `systemd.services.` as tendcf's service options would make "existing configs carry over" (G2) literally true for the supervisor layer at almost no cost. It also gives the first adopters (Nix sysadmins) something familiar on day one. +5. **CFEngine's own handshake may be most of G3.** cf-serverd already does key-authenticated peer connections. Pairing it with TUF signatures (transport plus content) could deliver "updates from any device with the handshake" without writing a transport. This is a G7 ruling, but cheap to evaluate. +6. **The Mac runs upstream CFEngine, not the fork.** The checked Mac has Homebrew CFEngine 3.29.0, which still carries the data-path crashes §19 lists (null in `host_specific.json` and the rest, per the guide). There is no macOS CI. State 1 Step 1 needs a macOS fork build and some macOS test leg, which the CI policy reserves for explicit request, so the operator should rule on it early. +7. **Android in a work profile doubles everything.** Termux, CFEngine, the agent and the record may be needed once per profile, with cross-profile actions only through the profile owner. Prototyping CFEngine under Termux inside an Insular profile before writing the Android adapter would surface the hard limits cheaply. +8. **Let the overlay be G9's first customer.** `bin/overlay.py` already does pinned patches, drift checks and retirement for the CFEngine fork. Generalising it for the operator's own forks (ShizukuTendCF, the CFEngine fork) before any non-technical user exists tests G9's core on real forks at no product cost. +9. **The guide is written for reviewers, not adopters.** Its voice, length and Bcfg2 lineage serve a reviewer like Desai, while G8 state 3 needs public docs a stranger's AI can follow. Plan a separate, short adopter document instead of growing the guide. Measure the guide's line count, because the docs-to-code ratio (240 of 398 non-merge commits docs-only) is the risk the 2026-08 pre-mortem named. +10. **Re-sequence before more Linux depth.** Open work today (PRs #41 and #42, the s5 detector, the validate picklist) is mostly Linux-specific. Without a ruling on G-§18-02, the next weeks will likely keep deepening platform 4 while platforms 1 and 2 have no code. Parking the Debian-only items explicitly would make the reorder real. + +Last search run: exempt: review of a given document; searches run at the start are listed under "Prior art / docs checked". + +Not checked: live hosts (no SSH); CI not re-run; no test or build run; PR #41/#42 state taken from the inventory; the fork branch contents; the Shizuku reboot/ADB behaviour against its docs; whether the Mac checked here is the one meant for state 1; CFEngine under Termux in a work profile; the map beyond §0–§2 and §12–§13; plugin-layout.md, change-process.md and linux-targets.md beyond cited lines. + +Counts: 45 full items plus 10 table nits; see the header for counts after checking. + +## Withdrawn after checking + +None. The independent checker refuted no item in this document. diff --git a/docs/review-2026-11-13/03-response-map.md b/docs/review-2026-11-13/03-response-map.md new file mode 100644 index 0000000..e13348b --- /dev/null +++ b/docs/review-2026-11-13/03-response-map.md @@ -0,0 +1,992 @@ +# Response: implementer map against the 2026-11-13 goal + +Target: `docs/architecture/architecture-DEFINITIVE-v3.md` (1,346 lines, read in full) + +Base commit: eefea3c + +How this was produced: one reviewing agent (Claude Opus), then an independent checking agent that tried to refute each finding; nothing was executed unless an item says so. + +Item counts by Weight after corrections: 48 full items and 10 table nits; blocks-goal 21, misleads 13, improves 13, nit 11 (1 full, 10 in the table). One change from checking: M-§2-05 moved from blocks-goal to misleads. Checking: 42 items checked (24 confirmed, 18 weakened and corrected, 0 withdrawn); the other 6 full items and the nit table were not sampled and stand as written. + +**Goal:** `docs/review-2026-11-13/00-goal-definition.md` G1–G9 +**Reviewer:** Opus 5.5 high, read-only. Line numbers below are at `eefea3c` and are evidence only; anchors are quoted phrases. + +Sources consulted: firecrawl search "Textual Python TUI framework" (found Textualize/textual, a Python TUI framework that also runs in a browser); firecrawl search "Insular Island work profile Shizuku device owner" (F-Droid: Insular needs device-admin to create its work profile); Basic Memory `books` + `book-kb query 'trustkeysfrom|ppkeys'` (Learning CFEngine ch. 33: cf-serverd trusts keys by address via `trustkeysfrom`). + +--- + +## §0 Orientation + +### M-§0-01: "The trust/consent layer is the point" no longer states the aim + +**Target:** `architecture-DEFINITIVE-v3.md` §0 "Orientation for the AI that implements this", item 3, at "The trust/consent layer is the point." +**Kind:** ruling-drift +**Goal:** G1, G4, G8 +**Weight:** misleads +**Finding:** The aim is now an adoptable tool that gives people control of their own devices, used through an AI or directly (G1). See-and-refuse is the safety mechanism (G4), not the point. An implementer who reads item 3 first will keep ranking consent work above convergence. G8 gives the implementer a measurable target, and the map has none. +**Evidence:** map:37-39; goal-definition:96-102 (difference 3, difference 7). +**Proposed text:** + +> 3. **The aim is an adoptable tool that gives people control of their own devices** (goal G1, [`../review-2026-11-13/00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md)). A person works through their own AI or directly in code, whichever they prefer at the moment. The safety mechanism is see-and-refuse (G4): nothing changes a device except as an exact, mechanically checked difference that its owner can see and refuse. Measure every step against the finish line (G8). State 1 comes first: one Mac and one Android device converge from Nix-authored config, accept updates only after the handshake, and archive logs on the Mac. + +**Ruled:** D47 is ruled: "1. Yes, supersede D8's wording" (`operator ruling, 2026-11-14, Smaller 3, M-§15-01`). Adoption is the aim, and G4 see-and-refuse is its safety mechanism; D47 supersedes D8 "Sovereignty is the point" and §0 items 1 and 3. + +**Merge:** replace that item. Ruled (operator ruling, 2026-11-14, Smaller 3, M-§15-01). +**Checked:** verified (read map §0 and the goal file); independently checked 2026-11-13: weakened, corrected + +### M-§0-02: "Interesting and correct beats minimal and safe" conflicts with G1 and G4 + +**Target:** §0 item 1, at "This is a freedom project. Interesting and correct beats minimal and safe" +**Kind:** reword +**Goal:** G1, G4 +**Weight:** misleads +**Finding:** Read literally, "minimal and safe" losing to "interesting" sits badly with G4 for a tool strangers adopt, though the maxim was about design ambition, not device safety. "Token spend is the cost that matters (§13)" points to a section that never mentions tokens. The pointer "(§13)" has no token text; §14 "Premium-token residue" is probably what was meant. It also contradicts the 2026-10-31 standing rule that getting tendcf right outranks cost. +**Evidence:** map:28-30; map:1152-1176 (no token text); `CLAUDE.md` "Standing rule: most important work" (2026-10-31). +**Proposed text:** + +> 1. **This is free software for people who want control of their own devices.** Correct beats interesting; when correct and safe conflict, stop and ask (item 5). Development cost is secondary to getting it right (operator, 2026-10-31). A user's own AI token cost at run time is a design constraint (R12). + +**Ruled:** "1. Adopt the proposed text" (`operator ruling, 2026-11-14, Smaller 2, M-§0-02`). The proposed text above replaces §0 item 1 as written; it is no longer a proposal. Ruled; merged into the map's §0 item 1 on 2026-11-14 (the rulings commit of this PR). + +**Merge:** replace §0 item 1 with the proposed text. Ruled (operator ruling, 2026-11-14, Smaller 2); it rewrites an operator principle and the operator has approved the rewrite. +**Checked:** verified (grep of §13 for "token": no hit); independently checked 2026-11-13: weakened, corrected + +### M-§0-03: The reference target is now macOS, and the distro is de facto Debian + +**Target:** §0 item 2, at "The reference target is a stock Linux distro on bare metal" +**Kind:** ruling-drift +**Goal:** G5, G2 +**Weight:** misleads +**Finding:** G5 puts macOS first, Android second and Linux fourth and fifth. "Ubuntu Server LTS is the working default; the distro name is open until Step 4" is also stale. The first live Linux host is Debian 13, and schema v5 is dpkg-specific. "One of two equal Site Model authoring languages" contradicts G2's Nix-first rule. +**Evidence:** map:31-36; digest-current-plan C1, D2; goal-definition:39-45. +**Proposed text:** + +> 2. **Platforms come in the order of goal G5:** macOS as server, Android as client, macOS as client, Linux as server, Linux as client. Nix is the authoring language (real Nix, NixOS-style options; G2), with plain YAML/JSON beneath it as the data form Nix evaluates to. Nix is used verbatim on hosts that already run NixOS or nix-darwin, and is never the installed OS a stranger must adopt. The first Linux host is Debian 13 (pastebin); a Linux distro default is chosen when Linux becomes the current platform. + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`): D48 and D49 are adopted as corrected (M-§15-02, M-§15-03). Linux is later in the order, not paused: "1. Order language" (`operator ruling, 2026-11-14, B4 rider, Linux`). + +**Merge:** replace that item. Ruled (operator ruling, 2026-11-14, B4). +**Checked:** verified (map and digest); independently checked 2026-11-13: confirmed + +--- + +## §1 The architecture in one screen + +### M-§1-01: The diagram lacks peer delivery, service roles and the owner's review surface + +**Target:** §1, the diagram from "Signed release" to "JSONL log (capture)" +**Kind:** add +**Goal:** G3, G4, G8 +**Weight:** improves +**Finding:** The diagram runs one way, from compile to device. G3's "accepts updates from any other device" and G8's "logs archived on the Mac" have no box. Neither does G4's owner-facing scan and CLI/TUI, so the parts the owner actually touches are invisible. +**Evidence:** map:55-96. +**Proposed text** (insert between "Signed release" and "CFEngine +"): + +> ``` +> ▼ delivered by any peer that completes the handshake (G3; +> │ what it covers is open, §16 Q17); delivery never authorizes +> Owner review device-computed diff, scanned (rules + AI): +> (CLI or TUI) confidence /100, explanation, graded +> highlighting; owner signs accept or refuses +> ``` +> +> and after "SQLite (index)": +> +> ``` +> ▼ shipped to a peer that provides the service +> Service roles log archive, monitoring (a "server" is any +> ("servers", G3) device holding such a role; not a control node) +> ``` + +**Merge:** insert after it. The handshake is ruled (operator ruling, 2026-11-14, B1: content checks; "1. Content checks; v0 first"). +**Checked:** verified (read the diagram) + +--- + +## §2 Requirements + +### M-§2-01: R2, R3, R11 and the license clause of R10 are confirmed + +**Target:** §2, R2 "No permanent control node", R3 "Resource efficiency", R11 "Preserve", and R7/R10 "Generic layer publishable (GPL-3.0-or-later for code)" +**Kind:** question +**Goal:** G3, G1 +**Weight:** nit +**Finding:** G3 restates R2 more strongly, and R3 is untouched. R11 holds, except that its "observability stack as optional sink" is extended by R15 (M-§2-11). GPL-3.0-or-later satisfies G1 and G9's "stays free software". There is no text change except a pointer. +**Evidence:** map:109-112, 118-122. +**Proposed text:** + +> **R2** No permanent control node; every device converges on its own (G3). Feature roles `{main, backups[], peers[]}` are data. + +**Merge:** replace R2's first sentence +**Checked:** verified + +### M-§2-02: R1 targets: reorder for G5 and add work profiles + +**Target:** §2, R1, at "Targets: macOS/Apple Silicon, Linux x86_64, Linux aarch64, Android" +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** The list order reads as priority and puts Android last. G5 makes Android the differentiator and requires it to work with Island/Insular work profiles. R1 says nothing about profiles. +**Evidence:** map:105-108; goal-definition:47-49. +**Proposed text:** + +> - **R1** Targets, in build order (G5): macOS/Apple Silicon as server, Android as client (every user profile, including Island/Insular work profiles), macOS as client, Linux x86_64 and aarch64 as server, then as client. Intel Mac mini out of scope. tendcf-agent is Android-only; macOS and Linux run CFEngine plus the `tendcf-validate` command, with no daemon (D45). + +**Merge:** replace R1. Ruled (operator ruling, 2026-11-14, B4, "1. Adopt D47-D50": D48 adopted). +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§2-03: R4 Android: user-space ShizukuPlus, no device-owner + +**Target:** §2, R4, at "Android keeps Termux (+api, +x11), the built-in Terminal app, a Shizuku-class helper" +**Kind:** add +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** G5's differentiator is user-space ShizukuPlus working with Island/Insular. Insular needs the device-admin/profile-owner slot to create its work profile. So tendcf must never take the device-owner slot, a rule the 2026-08-13 session recorded ("`dpm set-device-owner` is a hard no") that never reached the map. The helper is now a known fork, `frdminc/ShizukuTendCF`, a ShizukuPlus fork. +**Evidence:** map:113-115; `docs/handoffs/HANDOFF_standalone-3fd9_nix2cf-split-communal-orchestration_2026-08-13_601f.md:218-219, :350`; https://f-droid.org/en/packages/com.oasisfeng.island.fdroid/ ("Device administrator privilege is required to create the Insular space (work profile)"); inventory C (ShizukuTendCF). +**Proposed text:** + +> - **R4** Android keeps Termux (+api, +x11), the built-in Terminal app, user-space ShizukuPlus (our fork `frdminc/ShizukuTendCF`), tendcf-agent (Kotlin, D45) and CFEngine. tendcf never takes the device-owner slot, which Island/Insular need (operator, 2026-08-13: "`dpm set-device-owner` is a hard no"); [whether this extends to the profile-owner slot: operator's ruling]; it works in every user profile as an ordinary app plus Shizuku. No nix-on-droid. Nix may build zero-on-device-footprint artifacts only. + +**Merge:** replace R4. The profile-owner extension is ruled: "1. Never" (operator ruling, 2026-11-14, B3 sub 3): tendcf never holds a DPC slot (profile owner or device owner), and never requires MDM enrolment. +**Checked:** verified (handoff lines and F-Droid page excerpt); not checked: whether ShizukuPlus can act on a work profile's packages without root; independently checked 2026-11-13: weakened, corrected + +### M-§2-04: R5 "No bare-metal Nix ... stock distro is the reference" needs rescoping + +**Target:** §2, R5, at "No bare-metal Nix. A mainstream stock distro is the reference." +**Kind:** reword +**Goal:** G2, G5 +**Weight:** misleads +**Finding:** With macOS first, "the reference" is no longer a Linux distro. "No bare-metal Nix" coexists with two NixOS target hosts (passthrough) and with Nix-first authoring, so it needs to say what it forbids: requiring a stranger to install NixOS. +**Evidence:** map:116-117; digest-current-plan D3. +**Proposed text:** + +> - **R5** tendcf never requires NixOS as the installed OS. Hosts already on NixOS or nix-darwin keep that configuration verbatim (passthrough, D12). On Linux, a mainstream stock distro is the target; Debian 13 is the first live host. Nix may be required to build a release (build time only): a device never needs Nix at run time. + +**Ruled:** "2. Allow on release path" (`operator ruling, 2026-11-14, B4 rider, Nix on release path`): Nix may be required to build a release. Scope: "1. Build-time only" (same rider, 2026-11-14): devices never need Nix at run time. This amends R5 and D6 here, and change-process §2 "Nix is an optional builder" (see `04-response-plans.md` PL-§2-02 and X-CO-02). The last sentence of the proposed R5 text above is the amendment; D6 ("Nix on bare metal: No. Builds / dev shells / authoring language / passthrough ...") is amended the same way: the build and authoring uses may be a requirement of building a release, and Nix is still never needed on a device at run time. Ruled; merged on 2026-11-14 (the rulings commit of this PR): the map's R5 and D6 and change-process §2 carry the amendment. The rest of this item's older wording is not otherwise rewritten. + +**Merge:** replace R5; amend D6 and change-process §2 to match. Ruled (operator ruling, 2026-11-14, B4 rider, Nix on release path). +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§2-05: R7/R10 "auto-review" lets an AI accept without the owner seeing + +**Target:** §2, R7/R10, at "Pull becomes user sovereignty: the person's own AI, suggested default prompt plus their extras, auto-review or a conversation." +**Kind:** ruling-drift +**Goal:** G4, G3 +**Weight:** misleads +**Finding:** G4 says the owner can see and refuse every difference. Auto-review is a mode the person chooses, not a default. In it the person's AI signs the yes, so a change can apply that the owner never saw; whether an owner-chosen delegation satisfies G4 is the ruling. G3 also makes delivery peer-to-peer ("from any other device"), not just push or pull. +**Evidence:** map:118-120, 963; goal-definition:31-37. +**Proposed text:** + +> - **R7 / R10** Push, pull and peer delivery: a device accepts a release from any device that completes the handshake (G3, R14). The owner sees every difference and may refuse it (R16). The owner's own AI explains and warns, but does not accept on the owner's behalf unless the owner has chosen that explicitly, per device, and can revoke it. Generic layer publishable (GPL-3.0-or-later for code). + +**Merge:** replace R7/R10. Needs the operator's ruling first: whether any AI-only accept mode survives G4. +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### M-§2-06: R12 "Token budget is real" should mean the user's run-time cost + +**Target:** §2, R12, at "Token budget is real. Design so routine work is cheap." +**Kind:** reword +**Goal:** G1, G4 +**Weight:** improves +**Finding:** For development, the 2026-10-31 ruling lifted cost. For adoption (G1), though, every change is scanned by AI (G4), and a person with no admin skill pays for that. R12 is more important than before, but it now concerns run time. +**Evidence:** map:123; `CLAUDE.md` standing rule 2026-10-31. +**Proposed text:** + +> - **R12** A user's AI cost per change is a design constraint: authoring and the G4 safety scan must be cheap enough for routine changes on a personal budget. Mechanical scanners run first, and AI scanning sees only the device-computed diff and what it cites, not whole files. (Development cost is governed by the 2026-10-31 standing rule, not by R12.) + +**Merge:** replace R12 +**Checked:** verified + +### M-§2-07: R13 becomes the premise and covers direct code-level use + +**Target:** §2, R13, at "AI agents are the primary authors." +**Kind:** reword +**Goal:** G6, G1 +**Weight:** improves +**Finding:** G6 makes AI authorship the premise, not a hypothesis. G1 also requires direct code-level use "whichever the user prefers at any moment", so nothing may be reachable only through an AI. G1 additionally gives the AI an authoring-side duty: explain, and warn when a request looks unwise. Nothing in the map ships for that duty (§11 covers only the consent-side advisor). +**Evidence:** map:124-125, 953-980; goal-definition:11-17, 51-52. +**Proposed text:** + +> - **R13** AI agents write the configuration; that is the premise (G6), not a hypothesis. Every action an AI can take is equally available at the code level (G1). tendcf ships an authoring guide for the user's AI, a replaceable public file beside the default advisor prompt, covering how to turn a wish into Site Model config, when to warn, and how to explain. Local knowledge; machine-checkable conventions. + +**Merge:** replace R13 +**Checked:** verified + +### M-§2-08: New R14, peer updates by handshake (G3) + +**Target:** §2, after R13 +**Kind:** add +**Goal:** G3, G8 +**Weight:** blocks-goal +**Finding:** G3 is firmer than any map text. A device accepts updates from any other device that completes the correct cryptographic handshake. The map has delivery only as push from a `deploy-origin` host or pull on schedule (§9.11). The word "handshake" does not say whether it authenticates the peer (transport) or the content (signature); see M-§16-03 Q17. +**Evidence:** map:917-920; goal-definition:24-29, 104-106. +**Proposed text:** + +> - **R14** Peer updates (G3). Any device may hand a release to any other. The receiving device accepts a release only after the handshake [what it covers, release signature, peer authentication or both, is §16 Q17, operator's ruling]. It then authenticates the release itself by signature (§9.11) and authorizes it only through its own diff and the owner's decision (§9, R16). Delivery never authorizes; a compromised peer can withhold or replay, never change a device. + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): G3's handshake means content checks (signed by trusted keys, fresh, names this device, owner approval); transport auth decides only who may talk. First build: SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter); the 2-of-3 offline-root floor may lag until TUF. This settles §16 Q17 and the bracketed M-§2-08, M-§9-07, M-§10-02 claims: any device may deliver, and the content is checked. Ruled; the ruling is merged into the map's §9.11 ("The handshake is content checks (D50)") and D50 (2026-11-14, the rulings commit of this PR). The R14 requirement text itself is not yet inserted into §2. + +**Merge:** insert after R13, with the bracket resolved to B1's content checks. Ruled (operator ruling, 2026-11-14, B1). +**Checked:** inferred (the design reading); map text verified; independently checked 2026-11-13: weakened, corrected + +### M-§2-09: New R15, service roles ("servers") + +**Target:** §2, after R14 +**Kind:** add +**Goal:** G3, G8 +**Weight:** blocks-goal +**Finding:** G3 defines a "server" as a device that provides services such as log archiving and monitoring, and G8 state 1 needs logs archived on the Mac. The map treats any central log copy as "optional best-effort" (§8) and has no service role in the build order. +**Evidence:** map:460-462, 1156-1168; goal-definition:26-29, 108-109. +**Proposed text:** + +> - **R15** Service roles (G3). A "server" is any device holding a role that serves others: first the **log archive** (receives and keeps other devices' JSONL), later **monitoring** (watches other devices' reports and convergence). Roles are data in `roles` (§4.1), are rendered as ordinary tendcf service records, and change no architecture: each device's own JSONL stays its authoritative record (§8). The archive holds an authenticated copy, never a source of truth or a control point. + +**Merge:** insert after R14 +**Checked:** verified (map §8, §13); independently checked 2026-11-13: confirmed + +### M-§2-10: New R16, see-and-refuse on every device, every tier + +**Target:** §2, after R15 +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 covers every device: "Nothing changes a device except as an exact, mechanically checked difference that the device's owner can see and refuse." The map's §10 default is `operator`: no local yes, so on operator hosts (the whole of G8 state 1) nothing shows the owner a diff before apply. The map also has no requirement that what is shown "reads clearly without manuals" (G2). +**Evidence:** map:938; guide:846 (same default); goal-definition:21-22, 31-33. +**Proposed text:** + +> - **R16** See and refuse (G4). On every device, whatever its `trust_tier`, a change applies only as the device-computed diff of §9.1, shown to the owner before apply in words that need no manual, with a refuse that wins. Standing approvals are the owner's own choice, per device, revocable, and logged; none is a default. + +**Ruled:** B2: "3 but also the existance of standing wait for user and standing refusal" (`operator ruling, 2026-11-14, B2`). Option 3 (a hold window, or an owner-enrolled standing approval, shown and refusable before apply; a new approval-record shape without a per-change nonce, which is a schema bump), plus two further standing modes: a standing "wait for user" (hold until the owner answers) and a standing refusal. Smaller 1: every build gets a developer mode open to any owner, using an owner-enrolled standing approval for a signer of their choice (the B2 mechanism), with revoke and deny always honoured and a persistent indicator; the separate developer build is `05-response-code.md` C-android-03. Ruled; schema bump pending (SCHEMA-TOUCHING). + +**Merge:** insert after R15. Ruled (operator ruling, 2026-11-14, B2: "3 but also the existance of standing wait for user and standing refusal"; it changes the §10 `operator` default, M-§10-01). +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§2-11: New R17, safety scan with confidence, explanation and graded highlighting + +**Target:** §2, after R16 +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** The 0–100 confidence, its explanation and highlighting graded by risk are in no document. They need a requirement so that §9 and the build order have something to implement against. +**Evidence:** goal-definition:33-36, 103-104 (difference 4); `rg -n -i '\bTUI\b' docs` (hits only in deprecated tooling reviews). +**Proposed text:** + +> - **R17** Safety scan (G4). Every diff is scanned in several ways: mechanical rules derived from §9 (privilege, ceremony class, coverage transitions, removals, integrity flags) and at least one AI reviewer. The owner sees a safety confidence from 0 to 100%, an explanation of why that figure was chosen that cites the hunks behind it, and each questionable hunk highlighted more dramatically the lower its score. The scan advises and never authorizes (§9.12). + +**Ruled:** B8: "1. Capped 0-100 score" (`operator ruling, 2026-11-14, B8`): "score from 0 to 100", mechanical checks set a ceiling that AI review can lower but never raise, an explanation of each part, and a measured hit rate once a corpus exists (B13 wording 3, X-pm-03). The cap values are in M-§9-03. B8 sub 4: "2. Should not (as written)" (`operator ruling, 2026-11-14, B8 sub 4`), adopting X-safety-06's text (`09-safety-score-and-tui.md`). Ruled; the score and the authoring-model rule are merged into the map's §9.12 and §11 (2026-11-14, the rulings commit of this PR). The R17 requirement text itself is not yet inserted into §2. + +**Merge:** insert after R16 +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§2-12: New R18, command-line and TUI modes on a borrowed scaffold + +**Target:** §2, after R17 +**Kind:** add +**Goal:** G4, G1 +**Weight:** improves +**Finding:** G4 asks for both modes and a TUI scaffold borrowed from another project. Since the compiler and validator are Python, a Python TUI framework keeps one language; Textual is an obvious candidate and also serves a browser. Choosing the scaffold is the operator's call (G7 does not cover it, but G4 says "borrowed"). +**Evidence:** goal-definition:36-37; https://github.com/Textualize/textual (search excerpt: "lean application framework for Python"). +**Proposed text:** + +> - **R18** Two review modes over the same scan output (G4): a command-line mode (plain text, scriptable, every screen reproducible as text) and a TUI mode built on a scaffold borrowed from an existing project, not written from scratch. Both show the same figures and highlighting; neither has an action the other lacks. The scaffold is chosen by the operator (§16). + +**Ruled:** B12: "2. Borrow both freely; raise Python" (`operator ruling, 2026-11-14, B12`): borrow Toad and textual-diff-view (AGPL-3.0) as needed; the review TUI becomes AGPL-3.0-only and moves to Python >=3.14 (Toad's floor; Toad pins `textual==8.2.7`). Follow-ups: Termux and Mac Python >=3.14 availability; keep incompatible licences out of the TUI module. §16 Q22 is answered. Ruled; the B12 ruling is merged into the map's §6 ("Review TUI borrows (B12)") (2026-11-14, the rulings commit of this PR). The R18 requirement text itself is not yet inserted into §2. + +**Merge:** insert after R17 +**Checked:** verified (search only; no scaffold was evaluated); independently checked 2026-11-13: confirmed + +### M-§2-13: New R19, Nix-first authoring with YAML beneath + +**Target:** §2, after R18 +**Kind:** add +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** No requirement covers the authoring language; it lives only in D12, which says "two equal frontends". G2 is a requirement on the user's experience. G8 state 1 requires "Nix-authored config", yet today the Nix side is only an `eval-nix` wrapper over a plain attribute set. +**Evidence:** map:1211; inventory A "Compiler" (cli.py:150-171, `site.nix` a plain attribute set); goal-definition:19-22. +**Proposed text:** + +> - **R19** Authoring (G2). Config is written in the real Nix language with NixOS-style options (`mkOption`, `mkIf`, `mkDefault`, module imports), so existing NixOS and nix-darwin configs carry over. Plain YAML/JSON is the data form Nix evaluates to; it can be written by hand and is what the compiler validates. A Nix-authored site runs on hosts without Nix. "Carry over" means a one-shot importer for the pure-data option families (it lists what it did not carry over), plus tendcf option names that match nix-darwin and NixOS where the meaning is the same. + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`) adopts D49. The meaning of "carry over" in the last sentence is ruled by B7: "1. Importer + matching names" (`operator ruling, 2026-11-14, B7`), a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin/NixOS where the meaning is the same. Ruled; D49 and the importer ruling are merged into the map's §5 and decision register (2026-11-14, the rulings commit of this PR). The R19 requirement text itself is not yet inserted into §2. + +**Merge:** insert after R18. Ruled (operator ruling, 2026-11-14, B4: "1. Adopt D47-D50", D49 adopted). +**Checked:** verified (inventory digest; I did not open cli.py); independently checked 2026-11-13: confirmed + +### M-§2-14: New R20, branch management later (G9) + +**Target:** §2, after R19 +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** G9 is new and is "built as an extension of the platform's existing patch patterns": the `overlay/` manifest, drift check and retirement check, and §11's "personal branch". Recording it now as an extension point stops near-term designs closing it off, for example by hard-coding the fork's integration-branch workflow as agent-only process. +**Evidence:** goal-definition:67-70; map:978-980; inventory E (overlay.json, 6 patches, weekly drift check). +**Proposed text:** + +> - **R20** Later (G9): free-software branch management for people who cannot merge, rebase or compile, built as an extension of the `overlay/` patch pattern (manifest, pin, drift and retirement checks) and of §11's personal branch. Extension point only before G8 state 3; designs in the meantime must not preclude it. + +**Merge:** insert after R19 +**Checked:** verified + +--- + +## §4 The Site Model + +### M-§4-01: "Optional Nix module frontend ... Strangers need not know Nix" contradicts D12 and G2, and inverts schema authority + +**Target:** §4.1, paragraph beginning "Optional Nix module frontend (`mkOption` / `mkIf` / `mkDefault`)", and the bullet "YAML fallback gets a parse/re-serialize/diff check (D23) until the Nix authoring frontend exists" +**Kind:** ruling-drift +**Goal:** G2, G7 +**Weight:** misleads +**Finding:** The paragraph calls Nix "optional" and YAML a "fallback", contradicting both D12 (equal) and G2 (Nix first). It also says "JSON Schema is generated from the module options; never hand-maintain both". That would make the Nix module the schema authority and demote the hand-written `schema/` of eight schemas and 159 broken fixtures (125 schema-level, 6 byte-level, 28 projection-level). Under G2 (YAML/JSON beneath, which Nix evaluates to), the natural direction is the reverse: options generated from, or checked against, `schema/`. That direction is an instrument choice (G7) and needs a ruling. +**Evidence:** map:216-218, 248-250; inventory A (schema/ 8 files, 1,555 lines). +**Proposed text:** + +> The Nix module frontend (`mkOption` / `mkIf` / `mkDefault`; `nix2cf`, D12, D49) is the primary authoring surface (G2). It evaluates to the same YAML/JSON data form a person may also write by hand. `schema/` stays the single authority: the module options are generated from it, or checked against it in CI, never maintained as a second source. A person who does not know Nix can write the YAML/JSON form directly. + +**Merge:** replace that paragraph. Needs the operator's ruling first on which side is generated (§16 Q23). +**Checked:** verified (map text); not checked: the feasibility of generating NixOS-style options from JSON Schema; independently checked 2026-11-13: weakened, corrected + +--- + +## §8 Local record + +### M-§8-01: The log archive needs a JSONL writer that exists nowhere, and the index question changes + +**Target:** §8, at "Optional best-effort push of a subset into Vector / OpenObserve / Grafana is never the record of truth." and "It is not built yet on any host — nothing writes report rows" +**Kind:** add +**Goal:** G8, G3 +**Weight:** blocks-goal +**Finding:** G8 state 1 requires logs archived on the Mac. Nothing writes JSONL on any platform yet, so the capture writer on macOS and on Android, plus authenticated shipping to the archive, sit on the critical path. They are no longer optional. The device's own copy stays authoritative, and §8's reasoning holds. D45 item 7 (who owns the SQLite index on Linux and macOS) is ruled: both. The archive service keeps a fleet-wide SQLite index over every device, and each device keeps its own index over its own JSONL (see **Ruled** below). +**Evidence:** map:436-444, 460-462, 1130-1132; inventory A ("No hits at all: ... jsonl, sqlite"). +**Proposed text** (insert after "Optional best-effort push ..."): + +> **Log archive (R15, G8 state 1).** A device holding the `log-archive` role receives other devices' JSONL rows over the R14 handshake and appends them, keyed by device public key and release stamp. Shipping is retried, idempotent by row identity, and never blocks convergence. The sender's JSONL stays the record; the archive is an authenticated copy. **Indexes (D45 item 7):** the log archive keeps a fleet-wide SQLite index over every device's rows, and each device also keeps its own SQLite index over its own JSONL. The device's JSONL stays authoritative. The JSONL writer on macOS and on Android is therefore on the path to G8 state 1. + +**Ruled:** "make that both" (`operator ruling, 2026-11-14, Smaller 6, M-§8-01`, given after first answering "2. Per-device indexes"): option 3 "Both". The log archive keeps a fleet-wide SQLite index over every device, AND each device keeps its own index; device JSONL stays authoritative. This supersedes the earlier "2. Per-device indexes" answer (every device keeps its own SQLite index; the archive stores JSONL only; no fleet-wide index) and supersedes this item's earlier recommendation (a fleet-wide index at the archive only, with per-device indexes off Android waiting), which is why the proposed text above was rewritten. D45 item 7 is answered; ruled; merged on 2026-11-14 (the rulings commit of this PR) into the map's §8, §12 item 7 and D45/D18. The new log-archive paragraph in the proposed text above (rows "authenticated by device public key", "idempotent by row identity") is reviewer-proposed wording that was merged with it; kept by the operator ("1. Keep both", `operator ruling, 2026-11-14, PR 62 review Q6`, record line L62; see 14 "PR 62 review rulings (2026-11-14)"). + +**Merge:** insert after it. Ruled (operator ruling, 2026-11-14, Smaller 6); the index clause answers D45 item 7. +**Checked:** verified (map; inventory search results); independently checked 2026-11-13: weakened, corrected + +--- + +## §9 Releases, ChangePlan, TUF (Model B) + +### M-§9-01: What still holds: Model B is G4's "exact, mechanically checked difference" + +**Target:** §9 intro, at "The **ChangePlan is the diff** between the goal file the device has already approved and the one the release proposes" +**Kind:** add +**Goal:** G4 +**Weight:** improves +**Finding:** G4's first sentence describes what Model B already specifies: the device-computed diff (§9.1), canonical bytes and refuse-never-normalize (§9.2), entry-granular structural hunks (§9.2), all-or-nothing accept (§9.3), fail-closed versions (§9.6) and coverage in the file (§9.7). Saying so in one sentence protects these sub-decisions from being cut as "larger than needed". They are the mechanism G4 names, and the hunk key-paths are exactly what graded highlighting needs to anchor on. +**Evidence:** map:471-478, 526-616, 688-700, 736-770. +**Proposed text:** + +> This is the mechanism of goal G4: the device-computed diff is the "exact, mechanically checked difference" the owner sees and may refuse, and its `(domain, kind, id)` hunks are the units the safety scan scores and highlights (§9.12). §9.1–§9.3, §9.6 and §9.7 are therefore not candidates for simplification. + +**Merge:** insert after that paragraph +**Checked:** verified + +### M-§9-02: Add §9.12, "Safety scan", what G4 adds to Model B + +**Target:** §9, new subsection after §9.11 "Signing and delivery" +**Kind:** add +**Goal:** G4, G1 +**Weight:** blocks-goal +**Finding:** Nothing in §9 scores or highlights a diff. The design constraints follow from existing rules. The scan is semantic-layer output (D29, DC-3), so it never authorizes. It must run over the device-computed diff (§9.1), because a release-time scan is only a preview. Its bytes should be bound in the approval record, and `briefing_sha256` already exists for this. Score and explanation must cite hunk key-paths, so a reader can check them. +**Evidence:** map:910-915, 1228; `schema/approval-record.schema.json:35` (`briefing_sha256`). +**Proposed text:** + +> ### 9.12 Safety scan (goal G4, R17) +> +> - The scan runs over the **device-computed** diff (§9.1). A scan of the compiler's preview is itself a preview. +> - Scanners are of two kinds. **Mechanical** scanners are deterministic and derived from this section: validator-held privilege (§9.8), derived ceremony class (§9.4, §9.8), coverage transitions (§9.7), tombstone versus bare deletion (§9.8), predicted-versus-device diff inequality (§9.1), unbound fetched content (§9.8). **AI** scanners are one or more models the owner chooses, given the diff, the hunks' full old and new entries, and nothing they cannot cite. +> - Output is one **scan report**: a score from 0 to 100 (capped; ruled, B8, M-§9-03), an explanation that cites hunk key-paths, and a per-hunk score that drives highlighting. CLI and TUI render the same report (R18). +> - The scan **advises and never authorizes** (D29). No score accepts a change. The owner's accept or refusal is the approval record of §9.1, and the scan report's hash is carried as its `briefing_sha256`, so the record shows what the owner was shown. +> - The scan report is DC-3-labelled untrusted text: a diff can carry a prompt injection aimed at the AI scanner (§14.3). + +**Merge:** insert after §9.11 +**Checked:** verified (map rules and schema field); inferred: reusing `briefing_sha256` needs no schema bump (the field exists, but its description was not read); independently checked 2026-11-13: confirmed + +### M-§9-03: Mechanical findings set a ceiling that the AI score cannot raise + +**Target:** the proposed §9.12 (M-§9-02), "Output is one scan report" +**Kind:** add +**Goal:** G4 +**Weight:** improves +**Finding:** A single 0–100 figure that blends rules with an AI's opinion lets a persuasive AI, or a prompt-injected one, talk a privileged hunk up to "97% safe". The validator already derives privilege and ceremony class deterministically. These should cap the score, and the explanation should say which rule set the cap. This also gives the "graded highlighting" a stable floor that does not move between AI runs. +**Evidence:** map:772-797 (privilege derivation, transition table). +**Proposed text:** + +> - The score is a **capped 0-100 score**. The base is 95; it never shows 100. Mechanical findings subtract penalties and set caps; an AI reviewer can lower the figure (by up to 30; whether per reviewer or in total is open: deferred to the schema design review (operator ruling, 2026-11-14, PR 62 review Q7)) and never raise it, and the figure is never above any cap that applies. The explanation names every penalty and cap applied. Values are fixed in the schema, not by the scanner, and change only by an operator ruling, later backed by a labelled corpus: +> +> | Part | Value | +> |---|---| +> | Base | 95; never 100 | +> | Penalty, lockout | 60 | +> | Penalty, privilege | 50 | +> | Penalty, management | 45 | +> | Penalty, data-loss | 40 | +> | Penalty, reversible | 10 | +> | Penalty, notice | 3 | +> | AI reviewer | subtracts up to 30, from findings that cite a key path only (whether per reviewer or in total: open: deferred to the schema design review (operator ruling, 2026-11-14, PR 62 review Q7)) | +> | Cap 40 | a lockout, privilege or management finding | +> | Cap 60 | a check not run or failed, including an AI reviewer that is unavailable | +> | Cap 70 | an uncovered hunk kind; or AI model families that disagree on a tier | +> | Cap 80 | a touched domain that is not comprehensive | +> | Cap 0 | an integrity flag | +> +> Bands: 0-39 danger, 40-69 caution, 70-89 notice, 90-95 plain. The table's source is `09-safety-score-and-tui.md`, "Recommended design: capped checklist score" (the formula `base - penalty - ai_sub`, then `min` with the caps that apply). + +**Ruled:** "1. 09's table, top 95" (`operator ruling, 2026-11-14, B8 sub 1, M-§9-03 / Q25 / 01 Idea 1 / 09 Idea 1`). The values in the proposed text above are the ruling's values, copied in full; 09's "capped checklist score" table is the source. The auto-refuse floor (B8 sub 2, "1. Allowed, off by default") is in the guide response, G-§7-01; the scan's authoring-model rule (B8 sub 4, "2. Should not (as written)") is `09-safety-score-and-tui.md` X-safety-06. Q25 is answered. Ruled; merged into the map's §9.12 and §11 (2026-11-14, the rulings commit of this PR). + +**Merge:** insert after the "Output is one scan report" bullet of §9.12 once M-§9-02 is merged. Ruled (operator ruling, 2026-11-14, B8 sub 1). +**Checked:** inferred (design proposal); independently checked 2026-11-13: weakened, corrected + +### M-§9-04: TUF subset: defer emergency/pre-grant and rule on the root threshold for state 1 + +**Target:** §9.11, at "TUF subset sized for one operator (offline root 2-of-3, targets, snapshot, emergency)" and the D42 paragraph "An optional enrolled policy “I pre-grant emergency security patches from role E” may exist" +**Kind:** question +**Goal:** G8, G4 +**Weight:** improves +**Finding:** G8 state 1 is two of the operator's own devices. The 2-of-3 offline root, the emergency role and the out-of-band runbook are bigger than state 1 needs. §9.11 itself doubts that a one-operator 2-of-3 means anything when all keys sit on one machine. The guide makes the 2-of-3 a floor that its silence cannot relax, so only the operator can stage it. Separately, D42's "pre-grant emergency patches" is an install without the owner seeing it, which conflicts with G4 even as an opt-in. +**Evidence:** map:879-893, 904-908; guide:9-12. +**Proposed text:** + +> For G8 state 1 the release is TUF-shaped (root, targets, timestamp, high-water mark) with a root threshold the operator sets at the first-run ceremony (§16 Q26). The emergency role and DC-20's runbook land before the first non-operator device enrolls. D42's pre-grant is withdrawn under G4: revocation and freezes still need no local yes, but every install is shown. + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): "the map's 2-of-3 offline-root floor may lag until TUF" for the first SSH-signature v0 build. The emergency role, D42's pre-grant and the root threshold beyond v0 are not ruled by the 2026-11-14 rulings. Ruled in part; the rest stays open. + +**Merge:** needs the operator's ruling first (the 2-of-3 floor and D42's pre-grant) +**Checked:** verified (map and guide text); independently checked 2026-11-13: confirmed + +### M-§9-05: The advisor-key signature and auto-review are larger than G4 needs; the owner key comes first + +**Target:** §9.1, at "`signature`, valid for exactly one target key", and §11, at "At install they enroll an **advisor key**" +**Kind:** cut +**Goal:** G4, G8 +**Weight:** misleads +**Finding:** In G4 the owner sees and refuses; the AI scans and explains. §11 has the person's AI hold the signing key, including in an auto-review mode, which removes the owner from the loop. For G8 state 1, the approval record should be signed by an owner key enrolled on the device and used from the CLI or TUI. An advisor-key signature can stay as an explicit owner-delegated option later. The approval-record shape does not change, only whose key is enrolled. +**Evidence:** map:552-571, 959-967. +**Proposed text** (§11 first bullet): + +> - At install the owner enrolls an **owner key** on the device; the CLI and TUI sign the approval record with it. An **advisor key** may be enrolled later as an owner-chosen, revocable delegation (R7/R10, R16); it is not the default and is not built before the first non-operator device enrolls. + +**Merge:** replace that bullet. Needs the operator's ruling first; it supersedes D39 ("Their AI, their key"). +**Checked:** verified (map text); independently checked 2026-11-13: confirmed + +### M-§9-06: `explain-hunk` is not needed for state 1; G4's explanation is a different thing + +**Target:** §9.5, at "The tool is due before the consent surface (Step 9)." +**Kind:** reword +**Goal:** G4, G8 +**Weight:** improves +**Finding:** `explain-hunk` attributes a hunk to a source layer by re-rendering. That matters once a site has several layers (site-shared, foreign inputs). G4's "explanation" explains a safety figure, and comes from the scan. In state 1 there is one private site and one author, so attribution is trivial. Tying `explain-hunk` to "Step 9" invites it into the critical path for the wrong reason. +**Evidence:** map:678-686. +**Proposed text:** + +> The tool is due before a site composes more than one input layer (site-shared or foreign), which is after G8 state 1. It is not the explanation of goal G4, which comes from the safety scan (§9.12); a scan MAY call it once it exists. + +**Merge:** replace that sentence +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§9-07: §9.11 "Push: any host holding `deploy-origin`" must become peer delivery + +**Target:** §9.11, paragraph beginning "Push: any host holding `deploy-origin`, to **operator** (and operator-chosen `managed`) hosts." +**Kind:** ruling-drift +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** G3 allows any device to deliver, after the handshake. TUF already separates content authenticity from transport (any mirror can serve), so G3 fits Model B with no architectural change. The text should say this, and name the transport. CFEngine's own `cf-serverd` already does key-based peer authentication (`trustkeysfrom`, `ppkeys`), and §6/D14 says every host runs one. The live install runs none, though, and CFEngine's default trust is by address, which must be replaced by an explicit key list. +**Evidence:** map:372-376, 917-920, 1214; `rg -n 'cf-serverd|serverd' deploy/linux/tendcf-install.sh` (no hits); Learning CFEngine ch. 33 (`trustkeysfrom => { "127.0.0.1", ... @(def.acl) }`, via `book-kb query`). +**Proposed text:** + +> Delivery (G3, R14): any device may offer a release to any other. The receiver completes the handshake [scope: §16 Q17, operator's ruling; if it includes peer authentication, by explicit key lists rather than CFEngine's address-based trust], then verifies the release signature and high-water mark. Delivery authorizes nothing: push, pull and peer relay are one transport, and every install still passes the device-computed diff and the owner's decision (R16). Transport candidate: each device's own `cf-serverd` with key-pinned access (D14), to be confirmed at the step that builds it. + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): content checks; transport auth decides only who may talk, so any device may deliver. Ruled; the map's §9.11 now carries "The handshake is content checks (D50)" (2026-11-14, the rulings commit of this PR); the paragraph replacement proposed above is not otherwise made. + +**Merge:** replace that paragraph, with the bracket resolved to B1's content checks. Ruled (operator ruling, 2026-11-14, B1). +**Checked:** verified (installer grep, book chapter); not checked: whether the fork's cf-serverd works on Termux; independently checked 2026-11-13: weakened, corrected + +--- + +## §10 Per-device trust + +### M-§10-01: The Consent default `operator`: no contradicts G4 + +**Target:** §10 table, row "**Consent** | Do I also need a local yes? | `operator`: no." +**Kind:** ruling-drift +**Goal:** G4, G8 +**Weight:** blocks-goal +**Finding:** Under this default, G8 state 1's devices, all of them the operator's, would apply changes without the owner seeing a diff. That fails G4's "nothing changes a device except as ... the owner can see and refuse". The guide carries the same row. Options: (a) a local yes on every tier; (b) operator tier gets a hold window, with the diff and scan shown and a refuse that wins before apply; (c) a standing yes the owner enrolls explicitly. Each is a ruling. +**Evidence:** map:938; guide:846. +**Proposed text:** + +> | **Consent** | Do I also need a local yes? | Every tier: the owner sees the device-computed diff and its scan and may refuse it (G4, R16). `operator`: [per-change yes, a hold window, or an owner-enrolled standing approval: §16 Q19, operator's ruling; a standing approval needs an approval-record shape without a per-change nonce, which is a schema change]. `consented`: an explicit yes per change. `managed`: operator-chosen within that floor | + +**Ruled:** B2: "3 but also the existance of standing wait for user and standing refusal" (`operator ruling, 2026-11-14, B2`): option 3 (a hold window, or an owner-enrolled standing approval, shown and refusable before apply; a new approval-record shape without a per-change nonce, i.e. a schema bump), plus a standing "wait for user" (hold until the owner answers) and a standing refusal. §16 Q19 is answered. Ruled; schema bump pending (SCHEMA-TOUCHING). Which schema version carries the new approval-record shape, and whether it is one bump with the Android profile field and the agent id, is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides (shipped v6 is already taken by C-policy-01, PR 52, 83d7280). + +A reading of the ruling (L5, B2), not part of it (lead decision, PR 62 round-3 review): a standing approval drops only the per-change nonce (DC-2's device nonce); it is signed by an owner-held trusted key and keeps B1's other content checks (signed by trusted keys, fresh, names this device) and the rest of DC-2 (per-target validity, monotonic-counter single use or high-water mark, persisted rejects); its ceremony class is still checked against the validator's derived requirement (§9.8); until the operator rules, a standing approval covers `ordinary` changes only; whether one may cover `privileged` or `baseline` changes is for the schema design review to propose and the operator to rule; it names its signer and algorithm only if X-trust-06 is adopted (proposed, not ruled); every standing mode (hold window, standing approval, standing "wait for user", standing refusal) is owner-enrolled and refusable, and none is a default; dropping any other check needs an operator ruling; the schema design review confirms the approval-record shape. + +**Merge:** replace that row. Ruled (operator ruling, 2026-11-14, B2). Names its twin in the guide §14 (the guide reviewer's item). +**Checked:** verified (both tables); independently checked 2026-11-13: weakened, corrected + +### M-§10-02: Add a Delivery axis for G3's handshake + +**Target:** §10 table, after the "**Release**" row +**Kind:** add +**Goal:** G3 +**Weight:** improves +**Finding:** "Whose signatures may change me" (Release) and "who may act on me" (Peer) both differ from "whom do I accept a delivery from". G3 makes the third explicit, and separating it keeps delivery from being mistaken for authority. +**Evidence:** map:935-941. +**Proposed text:** + +> | **Delivery** | Which peers may hand me a release (the G3 handshake)? | [Any device (G3's 'any other device'), or only devices my trust policy lists: §16 Q17, operator's ruling]; delivery grants no authority | + +**Ruled:** B1: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): the Delivery axis's bracketed choice resolves to any device may deliver (content checks), and transport authentication decides only who may talk. Ruled; the ruling is merged into the map's §9.11 and D50 (2026-11-14, the rulings commit of this PR). The Delivery row itself is not yet inserted into the §10 table. + +**Merge:** insert after the Release row. Ruled (operator ruling, 2026-11-14, B1). +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +--- + +## §12 Platforms and D45 + +### M-§12-01: The Mac must converge, not dry-run: which Mac, and what is enforced + +**Target:** §12, "**macOS (adapter #1).** ... Dry-run default." and §13, "Dry-run is the standing posture on the first platform (the machine that cannot easily be reimaged)." +**Kind:** question +**Goal:** G8, G5 +**Weight:** blocks-goal +**Finding:** G8 state 1 says the Mac "converge[s]", and as the log-archive server it must run a service tendcf enforces. The map's macOS posture is dry-run because the first Mac is the daily driver. Either a second Mac is the state-1 server, or the daily driver enforces under §9.4's minimal-claim rule: only the domains the owner enumerates, beginning with the archive service and a canary. R1 excludes the Intel Mac mini, which narrows the candidates. +**Evidence:** map:986-991, 1170-1171, 644-651, 106. +**Proposed text:** + +> **macOS (adapter #1, server first, G5).** The G8 state-1 Mac is an Apple Silicon macOS VM (tart / Virtualization.framework) on bigmac (MacBookPro18,1): current macOS, snapshot and rollback, and CI can run the same image. It is a client, not an always-on server. The VM is the only enforcing Mac in state 1. It runs tendcf as a root LaunchDaemon, and under §9.4's minimal-claim rule its first goal file manages only the domains the owner names at first adoption: a canary and the log-archive service (R15). Every other domain is `not-yet-migrated`. The VM is also the G8 log-archive server, reachable only while bigmac is awake; devices buffer JSONL meanwhile. bigmac itself may run tendcf in dry-run only (compute and report the diff, log drift, apply nothing), as a user LaunchAgent with no root. The state-1 VM image is minimised: start from the smallest base (vanilla, not a dev-tools image) and strip what state 1 does not need. State 1 must verify the root launchd render path (the WarpBuild spike skipped it). §16 Q18 is answered. Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): the VM may enforce early as an explicit, ruled exception like pastebin's: canary only, operator-authored data (its root `cf-execd` enforcement at the stage 1 / guide Step 1 VM stands as an exception to D45's "`tendcf-validate` before any further host is enforced"). The order is not changed. + +**Ruled:** B6 and its sub-rulings, all dated 2026-11-14. B6: "1. Plain Mac, launchd by tendcf" (state 1's Mac has no nix-darwin; tendcf renders launchd; Nix for authoring and building only). B6 sub 1: "1. macOS VM on bigmac". B6 sub 2 (Q18): "1. Dry-run only". B6 sub 1 rider: "Try to cut down the MacOS VM image so be smaller, remove stuff we don't need." (queued as build work: research the floor, what macOS can drop in a guest, for example tart vanilla against base images). B6 sub 3: "1. Root in VM, user on bigmac". (`operator ruling, 2026-11-14, B6, B6 sub 1, B6 sub 2, B6 sub 3, M-§12-01 / Q18`.) The proposed text above was rewritten to match; the earlier "daily driver enforces" alternative is closed. Ruled; the image minimisation is build work, queued. + +**Merge:** replace the first two sentences of the macOS paragraph. Ruled (operator ruling, 2026-11-14, B6 sub 1, sub 2, sub 3). +**Checked:** verified (map text); independently checked 2026-11-13: confirmed + +### M-§12-02: macOS server needs an installer, a launchd `cf-execd`, a renderer path and CI, and none exist + +**Target:** §12 macOS paragraph, at "Runtime: CFEngine + `tendcf-validate` (D45, below)." +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** Everything deployable is Linux: `deploy/` contains only `linux/`, the root install and `tendcf-execd.service` are systemd, and there is no macOS CI. The Mac has only a dev build used for tests. Platform 1 needs the macOS analogue of `tendcf-install.sh`: a root-owned prefix and a launchd daemon for `cf-execd`. The compiler's launchd renderer exists. What is missing is a fork build checked on macOS in CI; given the operator's macOS-CI policy, this needs his say. +**Evidence:** `ls deploy` (prints `linux/`); inventory F ("There is no macOS CI"); inventory G4. +**Proposed text:** + +> Not built for macOS: a root-owned install of the fork (prefix open, §12 item 6), a launchd daemon running `cf-execd`, a macOS installer beside `deploy/linux/`, and a CI job that builds the pinned fork and runs `tests/policy/run.sh` on macOS. These are the first work of G5's platform 1. + +**Ruled:** the explicit macOS CI step is part of the adopted build order: "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`: "guide's build order as base with the map's Step 0 and an explicit macOS CI step folded in"). B5: "1. Keep fork; spike stock" (`operator ruling, 2026-11-14, B5`): the full fork pin on every platform, with the macOS fork build in CI; run report 11's 2-3 day stock/Termux spike before deciding the adopter path (options 2-4). On PR 52's macOS check 8 the operator ruled "let's finish the codewarp setup and then try running on their fastest mac setup" (`operator ruling, 2026-11-14, PR 52 gate 2`): WarpBuild, with `frdminc/tendcf` in runner group 1, spike branch `spike/macos-check8-warp` building the fork pin on `warp-macos-26-arm64-12x` and running `tests/policy/run.sh` (worker 68cf038a); the merge of PR 52 waited on that run (historical: the run "macOS check 8 spike (WarpBuild)", https://github.com/frdminc/tendcf/actions/runs/43602684071, completed with conclusion success, and PR 52 merged on 2026-11-14 at 2c78680). The root launchd render path was skipped by that spike and state 1 must verify it (B6 sub 3, M-§12-01). + +**Merge:** insert after that sentence. Ruled (operator ruling, 2026-11-14, B4, B5); the macOS CI policy question is answered by the ruling above. +**Checked:** verified (ls, inventory); independently checked 2026-11-13: confirmed + +### M-§12-03: Android (platform 2): the list of missing pieces is long, and the map lists none + +**Target:** §12, "**Android (adapter #2).** Same Site Model vocabulary. Runtime: Termux + tendcf-agent (Kotlin, D45) + Shizuku-class helper + CFEngine." +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** Missing, on the path to state 1: +1. A fork build for Termux (bionic, aarch64). +2. A runit/termux-services renderer. The bundle refuses runit by name, and the compiler refuses `android` outright. +3. The agent, which is unbuilt; `ShizukuTendCF` is only a helper. +4. A JSONL writer under the UID split of §8. +5. A protected baseline (§16 Q13, "Android under Termux is the awkward case"). +6. APK build and signing. R6, "Gradle stays for APKs", was dropped from v3 without a decision. + +The map lists none of these. +**Evidence:** map:993-995, 446-458, 1292-1294; `compiler/nix2cf/compile.py:82-83` (Android refused, "TODO(operator)"); `policy/tendcf_services.cf:125, :251` (runit names fall through); `docs/architecture/deprecated/architecture-DEFINITIVE-v2.md:183` (R6); inventory C (ShizukuTendCF "contains no goal-file, host_specific or cf-agent code"). +**Proposed text:** + +> **Android (adapter #2, client, G5).** Same Site Model vocabulary. Runtime: Termux + tendcf-agent (Kotlin, D45) + user-space ShizukuPlus (`frdminc/ShizukuTendCF`) + CFEngine. To build, in order: the fork for Termux; the runit renderer (compiler and bundle); the compiler's `android` platform row; the agent's validator, JSONL writer and protected baseline (§8, §16 Q13); APK build and signing (Gradle). Peer actions cover devices that need external ADB help. + +**Ruled:** B3: "3. Termux CFEngine + thin Kotlin" (`operator ruling, 2026-11-14, B3`): state 1 on Android is Termux CFEngine fed tendcf projections, and the Kotlin agent holds trust and consent only (05 Idea 4). The paragraph above is the shape; the agent's validator row is settled by B3 sub 2 (M-§12-06: the single Python `tendcf-validate` runs in Termux, the Kotlin agent re-checks and shows consent). B3 sub 3: "1. Never" (`operator ruling, 2026-11-14, B3 sub 3, X-android-09`): tendcf never holds a DPC slot (profile owner or device owner); it works with Island/Insular through shell (`--user N`) and the owner app's API; an unreachable profile reports `not_kept`; tendcf never requires MDM enrolment. Ruled; implementation pending. Whether the fork builds on Termux stays unchecked, and 11's 2-3 day stock/Termux spike (B5) runs before the adopter path is decided. + +The B3 ruling above is the trust, consent and Termux decision. Its consequence for the Android log and index is ruled (operator ruling, 2026-11-14, PR 62 review Q3, "1. Agent keeps log role"): "only" is about decisions; the thin Kotlin agent still writes the device JSONL and index as a support role; map and D18 stand. The proposed text above ("the agent's validator, JSONL writer and protected baseline") and the map's §8 and D18 (which place the Android index in tendcf-agent) stand for the log and index role; the validator is not in the agent (B3 sub 2). + +**Merge:** replace that paragraph. Ruled (operator ruling, 2026-11-14, B3, B3 sub 3). +**Checked:** verified (files cited); not checked: whether the fork builds on Termux at all; independently checked 2026-11-13: confirmed + +### M-§12-04: Island/Insular profiles need a model: is a profile a host, a domain or a scope? + +**Target:** §12 Android paragraph (as replaced by M-§12-03) +**Kind:** question +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** Each Android user profile (main, Island/Insular work profile, secondary users) is a separate Android user with its own app data. Termux in one profile cannot see another, and Shizuku acts with `--user N`. The Site Model has no notion of a profile, so per-profile app lists and policy cannot even be stated. Three options: one host per profile, each with its own key and baseline; one host with a profile-keyed domain; or a `profile` field on entries. The choice touches the goal-file schema (a `schema_version` bump), so it is a design ruling with two frontier reviews under the repo's standing rule. +**Evidence:** `rg -il 'insular|island' docs schema compiler policy` (hits only in the goal file and handoff 601f); https://f-droid.org/en/packages/com.oasisfeng.island.fdroid/. +**Proposed text:** + +> **Profiles.** Each Android user profile, including an Island/Insular work profile, is managed. There is one host per phone: one key, one baseline, one review. Each Android promise names its target user (`owner`, `work` or `private`) and the work profile's owner app (`island`, `insular` or `none`), per X-android-05's text. A profile tendcf cannot reach reports `not_kept`. tendcf never holds a device-policy-controller slot (profile owner or device owner); it works with Island/Insular through shell (`--user N`) and the owner app's API, and never requires MDM enrolment. The field is a `schema_version` bump, and it rides the same bump as the agent id (§12 item 4). + +**Ruled:** B3 sub 1: "1. Field on entries" (`operator ruling, 2026-11-14, B3 sub 1, Q20 / M-§12-04 / X-android-05`). One host per phone; the profile target and owner app are fields on entries; an unreachable profile reports `not_kept`. The schema bump is a design ruling and takes two frontier reviews, and it rides the same bump as the agent id (M-§12-05 item 4). B3 sub 3: "1. Never" (`operator ruling, 2026-11-14, B3 sub 3, X-android-09`). §16 Q20 is answered. Ruled; schema bump pending (SCHEMA-TOUCHING). + +**Merge:** insert after the Android paragraph. Ruled (operator ruling, 2026-11-14, B3 sub 1, B3 sub 3). +**Checked:** verified (grep); inferred: per-profile Termux isolation (standard Android multi-user behaviour, not tested here); independently checked 2026-11-13: confirmed + +### M-§12-05: D45's open items, re-read under G5 and G8 + +**Target:** §12, "**Open, for the operator (D45 leaves these undecided ...)**", items 1–8 +**Kind:** reword +**Goal:** G5, G8, G4 +**Weight:** blocks-goal +**Finding:** The items were written for Linux-next. Under G5 and G8 state 1, macOS is the first host, and the first build must carry the whole gate, because state 1 needs "updates accepted only after the cryptographic handshake" and G4's see-and-refuse. Item 2's "schema-only" first build therefore does not reach the goal. Item 4's timing is stale: at the base this review read (`eefea3c`) v5 had landed (`"const": 5`), so an id change then cost v6; since then v6 itself has shipped (C-policy-01, PR 52, 83d7280), so an id change now costs the next unused schema version (v7 or later). On item 6, the review machine's `/usr/bin/python3` is 3.9.6, below the projector's `>=3.11`. The map notes this does not establish what a CLT-only install supplies, so a bundled interpreter is the likely, not the forced, answer. +**Evidence:** map:1070-1075, 1103-1106, 1117-1129; `schema/goal-file.schema.json:11` (`"const": 5`); `bin/projector.py:3-4` (`requires-python >=3.11`, `rfc8785`). +**Proposed text** (insert before item 1): + +> **Under goal G5/G8 (2026-11-13).** macOS is the first host these items apply to, then Android (agent), then Linux. G8 state 1 needs the whole §9 gate, so item 2's first build is the full validator: signature and high-water mark, baseline integrity, device-computed diff, approval record and DC-2, projection. Item 3 assigns all of these, plus the JSONL writer and the `device_convergence` row, to `tendcf-validate` or a sibling command run under launchd. Item 4: the schema is at v6 (C-policy-01, PR 52, 83d7280), so changing the `agent` id now costs the next unused schema version (v7 or later) and a baseline ceremony per device; the Android profile ruling is made ("1. Field on entries", §16 Q20, M-§12-04), so the agent-id change shares that bump with the profile field (ruled, B3 sub 1). Whether the standing-modes approval-record shape (§9.1) also shares it is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. Items 5–6: on macOS, likely a bundled interpreter of at least 3.11 with `rfc8785` vendored, invoked by absolute path with `-I`; on Android the single Python `tendcf-validate` runs in Termux (M-§12-06). Item 7: ruled both: the log archive keeps a fleet-wide SQLite index and each device keeps its own (§8, M-§8-01). Item 8: Linux only, later in the order (not paused, D48). + +**Ruled:** B3 sub 1 shares its schema bump with item 4 (`operator ruling, 2026-11-14, B3 sub 1, M-§12-05 item 4`: "Schema bump = design ruling (two frontier reviews); ride the same bump as the agent id"). Item 7: "make that both" (`operator ruling, 2026-11-14, Smaller 6`). Items 5-6 on Android: B3 sub 2 (M-§12-06). Items 2, 3 and 8 are not ruled by the 2026-11-14 rulings except as the build order's "CLI diff + y/N first" (B8 sub 3, M-§13-01); the rest of the text stays proposed. + +**Merge:** insert before item 1. Items 4 and 7 are ruled as above; the other items remain the operator's open items (2 and 3). +**Checked:** verified (schema const, projector header); not checked: CLT Python version on a current macOS; independently checked 2026-11-13: weakened, corrected + +### M-§12-06: The Kotlin port arrives at platform 2: reconsider one Python implementation inside Termux + +**Target:** §12, at "On Android the Kotlin agent runs the same validation and projection logic as a port, held byte-for-byte to the same checked-in goldens in CI" +**Kind:** question +**Goal:** G5, G7 +**Weight:** improves +**Finding:** D45 chose Kotlin on Android when Android was deferred. With Android second, a second implementation of the whole §9 validator (not just the projector) becomes early, critical-path work, and a drift risk on the one platform that differentiates the project. Termux ships Python, so `tendcf-validate` could run there unchanged. The agent would keep what only an APK can do: Shizuku bridging, Room index and app-private storage, notifications and the TUI's Android counterpart. The cost is that the baseline and the JSONL live in Termux's app-private storage rather than the agent's. That is a ruling on an instrument (G7). +**Evidence:** map:1033-1037, 1243 (D45 (1)-(2)); map:446-458 (UID split). +**Proposed text:** + +> Under G5 (§16 Q21, ruled): Android runs the single Python `tendcf-validate` in Termux. The Kotlin `tendcf-agent` independently re-checks the signature and high-water mark, keeps the trust anchor and the approval record in its own app-private storage, and shows consent. There is no full Kotlin port of the validator. + +**Ruled:** B3 sub 2: "1. Termux + Kotlin trust check" (`operator ruling, 2026-11-14, B3 sub 2, Q21 / M-§12-06`). This amends D45 (1)-(2): no full Kotlin port of the validator. §16 Q21 is answered. Ruled; merged on 2026-11-14 (the rulings commit of this PR) as the map's D45 (1)-(2) amendment and §12 text. The earlier question form above ("whether Android runs `tendcf-validate` itself inside Termux's Python, leaving tendcf-agent the privileged-helper, index and notification roles") is closed. + +**Merge:** replace D45 (1)-(2)'s Kotlin-port clause with the proposed text. Ruled (operator ruling, 2026-11-14, B3 sub 2). +**Checked:** inferred (Termux providing Python is common knowledge, not checked here); independently checked 2026-11-13: confirmed + +### M-§12-07: Linux becomes platforms 4 and 5; keep pastebin; Linux-only design work is later in the order, not paused + +**Target:** §12, "**Linux (adapter #3, adoptability keystone).**" +**Kind:** ruling-drift +**Goal:** G5 +**Weight:** misleads +**Finding:** "Adoptability keystone" and "#3" are stale under G5. Every live host is Linux, though, and pastebin enforces a canary that the operator ruled stays "as the standing proof". The consequence the reviewer drew was that Linux-only work waits behind state 2 (the s5 detector design (873 lines), the Linux validate build and the systemd renderer in the compiler). The operator ruled otherwise (see Ruled below): Linux is later in the order, not paused; only the s5 design is parked (B11, "park s5"). Merging the green PRs #41 and #42 is cheap and unblocks D46. +**Evidence:** map:997-999; inventory C, D (#41, #42 green); digest-history B2.7. +**Proposed text:** + +> **Linux (adapters #4 server and #5 client, G5).** Stock distro; mise toolchains + CFEngine everything else, plus `tendcf-validate`. pastebin (Debian 13) keeps its enforced canary as the standing proof. Linux-only design work (the unit-writer detector, the systemd renderer in the compiler) comes later in the order, not paused (D48). + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`) adopts D48. B4 rider, Linux: "1. Order language" (`operator ruling, 2026-11-14, B4 rider, Linux`): Linux is later in the order, not paused. B4 rider, canary: "1. Keep it" (`operator ruling, 2026-11-14, B4 rider, canary`): the pastebin canary stays the standing end-to-end proof. The proposed text above carries only that order language ("later in the order, not paused"); it no longer carries the earlier "freeze" title or the "waits for G8 state 2" restriction, which the ruling does not contain. The separate B11 ruling "park s5-design" stays as ruled. + +**Merge:** replace that paragraph. Ruled (operator ruling, 2026-11-14, B4 and its Linux and canary riders). +**Checked:** verified (inventory; did not check PR state live); independently checked 2026-11-13: confirmed + +--- + +## §13 Build order + +### M-§13-01: A replacement build order that reaches G8 state 1 first + +**Target:** §13 "Build order", the whole table and the two paragraphs after it +**Kind:** correct +**Goal:** G8, G5, G2, G3, G4 +**Weight:** blocks-goal +**Finding:** The current order (macOS dry-run, Android deferred, Linux steps 4–5, consent at Step 9, Nix nowhere) cannot reach G8 state 1. That state needs a Nix frontend, an enforcing Mac, Android, the full device gate, peer delivery and a log archive. The guide's §18 table differs from the map again: it shows Android as Step 2 without the deferral. The replacement below is ordered by state 1's dependencies. Every step leaves something runnable and is measured against a G8 state. It assumes rulings D47–D50; where one goes the other way, the affected rows move. This order defers ordering inference (D16) to "13+ Demand": it is on the path to no G8 state. That amends D16 and needs the operator's ruling (the guide response's G-§10-01 proposes the same deferral). +**Evidence:** map:1152-1176; guide:1362-1374; goal-definition:58-65. +**Proposed text:** + +> ## 13. Build order +> +> Each step leaves a coherent system and names the G8 state it serves. Not a schedule. Done before 2026-11-13: schemas through v5 (v6 followed on 2026-11-14: C-policy-01, PR 52, 83d7280), the launchd and systemd bundle branches, `buildfile`, the reference projector, the pastebin canary, NixOS passthrough stages A–C on get. +> +> | Step | What | G8 | +> | --- | --- | --- | +> | 0 | Merge #41 and #42 (historical: both merged 2026-11-14, #42 at acec5b5 and #41 at daa4530); the D46 restructure (`tendcf compile`, `plugins/`), amended: all plugins in tree, compile-time only, never on a device; Python entry-point discovery is deferred until a user needs one and out-of-tree plugins can be pinned (ruled, Smaller 5). Schema additions, each at the next unused schema version (v7 or later; shipped v6 is C-policy-01, PR 52): owner key in device trust, the `log-archive` and `monitor` roles, and whatever of these has been ruled by then: the operator-tier consent shape (§16 Q19), the Android profile model (§16 Q20), the `agent` id (§12 item 4), the scan-report shape. The Android profile model and the `agent` id share one bump (ruled, B3 sub 1); how the other additions group is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. Unruled items ride a later bump. | 1 | +> | 1 | **Nix frontend.** `plugins/frontends/nix` with NixOS-style options (module system), rendering byte-identical to its YAML twin; the state-1 Mac and Android device are authored in Nix. | 1 | +> | 2 | **Mac enforces.** Root install of the fork on the state-1 Mac (launchd `cf-execd`), `deploy/macos/`, a macOS CI job (ruled, B4), a launchd canary enforced under the minimal-claim rule. | 1 | +> | 3 | **`tendcf-validate` on macOS.** Baseline integrity, device-computed diff, approval record and DC-2, projection, `device_convergence` row, JSONL writer. Bundled interpreter. Release-signature and high-water verification arrive with signed releases (Step 5). | 1 | +> | 4 | **Owner review, CLI.** Built first, as a CLI diff with `y/N`, and used on the state-1 VM and dev devices before any TUI or score work (B8 sub 3). Shows the device-computed diff; mechanical scanners, confidence with ceilings, explanation, graded highlighting; the owner key signs accept or refuse. | 1 | +> | 5 | **Signed release and peer delivery.** TUF-shaped release (root threshold per ruling); `tendcf-validate` verifies the release signature and high-water mark; the R14 handshake (what it covers: §16 Q17, operator's ruling); any device may relay. | 1 | +> | 6 | **Android client.** Fork on Termux, runit renderer, compiler `android` row, validator (the single Python `tendcf-validate` in Termux, with the Kotlin agent re-checking trust; ruled, B3 sub 2), ShizukuTendCF, profiles (a field on entries; ruled, B3 sub 1), APK build; owner review on the device as the native screen opened from the agent notification, with Termux CLI/TUI as the operator's path (ruled, B3 sub 4). | 1 | +> | 7 | **Log archive on the Mac.** A tendcf-rendered service; Mac and Android ship JSONL over R14; the archive indexes. **G8 state 1 is reached when** one Mac and one Android device converge from Nix-authored config, refuse an unsigned or unhandshaken update in a test, and the Mac holds both devices' logs; and Step 8 has landed (B8 sub 3: state 1 is declared only once score, explanation, highlighting and TUI land). | 1 | +> | 8 | **AI scanner and TUI.** AI scanners under §9.12's ceilings; the TUI on the borrowed scaffold (Toad and textual-diff-view, ruled, B12); both modes complete. G4 stays whole in state 1; there is no "state 1.5". | 1 | +> | 9 | **macOS as client.** Further Macs; nix-darwin passthrough (§14.1 for the workstation); pull and self-update; the `monitor` role (state 2; ruled, B4 rider). | 2 | +> | 10 | **Linux as server.** pastebin through the full gate; the systemd renderer in the compiler; the unit-writer detector. | 2 | +> | 10b | **Linux as client.** NixOS passthrough beyond reporting; distro default. | 2 | +> | 11 | **Retire `~/ops`.** Every operator device on tendcf; the release-train replacement (#2) proved. **G8 state 2.** | 2 | +> | 12 | **Strangers.** Public install docs, the authoring guide for the user's AI (R13), first non-operator enrolment (multi-version render returns, §9.6), trust tiers, TUF emergency role and runbook, optional advisor delegation. **G8 state 3** when someone the operator has not helped installs and keeps using it. | 3 | +> | 13+ | Demand: ordering inference (D16; deferred explicitly, ruled, B4 rider), builder/cache, APK provenance, WoT as advisor tools, composition with site-shared and foreign inputs (`explain-hunk`), branch management (G9). | later | +> +> Reporting ("what changed, what is dirty, what release am I on") is an adoption requirement, not an observability extra. The §9.9 schema family and its §14.2 review gate Step 3, as before. + +**Differences from the other proposal** (the guide response's build order, G-§18-02, as corrected after checking; from the independent checker's comparison; the two proposals are kept separate so the owner can choose): +1. **First step.** Here the Nix frontend comes first (1) and the Mac second (2); the guide has the fork on the Mac first and Nix authoring second. The checker notes the Mac today runs Homebrew upstream CFEngine 3.29.0 with the guide §19 data-path defects, which slightly favours the fork first; the two steps are otherwise independent. +2. **Step 0.** Only this proposal has a Step 0 (merge #41 and #42, the D46 restructure, the ruled schema additions). The checker finds it better supported on #41 and #42, which touch only platform-neutral files and so close the interlock fail-open on the Mac too; on the schema additions, it argues against bumping before Q19 and Q20 are ruled, which the corrected Step 0 now respects. (Both PRs merged 2026-11-14; which schema version the additions take is the next unused version (v7 or later) and how they group is ruled (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides.) +3. **Validator and signing.** Both now put the validator first and signature verification with signed releases after it: here validator (3), owner review (4), signed release (5); the guide validator (3), then signing and the handshake (4), flagged for a ruling. +4. **Safety scan and TUI.** Here mechanical scanning and the CLI are at Step 4 and the AI scanner and TUI at Step 8; the guide puts all scanning, AI included, and the TUI at its Step 7 inside state 1. G4 names AI among the scanners, so a state 1 without them ships a partial G4. Ruled (B8 sub 3, "1. Build order, not scope"): G4 stays whole in state 1; the CLI diff and `y/N` is built first, and state 1 is declared only once score, explanation, highlighting and TUI land; the table's Step 8 is state 1 and there is no "state 1.5". +5. **Owner signature.** Here an owner key signs at Step 4 (supersedes D39, needs that ruling); the guide's Step 3 takes accept or refuse with no key specified. +6. **Peer actions.** The guide schedules ShizukuPlus start-over-ADB as a state-1 step (its 6); this proposal has no peer-action step. The checker finds the guide better supported here. +7. **Monitoring.** Here the `monitor` role is at Step 9, state 2, matching G8.1's literal text; the guide puts it in state 1 (its Step 6). Ruled: "1. State 2" (`operator ruling, 2026-11-14, B4 rider, monitor role`): state 1 needs only the log archive (G8.1). +8. **Extra-entry reporting.** Here only the Linux unit-writer detector comes before retiring `~/ops`; the guide has a separate step with launchd and Android detectors before migration. The checker finds the guide better: retirement needs `not-yet-migrated` counts on macOS and Android too. +9. **Linux.** Both now keep G5's order 4 then 5 (here 10 and 10b, as corrected; the guide 12 and 13). This proposal moves nix-darwin passthrough to Step 9. +10. **Inference.** Both defer it with a ruling flagged: here to "13+ Demand" (added after checking), the guide to "Later" (G-§10-01). Ruled: "1. Defer explicitly" (`operator ruling, 2026-11-14, B4 rider, D16`): D16's ordering inference is recorded as deferred. +11. **macOS CI.** Here Step 2 names a macOS CI job (ruled); the guide's Step 1 says only "the CI build action". Ruled: the explicit macOS CI step is folded into the guide's order (B4). +12. **State 3.** Here public docs, the authoring guide, first non-operator enrolment, the TUF emergency role and advisor delegation (12); the guide has the publishable layer and a root ceremony a novice can complete, then the `consented` tier. Complementary; the emergency-role deferral (M-§9-04) is a ruling the guide does not propose. +13. **When state 1 is reached.** Here refusing an unsigned or unhandshaken update in a test; the guide requires each device to refuse both a release failing the handshake and a diff its owner refused. The checker finds the guide's test closer to G4. +14. **Plugins.** Step 0 here does the D46 restructure as decided; the guide's G-§4-01 cuts out-of-tree entry points (amends D46). One ruling covers both: "1. Defer out-of-tree discovery" (`operator ruling, 2026-11-14, Smaller 5`): D46 is amended with G-§4-01's text (all plugins in tree, compile-time only, never on a device; Python entry-point discovery deferred until a user needs one and out-of-tree plugins can be pinned). + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`): adopt draft D47-D50 as corrected (M-§15-01..04), "guide's build order as base with the map's Step 0 and an explicit macOS CI step folded in". The base is therefore the guide's order (G-§18-02 in `02-response-guide.md`, which carries the ruled text); the table above is this response's proposal, kept as the source of Step 0 and the macOS CI step, and rows that differ from the guide's order are not adopted unless a difference item above says "Ruled". D16 is deferred explicitly ("1. Defer explicitly", B4 rider); the `monitor` role is state 2 ("1. State 2", B4 rider); Linux is "later in the order, not paused" ("1. Order language"); the pastebin canary stays ("1. Keep it"). Smaller 5 (D46 plugin entry points, "1. Defer out-of-tree discovery") is applied in Step 0. B8 sub 3 ("1. Build order, not scope") is applied in Steps 4, 7 and 8. B3's phone review surface (X-safety-08, "1. Native screen + Termux", `operator ruling, 2026-11-14, B3 sub 4`) replaces the original map's Step 9 "consent surface" row: one review document (R14) is rendered three ways (CLI `--plain`/`--json`, the Textual TUI including Termux and SSH, and a native screen in `tendcf-agent`); the goldens hold all three and the renderers compute nothing; the agent notification opens the native screen with Accept and Refuse; the Termux CLI/TUI is the operator's path; no answer means held, and a refusal is logged. Ruled; the map's §13 carries the adopted order as its stage table (2026-11-14, the rulings commit of this PR). Numbering: this response's "Step N" is its own proposal; the adopted order's two numberings are the guide's Steps 0-15 and the map's Stages 0-16, which are the same order with the macOS CI job split out of guide Step 1 as map Stage 2, so guide Steps 2-15 are map Stages 3-16 (Step N is Stage N+1); "Step 8" and "Steps 3 and 7" cited elsewhere in the review documents are guide numbering unless they say "Stage". Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): the VM may enforce early as an explicit, ruled exception like pastebin's: canary only, operator-authored data (its root `cf-execd` enforcement at the stage 1 / guide Step 1 VM stands as an exception to D45's "`tendcf-validate` before any further host is enforced"). The order is not changed. + +**Merge:** replace the section with the guide's ruled order carrying Step 0 and the macOS CI step. Ruled (operator ruling, 2026-11-14, B4); amends D16 (deferred), D22 and D46. +**Checked:** inferred (the ordering is a proposal); the inputs it rests on were verified as cited in the items above; independently checked 2026-11-13: weakened, corrected + +--- + +## §15 Decision register + +### M-§15-01: Draft D47, the goal (supersedes D8's wording and §0 items 1 and 3) + +**Target:** §15, after D46 +**Kind:** add +**Goal:** G1, G4, G8 +**Weight:** blocks-goal +**Finding:** The 2026-11-13 goal is the operator's ruling but has no register entry. Whether D8 "Sovereignty is the point" is superseded in emphasis is this response's reading, not a ruling. +**Evidence:** map:1209; goal-definition:3-5, 75-89. +**Proposed text:** + +> | D47 | Goal | **Operator, 2026-11-13.** The goal is G1–G9 of [`../review-2026-11-13/00-goal-definition.md`](../review-2026-11-13/00-goal-definition.md), as its rulings table records: primary aim "Adoptable tool" (row 1); first adopter "Nobody named yet." (row 2); finish line "The ladder of three states in G8" (row 7); wording "Agreed, with two changes to the draft", framing "focus on the user's freedom to control their own computing devices as they see fit", and "G9 added" (row 8). **Operator, 2026-11-14** ("1. Yes, supersede D8's wording"): adoption is the aim and see-and-refuse (G4) is its safety mechanism; this supersedes D8's "Sovereignty is the point" (the trust layer stays, as G4's mechanism) and §0 items 1 and 3. | + +**Ruled:** "1. Yes, supersede D8's wording" (`operator ruling, 2026-11-14, Smaller 3, M-§15-01`) and "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4`). D47's clause is ruled: adoption is the aim, G4 see-and-refuse is its safety mechanism; it supersedes D8 "Sovereignty is the point" (the trust layer stays as G4's mechanism) and §0 items 1 and 3. The "Proposed, not ruled" label is dropped. Ruled; merged as D47 into the map's decision register on 2026-11-14 (the rulings commit of this PR). + +**Merge:** insert after D46. Ruled (operator ruling, 2026-11-14, Smaller 3 and B4). +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§15-02: Draft D48, the platform order (supersedes D22 and the 2026-10-29 Linux-first ruling) + +**Target:** §15, after D47 +**Kind:** add +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** D22 reads "macOS, Linux. Android deferred". G5 reverses the deferral and puts Linux fourth and fifth. +**Evidence:** map:1221; `docs/architecture/linux-targets.md:3-4` (per digest B1). +**Proposed text:** + +> | D48 | Platform sequence | **Operator, 2026-11-13** (rulings row 6): "The first platforms should be MacOS as server and Android as client, followed by MacOS as client, followed by linux server, followed by linux client. Android is one of the most important pieces as it will be the major marketplace differentiator". Goal G5 (wording agreed, row 8) adds that Android management "works with Island/Insular profiles and with user-space ShizukuPlus". **Operator, 2026-11-14** ("1. Adopt D47-D50"): this supersedes D22 and the 2026-10-29 Linux-first ruling and Android deferral ([`linux-targets.md`](../architecture/linux-targets.md)). Linux is later in the order, not paused ("1. Order language"). Linux work already done stays: pastebin's canary keeps running as the standing proof ("1. Keep it"; operator, 2026-10-31). | + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4, M-§15-02`), D48 as corrected: it carries only the operator's text, with the Linux order wording of B4 rider "1. Order language" and the canary of B4 rider "1. Keep it". D48 supersedes D22 and the 2026-10-29 Linux-first ruling. The "Proposed, not ruled" label is dropped. Ruled; merged as D48 into the map's decision register on 2026-11-14 (the rulings commit of this PR). The merged D48 row carries only the operator's text and the two riders (order language, canary). + +**Merge:** insert after D47. Ruled (operator ruling, 2026-11-14, B4). +**Checked:** verified (map; linux-targets via digest); independently checked 2026-11-13: weakened, corrected + +### M-§15-03: Draft D49, Nix first (amends D12's equal frontends) + +**Target:** §15, after D48 +**Kind:** add +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** D12 says "Two equal frontends". G2 says real Nix first, with YAML/JSON beneath as the data form Nix evaluates to. Whether byte-identical twins survive as a test is open. +**Evidence:** map:1211. +**Proposed text:** + +> | D49 | Authoring | **Operator, 2026-11-13** (rulings row 4): "Real Nix first, YAML beneath." Goal G2 (wording agreed, row 8): config is written in the real Nix language with NixOS-style options, so existing NixOS and nix-darwin configs carry over; plain YAML/JSON sits beneath it as the data form Nix evaluates to and can be written by hand; what a person is shown reads clearly without manuals. **Operator, 2026-11-14** ("1. Adopt D47-D50"): this amends D12 (Nix is first, not one of two equals). Nix may be required to build a release, at build time only ("2. Allow on release path", "1. Build-time only"; amends R5 and D6, M-§2-04). Still open, needs the operator's ruling: whether `schema/` or the Nix module options is the schema authority (map §4.1 currently says JSON Schema is generated from the module options; §16 Q23), and whether a byte-identical YAML twin stays as the frontend's test. | + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4, M-§15-03`), D49 as corrected: it amends D12. D49 leaves the schema authority open (§16 Q23); that and the byte-identical YAML twin are not ruled. B7 ("1. Importer + matching names", `operator ruling, 2026-11-14, B7`) supplies the meaning of "carry over" in G2: a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin and NixOS where the meaning is the same. The "Proposed, not ruled" label is dropped. Ruled; merged as D49 into the map's decision register on 2026-11-14 (the rulings commit of this PR), with Q23 still open. + +**Merge:** insert after D48. Ruled (operator ruling, 2026-11-14, B4); the Q23 clause stays open. +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### M-§15-04: Draft D50, device shape, peer updates and server/client + +**Target:** §15, after D49 +**Kind:** add +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** G3 confirms D33 (no control node), amends D14's git-synced policy, and adds peer delivery and the vocabulary of service roles. It amends §9.11's push rule, and the handshake is undefined. +**Evidence:** map:917-920, 1214, 1232. +**Proposed text:** + +> | D50 | Device shape | **Operator, 2026-11-13** (rulings row 6b): "I am not trying to change the architecture; client and server are not entirely meaningful here as each device will be self-sufficient and able to take updates from any other device that uses the correct crytoographic handshake. So when I say server I am refering only to the machines that are a server for services like recieving and archiving logs and doing monitoring of other machines." Goal G3 (wording agreed, row 8): every device converges on its own and there is no control node. **Operator, 2026-11-14** ("1. Adopt D47-D50"): this confirms D33, amends D14's git-synced policy, and amends §9.11's push rule (peer delivery, R14). "The correct cryptographic handshake" means content checks ("1. Content checks; v0 first", B1): the update is signed by keys the device trusts, fresh, names this device, and carries the owner's approval; transport authentication decides only who may talk (§16 Q17 answered). | + +**Ruled:** "1. Adopt D47-D50" (`operator ruling, 2026-11-14, B4, M-§15-04`), D50 as corrected: it amends D14 rather than confirming it. The handshake: "1. Content checks; v0 first" (`operator ruling, 2026-11-14, B1`): G3's handshake means content checks (signed by trusted keys, fresh, names this device, owner approval); transport auth decides only who may talk. The first build is the SSH-signature v0 (`ssh-keygen -Y` over goal-file bytes plus a counter); the map's 2-of-3 offline-root floor may lag until TUF. §16 Q17 is answered; the state-1 root threshold (Q26) follows the "may lag" clause. The "Proposed, not ruled" label is dropped. Ruled; merged as D50 into the map's decision register on 2026-11-14 (the rulings commit of this PR). + +**Merge:** insert after D49. Ruled (operator ruling, 2026-11-14, B4 and B1). +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### M-§15-05: Draft D51–D57, the remaining 2026-11-13 rulings (none supersedes an entry; the clauses beyond the rulings are proposals) + +**Target:** §15, after D50 +**Kind:** add +**Goal:** G4, G6, G7, G8, G9 +**Weight:** improves +**Finding:** The remaining rulings add to the register without reversing an entry. D51 is consistent with D29, D53 settles §16 Q2's framing, and D54 states the status of what the fork ruling ("the fork is the destination") and D13 chose. +**Evidence:** map:1212, 1228; goal-definition:31-37, 51-70. +**Proposed text:** + +> | D51 | Safety scan | **Operator, 2026-11-13** (rulings row 8, G4 wording): "the diffs are also scanned in various ways including using AI for likely safety, and the user gets to see safety confidence out of 100% as well as an explanation of why that percentage was choosen and the code that is questionable should be hilighted in increasingly dramatic ways depending on safety". **Proposed, not ruled** (consistent with D29): the scan advises and never authorizes (§9.12). | +> | D52 | Review modes | **Operator, 2026-11-13** (rulings row 8): "we should borrow a TUI scaffold from another project, and have both command-line and TUI modes". Scaffold not yet chosen (§16 Q22). | +> | D53 | AI authorship | **Operator, 2026-11-13** (rulings row 5): "Taken as given; no experiment asked for." Goal G6 (wording agreed, row 8): that AIs write the configuration is the premise of the project, not a hypothesis it sets out to test. **Proposed, not ruled:** R13 and §9's writing rule rest on it; §16 questions 2 and 9 are re-posed accordingly. | +> | D54 | Instruments | **Operator, 2026-11-13** (rulings row 3): "Instrument, open to challenge." Goal G7 (wording agreed, row 8): CFEngine, the CFEngine fork, the Site Model and the compiler are instruments, and nothing about them changes without the operator's ruling. **Proposed, not ruled:** D13, D15 and the 2026-08-22 fork ruling hold as instrument choices. | +> | D55 | Finish line | **Operator, 2026-11-13** (rulings row 7): "The ladder of three states in G8": (1) one of the operator's Macs and one of his Android devices converge from Nix-authored config, with updates accepted only after the handshake and logs archived on the Mac; (2) his whole fleet runs on tendcf and `~/ops` is retired; (3) a person he has not helped installs it from the public docs with their own AI and keeps using it. (Ordering §13 against them is proposed in M-§13-01 and needs the ruling.) | +> | D56 | Branch management | **Operator, 2026-11-13** (rulings row 8): "G9 added." Goal G9: later, free-software branch management, built as an extension of the platform's existing patch patterns, so non-technical users can maintain forks of projects or plugins without knowing about merging, rebasing or compiling. **Proposed, not ruled:** those patch patterns are `overlay/`'s; extension point only before D55 state 3 (R20). | +> | D57 | First adopter | **Operator, 2026-11-13** (rulings row 2): "Nobody named yet." Goal G1 (wording agreed, row 8): the first adopters are sysadmins who already share configs in Nix. | + +**Merge:** needs the operator's ruling first (the clauses still marked "Proposed, not ruled"; D52's scaffold is ruled in part by B12 "2. Borrow both freely; raise Python", and D51's figure by B8 "1. Capped 0-100 score"); then insert after D50 +**Checked:** verified (each row against the goal file); independently checked 2026-11-13: weakened, corrected + +--- + +## §16 Open questions + +### M-§16-01: Answered or re-posed by the goal: Q2, Q9, and partly Q5 and Q6 + +**Target:** §16, items 2, 5, 6 and 9 +**Kind:** reword +**Goal:** G6, G3, G4 +**Weight:** improves +**Finding:** +1. Q2 asks whether the writing rule is an argument or a hypothesis. Under G6, AI authorship is the premise. What remains open is whether the local-knowledge rule is the right way to make that premise safe. +2. Q9 asks whether the project is hardening the wrong surface. G4's AI scan targets plausible-looking output, which is the failure Q9 names. +3. Q5 and Q6 (local-first, fleet-wide answers) are partly answered by R15's log archive, which gives a fleet view without becoming a source of truth. + +None of these calls for an experiment. +**Evidence:** map:1263, 1266-1269, 1279-1280. +**Proposed text:** + +> 2. ~~Is the writing rule an argument or a hypothesis?~~ **Re-posed 2026-11-13 (D53):** AI authorship is the premise. Open: is "prefer local knowledge, prefer machine-checkable" the right discipline to make AI-written config safe, and what does the G4 scan need from it? +> 5–6. **Partly answered 2026-11-13 (R15):** the log archive gives a fleet-wide view; each device's JSONL stays the record. Open: what monitoring asks of it. +> 9. **Re-posed 2026-11-13 (D51):** the G4 scan, AI among its scanners, is aimed at plausible-looking output types do not catch. Open: whether it catches it. + +**Merge:** replace items 2, 5, 6 and 9 +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§16-02: Standing, re-prioritized: Q13, Q15 and Q10 are now on the state-1 path + +**Target:** §16, items 10, 13 and 15 +**Kind:** reword +**Goal:** G5, G4, G1 +**Weight:** misleads +**Finding:** +1. Q13 (what protects the stored baseline; "Android under Termux is the awkward case") is no longer deferred work: it is platform 2. +2. Q15 (a device-local trust root buildable across three platforms by one person) now has an order: macOS, then Android. +3. Q10 (can a person consent to a diff) is what G1's long-run user turns on. It is a test of a display with people, not of AI authorship, so G6 does not exclude it. + +Q1, Q3, Q4, Q7, Q8, Q11, Q12, Q14 and Q16 stand unchanged. +**Evidence:** map:1281-1285, 1292-1301. +**Proposed text** (insert after the list): + +> **Priority under the 2026-11-13 goal.** Q13 and Q15 are on the path to G8 state 1 (macOS, then Android); Q10 is on the path to state 3 and is answered by putting the G4 review screens in front of a person without admin skill. The rest stand as written. + +**Merge:** insert after item 16 +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§16-03: New open questions from the goal + +**Target:** §16, after item 16 +**Kind:** add +**Goal:** G2, G3, G4, G5, G8, G9 +**Weight:** blocks-goal +**Finding:** Each of these blocks a step of the M-§13-01 order or a schema bump. Each is the operator's to answer. +**Evidence:** the items cited in each line. +**Proposed text:** + +> 17. **What is "the correct cryptographic handshake"** (G3, R14)? Peer authentication by device keys, release signature verification, or both, and is the owner's approval part of it? (M-§9-07) **Ruled 2026-11-14 (B1, "1. Content checks; v0 first"):** content checks (signed by trusted keys, fresh, names this device, owner approval); transport auth decides only who may talk. +> 18. **Which Mac is the G8 state-1 server**, and may the daily driver enforce under the minimal-claim rule? (M-§12-01) **Ruled 2026-11-14 (B6 sub 1, "1. macOS VM on bigmac"; B6 sub 2, "1. Dry-run only"):** an Apple Silicon macOS VM on bigmac enforces; bigmac itself runs dry-run only. +> 19. **What does "can refuse" mean on an operator-tier device:** a local yes per change, a hold window, or an enrolled standing approval? (M-§10-01) **Ruled 2026-11-14 (B2, "3 but also the existance of standing wait for user and standing refusal").** +> 20. **How are Android profiles modelled** (Island/Insular): own host, domain, or entry field? A schema bump. (M-§12-04) **Ruled 2026-11-14 (B3 sub 1, "1. Field on entries").** +> 21. **Does Android run `tendcf-validate` in Termux** instead of a Kotlin port? (M-§12-06) **Ruled 2026-11-14 (B3 sub 2, "1. Termux + Kotlin trust check").** +> 22. **Which TUI scaffold** is borrowed? (R18) **Ruled 2026-11-14 (B12, "2. Borrow both freely; raise Python"):** Toad and textual-diff-view. +> 23. **Which side is generated:** Nix options from `schema/`, or JSON Schema from Nix options? (M-§4-01) +> 24. **What does the `monitor` role watch,** and what does it do on a finding, given that it may not change another device? +> 25. **What are the scan's ceiling values,** and how is a confidence figure calibrated so that 90% means something? (M-§9-03) **Ruled 2026-11-14 (B8 sub 1, "1. 09's table, top 95"):** the cap values are in M-§9-03; calibration against a labelled corpus is later. +> 26. **What root threshold does a one-operator G8 state 1 use?** (M-§9-04) **Partly ruled 2026-11-14 (B1):** the 2-of-3 offline-root floor may lag until TUF; the first build is the SSH-signature v0. +> 27. **What does "carry over" mean** for an existing NixOS or nix-darwin config on a host that does not run Nix? Evaluated through tendcf's own option set (a reimplementation of NixOS modules), or only as passthrough? (G2) **Ruled 2026-11-14 (B7, "1. Importer + matching names"):** a one-shot importer for pure-data option families, plus matching option names. + +**Merge:** insert after item 16; renumber to the guide's §20 numbering once both lists are ruled; map:1252 says §16 keeps the guide's order and numbering, and the guide response's new questions 17-26 differ in content +**Checked:** verified (each cross-reference exists in this file); independently checked 2026-11-13: weakened, corrected + +--- + +## Drift (§ various, against the guide and repo) + +### M-§12-08: "First host: vps-primary" contradicts linux-targets and the record + +**Target:** §12, "**NixOS / nix-darwin (passthrough).**", at "First host: vps-primary." +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** vps-primary is "not in the first milestone (operator)", and stage C ran on get.sipb.cloud first. vps-primary has the module imported but not enabled. +**Evidence:** map:1004; digest-current-plan D1 (linux-targets:13-14; nixos-passthrough:128-133). +**Proposed text:** + +> First host: get.sipb.cloud (stage C, report only, `cf-execd` off); vps-primary is not in the first milestone. + +**Merge:** replace that sentence +**Checked:** verified (via the phase-1 digest; linux-targets itself not re-opened); independently checked 2026-11-13: confirmed + +### M-§12-09: §12 item 4's "the schema is at v4 and v5 is in flight" is stale + +**Target:** §12 open item 4, at "Timing: the schema is at v4 and v5 is in flight" +**Kind:** correct +**Goal:** G7 +**Weight:** misleads +**Finding:** v5 landed on 2026-11-02 (and v6 on 2026-11-14), so the "rides that bump" window has closed. An implementer reading this could believe an `agent` id change is still free. +**Evidence:** map:1103-1106; `schema/goal-file.schema.json:11` (`"const": 5`). +**Proposed text:** + +> Timing: v5 landed on 2026-11-02 and v6 on 2026-11-14 (C-policy-01, PR 52, 83d7280), so an id change now costs the next unused schema version (v7 or later) and a baseline ceremony per device; it rides the same bump as the Android profile model (§16 Q20; ruled, B3 sub 1). Whether the standing-modes approval record shares that bump is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. + +**Merge:** replace those sentences. The text as first proposed ("an id change now costs v6") is superseded: v6 shipped for a different change, so it cannot carry these +**Checked:** verified; independently checked 2026-11-13: confirmed + +### M-§13-02: Guide §18 still lists Android as Step 2 with no deferral, and the map and guide disagree + +**Target:** §13 Step 2 "Deferred (operator, 2026-10-29)" against guide §18 Step 2 "Android under the Site Model | Same vocabulary." +**Kind:** ruling-drift +**Goal:** G5 +**Weight:** misleads +**Finding:** The map says "where this file and that guide disagree on the current design, the guide wins", and the guide does not record the 2026-10-29 deferral. The irony is that the guide's stale text is now closer to G5 than the map's. Whatever order is ruled, both tables must change in one commit, and the map should stop carrying its own copy of the order, pointing at one table instead. +**Evidence:** map:10-11, 1160; guide:1366. +**Proposed text:** + +> (Map §13 header) The build order is kept in one place, this table; the guide's §18 summarizes it and links here. + +**Merge:** the build order is ruled (operator ruling, 2026-11-14, B4: "1. Adopt D47-D50", the guide's order as base); the guide-wins rule on which document owns the build order still needs the operator's ruling +**Checked:** verified (both tables); independently checked 2026-11-13: confirmed + +--- + +## Nits + +| ID | Target (quoted phrase) | Finding | Proposed fix | +| --- | --- | --- | --- | +| M-nit-01 | Header "**Date:** 2026-08-15 (§9 rewritten for Model B; D43/D44 added)" | Amended through 2026-11-13 (D45, D46) | "Last amended 2026-11-13 (D46)" | +| M-nit-02 | §16 "Compressed from guide §19, in its order and numbering" | The guide's open questions are §20; §19 is "What we found underneath" (guide:1383, 1529) | "guide §20" | +| M-nit-03 | §9.1 "File the upstream `--simulate-output=json` issue before Step 3 code." | Step 3 code exists; the fork carries `--simulate-json`; upstream contact is cut except simulate-json (digest-history E) | Delete, or "The fork carries `--simulate-json` (upstream-overlay §2)." | +| M-nit-04 | §2 jumps R5 → R7/R10 → R11 | R6 (Gradle for APKs), R8 (trust layer minimal safe implementations) and R9 (literate programming) were dropped from v2 without a register line (deprecated v2:183-196). R6 matters again under G5 | Add "R6, R8, R9 dropped 2026-08-15" or restore R6 | +| M-nit-05 | §3 "A host identity in trust and ChangePlans is the **device public key**" | "ChangePlans" is Model A vocabulary; under D43 it is goal files and approval records | "in trust policy, goal files and approval records" | +| M-nit-06 | §6 "Deployment: every host runs its own `cf-serverd`, policy from the signed release via git" | No host runs `cf-serverd` (installer grep: no hits); "via git" predates the TUF release | Mark "planned (R14 transport)" | +| M-nit-07 | §13 Step 1 "Dry-run default" vs pastebin enforcing | The only enforcing host is Linux; Step 1's dry-run reads as the project's posture | Fold into M-§13-01 | +| M-nit-08 | §12 "Distro choice open until this step." | Debian 13 is the live host and v5 is dpkg-specific | "Debian 13 first (pastebin); rpm needs a schema bump" | +| M-nit-09 | §17 "`frdminc/nix2cf` — compiler tool (Step 3) until 2026-11-13" | Fine, but `tendcf-validate-proposal` "deciding nothing" is stale for Q10/Q12 (digest D8a) | Add "(Q10 and Q12 decided 2026-11-02)" | +| M-nit-10 | §4.1 "Lookup CLI (D24, D40)" | Unbuilt (compile.py:118, :322 per inventory) | Add "not built" | + +--- + +## Ideas and risks + +1. **The score becomes the decision.** A figure out of 100 invites "accept if ≥ 90" scripts, and then the AI's opinion authorizes in practice even though §9.12 says it never does. Rendering the explanation and the highlighted hunks before the number, and never offering a threshold-accept option in the tool, keeps G4's "owner sees and refuses" real. +2. **Prompt injection through the diff.** Service names, argv and file contents in a hunk are attacker-reachable text that the AI scanner reads. The mechanical ceilings (M-§9-03) are the defence: a scanner talked into "safe" still cannot lift a privileged hunk above its cap. Add a §14.3 red-team on exactly this path before Step 8. +3. **The Nix frontend is the largest unestimated item on the state-1 path.** "Existing NixOS configs carry over" can silently grow into reimplementing NixOS modules (`services.*`) for non-Nix hosts. Question 27 should be ruled before Step 1 starts, and the first cut kept to tendcf's own option tree. +4. **Two big unknowns land on Android at once:** the fork building under Termux/bionic and the profile model. A one-day spike that builds the fork in Termux on the actual device, before Step 0's schema bump, de-risks the most important platform cheaply. +5. **Documentation gravity.** The digests show docs at about 70k added lines against about 5k in the compiler, and the largest recent specs are Linux report-only detection, which G5 now places in state 2. A rule that each §13 step closes with a runnable demonstration on a real device would keep the new order from being written rather than built. +6. **Dogfood the server role.** Rendering the log-archive receiver as an ordinary tendcf service record on the Mac makes the first "server" prove the launchd adapter, the gate and the review screen at once, with no special-case install path. +7. **Use CFEngine's own key handshake for R14.** cf-serverd/cf-agent already authenticate by RSA keys (`ppkeys`). Pinning them explicitly, rather than through address-based `trustkeysfrom`, may give G3's handshake almost for free, with TUF signatures on top for content. Worth checking whether the fork's protocol builds on Termux. +8. **Owner key loss.** Moving the signature from an advisor key to an owner key (M-§9-05) makes the owner key's loss a lockout of that device. The recovery story belongs with Q26's root threshold, not after it. +9. **G9 can shape today's overlay tooling cheaply.** `bin/overlay.py` already has manifest, drift and retirement checks. Keeping its data model user-facing (one patch = one named intent with a plain-language reason) costs little now and is the seed of G9. +10. **The map and the guide each carry a build order and requirement prose, and they drift** (M-§13-02, Android). With the goal now explicit, one owner per fact (the goal file for aims, the map for order and decisions, the guide for explanation) would stop a fourth copy appearing. + +Not checked: live hosts; PR #41 and #42 state today; CI; whether the fork builds on macOS outside the dev build or on Termux at all; ShizukuPlus behaviour across work profiles; the guide outside §1, §18 and §20 headings; linux-targets.md and nixos-passthrough-plan.md themselves (relied on the phase-1 digest); `compiler/` source beyond the two grep hits. + +Last search run: Learning CFEngine (Basic Memory `books`, then `book-kb query 'trustkeysfrom|ppkeys'`) confirmed cf-serverd's key-trust mechanism cited in M-§9-07 and Idea 7. The firecrawl search for CFEngine key exchange returned only irrelevant hits. + +## Withdrawn after checking + +None. The independent checker refuted no item in this document. diff --git a/docs/review-2026-11-13/04-response-plans.md b/docs/review-2026-11-13/04-response-plans.md new file mode 100644 index 0000000..1a5bba1 --- /dev/null +++ b/docs/review-2026-11-13/04-response-plans.md @@ -0,0 +1,913 @@ +# Response: the platform and implementation plans, measured against the 2026-11-13 goal + +**Targets:** `docs/architecture/linux-targets.md` (L), `docs/architecture/nixos-passthrough-plan.md` (N), +`docs/architecture/plugin-layout.md` (PL), `docs/architecture/tendcf-validate-proposal-2026-11-03.md` (V), +and cross-cutting (X): `change-process.md`, `upstream-overlay.md`, `README.md`, `docs/architecture/README.md`, +`AGENTS.md`, `compiler/**/*.md`, handoffs `3a99` and `7c41`. + +**Base commit:** eefea3c + +**How this was produced:** one reviewing agent (Claude Opus), then an independent checking agent that tried to +refute each finding; nothing was executed, and nothing was run under Nix. Each item's **Checked:** line records +the independent check's verdict (2026-11-13) where it ruled on the item. Refuted claims are listed under +"Withdrawn after checking" at the end. + +**Item counts by Weight, after corrections:** blocks-goal 14, misleads 18, improves 19, nit 1 (52 items), plus 9 nits in the +Nits table. Independent check: 20 items confirmed, 15 weakened and corrected, X-AR-01 corrected under C1; one idea +withdrawn (and L-§5-09's original remedy). + +Reviewer: Claude Opus 5.5 (p2-plans slice), read-only, 2026-11-13. Base `eefea3c`. +Targets: `linux-targets.md` (L), `nixos-passthrough-plan.md` (N), `plugin-layout.md` (PL), +`tendcf-validate-proposal-2026-11-03.md` (V), and cross-cutting (X): `change-process.md`, +`upstream-overlay.md`, `README.md`, `docs/architecture/README.md`, `AGENTS.md`, `compiler/**/*.md`, +handoffs `3a99` and `7c41`. Items are in section order within each target. A short status table +for the work in flight is in X-WIP. Nits are in one table at the end. + +Sources consulted: firecrawl search + scrape of the NixOS manual's modular-services section +(`system.services.`, `_class = "service"`, `process.argv`) through an unofficial mirror; the section says +"new in NixOS 25.11" and links https://github.com/NixOS/nixpkgs/pull/372170. The independent check read the +canonical page (https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/development/modular-services.md) +and nix-darwin/nix-darwin#1765; see L-§5-09. Nothing else was searched. + +Local checks run: read every target in full (the validator proposal in four spans, all of it); `git worktree list`; +`gh pr view 41/42`; `rg` over `docs/architecture`, `schema/`, `.github/workflows/`; `ls deploy policy/templates`; +`command -v nix nix-instantiate darwin-rebuild` printed nothing on this Mac, and neither `/nix/var/nix/profiles/default/bin/nix` nor +`/run/current-system/sw/bin/darwin-rebuild` exists (`/etc/nix` has only `macos-keychain.crt`, `sentry-endpoint`). + +Other `docs/architecture/` files: **opened** `architecture-DEFINITIVE-v3.md` (§13 build order, §14, +D6/D12 rows, the nix-darwin lines only) and `site-pika-requirement-change-2026-08-13.md` (header only). I also searched the whole directory for Android, +Island/Insular, Shizuku, macOS, logs, monitoring, peer and signing. **No file mentions Island or Insular. No file +plans a log archive or monitoring service, macOS install, Android install or peer transport.** Left unopened: all +`upstream-*`, `UPSTREAM-*`, `*-BRIEF.md`, opinions, reconciliations other than as cited, `GLOSSARY.md`, +`upstream-register.md`, `deprecated/`, `fork-integration-2026-10-29/`. Also read, outside the targets: +`tendcf-s5-design-wt/docs/architecture/s5-unit-detector.md` §11. + +--- + +## L: `docs/architecture/linux-targets.md` + +### L-hdr-01: header still says Linux first and Android deferred + +**Target:** `docs/architecture/linux-targets.md` header blockquote, at "Android/Termux is deferred;" / "Linux is the platform" (two lines of the blockquote) +**Kind:** ruling-drift +**Goal:** G5 +**Weight:** misleads +**Finding:** The header states the 2026-10-29 order as current. G5 reverses it: macOS server, then Android client, then macOS client, then Linux server, then Linux client. The header also says Linux is the platform for "build-order Steps 1 and 3", but map §13 Step 1 is "macOS services adapter", so the sentence contradicted the map even before G5. +**Evidence:** `linux-targets.md:3-4`; `architecture-DEFINITIVE-v3.md` §13 row 1 ("macOS services adapter. Dry-run default. No nix-darwin."); goal G5. +**Proposed text:** + +> Operator ruling, 2026-10-29, **superseded in its ordering by the goal of 2026-11-13** (G5: macOS server, Android client, macOS client, Linux server, Linux client). Status: superseded in its ordering by the goal of 2026-11-13 (G5). Linux is fourth and fifth in line; finished pieces stay as standing proofs. Nothing here is deleted. + +**Merge:** replace the blockquote; needs the operator's ruling first if "paused" is to be kept; ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept (G5 orders the platforms; no ruling pauses Linux work) +**Checked:** verified (read both files); independently checked 2026-11-13: weakened, corrected + +### L-§1-02: the target table has no macOS or Android device + +**Target:** §1 "Targets", the table beginning "| T1 | GitHub CI" +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** G8 state 1 names "one of the operator's Macs and one of his Android devices". No document names either one, records its OS version, or says which Mac is the server (log archive) Mac. Every row in the table is Linux or a Linux container. The Mac rows need macOS version, architecture and whether it runs nix-darwin. The Android row needs Android version, profile layout (Island/Insular), and whether ShizukuPlus/ShizukuTendCF is installed. +**Evidence:** `linux-targets.md:8-16`; `rg -il 'insular|island' docs/architecture` returns nothing. +**Proposed text:** + +> Targets for the first milestone (G8 state 1) live in a separate file, `docs/architecture/first-milestone-targets.md` (to be written): M1, the operator's server Mac (receives and archives logs); A1, one Android device (Island/Insular profiles, ShizukuPlus). The rows below are the Linux targets. Their work comes later in the order, not paused (G5 places Linux fourth and fifth; B4 rider, "1. Order language"). + +**Ruled (which Mac):** "1. macOS VM on bigmac" (operator ruling, 2026-11-14, B6 sub 1, 13 E-2): state 1's Mac (M1, the server Mac) is an Apple Silicon macOS VM (tart / Virtualization.framework) on bigmac (MacBookPro18,1): current macOS, snapshot and rollback, CI can run the same image; it is a client, not an always-on server. "1. Dry-run only" (B6 sub 2, M-§12-01 / Q18): bigmac may run tendcf in dry-run (compute and report the diff, log drift, apply nothing); the VM is the only enforcing Mac in state 1. Note: the VM is also the G8 log-archive server, reachable only while bigmac is awake; devices buffer JSONL. "1. Root in VM, user on bigmac" (B6 sub 3): the enforcing VM runs tendcf as a root LaunchDaemon, bigmac's dry-run runs as a user LaunchAgent, no root; state 1 must verify the root launchd render path (skipped by the WarpBuild spike). Ruled exception (operator ruling, 2026-11-14, PR 62 review Q1, "2. Exception for the VM"): the VM may enforce early as an explicit, ruled exception like pastebin's: canary only, operator-authored data (its root `cf-execd` enforcement at the stage 1 / guide Step 1 VM stands as an exception to D45's "`tendcf-validate` before any further host is enforced"). The order is not changed. Rider: "Try to cut down the MacOS VM image so be smaller, remove stuff we don't need." (B6 sub 1 rider): the state-1 macOS VM image is minimised, starting from the smallest base (vanilla, not a dev-tools image) and stripping what state 1 does not need; queued as build work. Which Android device (A1) is not ruled. Ruled; implementation pending. + +**Merge:** the Mac is ruled (M1 is the VM on bigmac); which Android device still needs the operator's ruling +**Checked:** verified (table read; grep); independently checked 2026-11-13: confirmed + +### L-§3-03: say what each Linux step is worth to the macOS-plus-Android milestone + +**Target:** §3 "Order", after the table +**Kind:** add +**Goal:** G5, G8 +**Weight:** improves +**Finding:** Much of the Linux work is platform-neutral or has a direct macOS counterpart. The plan does not say which. Without that list, pausing Linux may be read as discarding it. Several pieces carry straight over: the fail-closed flavour guard (step 3) already lets launchd act only on `darwin`; schemas v2–v5 carry the `supervisor` fact and the `launchd` writer vocabulary; the root-owned prefix and root `cf-execd` install shape (step 7) is the shape a macOS LaunchDaemon install needs; and the policy harness runs on the Mac. Other pieces are Linux-only and should pause: the systemd renderer (step 6), dpkg claims (v5), and the NixOS passthrough (step 8). +**Evidence:** `linux-targets.md:35-40`; `policy/templates/launchd.plist.mustache` exists; `deploy/` holds only `linux/`; the compiler renders launchd only (`compiler/README.md` "Units for any supervisor but launchd"). +**Proposed text:** + +> **Under the 2026-11-13 goal (G5).** Finished, kept as standing proofs: steps 2, 3, 5, 7 (pastebin's canary, under its root `cf-execd`) and 8 stage C (get.sipb.cloud). Carried to macOS unchanged: step 3's guard; the schema v2-v5 vocabulary; `tests/policy/run.sh`. Carried to macOS as a pattern, to be rewritten: step 7's root-owned prefix and install (`deploy/linux/tendcf-install.sh` has no macOS twin; a LaunchDaemon replaces `tendcf-execd.service`); step 2's CI fork build (Linux runners only). Later in the order, not paused: step 6's systemd renderer, the v5 dpkg claims and detector, and step 8 beyond stage C. The macOS adapter (map Step 1) and the compiler's launchd renderer are already the most advanced pieces in the repository. + +**Merge:** insert after the table; needs the operator's ruling first ("Paused": G5 orders the platforms, and no ruling pauses Linux work); ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified (files listed; compiler README read); the macOS run of `run.sh` comes from AGENTS.md and was not rerun + +### L-§3-04: step 6 should say it comes after macOS and Android, and name the compiler work G8 needs + +**Target:** §3 row 6, at "Compiler (`tendcf compile`, was nix2cf; map D46): systemd renderer" +**Kind:** reword +**Goal:** G2, G5 +**Weight:** misleads +**Finding:** Step 6 says the next compiler work is the systemd renderer. For G8 state 1, the compiler needs three other things: a Nix frontend (G2), an Android platform and supervisor (G5 #2), and nothing new for launchd, because that renderer exists. As written, the row sends the next compiler slice to Linux. +**Evidence:** `linux-targets.md:38`; `compiler/docs/DESIGN.md` platform↔supervisor row ("`android`, is refused"). +**Proposed text:** + +> | 6 | Compiler (`tendcf compile`; map D46). **After macOS and Android in the goal's order (G5, 2026-11-13):** the systemd renderer and the Linux `TODO(operator)` markers. The compiler work for the first milestone is the Nix frontend (G2) and an Android platform and supervisor, neither in this file. The compiler emits only the goal file; Augments stay on the device (`projector.py`). | + +**Merge:** replace the row; needs the operator's ruling first if "paused" is to be kept; ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### L-§4-05: the "Consequences of deferring Android" section is obsolete, and its Termux premise is open + +**Target:** §4 "Consequences of deferring Android", item 1, at "The `termux` Site Model block, the `runit` goal-file flavour" +**Kind:** question +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** Android is no longer deferred. Item 1 and map §12 assume Android runs Termux with runit services, alongside tendcf-agent and a 'Shizuku-class helper'. G5 adds Island/Insular profiles, which no document or schema models (no work-profile versus personal-profile split), and names ShizukuPlus specifically. Neither profiles nor ShizukuPlus is a service supervisor. Item 2 already allows that "Android may still change the adapter shape later". That cost is now due. It is cheapest before any device holds a baseline, and the validator proposal confirms none does (fact 12). +**Evidence:** `linux-targets.md:44-48`; `schema/services.schema.json:64` (`platform` enum includes `android`), `:114` (`termux`); `tendcf-validate-proposal-2026-11-03.md` §0 fact 12. +**Proposed text:** + +> ## 4. Android (no longer deferred; G5 places it second) +> +> The `termux` block, the `runit` flavour and the `android-termux-services` fixture stay until the Android adapter is designed. Open, for the operator: whether Android devices are configured through Termux services at all, or through the profile (Island/Insular) and ShizukuPlus surfaces G5 names; the answer decides whether `runit` is an Android supervisor or only a Linux one. A schema change for it costs no baseline ceremony while no device holds a baseline. + +**Merge:** replace §4's heading and item 1–2; needs the operator's ruling first (Android shape) +**Checked:** verified (schema grep, docs grep); independently checked 2026-11-13: weakened, corrected + +### L-§4-06: report rows now have a destination, the Mac log archive + +**Target:** §4 item 3, at "D18's report rows need a Linux writer. Open." +**Kind:** reword +**Goal:** G3, G8 +**Weight:** improves +**Finding:** G3 defines a server as a machine that receives and archives logs. G8 state 1 requires "logs archived on the Mac". So the open point is no longer "who writes rows on Linux". It is two questions: what writes rows on macOS and Android, and what service on the server Mac receives them. No document plans that receiving service. Validator picklist 11 is the closest, and it assumes a pusher collects rows over SSH (see V-§10-10). +**Evidence:** `linux-targets.md:49-51`; goal G3, G8; `tendcf-validate-proposal-2026-11-03.md` §10 item 11. +**Proposed text:** + +> 3. Report rows (D18) go to the log-archive service on a server device (G3; on the first milestone, the operator's Mac). On macOS `tendcf-validate run` writes them; on Android tendcf-agent does. The receiving service, its transport and its authentication are not designed. + +**Merge:** replace item 3 +**Checked:** verified (docs grep: no log-archive design) + +### L-§4-07: `tendcf-validate` is described as Linux-only + +**Target:** §4 item 5, at "the Linux device-side component" +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** Map D45 and the validator proposal both scope `tendcf-validate` to every host other than Android ("on Linux and macOS"). With macOS first, calling it the Linux component misplaces the first build. The item also says it is "built ... before any further host is enforced". The first further host is now a Mac. +**Evidence:** `linux-targets.md:54-61`; `tendcf-validate-proposal-2026-11-03.md` title and §3 ("on Linux and macOS"); map line 108 ("CFEngine plus the `tendcf-validate` command, with no daemon (D45)"). +**Proposed text:** + +> 5. **`tendcf-validate`** (map D45): the device-side component on macOS and Linux (Android has tendcf-agent), a Python command (`bin/projector.py` promoted) that validates the approved goal file and writes `host_specific.json` before cf-agent reads it; no daemon. Which host it is first enforced on is for the operator (G5 puts the server Mac first). + +**Merge:** replace the first sentence of item 5 +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### L-§5-08: "equal frontends" contradicts G2 + +**Target:** §5 "Nix", at "YAML and Nix are equal frontends" +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** misleads +**Finding:** G2 and ruling 4 say "Real Nix first, YAML beneath": YAML/JSON is the data form that Nix evaluates to, and it can be written by hand. "Equal frontends ... Nobody has to learn Nix" puts the two at the same level. It also requires a YAML twin for every Nix fixture, which doubles the fixture work and keeps YAML in the first position. The byte-identical check is still worth keeping. It only needs restating. +**Evidence:** `linux-targets.md:92-94`; goal G2 and ruling 4. +**Proposed text:** + +> Nix is the authoring language (G2, 2026-11-13). YAML/JSON is the Site Model data a Nix configuration evaluates to; a person may also write it by hand. Every Nix fixture is checked by evaluating it and comparing the result with its committed YAML/JSON form, byte for byte after canonicalization. Nobody has to learn Nix to edit the data form; a person who knows Nix never has to leave it. + +**Merge:** replace the paragraph +**Checked:** verified; independently checked 2026-11-13: confirmed + +### L-§5-09: path 2 invents a tendcf option set, so existing NixOS and nix-darwin configs do not carry over + +**Target:** §5 path 2, at "The Site Model's types are also Nix module options (`mkOption`, `mkIf`, `mkDefault`)" +**Kind:** add +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** G2 says "NixOS-style options, so existing NixOS and nix-darwin configs carry over". Path 2 gives the Site Model its own options. A person's `services.foo.enable` or `launchd.daemons.` would therefore not carry over to a non-Nix target. Only passthrough carries anything over, and passthrough applies only on a Nix host. NixOS 25.11 added *modular services* (`system.services.`, a module with `_class = "service"` setting `process.argv`). The manual marks them "in development … significant changes should be expected". Their portability is between Nix module-system frameworks: "a configuration management framework is an application of `evalModules`" (NixOS, Home Manager, nix-darwin). nix-darwin has no merged support; nix-darwin/nix-darwin#1765, "add modular service interface for launchd", is an open draft (2026-05). nixpkgs ships about eight such services, mostly Linux network daemons (`modular-services.nix`). The canonical `process.argv` is `lib.getExe` of a package, a `/nix/store` path that a Mac without Nix lacks. A tendcf Nix frontend could be one more such framework, but only for services whose argv it can map to a non-store path. That conflicts with X-nix-04's no-`pkgs`, no-store-path envelope, and it does not carry over the conventional `services..enable` modules that existing configs use. For a machine without Nix, "carry over" can mean only that evaluated pure-data option values are translated into the Site Model off the device; store paths, the packages themselves and high-level `services..enable` modules do not carry over (08 Summary 2). No existing tool was found that does this for a whole OS configuration (08 §2, searches 2026-11-13). +**Evidence:** `linux-targets.md:80-91`; NixOS manual, "Modular Services": https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/development/modular-services.md ("new in NixOS 25.11", "in development"); nixpkgs PR https://github.com/NixOS/nixpkgs/pull/372170; nix-darwin draft https://github.com/nix-darwin/nix-darwin/pull/1765. +**Proposed text:** + +> Open, for the operator: whether the Nix frontend accepts NixOS modular services (`system.services.`, NixOS 25.11, in development) as one input shape, given that their `process.argv` normally names a store path. Options tendcf cannot honour on the target refuse the compile by name. + +**Ruled:** "1. Importer + matching names" (operator ruling, 2026-11-14, B7): a one-shot importer for pure-data option families (it lists what it did not carry), plus tendcf option names matching nix-darwin and NixOS where the meaning is the same. This is the one choice named in the merge line below with 08's X-nix-02 (the importer) and X-nix-05 (the names). Whether the Nix frontend also accepts NixOS modular services as an input shape is not separately ruled. Ruled; implementation pending. + +**Merge:** insert after the path 2 paragraph; the carry-over choice (08's X-nix-02, a one-shot carry-over import, and X-nix-05, nix-darwin option names) is ruled as above; whether the Nix frontend accepts modular services as one input shape is not +**Checked:** verified against an unofficial mirror of the manual (no modular service evaluated); independently checked 2026-11-13: weakened, corrected (the original remedy, modular services as a ready carry-over route, was refuted and is withdrawn below) + +### L-§5-10: path 1 promises distribution and a consent diff on Nix hosts that the NixOS plan withdrew + +**Target:** §5 path 1, at "tendcf adds only the thin layer Nix does not do: distribution (lockfile, signed release, consent diff, pull)" +**Kind:** correct +**Goal:** G2, G4 +**Weight:** misleads +**Finding:** The NixOS plan's stage D ruling says tendcf "enforces nothing on a Nix host for now. It only reports and refuses". The settled consent diff for the host flake is the GitHub PR's diff, which djbclark approves. That is not a tendcf release and not a device-side diff. Path 1 still claims tendcf distributes to Nix hosts. As written, a reader expects G4's see-and-refuse on NixOS. The plans do not provide it (see N-§3-02). +**Evidence:** `linux-targets.md:73-79`; `nixos-passthrough-plan.md:89-93`, `:105-111`. +**Proposed text:** + +> 1. **Passthrough.** On a host that already runs NixOS or nix-darwin, the host's Nix configuration is left to Nix unchanged; services, packages and files stay Nix's (`supervisor: nixos`, schema v4). Ruled 2026-10-31 for NixOS: tendcf there only refuses and reports, and changes arrive through the host flake's own review (nixos-passthrough-plan.md §3 D, §4). Whether tendcf ever distributes to a Nix host is open. No rewrite of a working configuration is ever required. + +**Merge:** replace path 1 +**Checked:** verified; independently checked 2026-11-13: confirmed + +### L-§5-11: nix-darwin has no plan, and the map points at one that is not there + +**Target:** §5 Consequences item 2, at "The nix-darwin passthrough adapter is required either way and shares the Step 8 design" +**Kind:** add +**Goal:** G2, G5 +**Weight:** blocks-goal +**Finding:** Map §13 Step 7 defers the nix-darwin passthrough adapter to "linux-targets.md Step 8". Step 8 and the whole NixOS plan cover NixOS only: vps-primary and get.sipb.cloud, a read-only `/etc/systemd/system`, and systemd refusal. Neither file covers launchd on nix-darwin, which writes plists into `/Library/LaunchDaemons`, or how the bundle refuses there. macOS is now first, and G2 names nix-darwin. Map §14.1 (nix-darwin on the Mac, yes or no) is still open. This Mac has no Nix installed (checked). So which way G8 state 1 goes on the Mac is undecided: nix-darwin passthrough, or a Nix frontend compiled to launchd for a Mac without Nix. +**Evidence:** `linux-targets.md:99-101`; `architecture-DEFINITIVE-v3.md` §13 row 7 and §14.1; `nixos-passthrough-plan.md` (no "darwin" except via cross-reference); `command -v nix darwin-rebuild` empty. +**Proposed text:** + +> 2. nix-darwin has no adapter design yet; Step 8 covers NixOS only. Before the first macOS milestone the operator rules map §14.1 for the server Mac: (a) the Mac runs nix-darwin, and tendcf passes its configuration through (a nix-darwin analogue of nixos-passthrough-plan.md, including how the launchd bundle refuses a label nix-darwin owns); or (b) the Mac has no Nix runtime, and its Nix configuration is compiled by the Nix frontend to a launchd goal file (path 2). G8 state 1 is reachable either way; the two differ in where Nix must be installed. + +**Ruled:** "1. Plain Mac, launchd by tendcf" (operator ruling, 2026-11-14, B6): state 1's Mac has no nix-darwin; tendcf renders launchd; Nix is for authoring and building only. That is option (b) in the proposed text: the Mac has no Nix runtime, and its Nix configuration is compiled by the Nix frontend to a launchd goal file. Map §14.1 is answered for state 1. Sub-rulings: "1. macOS VM on bigmac" (B6 sub 1), "1. Dry-run only" (B6 sub 2), "1. Root in VM, user on bigmac" (B6 sub 3); see L-§1-02. Ruled; implementation pending. + +**Merge:** replace item 2; map §14.1 is ruled for state 1 (option (b)) +**Checked:** verified (files read; this Mac checked for Nix); independently checked 2026-11-13: confirmed + +### L-§5-12: consequence 3 restates a writer vocabulary that v4 retired + +**Target:** §5 Consequences item 3, at "The Step 4 schema bump adds `nix-darwin` to the writer vocabulary next to `nixos`" +**Kind:** correct +**Goal:** G2 +**Weight:** misleads +**Finding:** `nixos` left the writer vocabulary in v4 and became the `supervisor: nixos` fact, as §3 step 4 of this same file records. `nix-darwin` is still a writer value. Consequence 4's "how a passthrough host's goal file carries the Nix side" was settled for NixOS by the v4 reconciliation. It is open only for nix-darwin. +**Evidence:** `linux-targets.md:36` (v4: "`nixos` left the writer vocabulary"), `:102-108`. +**Proposed text:** + +> 3. `nix-darwin` is a `launchd-writers` writer value (since before v3); `nixos` is no longer a writer but the host-level `supervisor: nixos` fact (v4). 4. For NixOS, how the goal file carries the Nix side was settled by schema v4 (`supervision` is `deliberately-unmanaged`; the consent object is the host flake's PR diff). For nix-darwin it is open (item 2). + +**Merge:** replace items 3 and 4 +**Checked:** verified; independently checked 2026-11-13: confirmed + +--- + +## N: `docs/architecture/nixos-passthrough-plan.md` + +### N-hdr-01: status says "awaiting sign-off" although every decision was taken + +**Target:** header, at "Status: proposed 2026-10-31, awaiting operator sign-off" +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** §6 records all four decisions as taken on 2026-10-31. Stages A–C are done and D is ruled. The header still reads as an open proposal. Under G5 the plan also comes after macOS and Android. +**Evidence:** `nixos-passthrough-plan.md:3-5`, `:125-139`. +**Proposed text:** + +> Status: decided and executed through stage C (2026-10-31); stage D ruled (enforce nothing on a Nix host). Under the goal's platform order (G5) Linux and NixOS work comes fourth and fifth. get.sipb.cloud keeps the module as a standing proof; vps-primary stays imported, not enabled. + +**Merge:** replace the status paragraph; needs the operator's ruling first if "paused" is to be kept; ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### N-§3-02: on a passthrough host nothing satisfies G4's device-side see-and-refuse + +**Target:** §4 "The passthrough goal file for this host", at "djbclark approves it on the host-flake PR, behind a required CI job" +**Kind:** question +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 says "Nothing changes a device except as an exact, mechanically checked difference that the device's owner can see and refuse." On a NixOS host every change comes through `nixos-rebuild` or `deploy-vps-primary`. The only check is a GitHub PR review, and nothing on the device verifies that what activated is what was reviewed. That is acceptable for the operator's own host today. It does not meet G4 as stated, and G2 invites other NixOS users to bring their configurations. Either G4 has a stated exception for passthrough hosts, or tendcf must gate activation, for example by checking the activated system's toplevel store path against the reviewed `diff-closures`. +**Evidence:** `nixos-passthrough-plan.md:105-111`, `:89-93`; goal G4. +**Proposed text:** + +> **Against G4 (2026-11-13):** a passthrough host's changes are not yet a device-checked difference. Open, for the operator: (a) passthrough hosts are outside G4 until stated otherwise; or (b) tendcf records the reviewed toplevel store path and refuses to report the host converged when the activated system differs, a report-only first step toward gating activation. + +**Merge:** insert after the consent-diff list; needs the operator's ruling first +**Checked:** verified (text read); option (b) is a design idea, not checked; independently checked 2026-11-13: confirmed + +### N-§4-03: "verbatim" is delivered only in the sense that tendcf does nothing + +**Target:** §4, at "So the passthrough host is described by a required host-level `supervisor: nixos` fact" +**Kind:** add +**Goal:** G2 +**Weight:** improves +**Finding:** G2's "existing NixOS ... configs carry over" is met on NixOS hosts only trivially: the configuration is untouched because tendcf manages nothing there. The goal's adopters are "sysadmins who already share configs in Nix" (G1), and what they would value is carrying a NixOS service definition to a Mac or an Android device. This plan cannot give that, and it should say so, so that passthrough is not mistaken for G2 delivered. How anything carries over to a host without Nix is the open choice of L-§5-09 (with 08's X-nix-02 and X-nix-05). +**Evidence:** `nixos-passthrough-plan.md:97-114`; goal G1, G2. +**Proposed text:** + +> Passthrough keeps an existing NixOS configuration working; it does not carry any of it to a host that is not NixOS. That is the Nix frontend's job (linux-targets.md §5, path 2). + +**Merge:** insert at the end of §4's first paragraph +**Checked:** verified + +### N-§5-04: "Work this unlocks" lists finished work as pending + +**Target:** §5 "Work this unlocks, in order", item 1, at "Bundle guard from §2 plus negative test" +**Kind:** correct +**Goal:** G5 +**Weight:** misleads +**Finding:** All three items are done: the guard (§2, check 7), slices B and S1 (schemas v3, v4), and stages A–D. The section reads like a to-do list. Under G5 the next NixOS item is vps-primary's stage C, and it should be marked as coming after macOS and Android in the goal's order, not next. +**Evidence:** `nixos-passthrough-plan.md:28-34` (guard done), `:116-123`. +**Proposed text:** + +> ## 5. Work this unlocked (all done 2026-10-31) +> +> 1. Bundle guard and negative test: done (`tendcf_systemd_units_writable`, check 7). 2. Writer vocabulary (v3) and `supervisor` fact (v4): done. 3. Stages A–C: done (C on get.sipb.cloud); D ruled. Next, **after macOS and Android in the goal's order (G5):** stage C on vps-primary. + +**Merge:** replace §5; needs the operator's ruling first if "paused" is to be kept; ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified; independently checked 2026-11-13: confirmed + +### N-§3A-05: what the NixOS derivation and module are worth to the Mac + +**Target:** §3 stage A, at "`nixos/pkgs/cfengine-tendcf.nix` (fork `b8abf2840`" +**Kind:** add +**Goal:** G2, G5, G8 +**Weight:** improves +**Finding:** Stage A built a Nix derivation of the pinned fork and a `services.cfengine-tendcf` module. If the server Mac takes nix-darwin (L-§5-11 (a)), that derivation is the obvious way to put a pinned, store-owned fork build on the Mac, and nix-darwin's `launchd.daemons` gives the `execd.enable` analogue. That would also solve the missing macOS fork build (X-OV-01). Whether the derivation builds on `aarch64-darwin` was not checked. Its two build patches (perl shebang, `USERMOD` guard) suggest Linux assumptions. +**Evidence:** `nixos-passthrough-plan.md:43-59`; the derivation lives in `site-public-djbclark`, not read here. +**Proposed text:** + +> **For macOS (2026-11-13):** the same derivation, built for `aarch64-darwin`, plus a nix-darwin module using `launchd.daemons`, is one candidate for the server Mac's CFEngine install if map §14.1 rules for nix-darwin. Untested on Darwin. + +**Ruled (B6):** "1. Plain Mac, launchd by tendcf" (operator ruling, 2026-11-14, B6): state 1's Mac has no nix-darwin. The nix-darwin module candidate in the proposed text is therefore not state 1's path; whether the derivation alone, built for `aarch64-darwin`, is used for the Mac's CFEngine install is not ruled (Nix for building is allowed on the release path, "2. Allow on release path", B4 rider). + +**Merge:** insert after stage A's paragraph +**Checked:** not checked (Darwin build) + +--- + +## PL: `docs/architecture/plugin-layout.md` + +### PL-§3-01: "the two equal frontends" contradicts G2 + +**Target:** §3 table, Frontend row, at "YAML and Nix are the two equal frontends of map D12" +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** misleads +**Finding:** Under G2, Nix is the authoring language and YAML/JSON is the Site Model's data form beneath it. The `yaml` plugin is then not a peer frontend. It is the loader for the data form every frontend produces, and a person may also edit that data by hand. The layout can stay. The description has to change, or the restructure will build the wrong priority into the plugin interface (for example, a frontend API shaped around YAML's line-number provenance). +**Evidence:** `plugin-layout.md:104`, `:64-65`; goal G2. +**Proposed text:** + +> | Frontend | `tendcf.frontends` (public) | A language a site authors in. It turns its source into Site Model data (YAML/JSON), which the compiler merges, checks and renders. Nix is the primary authoring language (G2, 2026-11-13); the built-in `yaml` frontend loads the data form itself, hand-written or committed beside its Nix source. Guix may follow as an authoring frontend. | + +**Merge:** replace the row +**Checked:** verified; independently checked 2026-11-13: confirmed + +### PL-§2-02: the Nix frontend needs a Nix evaluator on the compile host, and none is planned + +**Target:** §2 table, row `plugins/frontends/nix/`, at "only the hook: `nix2cf eval-nix FILE`" +**Kind:** add +**Goal:** G2, G8 +**Weight:** blocks-goal +**Finding:** Nix-first authoring means every compile evaluates Nix. Map D6 keeps Nix off devices, which is fine, but the compile host needs an evaluator. The operator's Mac has none installed (checked), and `compiler/docs/DESIGN.md` records the same absence when nix2cf was built. Today's hook test is skipped without Nix. Before G8 state 1, the plan must name where evaluation runs (the Mac, CI or another device) and how the evaluator is pinned. The evaluator becomes release-path code, so it belongs in §7's "toolchain closure" question. This contradicts `change-process.md` §2 ('Nix is an optional builder, never a dependency of the path', and alternative 5, 'R5/D6 keep Nix optional') and map R5. G2 may override them, but only by the operator's ruling. +**Evidence:** `plugin-layout.md:83`, `:341-346`; `compiler/README.md` ("the test for it is skipped without a Nix install"); `command -v nix` empty on this Mac. +**Proposed text:** + +> Open (G2): where the Nix frontend's evaluator runs for a release build, and how its version is pinned. A Nix evaluator is release-path code once Nix is the primary authoring language; until it is pinned, a Nix-authored release is not reproducible from `site.lock` alone. + +**Ruled:** "2. Allow on release path" (operator ruling, 2026-11-14, B4 rider, Nix on release path): Nix may be required to build a release; change-process §2 and map R5/D6 are amended. Scope: "1. Build-time only" (operator ruling, 2026-11-14, B4 rider): devices never need Nix at run time. How the evaluator is pinned is not ruled. Ruled; implementation pending. + +**Merge:** ruled (Nix on the release path vs change-process §2 and map R5/D6); insert as a bullet in §7 +**Checked:** verified (this Mac); CI images not checked; independently checked 2026-11-13: weakened, corrected + +### PL-§2-03: no Android supervisor or platform in the planned tree + +**Target:** §2 tree, at "supervisors/launchd/ unit renderers, one per supervisor; in tree only" +**Kind:** add +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** The planned supervisors are launchd, systemd and runit. The second platform in G5 is Android. Its configuration surface (profiles, ShizukuPlus-mediated settings, app state) is not a unit supervisor, and the compiler refuses `android` as a platform. A renderer kind for "Android device state" may be needed beside supervisors. Since §3 already says supervisors need a schema bump, that bump should be designed with Android in view, not after the restructure fixes the tree. +**Evidence:** `plugin-layout.md:67-69`, `:113-124`; `compiler/docs/DESIGN.md` platform↔supervisor row. +**Proposed text:** + +> `plugins/renderers/android/` (planned, G5): renders Site Model records for an Android device into goal-file entries tendcf-agent actuates. Whether this is a supervisor or a new renderer kind waits on the Android adapter design (linux-targets.md §4). + +**Ruled (part):** "1. Field on entries" (operator ruling, 2026-11-14, B3 sub 1, Q20 / M-§12-04 / X-android-05): one host per phone; each Android promise names its target user (owner/work/private) and the work profile's owner app (island/insular/none); unreachable profile reports `not_kept`; the schema bump is a design ruling (two frontier reviews) that rides the agent-id bump (M-§12-05 item 4). That bump is the next unused schema version (v7 or later; shipped v6 is C-policy-01, PR 52); whether the standing-modes approval record shares it is ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. Also "3. Termux CFEngine + thin Kotlin" (B3): state 1 on Android is Termux CFEngine fed tendcf projections. Whether the renderer is a supervisor or a new renderer kind is not ruled. + +**Merge:** insert in the §2 tree and table; the Android adapter shape is partly ruled (above) +**Checked:** verified; independently checked 2026-11-13: confirmed + +### PL-§4-04: "valid is not faithful" is the gap G4's safety scan fills, so say so + +**Target:** §4 "Plugins are trusted build-time code", item 3, at "A plugin **can** make the goal file say something other than what the Site Model says" +**Kind:** add +**Goal:** G4, G6 +**Weight:** improves +**Finding:** The layout says a plugin can emit valid but unfaithful output, and that on operator hosts the only human check is the PR preview diff. G6 makes AIs the authors of the configuration. A plugin may also be AI-written. G4 adds a scan of each difference for likely safety. That scan is exactly the second check item 3 lacks. A scanner that compares the rendered hunk with the Site Model change that caused it (`explain-hunk`, D44) flags an unexplained argv or `run_as`. The scan must run in the gates' plugin-free environment, or it inherits the plugins' trust like everything on the compile side. +**Evidence:** `plugin-layout.md:171-187`; handoff `7c41` D-b ruling ("they should be security-scanned before running them, including doing so with the help of AI"). +**Proposed text:** + +> Under the goal of 2026-11-13 (G4), every difference is also scanned for likely safety, AI among the scanners. A scanner that runs in the gates' plugin-free environment and compares each rendered hunk with the Site Model change it came from is the check item 3 lacks; it scores, it does not authorize. + +**Merge:** insert after item 3; coordinate with the in-flight D-a–D-d docs PR (X-HO-02) +**Checked:** verified (text); the handoff ruling is quoted from handoff `7c41` + +### PL-§4-05: G9 has no foothold: users cannot fork a plugin without a tendcf PR + +**Target:** §4 "Where a plugin lives", and activation item 4, at "a release build loads in-tree plugins only" +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** G9 asks for fork and branch management "as an extension of the platform's existing patch patterns", so that a non-technical user can maintain a fork of a plugin. The layout offers three homes: `plugins/`, `contrib/` (a PR to tendcf) and out-of-tree (not loadable until #47). None lets a user carry a local change to a plugin. The existing patch pattern is the upstream overlay: patch files plus a manifest, `check` for drift, `retired` for upstream catch-up, never a long-lived branch. A site-private overlay over a pinned plugin source, applied at compile time and held to `overlay.py lint/check/retired`, is G9 in its smallest form. The AI turns a user's request into the patch, and a `DRIFT` report is what it re-derives the patch against. +**Evidence:** `plugin-layout.md:198-205`, `:221-239`; `upstream-overlay.md` §3, §5, §6, §8 item 2. +**Proposed text:** + +> **Local changes to a plugin (G9, later).** A site may carry patches against an in-tree plugin in site-private, in the upstream overlay's format (patch files and a manifest; `bin/overlay.py` lint, `check`, `retired`). The release build applies them to the plugin source at the pinned tendcf rev and records the patched plugin's hash in `targets.json` `custom`. A drift is reported, never silently rebased. Not designed. + +**Merge:** insert at the end of "Where a plugin lives" +**Checked:** verified (both files read) + +### PL-§5-06: the restructure is churn against the first milestone + +**Target:** §5 row 4 and the paragraph after it, at "Step 4 rewrites every path reference in every file, dated records included" +**Kind:** question +**Goal:** G5, G8 +**Weight:** improves +**Finding:** Step 4 renames `bin/` to `tools/`, renames the package, splits the compiler, removes older-version rendering and rewrites paths in every dated record. It waits on #41, #42 and #48 (#42 and #41 merged 2026-11-14, at acec5b5 and daa4530). None of it moves G8 state 1 forward, except perhaps the frontend interface the Nix frontend will plug into. It is also the largest diff in the queue, and one cross-model review cycle each. One option is to do only the interface split now (`plugins/frontends/{yaml,nix}`, entry points) and defer the rename and the record rewrite. The rewrite of every dated record was djbclark's ruling, so this is his call. +**Evidence:** `plugin-layout.md:248-260`; handoff `3a99` "Where We're Going" item 3. +**Proposed text:** + +> **Under the goal of 2026-11-13:** Open, for the operator: whether step 4 goes in whole before the macOS-and-Android milestone, or only its frontend split (the part the Nix frontend needs), with the renames and the path rewrite after it. + +**Merge:** insert after the table; needs the operator's ruling first +**Checked:** verified + +--- + +## V: `docs/architecture/tendcf-validate-proposal-2026-11-03.md` + +### V-hdr-01: the proposal covers the launch gate only, and G4's scanned diff has no home in it + +**Target:** title block, after "Status: a proposal. It decides nothing." +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 names four device-facing parts: an exact, mechanically checked difference the owner can see and refuse; scans of that difference, AI among them; a 0–100% safety confidence with its reasons; and highlighting graded by risk, in CLI and TUI modes. The proposal is about launch handoff, state, privilege and the interlock fail-open. It mentions the human-facing side only as `propose`, "renders the briefing", in Step 9. Survives intact: the generation store, lock, atomic publication, launch wrapper, launch guard, §13, and the subcommand frame. Must be added: a device-computed diff in the first build (V-§2-03), a `scan`/`show` surface (V-§3-04), the score's semantics (V-§3-05), and where the AI runs (V-§3-06). +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:450-492` (subcommands; `propose` at Step 9), §9 "It does guarantee three things" (no owner-visibility item). +**Proposed text:** + +> **Against the goal of 2026-11-13.** This proposal designs the gate between an adopted goal file and cf-agent. G4 also requires, on every device, the difference shown to its owner, scanned for safety, with a 0–100% confidence, its explanation, and graded highlighting, in CLI and TUI modes. Items 2, 3 and 9 below are amended for that (diff in the first build; a `show` subcommand); the scanning and scoring design is not in this proposal. + +**Merge:** insert after the status paragraph +**Checked:** verified (all of it read); independently checked 2026-11-13: confirmed + +### V-§2-03: option 3's `adopt` lets root change a host with no diff shown + +**Target:** §2 option 3, at "The only way to promote is `tendcf-validate adopt FILE`, run as root on the host" +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** G4 has no operator exception: nothing changes a device except as a difference its owner can see and refuse. `adopt` checks structure and promotes. It computes no diff against `current`, and §9 lists "the device-computed diff" among what the first build does not guarantee. The diff is cheap. Both files are canonical JSON, and `schema_lint.py` already holds a reference `apply_diff`. Showing it, and requiring the diff's digest on the command line or an interactive yes, makes the first build meet G4 for operator hosts. It needs no approval record or advisor. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:382-391`, §9 "It does not yet guarantee" item 5; inventory report §A (`schema_lint.py` `apply_diff`, L1791-1821). +**Proposed text:** + +> `adopt FILE` computes the goal diff from `current` (empty baseline on first adoption) on the device, prints it, and promotes only on an interactive yes or `--accept DIGEST`, where `DIGEST` is the SHA-256 of the printed diff. A mismatch refuses. This is the owner's see-and-refuse (G4) for operator-tier hosts; it is not an approval record and claims none. + +**Merge:** insert after option 3's first paragraph as a proposal; needs the operator's ruling first (the `--accept DIGEST` interface). Amend §9 'does not yet guarantee' item 5 only when the first build implements it. +**Checked:** verified (text); `apply_diff` location from the inventory digest, not reopened; independently checked 2026-11-13: weakened, corrected + +### V-§3-04: add the `show` duty and the safety assessment to the duties table + +**Target:** §3 table, after the row "`--simulate-json` | `propose` only" +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** The table assigns every device-side duty except the one G4 makes central: presenting the scanned difference. The `--simulate-json` row is the nearest. It already says the simulation is a "human-facing confirmation", never the gate. That is the right status for the safety scan too. CLI and TUI should be two views of one machine-readable assessment, so the TUI adds no logic of its own. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:483-492`. +**Proposed text:** + +> | Safety assessment and display (G4) | `show` renders the device-computed diff with the scan results bound to it: per-hunk findings, an overall confidence 0–100%, the reasons, and highlighting graded by each hunk's score; `--format text` (CLI) and a TUI (on a borrowed scaffold, operator to name) read the same JSON assessment. Display only; never the gate. | first build for the mechanical diff; scanners as they land | + +**Merge:** insert the row +**Checked:** verified; independently checked 2026-11-13: confirmed + +### V-§3-05: the confidence figure needs defined semantics before anyone builds it + +**Target:** §3 (b) option 2, after the duties table +**Kind:** add +**Goal:** G4, G6 +**Weight:** improves +**Finding:** A 0–100% number invites three errors: treating it as a gate, averaging away one bad hunk, and showing a confident figure when a scanner did not run. G4 says the figure must come with "an explanation of why that percentage was chosen". So the assessment must list which scanners ran, which failed and which were missing. D-b's ruling makes AI a soft requirement for external imports, so a missing AI must lower the figure, visibly. Whether a low score may block a change is a ruling. G4 leaves the refusal to the owner. +**Evidence:** goal G4; handoff `7c41` D-b ruling; `tendcf-validate-proposal-2026-11-03.md:488-489` (the advisor timeout rule, "a timeout means no `accept`"). +**Proposed text:** + +> Semantics of the confidence (proposal): the overall figure is the minimum of the per-hunk figures, never an average; each figure states the scanners that produced it (rule scanners: privileged region, `run_as` root, new listener, tombstone of a running unit, interlock removed; `--simulate-json`; the owner's AI); a scanner that did not run caps the figure at a stated value and is named in the explanation. The score never authorizes and never refuses; the owner does. Whether a figure below a threshold requires an extra confirmation is for the operator. + +**Merge:** insert after the table; needs the operator's ruling first (threshold behaviour, caps) +**Checked:** inferred (design proposal); independently checked 2026-11-13: weakened, corrected (nothing existing misleads; it proposes new semantics, so Weight is now improves) + +### V-§3-06: where the AI scan runs, and what binds it to the diff + +**Target:** §3 table row "Local-yes exchange", at "`propose` (nonce, briefing) and `accept` (record)" +**Kind:** add +**Goal:** G1, G4 +**Weight:** improves +**Finding:** The README says the person reads a change "using **their** AI, not ours". Devices cannot be assumed to have an AI: an Android phone may be offline, and a Mac LaunchDaemon runs as root without one. So the AI scan runs where the owner's AI is, probably the advisor slot. Its output must be bound to the exact diff the device computed, by digest, or a scan of one diff can be displayed over another. The device's own mechanical diff stays the authority, and the scan is a signed or digest-bound annotation of it. +**Evidence:** `README.md:7-10`; `tendcf-validate-proposal-2026-11-03.md:488`. +**Proposed text:** + +> An AI scan's result names the SHA-256 of the device-computed diff it scanned; `show` displays it only over that diff and otherwise reports the scan as stale. The scan may run anywhere the owner's AI is (the advisor slot); the device never trusts it for anything but display. + +**Merge:** insert after the table +**Checked:** inferred + +### V-§1-07: every threat here is sized against root or accidents, none against plausible AI-written changes + +**Target:** §1 (b), at "**This guards against accidents and is not a boundary.**" +**Kind:** add +**Goal:** G4, G6 +**Weight:** improves +**Finding:** The launch guard is "against accidents", the detector is "threat-modelled for accidents only (R3b)", and every forgery path "needs root". Under G6 every change is AI-written. The realistic hazard is then neither root nor a slip. It is a schema-valid, well-formed change that does something the owner did not ask for: a hallucinated argv, a widened `run_as`, a tombstone of a needed unit, or an imported config with injected content (D-b). The mechanical gate passes all of these by design. That is fine, because G4's scan is what catches them. But the proposal should state this third threat class and point to where it is handled, or readers will assume the gate handles it. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:235`, `:806-807`, `:246-247`; goal G6. +**Proposed text:** + +> A third class is out of this gate's scope and must be named: a well-formed, schema-valid change that is wrong or unwanted, the expected failure when AIs author configuration (G6). The gate passes it by design; G4's safety scan and the owner's refusal are its only checks. + +**Merge:** insert after the paragraph ending "and so a change to the policy-tree digest." +**Checked:** verified (quotes) + +### V-§6-08: macOS is now first, so re-cost item 1 option 3 (launchd job) for macOS + +**Target:** §6 (d), at "Recommendation: option 3, prefix `/opt/tendcf/libexec/tendcf-validate/`"; and §1 (d) +**Kind:** question +**Goal:** G5 +**Weight:** improves +**Finding:** The recommendations were costed on Linux: cf-execd kept, `tendcf-install.sh`, Debian's `python3`. The proposal recommends item 1 option 3 (replace cf-execd with a timer or launchd job) only "if djbclark prefers" it and "on NixOS". On macOS cf-execd would itself run as a LaunchDaemon, so a LaunchDaemon that starts `tendcf-validate run` directly removes one process layer. It also removes the whole fact-5 process-group problem (cf-execd's single-child kill, the live `assert`). The macOS measurement (no root-owned Python 3.11+) already forces a bundled interpreter there. The first build is now a macOS build. Both platform choices should be re-ruled together. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:204-209`, `:316-322`, `:667-679`, `:724-728`. +**Proposed text:** + +> **macOS first (2026-11-13):** on macOS the recommended trigger is option 3, a LaunchDaemon that runs `tendcf-validate run -- cf-agent …` on a `StartInterval`, with cf-execd not installed, because cf-execd would itself be a LaunchDaemon and fact 5's kill path then never arises. Linux keeps option 1 when its work resumes. + +**Merge:** insert at the end of §1 (d); needs the operator's ruling first +**Checked:** inferred (launchd behaviour not tested here) + +### V-§9-09: the first build's install steps are Linux-only, and no macOS installer exists + +**Target:** §9 item 4 "Install changes", at "`tendcf-install.sh` installs the tree" +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** Every install step names `tendcf-install.sh` or `promises.cf` as the Linux installer writes it. `deploy/` has only `linux/`. The first enforced host under G5 is a Mac, so the first build needs a macOS installer: a root-owned `/opt/tendcf` (or other) prefix, a LaunchDaemon, the bundled interpreter, and a pinned macOS fork build (X-OV-01). §6(d) already recommends the bundled interpreter under `/opt/tendcf/libexec/tendcf-validate/` on macOS. The macOS installer, the LaunchDaemon and a pinned macOS fork build are not planned. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:858-865`; `ls deploy` → `linux` only. +**Proposed text:** + +> On macOS (first, G5) the same changes need a macOS installer that does not exist yet: a root-owned prefix with the pinned fork build, the bundled interpreter §6(d) recommends, the LaunchDaemon of item 1, and `adopt` in place of `data`. + +**Merge:** insert after item 4's list +**Checked:** verified (`ls deploy`); independently checked 2026-11-13: weakened, corrected + +### V-§10-10: picklist 11 assumes a central pusher; G3 makes the log archive a service on a server device + +**Target:** §10 item 11, at "(1) the pusher collects the JSONL over SSH at each push ... [recommended]" +**Kind:** reword +**Goal:** G3, G8 +**Weight:** misleads +**Finding:** The recommendation has the pusher collect rows, which presumes a single host that pushes to everyone. G3 says there is no control node. A "server" is a device offering a service such as receiving and archiving logs, and G8 state 1 puts that archive on the Mac. Option 2 (the device sends rows to an endpoint) matches the goal. The credential it needs is the same peer handshake G3 already requires. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:939-944`; goal G3, G8. +**Proposed text:** + +> 11. How report rows leave a device: (1) the pusher collects the JSONL over SSH; (2) the device sends rows to the log-archive service of a server device, authenticated by the same peer handshake updates use (G3) [recommended under the 2026-11-13 goal; the first archive is the operator's Mac, G8]; (3) nothing leaves the device before Step 8. + +**Merge:** replace item 11 +**Checked:** verified; independently checked 2026-11-13: confirmed + +### V-§13-11: the interlock fail-open was ruled, twice, and the proposal still says "not decided" + +**Target:** §13, at "It is flagged for djbclark, not decided here." +**Kind:** correct +**Goal:** G4, G7 +**Weight:** misleads +**Finding:** Two open PRs record operator rulings: Q10, 2026-11-02, takes option 3 (policy cross-check, PR #42), and R13 (Q49) takes option 5 (a fail-closed fork loader, PR #41). Option 5 reverses the fork's own B-5b, `8f0076b81`. Neither ruling is recorded on master. Map, overlay and register docs still describe the skip-one-entry loader as current. Under G7 an instrument change needs the operator's ruling, and here the ruling exists only in PR bodies. +**Evidence:** `gh pr view 41` ("Operator ruling R13 (Q49)"); `gh pr view 42` ("djbclark's ruling Q10, 2026-11-02, option 3"); `rg 'Q10|Q49|cmdb-fail-closed' docs` finds nothing on master outside this proposal's options. +**Proposed text:** + +> **Ruled 2026-11-02:** option 3 (Q10), implemented in PR #42, which records it below; and option 5 (R13, Q49), the fork's all-or-nothing loader pinned by PR #41 (upstream-register B-5b note). Each holds without the other. + +**Merge:** needs the operator's ruling first (how #41 and #42 land: both still lack their required frontier cross-model review and adversary verdict, and #41 needs a rebase on #42); then land with #41, after #42; do not duplicate #42's 'Implemented 2026-11-06' paragraph. Status, 2026-11-14 (historical for the text above): ruled by B11, "1. Review+merge #42, then #41; park s5" (operator ruling, 2026-11-14, B11); #42 merged at acec5b5 and #41 at daa4530. +**Checked:** verified (PR bodies read; grep); independently checked 2026-11-13: weakened, corrected (PR #42 itself adds the Q10 record to §13, and PR #41 records R13 in upstream-register) + +### V-§4-12: Android needs the same validator and diff, and the Kotlin port is now critical path + +**Target:** §4 (a), at "On Linux and macOS, does the id `tendcf-agent` change" +**Kind:** add +**Goal:** G5, G4 +**Weight:** improves +**Finding:** D45 makes tendcf-agent (Kotlin) the Android device component. The proposal's checks (version dispatch, canonical bytes, schema, projection, diff, display) must therefore exist twice, in Python and Kotlin (R22). With Android second in G5, the shared conformance corpus becomes a G8 state 1 dependency, not a later nicety. That corpus is today's goldens and broken fixtures, run by both implementations. G4's display also needs a native Android surface. The CLI and TUI modes do not reach a phone. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:1056-1058` (Kotlin port R22); `change-process.md:276-277` ("The Android agent's Kotlin port must agree with it on the same golden bytes"). +**Proposed text:** + +> Android (second in G5) runs these checks in tendcf-agent's Kotlin port (R22). The fixture corpus (`examples/`, `examples/broken*`) is the conformance suite both implementations must pass byte for byte; on Android the G4 display is a native screen, not the CLI or TUI. + +**Merge:** insert at the end of §4 (a) +**Checked:** verified (quotes); no Android code exists (inventory §H) + +--- + +## X: cross-cutting + +### X-CP-01: one signing builder sits uneasily with "no control node" and peer updates + +**Target:** `docs/architecture/change-process.md` §6, at "The signing key for `targets` lives on the builder, which is an operator host" +**Kind:** question +**Goal:** G3 +**Weight:** blocks-goal +**Finding:** G3: each device "accepts updates from any other device that completes the correct cryptographic handshake", with no control node. The change process has one pipeline (site-private CI) that compiles every host and one builder holding the `targets` key. In practice that builder is a control node for releases. TUF can express G3: per-device delegated targets roles under one offline root, so any enrolled device may sign a release for the hosts it is delegated. But the document picks a single builder, and G8 state 1 requires the handshake. The choice decides the Mac's role: release builder, or one peer among others. +**Evidence:** `change-process.md:186-194`, `:291-294`; goal G3, G8. +**Proposed text:** + +> **Against G3 (2026-11-13):** a device accepts a release from any device that completes the handshake. Open, for the operator: (a) one builder signs every release, and peers only relay it; or (b) each enrolled device holds a delegated `targets` key (TUF delegations under the offline root) and may sign releases for the hosts delegated to it. + +**Merge:** insert after the paragraph; needs the operator's ruling first +**Checked:** verified (text); TUF delegation semantics from general knowledge, not fetched; independently checked 2026-11-13: confirmed + +### X-CP-02: "an operator host applies" without a local yes conflicts with G4 + +**Target:** `change-process.md` §8 item 1, at "A consented device consents again; an operator host applies." +**Kind:** question +**Goal:** G4 +**Weight:** misleads +**Finding:** Here and in map §10, operator-tier hosts apply without a local yes. G4 gives the owner the power to see and refuse every change, on every device. For operator hosts, the refusal could be the PR review (as N-§3-02 discusses), the device-side `adopt` confirmation (V-§2-03), or an explicit standing "auto-accept above N% confidence" that the owner sets. That last option uses G4's score as a policy the owner sets, not as a gate the project sets. +**Evidence:** `change-process.md:326-330`; `plugin-layout.md:175-177`. +**Proposed text:** + +> An operator host applies under its owner's standing choice: confirm each diff on the device, or accept automatically the diffs the owner's policy allows (for example, a safety confidence at or above a threshold the owner set). Either way the diff is computed and kept on the device, so the owner can see it and refuse the next one (G4). + +**Merge:** replace the sentence; needs the operator's ruling first +**Checked:** verified (text); independently checked 2026-11-13: confirmed + +### X-CP-03: stale: the goal file already binds the policy-tree digest + +**Target:** `change-process.md` §3 property 3, at "the tarball whose digest the goal file will carry once map §9.8's obligation is discharged. Until then the digest is recorded in `targets.json`" +**Kind:** correct +**Goal:** G4 +**Weight:** misleads +**Finding:** The validator proposal records that `goal-file.schema.json` has required `device-trust.entries.policy-tree.tree.sha256` since `9fdf437` (2026-08-15). What is unpaid is R23 (the tree's byte serialization) and a device-side verifier. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:962-969` (stale fact 2). +**Proposed text:** + +> what arrives on a device is the tarball whose digest the goal file carries (`device-trust.entries.policy-tree.tree.sha256`, required since the schema family landed). Unpaid: the tree's byte serialization (R23) and the device-side check, by tendcf-agent on Android and `tendcf-validate` on macOS and Linux (map D45). + +**Merge:** replace the sentence +**Checked:** inferred from the proposal's cited evidence; schema not reopened; independently checked 2026-11-13: confirmed + +### X-CP-04: add the safety scan to the release gates + +**Target:** `change-process.md` §6 release gate 5, after "a host's `schema_version` exceeds the ceiling that host last reported" +**Kind:** add +**Goal:** G4 +**Weight:** improves +**Finding:** Gate 5 computes the per-host preview diff and attaches it to the PR. G4's scan belongs next to it, so that the PR reviewer and later the device owner see the same assessment for the same diff. It runs in the gates' plugin-free environment (§6, "Gates 3 to 6 run apart from plugin code") and never refuses on its own. +**Evidence:** `change-process.md:278-289`, `:296-304`. +**Proposed text:** + +> 5b. Scan each host's preview diff for likely safety (G4) and attach the assessment (per-hunk findings, confidence 0–100%, reasons) to the review artifact, bound to the diff's digest. The scan informs; it does not refuse. + +**Merge:** insert after gate 5 +**Checked:** verified + +### X-OV-01: no macOS (or Android) build of the pinned fork exists + +**Target:** `docs/architecture/upstream-overlay.md` §2 ruling paragraph, at "the Linux CI and hosts ... run the full fork build" +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** Only Linux CI builds the fork at `overlay/fork.json`'s pin. The Mac runs a dev build (installed in the operator's home directory), which PR #42 reports as `3.29.0a.086d27749`, lacking `8f0076b81`. So the Mac's CFEngine is not the pinned fork, and "every Linux result must name the fork revision" has no macOS counterpart. G8 state 1 needs a pinned, root-owned macOS build, and probably an Android CFEngine build too (map §12 keeps CFEngine on Android beside tendcf-agent, per the s5 note). The operator's global rule keeps macOS legs out of PR checks unless he names them, so this needs his ruling: a scheduled macOS build workflow, a nix-darwin derivation (N-§3A-05), or a local `bg` build. +**Evidence:** `upstream-overlay.md:50-65`; `.github/workflows/*.yml` have no macOS runner (`rg -i 'macos|darwin'` hits a comment only, `check.yml:33`); PR #42 body; the operator's global agent instructions, item 37; `s5-unit-detector.md` §11 (Android bullet). +**Proposed text:** + +> **macOS and Android (2026-11-13, G5):** the first milestone runs on a Mac and an Android device, and neither has a pinned build of the fork today (the Mac's dev build is at another revision). Open, for the operator: how the macOS build is produced and pinned (a named macOS CI job, a nix-darwin derivation, or a `bg` build recorded against `overlay/fork.json`), and whether Android runs CFEngine at all. Whichever is chosen, the binary enters a release only as a digest-bound fetched artifact (change-process.md §2 rule 5, 'A tool fork is never an input of its own'; the rule covers the project's own tool forks, which this is, and says nothing about a person's fork), so a local `bg` build counts only once it is published and its digest recorded. + +**Ruled:** "1. Keep fork; spike stock" (operator ruling, 2026-11-14, B5): full fork pin on every platform, macOS fork build in CI; the 2-3 day stock/Termux spike (11-engine-alternatives §7) runs before the adopter path is decided. Whether Android runs CFEngine at all: "3. Termux CFEngine + thin Kotlin" (B3): state 1 on Android is Termux CFEngine fed tendcf projections. The macOS fork build's check on the WarpBuild runner was PR 52 gate 2 (worker 68cf038a; the merge of PR 52 waited on that run). Historical outcome: the run "macOS check 8 spike (WarpBuild)" (https://github.com/frdminc/tendcf/actions/runs/43602684071) completed with conclusion success, and PR 52 merged on 2026-11-14 at 2c78680. Ruled; the CI job that builds the pinned fork on macOS is still to be built (implementation pending, apart from that spike). + +**Merge:** insert after the ruling paragraph; the build question is ruled as above +**Checked:** verified (workflows grep; PR body); the Mac build's version was not rerun; independently checked 2026-11-13: confirmed (clause on rule 5 added) + +### X-OV-02: the overlay is the "existing patch pattern" G9 should extend + +**Target:** `upstream-overlay.md` §8 item 2, at "A long-lived merged branch ... is a full parallel fork in all but name" +**Kind:** add +**Goal:** G9 +**Weight:** improves +**Finding:** G9 wants non-technical users to keep forks "without knowing about merging, rebasing or compiling". This document has already solved the hard part for one fork. A change is a named patch with a reason (`load_bearing_for`) and an exit condition (`retire_when`). Drift is detected without touching the checkout. Upstream catch-up is detected by patch-id. The rejected alternative is exactly the branch model G9 wants to hide. Recording that this mechanism is the intended base for G9 keeps a later design from starting over with branches. +**Evidence:** `upstream-overlay.md:79-87`, `:141-170`, `:185-208`, `:229-238`; goal G9. +**Proposed text:** + +> **G9 (2026-11-13).** This mechanism is the base for later user-facing fork management: a user's fork of a project or a plugin is a manifest of named patches with a reason and a retire condition, applied in order to a pinned base; drift and retirement are reported by `check` and `retired`, and an AI re-derives a drifted patch. No user-visible branch, merge or rebase. + +**Merge:** insert as a new §10 +**Checked:** verified + +### X-OV-03: stale: the `--simulate-json` caller is assigned + +**Target:** `upstream-overlay.md` §2, at "on Linux and macOS the caller is an open point of map D45" +**Kind:** correct +**Goal:** G4 +**Weight:** nit +**Finding:** The validator proposal assigns it to `propose` (Step 9), and as a G4 scanner it is a natural input: what cf-agent would actually do. The proposal is unruled, so "proposed" is the honest word. +**Evidence:** `tendcf-validate-proposal-2026-11-03.md:489`. +**Proposed text:** + +> on Linux and macOS the proposed caller is `tendcf-validate propose` ([`tendcf-validate-proposal-2026-11-03.md`](../architecture/tendcf-validate-proposal-2026-11-03.md) §3), as a human-facing confirmation and one input to the G4 safety scan. + +**Merge:** replace the clause +**Checked:** verified + +### X-RM-01: README says nothing is deployed + +**Target:** `README.md`, at "Nothing described here is deployed." +**Kind:** correct +**Goal:** G8 +**Weight:** misleads +**Finding:** pastebin runs a root-owned fork build with root `cf-execd`, enforcing one canary service, and get.sipb.cloud carries the module. AGENTS.md says so. +**Evidence:** `README.md:27`; `AGENTS.md:267-268`; `linux-targets.md:39`. +**Proposed text:** + +> One Linux host (pastebin) enforces one canary service under a root `cf-execd`, as a standing proof; one NixOS host carries the CFEngine module with nothing scheduled. Nothing runs on a Mac or an Android device yet, which is where the first milestone is (G8). + +**Merge:** replace the sentence +**Checked:** verified (docs); live hosts not contacted; independently checked 2026-11-13: confirmed + +### X-RM-02: README's opening does not state the goal + +**Target:** `README.md`, first paragraph, at "Configuration management for a mixed, intermittently-connected fleet" +**Kind:** reword +**Goal:** G1, G5 +**Weight:** misleads +**Finding:** The opening describes an operator fleet with "Android devices reached through Termux". G1 frames the project as the user's control of their own devices, used through an AI or at the code level. G5 names Android with Island/Insular profiles and ShizukuPlus as the differentiator. A first-time reader, who is G8 state 3's adopter, meets the old frame. +**Evidence:** `README.md:3-10`; goal G1, G5. +**Proposed text:** + +> Free software that gives people control of their own computing devices: a configuration management system you use through your own AI or directly in code. Configuration is to be written in Nix, with plain YAML/JSON beneath it; today the compiler reads the YAML/JSON form only. Nothing changes a device except as a checked difference its owner can see, with a safety score and the reasons, and refuse. First platforms: macOS, and Android with Island/Insular profiles and ShizukuPlus; then Linux. Goal: [`docs/review-2026-11-13/00-goal-definition.md`](00-goal-definition.md) (to move to a permanent home). + +**Merge:** replace the first two paragraphs; needs the operator's ruling first (wording, and where the goal file lives) +**Checked:** verified; independently checked 2026-11-13: weakened, corrected (the Nix frontend is not built, so the present tense was wrong) + +### X-AR-01: the architecture index omits the three plans that set current work + +**Target:** `docs/architecture/README.md`, at "Two living design notes that the map and the guide point at" +**Kind:** add +**Goal:** G5 +**Weight:** improves +**Finding:** The index lists change-process, upstream-overlay, upstream-register and plugin-layout. It does not list `linux-targets.md`, `nixos-passthrough-plan.md` or the validator proposal, and nothing on the page tells a reader the Linux plans come after macOS and Android in the goal's order. +**Evidence:** `docs/architecture/README.md:20-28`. +**Proposed text:** + +> Platform plans: [`linux-targets.md`](../architecture/linux-targets.md) and [`nixos-passthrough-plan.md`](../architecture/nixos-passthrough-plan.md) (Linux and NixOS; Linux is fourth and fifth in the goal's order, G5, 2026-11-13); the device-side gate: [`tendcf-validate-proposal-2026-11-03.md`](../architecture/tendcf-validate-proposal-2026-11-03.md) (a proposal, unruled). There is no macOS or Android plan yet. + +**Merge:** insert after the paragraph; needs the operator's ruling first if "paused" is to be kept; ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified; independently checked 2026-11-13: not in the verdict table, but correction C1 applies to it ("paused" replaced by order language) + +### X-AG-01: AGENTS.md's verification section has no macOS or Android path + +**Target:** `AGENTS.md` "Verifying policy and the CFEngine build", at "Live hosts: pastebin (root install, canary enforced), get.sipb.cloud" +**Kind:** add +**Goal:** G5, G8 +**Weight:** improves +**Finding:** Every check named is Linux CI, a Linux VM or a container. The Mac appears only as a dev build for `run.sh`. The section does not warn that this build is not the pinned fork (X-OV-01). There is no Android build check: ShizukuTendCF, its signing keystore in 1Password, nothing. Agents following AGENTS.md will keep doing Linux work. +**Evidence:** `AGENTS.md:241-268`. +**Proposed text:** + +> Under the 2026-11-13 goal the first platforms are macOS and Android. The Mac dev build (the one named above) is not the pinned fork; a result from it names its own `cf-agent --version`. No macOS install, macOS CI job or Android build of tendcf exists yet. Linux checks above stay as they are, for the Linux work that is later in the order (not paused). + +**Merge:** insert after "Live hosts …"; needs the operator's ruling first ("paused": G5 orders the platforms, and no ruling pauses Linux work); ruled 2026-11-14, B4 rider, "1. Order language": Linux is later in the order, not paused, so "paused" is not kept +**Checked:** verified + +### X-CO-01: compiler README calls Nix optional and later + +**Target:** `compiler/README.md`, at "The name is historical. YAML and JSON are the inputs. An optional Nix module frontend may author the same JSON later" +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** misleads +**Finding:** G2 makes Nix the authoring language. "The name is historical" was also overtaken by D46, under which `nix2cf` names the Nix frontend. +**Evidence:** `compiler/README.md:8-10`; `plugin-layout.md` §6 item 2. +**Proposed text:** + +> Today the inputs are YAML and JSON, the Site Model's data form. Nix is the authoring language the project is built around (goal G2); its module frontend, which will carry the name `nix2cf` (map D46), is not built. `nix2cf eval-nix` is the hook it will land behind. + +**Merge:** replace the paragraph +**Checked:** verified; independently checked 2026-11-13: confirmed + +### X-CO-02: DESIGN.md's case against Nix at build time inverts under G2 + +**Target:** `compiler/docs/DESIGN.md` "Language and tooling" item 3, at "Making Nix a toolchain requirement of the compiler would invert that." +**Kind:** ruling-drift +**Goal:** G2 +**Weight:** misleads +**Finding:** The reason given is that the guide says "nobody adopting the project has to know Nix and YAML/JSON is the stranger path". G2 reverses the priority. A Nix toolchain on the compile host (not on devices, D6) is now expected. "Nix is also not installed on the machine this was built on" is still true of this Mac (checked), and that is now a gap to close (PL-§2-02). This contradicts `change-process.md` §2 ('Nix is an optional builder, never a dependency of the path', and alternative 5, 'R5/D6 keep Nix optional') and map R5. G2 may override them, but only by the operator's ruling. +**Evidence:** `compiler/docs/DESIGN.md:60-69`; `command -v nix` empty. +**Proposed text:** + +> 3. **Nix at compile time, never on the device.** Under the goal of 2026-11-13 (G2) Nix is the authoring language, so the compile host evaluates Nix; devices never need it (D6); this amends change-process.md §2's 'Nix is an optional builder', pending the operator's ruling. The evaluator's pinning is open (plugin-layout.md §7). Until the module frontend exists the hook is `nix2cf eval-nix FILE` (`nix-instantiate --eval --strict --json`). YAML/JSON stays the data form, written by hand or produced by Nix. + +**Ruled:** "2. Allow on release path" (operator ruling, 2026-11-14, B4 rider, Nix on release path): Nix may be required to build a release; change-process §2 and map R5/D6 are amended. Scope: "1. Build-time only" (operator ruling, 2026-11-14, B4 rider): devices never need Nix at run time. How the evaluator is pinned is not ruled. Ruled; implementation pending. + +**Merge:** ruled (Nix on the release path vs change-process §2 and map R5/D6); replace item 3, with "pending the operator's ruling" removed +**Checked:** verified; independently checked 2026-11-13: weakened, corrected + +### X-CO-03: compiler AGENTS.md says it compiles from Nix expressions + +**Target:** `compiler/AGENTS.md`, at "It generates tendcf goal files from Nix expressions" +**Kind:** correct +**Goal:** G2 +**Weight:** misleads +**Finding:** The compiler reads YAML/JSON through `sitemodel.py`. `eval-nix` evaluates a plain expression and does not compile. An agent trusting this line would assume the Nix frontend exists. +**Evidence:** `compiler/AGENTS.md:16-18`; `compiler/README.md:95-97`; inventory §A. +**Proposed text:** + +> - It generates tendcf goal files from Site Model YAML/JSON (Nix authoring is the goal, G2, and is not built), so CFEngine and goal-file semantics are load-bearing. + +**Merge:** replace the bullet's first sentence +**Checked:** verified; independently checked 2026-11-13: confirmed + +### X-CO-04: the compiler refuses Android, now the second platform + +**Target:** `compiler/docs/DESIGN.md` "Not implemented" bullet, at "*Android/Termux* (Step 2) — deferred (linux-targets ruling 2026-10-29)" +**Kind:** ruling-drift +**Goal:** G5 +**Weight:** blocks-goal +**Finding:** `android` is refused as a platform and the `runit` flavour has no renderer. Under G5 that refusal stands between the compiler and G8 state 1. The fix waits on the Android adapter ruling (L-§4-05). Until then the bullet should say "not designed", not "deferred". +**Evidence:** `compiler/docs/DESIGN.md:41-43`, `:101`; `compiler/README.md:89`. +**Proposed text:** + +> - *Android* — second in the goal's order (G5, 2026-11-13) and not designed: whether its configuration is Termux/runit services or profile and ShizukuPlus state is open (linux-targets.md §4). Until then `android` is refused as a `--platform`. + +**Merge:** replace the bullet (and the matching table row); needs the operator's ruling first for anything beyond the wording +**Checked:** verified; independently checked 2026-11-13: confirmed + +### X-HO-01: current sessions are spending on harness and restructure work, none of it on G8 state 1 + +**Target:** `docs/handoffs/HANDOFF_standalone-97e8_issue48-decided-harness-fixes_2026-11-13_7c41.md`, "Where We're Going" +**Kind:** question +**Goal:** G8 +**Weight:** improves +**Finding:** The live queue has three djbclark-ade harness fixes, the D46 decisions docs PR, and then the restructure. Each docs PR costs two frontier reviews plus an adversary review under the standing rule. Nothing in the queue touches a Mac install, Android, the Nix frontend or G4's display. This is not an error, since the queue predates the goal. But the next lead will follow it unless it is re-ordered. +**Evidence:** handoff `7c41` "Where We Are" 1–5, "Where We're Going" 1–6; handoff `3a99` "Where We're Going" 3. +**Proposed text:** + +> (For the next handoff, not a merge into the dated one.) Re-order under the 2026-11-13 goal: review (frontier + adversary) and merge #42, then #41; finish the D46 decisions PR; then ask the operator for the first-milestone rulings (server Mac and map §14.1, Android shape, macOS fork build, Nix evaluator) before the restructure. + +**Merge:** needs the operator's ruling first (queue order, and what happens to the open PRs: #41 and #42 both still lack their required frontier cross-model review and adversary verdict, and #41 needs a rebase on #42); dated handoffs are not edited. Status, 2026-11-14 (historical for the text above): the order is ruled by B11, "1. Review+merge #42, then #41; park s5" (operator ruling, 2026-11-14, B11); #42 merged at acec5b5 and #41 at daa4530. +**Checked:** verified (both handoffs read); independently checked 2026-11-13: weakened, corrected + +### X-HO-02: the in-flight D46 decisions PR touches the same sections as PL items + +**Target:** handoff `7c41` "Where We Are" item 5, at "amends D46 + plugin-layout.md §4/§7 with D-a..D-d" +**Kind:** question +**Goal:** G4, G2 +**Weight:** improves +**Finding:** Worktree `tendcf-d46-decisions-wt` (branch `docs/d46-issue48-decisions`, head `7b93a64`) is rewriting `plugin-layout.md` §4 and §7, where PL-§4-04, PL-§4-05 and PL-§2-02 would land. Its D-b ruling ("security-scanned before running them, including ... with the help of AI") is the first concrete instance of G4. If that PR cites G4 and words "equal frontends" per G2, it saves a second review cycle. I did not read its diff. +**Evidence:** `git worktree list`; handoff `7c41`. +**Proposed text:** + +> (For the D46 decisions PR's brief.) Cite goal G4 at D-b's scanning rule and word frontends per G2 (Nix primary, YAML/JSON the data form beneath it) in any §3/§4 text the PR touches. + +**Merge:** needs the operator's ruling first (scope of an in-flight PR) +**Checked:** verified (worktree exists); its diff not checked + +### X-WIP: the three paused worktrees and PRs #41/#42, under the goal + +**Target:** worktrees `tendcf-fork-pin-wt` (PR #41), `tendcf-cmdb-xcheck-wt` (PR #42), `tendcf-s5-design-wt` (branch `s5-design`, no PR) +**Kind:** question +**Goal:** G4, G5, G7 +**Weight:** improves +**Finding:** The three are summarised in the table below. The owner decides. +**Evidence:** `git worktree list`; `gh pr view 41/42`; `s5-unit-detector.md` §11 (in its worktree). +**Proposed text:** + +> | Work | Recommendation | Reasoning | +> | --- | --- | --- | +> | **#42** policy CMDB cross-check (Q10, option 3) | **Finish: merge first.** | Platform-independent: the same `tendcf_services.cf` gates launchd on the Mac, so the fail-open closes on the first-milestone Mac too. Works without #41. Green and ruled; still needs its frontier cross-model review and adversary verdict (its body: 'Do not merge before both'). Merging it unblocks the restructure. Its proof (check 9) uses a simulated loader because the Mac dev build cannot skip one container; check 6b covers Linux systemd. | +> | **#41** fork pin to the fail-closed loader (R13) | **Finish, after #42.** | Ruled; green; moves the pin every later build (including the missing macOS build, X-OV-01) should start from. It reverses the fork's own B-5b and leaves the overlay's B-5b patch text describing the old commit (per its body). That inconsistency should be closed in the same PR or noted in the register. Also needs its frontier and adversary reviews. Rebase it on #42 and re-run CI. In the same PR, correct #42's check-8 comment in `tests/policy/run.sh` ('the fork's loader skips a bad entry') and the §13 sentence 'The Linux CI legs … exercise the real per-entry skip': after #41 neither is true. #41's body names pin `c3afaac26`; the diff pins `d32cade13`. | +> | **s5-design** report-only unit detector as a custom promise (873-line note, no PR, 54 commits behind master) | **Park.** | Its own §11 scopes it to systemd plus dpkg and puts macOS and Android out of scope. Under G5 it serves the fourth and fifth platforms. Keep the branch. The reusable part is the promise-module pattern and the row assembly (§6), worth reading when a launchd or Android extra-entry detector is designed. Do not spend two frontier reviews on it now. | + +**Merge:** needs the operator's ruling first (what to do with PRs #41 and #42 and the paused worktrees; both PRs still lack their required frontier cross-model review and adversary verdict, and #41 needs a rebase on #42) + +**Ruled:** "1. Review+merge #42, then #41; park s5" (operator ruling, 2026-11-14, B11): frontier and adversary review #42, merge; rebase #41, fix its two stale statements and stale pin hash, review, merge; record the two 2026-11-02 rulings with #41 without duplicating #42's paragraph; park s5-design. Outcome (historical for the text above): #42 merged at acec5b5 and #41 at daa4530, both on 2026-11-14; s5-design stays parked. + +**Checked:** verified (PR bodies, worktree list, s5 §11); PR diffs not read, CI state taken from the inventory digest; independently checked 2026-11-13: weakened, corrected + +--- + +## Nits + +| ID | Target, quoted phrase | Fix | +| --- | --- | --- | +| PL-§7-n1 | `plugin-layout.md` §7 "Whether the PyPI names `tendcf` and `nix2cf` are free; unchecked." | Stale: both reserved as 0.0.0 placeholders on 2026-11-13 (handoff `3a99` item 6; https://pypi.org/project/tendcf/, https://pypi.org/project/nix2cf/; URLs not fetched). Replace with "Reserved on PyPI as placeholders, 2026-11-13." | +| N-§3-n2 | `nixos-passthrough-plan.md` §3 A "Written by omp Sonnet 5.5 as a bigteam slice" | omp is retired (ADE); keep as history, add "(omp, since retired)". | +| L-§3-n3 | `linux-targets.md` §3 row 4, one table cell of ~400 words | Move the v2–v5 history into a sub-list under the table; the cell is unreadable rendered. | +| X-AG-n4 | `AGENTS.md` "tendcf and nix2cf are the most important work" | Already in plugin-layout §5 step 4's list; until then add "(nix2cf is now `compiler/`)". | +| X-CP-n5 | `change-process.md` §2 table, the site-private row, at "(today: ops repo" | The ops checkout in use is named `site-private-djbclark` (per the operator's global agent instructions), not `site-private`; check which name the docs standardise on. | +| X-OV-n6 | `upstream-overlay.md` §7 "State verified on 2026-10-09" | Add a line that the tested artifact is the fork pin in `overlay/fork.json` (§2 ruling), not this overlay state. | +| X-CO-n7 | `compiler/README.md` "Units for any supervisor but launchd** (Steps 1–2, 4, 6)" | Step numbers mix map steps and linux-targets steps; name the document for each. | +| V-§0-n8 | `tendcf-validate-proposal-2026-11-03.md` §0 fact 9 "`site-public-djbclark/nixos/modules/cfengine-tendcf.nix`" | Name the repo by its GitHub path, since the doc otherwise links site-djbclark PRs. | +| L-§1-n9 | `linux-targets.md` §1 T7 "prefer CI over Mac resources" | Under G5 the Mac is a target, not only a resource; reword when M1 is named. | + +## Ideas and risks + +Idea 1 was withdrawn after checking (see the last section); the remaining ideas keep their numbers. + +2. **Decide map §14.1 first.** Whether the server Mac runs nix-darwin decides everything else: where Nix evaluates, how the fork is built for macOS (a Nix derivation solves both), and whether macOS needs a passthrough design or only the launchd renderer that already exists. It is a single ruling, and it unblocks most of the first-milestone plan. **Ruled:** "1. Plain Mac, launchd by tendcf" (operator ruling, 2026-11-14, B6): state 1's Mac has no nix-darwin; tendcf renders launchd; Nix for authoring and building only. +3. **Risk: the Android model is unknown and the schema assumes Termux.** No document mentions Island/Insular. If Android configuration is profile and app state through ShizukuPlus rather than services, the goal file needs a new domain, not a supervisor. That is cheapest before any device holds a baseline, which is true today. **Ruled:** "1. Field on entries" (operator ruling, 2026-11-14, B3 sub 1): a field on entries, not a new domain or supervisor, carries the Android user and profile owner app (see PL-§2-03). +4. **One assessment, three views.** Make the G4 safety assessment a schema'd JSON artifact (`safety-assessment.schema.json`, digest-bound to the goal diff). CLI, TUI and the Android screen then become renderers of it. The same artifact goes on the PR (X-CP-04) and the device, so reviewer and owner see identical scores. **Ruled (device side):** "1. Native screen + Termux" (operator ruling, 2026-11-14, B3 sub 4, X-safety-08): one review document (R14) rendered three ways, with goldens for all three; renderers compute nothing. +5. **Risk: the score becomes the gate by habit.** If owners learn to accept anything at 90% or above, a scanner blind spot becomes a policy hole. Keep the minimum-over-hunks rule, show which scanners did not run, and make any automatic acceptance an explicit owner setting that the device records, never a project default. **Ruled for the auto-refuse floor:** "1. Allowed, off by default" (operator ruling, 2026-11-14, B8 sub 2, v2 on G-§7-01): an owner may set a floor, a bundle below it is refused automatically, logged, and the owner notified with the diff; no default floor; tighten-only (no score ever auto-accepts); the owner can re-request and accept a refused bundle. +6. **Rule scanners before AI scanners.** The privileged-region, `run_as`, tombstone, listener and interlock-removal checks are deterministic. They can ship with the first `adopt`, and they give the AI scanner a floor to explain. They also make the figure meaningful when no AI is reachable. +7. **G9 grows from the overlay, not from git.** `bin/overlay.py` already gives named patches, drift detection without touching a checkout, and patch-id retirement. Generalised to plugins and to forks such as ShizukuTendCF, it hides merge and rebase, as G9 asks, and the AI's job becomes re-deriving one drifted patch. +8. **Risk: review cost against the milestone.** Each docs PR costs two frontier reviews plus an adversary review, and the restructure rewrites every dated record. At the current queue, budget can run out on renames before a Mac converges. Split the restructure, as in PL-§5-06. +9. **The log archive is the first "server" service, and a good first peer protocol.** Rows flowing from Android to the Mac, under the handshake G3 requires, exercise peer authentication with no actuation risk. Building that before signed releases flow peer to peer would test the handshake cheaply. +10. **Keep pastebin as a regression host for the shared bundle.** Linux is later in the order, not paused, and `tendcf_services.cf` is one file for launchd and systemd. pastebin's canary under root `cf-execd` is the only enforced proof of the bundle. Re-installing it after each policy change, #41/#42 included, keeps a Mac-first edit from silently breaking it. + +Last search run: firecrawl search and scrape of the NixOS manual's modular-services section (an unofficial mirror), run after drafting L-§5-09; it confirmed `system.services.`, `_class = "service"`, `process.argv`, and that the feature is "new in NixOS 25.11 ... in development". The independent check read the canonical manual page and nix-darwin/nix-darwin#1765 and corrected L-§5-09 accordingly. No search on TUF delegations, nix-darwin's current launchd options, or Android profiles; those statements are marked as unfetched. + +Not checked: live hosts; any PR diff (#41, #42, the D46 decisions branch); whether `cfengine-tendcf.nix` builds on Darwin; CI images for Nix; the Mac dev build's version (taken from PR #42's body); the map, guide and paper beyond the cited lines; ShizukuTendCF. + +## Withdrawn after checking + +| ID | Claim | Refuting evidence | +| --- | --- | --- | +| 04 Ideas 1 | Adopting NixOS modular services as the Nix frontend's input is the cheapest literal delivery of G2, with nix-darwin's launchd named as the second process manager. | Modular services are portable only between Nix module-system (`evalModules`) frameworks; nix-darwin support is an unmerged draft (https://github.com/nix-darwin/nix-darwin/pull/1765); their `process.argv` is normally a `/nix/store` path (https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/development/modular-services.md). | +| L-§5-09 (original remedy) | A Nix frontend accepting modular-service options and mapping `process.argv` to a launchd `unit` would carry existing services to a Mac without Nix; the evidence was an unofficial manual mirror. | Same evidence as above; the item stays, with its finding and proposed text corrected to an open question for the operator. | + +Modular services, accurately: NixOS 25.11 added them (`system.services.`, nixpkgs#372170); the manual marks them in development, about eight exist in nixpkgs, nix-darwin has only a draft, and they do not by themselves carry configuration to a machine without Nix. diff --git a/docs/review-2026-11-13/05-response-code.md b/docs/review-2026-11-13/05-response-code.md new file mode 100644 index 0000000..4a02eec --- /dev/null +++ b/docs/review-2026-11-13/05-response-code.md @@ -0,0 +1,927 @@ +# 05 — Response: the code, against the goal (G1–G9) + +Targets: the code at `eefea3c`: `compiler/` (nix2cf), `policy/`, `schema/`, `bin/`, `tests/`, `deploy/` and `.github/workflows/`; for the Android items, the sibling repositories stayturgid and ShizukuTendCF. + +Base commit: eefea3c + +How this was produced: one reviewing agent (Claude Opus), then an independent checking agent that tried to refute each finding; nothing was built or executed, so every defect is established by reading the code. + +Items by Weight after corrections: blocks-goal 22, improves 21, nit 2 (45 items). + +Reviewer: Opus 5.5 (Claude Code sub-agent), 2026-11-13. Base `eefea3c` (a tendcf worktree at that commit). Read-only: no file changed in any repository, no build, no test suite, no live host. graft was run from the main tendcf checkout (same commit; the worktree has no `graft/` and building one would write to it). Paths are relative to the tendcf repository unless a sibling repository is named. + +Sources consulted: firecrawl (scrape) — Nix manual `restrict-eval`/`pure-eval` (https://nix.dev/manual/nix/2.28/command-ref/conf-file.html#conf-restrict-eval: restrict-eval is `false` by default); launchctl(1) (https://ss64.com/mac/launchctl.html: `load`/`unload` "will only return a non-zero exit code due to improper usage. Otherwise, zero is always returned"; `bootstrap`/`bootout` are the current verbs). CFEngine key type taken from the cfengine-core fork's source, `cf-key/cf-key-functions.c:322` (`RSA_generate_key_ex`). Two firecrawl web searches returned only irrelevant results. + +## Summary answers to (a)–(g) + +**(a) G8 state 1 gap list, in dependency order.** Sizes are guesses. + +| # | Gap | Exists today | Missing | Size (guess) | Item | +|---|---|---|---|---|---| +| 1 | Fork build for macOS, packaged, in CI | Linux build only: `.github/actions/build-fork/action.yml`, `linux.yml:25-118`; a hand-made Mac dev build (the one AGENTS.md names) | A macOS job that builds `overlay/fork.json`'s pin and runs `tests/policy/run.sh` with the launchd path live | ~150 lines YAML, 1–3 days | C-ci-01 | +| 2 | Root install and a root `cf-execd` on the Mac | `deploy/linux/tendcf-install.sh` (refuses non-Linux at :47) | A macOS installer and a LaunchDaemon for `cf-execd` | ~200 lines, 1–2 days | C-deploy-01 | +| 3 | A launchd adapter that converges | `policy/tendcf_services.cf:274-317`, `policy/templates/launchd.plist.mustache` | env, reload on change, error visibility, tombstone guard, backup files, a "data loaded" guard, tests | ~150 policy + ~150 test lines, 3–5 days | C-policy-01..06, C-tests-01 | +| 4 | Device identity and a signed update | ed25519 `host` patterns in schemas; approval-record `signature` member (fixtures only) | A device key that exists, a signature over the goal file, verification before projection | 400–800 lines, 1–2 weeks | C-schema-01, C-schema-02, C-bin-01 | +| 5 | See and refuse (G4's minimum) | `goal-diff.schema.json`; lint-only `apply_diff` (`bin/schema_lint.py:1821`) | A diff the owner reads and accepts or refuses on the device | 300–600 lines, ~1 week | C-bin-03, C-deploy-02 | +| 6 | Nix authoring with NixOS-style options | `nix2cf eval-nix` (`compiler/nix2cf/cli.py:150-171`), a plain attrset | A module system with tendcf options, and a whole-site Nix input | 300–600 lines, 1–2 weeks (carry-over importers: +1–2 weeks) | C-compiler-01 | +| 7 | Android in the contract | nothing: the compiler refuses android (`compile.py:85-88`), the schema has no Android supervisor or domain | Android domains (apps per user/profile, appops, settings, grants) in a schema bump, plus compiler rendering | ~400 schema + ~300 compiler lines, 1–2 weeks | C-schema-03, C-compiler-05 | +| 8 | Android client | nothing in tendcf; substrate in stayturgid's Kotlin agent, Termux CFEngine and ShizukuTendCF | Receive, verify, diff/consent UI, apply via Shizuku, report | 3–6k Kotlin lines, 4–8 weeks (less if Termux CFEngine converges: needs a ruling) | C-android-01..05 | +| 9 | Transport and peer handshake | nothing (inventory §H "Push: nothing") | Mac to Android delivery, and acceptance from any peer that completes the handshake | 1–2 weeks | C-schema-02 | +| 10 | Logs archived on the Mac | `schema/report-row.schema.json` (only `bin/unit_classifier.py`, Linux, uses it) | A sender on Android, a receiver and archive on the Mac, and a goal-file shape for both | 300–500 lines, ~1 week | C-macos-02 | +| 11 | Fail-closed CMDB on the Mac build | PR #41 (open when written; merged 2026-11-14, daa4530) | Merge it, and add a policy-side guard | days | C-policy-06 | + +The total is a guess of 3 to 5 months of focused work. Rows 4, 5 and 8 dominate. + +**Ruled, row 8:** "3. Termux CFEngine + thin Kotlin" (operator ruling, 2026-11-14, B3): state 1 on Android is Termux CFEngine fed tendcf projections; the Kotlin agent holds trust and consent only (Idea 4 below). The row's "less if Termux CFEngine converges: needs a ruling" is answered. + +**(b) Share of code by platform** (`wc -l` over the tracked files in the target dirs: 16,181 lines). +1. Linux-only: about 5,200 lines (32%). This is `bin/unit_classifier.py` 896 plus `tests/unit_classifier/` 3,135, `deploy/` 405, `tests/deploy/` 162, `run.sh` check 6 (about 194 lines, :163-356), the systemd half of the policy (66 lines naming systemd) and its template (13), `linux.yml` 118 and `build-fork` 81. +2. macOS-specific: about 60 lines, all policy and template, plus the launchd-only renderer inside `compiler/` (1,139 Python lines that render launchd units only). +3. Android: 0. +4. Platform-neutral contract machinery: the rest, about 10,900 lines (schemas, schema_lint 2,260, projector 620, overlay 2,029 plus 626, xref and flag lint). It is neutral in platform but CFEngine-shaped (C-bin-02). +5. Linux-shaped assumptions baked into shared parts: the v5 `unit-package` writer enum `["dpkg"]` (`schema/goal-file.schema.json:544-551`); the unit-writer key language of `.service/.socket/.timer/.path` (:520-524); the `tendcf-install` writer "systemd hosts only" (:535); a supervisor enum with no Android value (:679); `/usr/bin/systemctl` hard-coded (`policy/tendcf_services.cf:321-350`); `ldd` and systemd in the only installer; a `run_as` Unix-user pattern (:380) that has no meaning for Android app UIDs. + +**(c) The Nix frontend** is a JSON evaluator: about 20 lines that shell out to `nix-instantiate --eval --strict --json`. It has no options, no `lib`, no modules and no way to read a NixOS or nix-darwin configuration. Its example covers services only. A NixOS host is passthrough by design (`NIXOS_REFUSAL`, `compile.py:96`): tendcf writes none of its units, and nothing imports them into the Site Model. The distance to G2 is the whole frontend (C-compiler-01, C-compiler-02, C-tests-03). + +**(d) macOS.** The launchd adapter is about 25 lines of policy and a 32-line plist template, and it has never been executed in any test or CI run (C-tests-01). On reading it: +1. it drops `env`; +2. it never reloads a changed job; +3. it cannot see a failure, because `launchctl load` returns 0; +4. it deletes any named plist on a tombstone, guarded only by a lint that never runs on a device; +5. it leaves an edit backup beside the plist. + +Nothing in tendcf installs or schedules it on a Mac, and there is no macOS CI. + +**(e) Android.** stayturgid already runs CFEngine 3.27.1 in Termux (`cf-agent` and `cf-serverd`) and has a Kotlin Shizuku agent. Its Ansible `android_common` modules are the resource vocabulary an Android client needs, including `--user N` for Island profiles. Three things in them contradict tendcf's goal and decisions: +1. Key trust over the tailnet is trust-on-first-use, which is not G3's handshake. +2. The Mac pushes with `cf-runagent`, which makes it a control node. +3. ShizukuTendCF's signer allowlist ignores the owner's revoke and deny. + +D45 (a Kotlin agent) is consistent with stayturgid's native agent. It is in tension with the CFEngine that already runs on the fleet. Items C-android-01..05. **Ruled:** "3. Termux CFEngine + thin Kotlin" (operator ruling, 2026-11-14, B3); see C-android-01. + +**(f) Defects.** The strongest: +1. shell injection through interlock `pre_action` (C-policy-01); +2. env silently dropped (C-policy-02); +3. the launchd tombstone (C-policy-04); +4. eval-nix's impure evaluation of untrusted Nix on the authoring machine (C-compiler-02); +5. unvalidated output with exit 0 outside a checkout when neither `--tendcf` nor `$TENDCF_DIR` is given (C-compiler-03); +6. a `platform: any` crash (C-compiler-04); +7. tests that cannot fail (C-tests-02, C-tests-03); +8. schemas that nothing consumes (C-schema-04). + +**(g) G4 attach points.** These are in C-g4-01..04. +1. The scan and confidence figure attach between `conflict_check` and `canonical_bytes`, on the diff. +2. Highlighting needs a source map that the YAML loader half-has and the Nix path lacks. +3. The CLI attaches as a new subcommand beside `buildfile`. +4. The TUI attaches device-side over the same diff and report. Nothing for any of these exists. + +--- + +## Compiler + +### C-compiler-01: The Nix frontend evaluates JSON; it is not NixOS-style options + +**Target:** `compiler/nix2cf/cli.py` `cmd_eval_nix`, at "Evaluates a Nix expression to the JSON the compiler consumes" +**Kind:** add +**Goal:** G2 +**Weight:** blocks-goal +**Finding:** `eval-nix` runs `nix-instantiate --eval --strict --json FILE` and pretty-prints the result. That is all there is. The example is a plain attribute set with "No nixpkgs, no `lib`, no module system". It encodes only `services.yml`: roles and launchd-writers have no Nix form. `buildfile` cannot consume `eval-nix` output directly. It needs three separate files (`--services`, `--roles`, `--launchd-writers`), and it parses any non-`.json` suffix as YAML. So "existing NixOS and nix-darwin configs carry over" is entirely unbuilt. A NixOS host is passthrough by design (`NIXOS_REFUSAL`): tendcf writes none of its units, so a NixOS configuration "carries over" only by staying where it is; nothing imports it into the Site Model. +**Evidence:** `compiler/nix2cf/cli.py:150-171`, `:82-90`; `compiler/nix2cf/sitemodel.py:99-112`; `compiler/examples/site/site.nix:1-13`; `compiler/nix2cf/compile.py:96`, `:430-434`. +**Proposed text:** + +> Build the Nix frontend as a module evaluation, not a JSON dump: `lib.evalModules` over a `tendcf` option tree (`tendcf.services.`, `tendcf.roles`, `tendcf.writers`, later `tendcf.android.*`), evaluated with `--restrict-eval`, whose `config.tendcf` is the whole Site Model in one document. Add two importers that read an existing configuration's evaluated options: nix-darwin `config.launchd.daemons..serviceConfig` (ProgramArguments, UserName, WorkingDirectory, EnvironmentVariables, RunAtLoad, KeepAlive) to launchd services, and NixOS `config.systemd.services` to systemd services. `buildfile --site site.nix` takes the result directly. + +**Merge:** needs the operator's ruling first (the option namespace and whether "carry over" means import or co-existence) +**Checked:** verified (read cli.py, sitemodel.py, site.nix); independently checked 2026-11-13: weakened, corrected (latent: no Nix frontend in use) + +### C-compiler-02: `eval-nix` evaluates untrusted Nix with full file and network access + +**Target:** `compiler/nix2cf/cli.py` `cmd_eval_nix`, at `[exe, "--eval", "--strict", "--json", str(args.file)]` +**Kind:** correct +**Goal:** G4, G6 +**Weight:** improves +**Finding:** Config is AI-authored (G6), so a `.nix` file is untrusted input. The evaluator is run with defaults. `restrict-eval` is false by default, so `builtins.readFile` of the author's SSH private key or `builtins.fetchurl` works, and the value is printed to stdout and can travel into a goal file. A file named after `--` (`nix2cf eval-nix -- -x`) reaches nix-instantiate as an option, because the argv has no `--` before the path. Import-from-derivation is also on by default, so evaluation can trigger builds. Scope: this runs on the authoring machine, not on a managed device; no device runs `eval-nix`. +**Evidence:** `compiler/nix2cf/cli.py:155-160`; Nix manual: https://nix.dev/manual/nix/2.28/command-ref/conf-file.html#conf-restrict-eval ("Default: false"). +**Proposed text:** + +> Run the evaluator as `nix-instantiate --eval --strict --json --option restrict-eval true --option allowed-uris '' -I site= -- ` and refuse a file outside the site directory. A frontend that reads anything else is a compile error. + +**Merge:** replace that call +**Checked:** verified (code read; Nix default from manual); not run; independently checked 2026-11-13: weakened, corrected (latent: authoring machine only; no device runs it) + +### C-compiler-03: Outside a tendcf checkout the compiler writes an unvalidated goal file and exits 0 + +**Target:** `compiler/nix2cf/compile.py` `compile_host`, at "no tendcf schema directory found" +**Kind:** correct +**Goal:** G1, G4 +**Weight:** improves +**Finding:** When neither `--tendcf` nor `$TENDCF_DIR` is given, `_in_tree_tendcf` deliberately returns None for any installed layout (pip, venv, `--target`). Then: +1. `buildfile` skips Site Model validation (`cli.py:101`); +2. it compiles anyway; +3. it prints only a `note:`; +4. it writes the goal file with exit 0. + +The docstring "Raises CompileError; never emits a wrong file" is then false. Unvalidated input also reaches `rec["launchd"]`, `rec["bundle"]` and the like as raw KeyErrors. This is the path every adopter (G8 state 3) takes. +**Evidence:** `compiler/nix2cf/cli.py:40-59`, `:99-113`; `compiler/nix2cf/compile.py:663`, `:707-711`. +**Proposed text:** + +> Ship the schemas and the projector as package data of the compiler and validate always; with no schemas available, refuse (exit 2) rather than emit. + +**Merge:** replace that branch +**Checked:** verified (read; not run); independently checked 2026-11-13: weakened, corrected (latent) + +### C-compiler-04: A `platform: any` service crashes the compiler with a traceback + +**Target:** `compiler/nix2cf/compile.py` `conflict_check`, at `entry_id = sel.record["launchd"]["label"]` +**Kind:** correct +**Goal:** G1 +**Weight:** improves +**Finding:** `select_services` accepts `platform in (host.platform, "any")`. `services.schema.json` requires `launchd` only `if platform == macos`. So a schema-valid `platform: any` service selected for a launchd host has no `launchd` key, and `conflict_check` raises KeyError. The CLI catches only `CompileError`, so the user gets a Python traceback. +**Evidence:** `compiler/nix2cf/compile.py:238`, `:293`, `:535`; `schema/services.schema.json` top-level `allOf` (macos→launchd, linux→systemd); `compiler/nix2cf/cli.py:121-127`. +**Proposed text:** + +> In `select_services`, a selected service that lacks the host supervisor's unit block (`launchd` on a launchd host) is a compile error naming the record and line: "service X is platform any but has no launchd block; add one or set platform". + +**Merge:** insert after the platform check +**Checked:** verified by reading (not executed); independently checked 2026-11-13: confirmed by reading, not run (latent: no example uses `platform: any` without a launchd block) + +### C-compiler-05: Android is refused at every layer although the Site Model admits it + +**Target:** `compiler/nix2cf/compile.py` `PLATFORM_SUPERVISORS` +**Kind:** add +**Goal:** G5, G8 +**Weight:** blocks-goal +**Finding:** The Site Model's `platform` enum includes `android`, and the example declares an `android-termux-services` domain. But `PLATFORM_SUPERVISORS` has no android row, `--platform` offers only macos and linux, and the goal file has no Android supervisor or domain. G5's platform 2 cannot be compiled for at all. +**Evidence:** `compiler/nix2cf/compile.py:81-88`; `compiler/nix2cf/cli.py:182`; `schema/services.schema.json` (`platform` enum `["macos","android","linux","any"]`); `compiler/examples/site/site.nix:27-32`. +**Proposed text:** + +> Add `android` as a platform whose host fact is not a unit supervisor but an agent (`tendcf-agent`), with its own domains (C-schema-03); render those domains, and refuse services (launchd/systemd units) on it. + +**Merge:** needs the operator's ruling first (C-android-01 decides what converges on Android) +**Checked:** verified; independently checked 2026-11-13: confirmed + +### C-compiler-06: Only one actuated domain exists, so logs, files and packages have nowhere to go + +**Target:** `compiler/nix2cf/compile.py` `SUPERVISION_DOMAIN` and `render_goal_file`, at "keep one host's services in one domain" +**Kind:** add +**Goal:** G3, G8 +**Weight:** blocks-goal +**Finding:** The compiler maps exactly one Site Model domain to `supervision` and refuses a host whose services span two. The "Site-Model-domain → goal-file-domain mapping is not written down anywhere". A Mac that archives logs and an Android device that ships them need state beyond "a daemon runs": a log endpoint, a receiver, retention, a forwarding config, and files. The pipeline has no domain for any of these, and the projector projects only `supervision`. +**Evidence:** `compiler/nix2cf/compile.py:63-74`, `:503-511`; `bin/projector.py:127-128`. +**Proposed text:** + +> Write the domain mapping down and add the first two non-service domains the finish line needs: `log-forward` (client: where reports go, signed by whom) and `log-archive` (server: where they land, retention). + +**Merge:** needs the operator's ruling first (schema bump) +**Checked:** verified; independently checked 2026-11-13: confirmed + +### C-compiler-07: No tombstones, so removing a service changes nothing on the device + +**Target:** `compiler/README.md` "Not here yet", at "Tombstones from the Site Model" +**Kind:** add +**Goal:** G4 +**Weight:** blocks-goal +**Finding:** The compiler emits only `state: present`. A service deleted from the Site Model simply vanishes from the next goal file. The policy acts only on ids it is given, and extra-entry detection is not wired, so the daemon keeps running and its plist stays. G4's "exact difference" then reports a removal that never happens on the device. The removal hunk exists in the diff schema but not in reality. +**Evidence:** `compiler/README.md:93`; `compiler/nix2cf/compile.py:536-551` (present only); `policy/tendcf_services.cf:104-105` (acts on `getindices` of the given ids only). +**Proposed text:** + +> Derive tombstones from the previous accepted goal file (baseline) rather than from the Site Model: an id present in the baseline and absent from the new render becomes `{"state":"absent"}` in a comprehensive domain. + +**Merge:** needs the operator's ruling first (where the baseline lives, C-bin-01) +**Checked:** verified (read); independently checked 2026-11-13: confirmed + +### C-compiler-08: Invariants the lint enforces are not enforced at compile time + +**Target:** `compiler/nix2cf/compile.py` `render_goal_file`, at `owners = [w for w in writers if _prefix_matches(...)]` +**Kind:** correct +**Goal:** G4 +**Weight:** improves +**Finding:** Several rules are lint-only (`bin/schema_lint.py`), but the compiler never imports or runs that lint on user input or on its own output: +1. nested writer prefixes are refused (:1421-1429); +2. goal-file unit-writer keys must not overlap; +3. every interlock bundle must be used; +4. a tombstone must fall under a cfengine prefix. + +With nested prefixes the compiler takes `owners[0]`, the first declared, not the most specific, so its writer check depends on file order. The tests call the lint's cross-file check (`test_compile.py:70-74`); the CLI does not. +**Evidence:** `compiler/nix2cf/compile.py:599-612`; `bin/schema_lint.py:1408-1431`, `:1611`; `schema/goal-file.schema.json:520` ("Lint: no two keys overlap"); `rg lint compiler/nix2cf` (docstring mentions only). +**Proposed text:** + +> Move the cross-file checks into an importable library that `compile_host` runs over the Site Model and the rendered goal file, and that the device validator runs again; the lint calls the same library. + +**Merge:** needs a design decision (library location under the D46 layout) +**Checked:** verified (read); independently checked 2026-11-13: confirmed (latent) + +### C-compiler-09: Source locations exist for YAML only, so the Nix path cannot point at code + +**Target:** `compiler/nix2cf/sitemodel.py` `load_document`, at `return Document(path, data)` +**Kind:** add +**Goal:** G2, G4 +**Weight:** improves +**Finding:** Locations are recorded per YAML mapping only (`_LineLoader`). JSON input gets none, and the Nix route goes through JSON, so every error message and any future highlight points at a temporary file, not at the line in the `.nix` file. Entries in the goal file carry no provenance back to the Site Model at all. +**Evidence:** `compiler/nix2cf/sitemodel.py:33-45`, `:99-104`; `compiler/nix2cf/cli.py:169`. +**Proposed text:** + +> Carry a source map beside the goal file (`entry pointer -> file:line`, from `builtins.unsafeGetAttrPos` on the Nix side and `_LineLoader` on the YAML side); it is not part of the signed bytes. + +**Merge:** insert as a new compiler output +**Checked:** verified (read); `unsafeGetAttrPos` availability not checked + +## Policy + +### C-policy-01: Interlock `pre_action` argv is joined with spaces and run through a shell as root + +**Target:** `policy/tendcf_services.cf` bundle `tendcf_interlocks`, at "acceptable here since pre_action.command comes from our own schema-validated goal file" +**Kind:** correct +**Goal:** G4, G6 +**Weight:** blocks-goal +**Finding:** The policy builds the command string with `join(" ", …[pre_action][command])` and runs it with `useshell => "true"`. The goal-file schema puts no alphabet limit on `pre_action.command` items (contrast the systemd argv alphabet). So `["tailscale", "status; curl …|sh"]` runs as root every five minutes. Under G6 the author is an AI, which is exactly the input the comment calls trusted. A mechanical diff shows an argv array, but the device executes a different thing (a shell string), so what the owner sees is not what runs. The only other filter on these strings is the projector's refusal of `$(`, `${`, `@(`, `@{` (`bin/projector.py:145`). It does not stop `;`, `|`, `&&`, backticks or redirection, and `tendcf-install.sh data` installs a projection without running the projector. No other lint restricts them: `bin/schema_lint.py`, `bin/xref_lint.py`, `bin/overlay.py` and the compiler never mention `pre_action`, and the Site Model's `common.schema.json` items are plain strings too. The proposed text first given here (promiser `command[0]` with "absolute path required by schema", `arglist` from a container slice) cited a schema rule that does not exist and is not proven expressible in CFEngine: `getvalues()` can turn the container path into an slist, but whether that slist, split into head and tail, parses as an `arglist` is exactly what the policy comment reports failing, and needs a real `cf-promises` run. It is replaced below by the fallback, restricting the argument alphabet in the schema, as a certain step 1, with the no-shell `arglist` form as step 2 once a test proves it. +**Evidence:** `policy/tendcf_services.cf:72-98`, `:370-374`; `schema/goal-file.schema.json:497-504`; `bin/projector.py:145`; CFEngine `commands` reference (: `arglist` is an slist, `useshell` defaults to `noshell`) and `getvalues()` reference (). +**Proposed text:** + +> Step 1, certainly expressible today: set `useshell => "noshell"` (CFEngine's default) in `tendcf_interlock_contain`, so no shell parses the joined string, and require `pre_action.command[0]` to match `^/` and every item to match the systemd argv alphabet plus "no ASCII space" (schema bump, to `schema_version` 6; `contract_version` is the exact pin `const: 2`), so that the joined string splits back into the same argv. Step 2, once proven against a real build: build an slist per interlock with `getvalues("data:variables.tendcf_interlock[$(id)][pre_action][command]")` under a canonified, non-bracket name, and pass its tail as `arglist` with its head as the promiser. Keep step 1's alphabet until step 2 passes a test. + +**Ruled:** two rulings on step 1's schema change, recorded by the operator on 2026-11-14. + +1. Schema version: "1. Bump to 6" (operator ruling, 2026-11-14, C-policy-01 schema version). A strict narrowing of `pre_action.command` still bumps `schema_version`; the same version means the same acceptance set. So step 1's "(schema bump)" is a bump to schema_version 6. +2. Contract version: "1. Confirm const: 2" (operator ruling, 2026-11-14, C-policy-01 contract_version form). The `contract_version` is an exact pin (`const: 2`), not a floor; the lead's decision in PR 52 is confirmed. + +Ruled; the schema half is implemented: `schema_version` 6 and `contract_version` `const: 2` shipped with PR 52 (merged 2026-11-14 at 2c78680; the schema bump is 83d7280), so these two values are already in the checked-in schemas and are no longer pending. This record does not restate what else PR 52 changed in the policy. The bump changes `schema_version` and `contract_version`, so it was a design ruling with two frontier reviews under AGENTS.md rule 3. Later schema changes (the Android `profile` field with the `agent` id, and the standing-modes approval record) cannot reuse v6: they take the next unused schema version (v7 or later), ruled this way (operator ruling, 2026-11-14, PR 62 review Q4, "1. Decide at design review"): the next unused version (v7 or later); grouping not ruled; the schema design review (two frontier reviews) decides. + +**Merge:** replace the vars and commands sections of `tendcf_interlocks` +**Checked:** verified (read; not executed); independently checked 2026-11-13: confirmed (live on the deployed path as code: the deployed policy joins and shells every pre_action; the injection itself is latent, since the deployed canary pre_action is `/usr/bin/true`); no lint outside the schema restricts the strings: confirmed; proposed fix expressible as written: weakened, corrected (step 2 not proven; replaced by the fallback as step 1) + +### C-policy-02: `env` reaches the device and is silently dropped by both adapters + +**Target:** `policy/templates/launchd.plist.mustache` (whole template) +**Kind:** correct +**Goal:** G4, G8 +**Weight:** blocks-goal +**Finding:** The compiler emits `env` (litellm's `LITELLM_MASTER_KEY`, `OPENAI_API_KEY`), and the projector carries it into `host_specific.json`. Neither the launchd plist template nor the systemd unit template mentions it. No code resolves a secretspec name to a value. The service starts without its environment and nothing reports it. The goal file and the diff say one thing and the device does another, which G4 rules out. +**Evidence:** `compiler/nix2cf/compile.py:548-550`; `examples/host_specific.json` (`"env":{"CADDY_ADMIN_TOKEN":…}`); `policy/templates/launchd.plist.mustache:1-32`; `policy/templates/systemd.service.mustache:1-13`; `rg secretspec policy bin deploy compiler/nix2cf` (projector name check only). +**Proposed text:** + +> Until a device-side secret resolver exists, refuse (report, do not actuate) any service entry carrying `env`; when it exists, render `EnvironmentVariables` from a root-only file the resolver writes, never inline values in the plist. + +**Merge:** insert a refusal class beside `_refused` +**Checked:** verified (read); independently checked 2026-11-13: confirmed (latent: no deployed service carries `env`, and no Mac runs the policy) + +### C-policy-03: A changed launchd job never takes effect, and a failed load is invisible + +**Target:** `policy/tendcf_services.cf` `commands:`, at `"/bin/launchctl" arglist => { "load", "-w", … }` +**Kind:** correct +**Goal:** G4, G8 +**Weight:** blocks-goal +**Finding:** `launchctl load -w` runs on every pass with no "already loaded" probe and no unload on change. The systemd branch has `restart … _unit_changed`, but the launchd branch has no equivalent. So an edited plist keeps running the old definition until reboot. `load`/`unload` "only return a non-zero exit code due to improper usage. Otherwise, zero is always returned", so CFEngine records every outcome as repaired and a broken plist is never reported. +**Evidence:** `policy/tendcf_services.cf:274-280`, `:311-317`, contrast `:337-340`; https://ss64.com/mac/launchctl.html (load/unload NOTE). +**Proposed text:** + +> Use `launchctl print system/