From 2b393836a30bd707340e6dadc4788bac9a2ba2f8 Mon Sep 17 00:00:00 2001 From: Daniel JB Clark Date: Fri, 13 Nov 2026 11:25:09 -0500 Subject: [PATCH 01/11] docs: goal definition agreed 2026-11-13, and the review's response-item format New files only; no original document is changed. Co-Authored-By: Claude Fable 5.2 --- docs/review-2026-11-13/00-goal-definition.md | 112 +++++++++++++++++++ docs/review-2026-11-13/README.md | 46 ++++++++ 2 files changed, 158 insertions(+) create mode 100644 docs/review-2026-11-13/00-goal-definition.md create mode 100644 docs/review-2026-11-13/README.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..3772a0f --- /dev/null +++ b/docs/review-2026-11-13/00-goal-definition.md @@ -0,0 +1,112 @@ +# tendcf goal definition (agreed 2026-11-13) + +Status: agreed between djbclark and the reviewing session on 2026-11-13, in an +eight-question walk. 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 confidence out of 100%, an explanation of why that figure was +chosen, 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, in order: + +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. + +**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. | + +## 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/README.md b/docs/review-2026-11-13/README.md new file mode 100644 index 0000000..3431a9f --- /dev/null +++ b/docs/review-2026-11-13/README.md @@ -0,0 +1,46 @@ +# Goal review, 2026-11-13 + +A review of the whole project against the goal agreed on 2026-11-13 +(`00-goal-definition.md`). Every file here is new. No original document was +changed. Each response is written so it can be merged into its original later. + +Base commit for every anchor: `eefea3c` (master). + +## Response item format + +Every finding is one item with a stable ID. The ID prefix names the target: +`P` paper, `G` guide, `M` map (`architecture-DEFINITIVE-v3.md`), `L` +linux-targets, `N` nixos-passthrough-plan, `PL` plugin-layout, `V` +tendcf-validate proposal, `C` code, `X` cross-cutting. Example: `P-§5.1-02`. + +```markdown +### P-§5.1-02: short title + +**Target:** `docs/paper/tendcf-architecture-paper.md` §5.1 "Section heading", +at the sentence beginning "first six words of it" +**Kind:** correct | add | cut | reword | move | question | ruling-drift +**Goal:** G3 (the paragraph of the goal this serves or conflicts with) +**Weight:** blocks-goal | misleads | improves | nit +**Finding:** what is wrong or missing, in two to five sentences. +**Evidence:** `file:line`, a URL, or the command run and what it printed. +**Proposed text:** + +> Replacement or insertion text, ready to paste. + +**Merge:** replace that sentence | insert after it | delete the paragraph | +needs the operator's ruling first (say which) +**Checked:** verified (how) | inferred | not checked +``` + +Rules for items: + +1. Anchor by section number, heading text and a quoted phrase. Line numbers + drift; a quoted phrase survives. +2. One change per item. A finding that touches three sections is three items + that name each other. +3. `Proposed text` is in the original's own voice and style, so a merge is a + paste. +4. An item that needs a decision says so in `Merge` and proposes nothing as + settled. +5. A claim about the outside world carries a URL. A claim about this repo + carries `file:line` at `eefea3c`. From c88e0f1863ed065403d59aa75eed268e10654c8e Mon Sep 17 00:00:00 2001 From: Daniel JB Clark Date: Fri, 13 Nov 2026 12:07:20 -0500 Subject: [PATCH 02/11] docs(review): goal review responses, checks and synthesis Thirteen response and research documents (01-13) measured against the goal agreed 2026-11-13, the six independent check files that tried to refute them, and a synthesis listing the rulings needed, confirmed defects and a merge map. No original document is changed. Reviewers and checkers are all Claude Opus; this is not the cross-model frontier review, and nothing was built or executed. Co-Authored-By: Claude Fable 5.2 --- docs/review-2026-11-13/01-response-paper.md | 1406 +++++++++++++++++ docs/review-2026-11-13/02-response-guide.md | 1197 ++++++++++++++ docs/review-2026-11-13/03-response-map.md | 916 +++++++++++ docs/review-2026-11-13/04-response-plans.md | 894 +++++++++++ docs/review-2026-11-13/05-response-code.md | 892 +++++++++++ docs/review-2026-11-13/06-sources-check.md | 566 +++++++ .../review-2026-11-13/07-android-landscape.md | 547 +++++++ docs/review-2026-11-13/08-nix-ecosystem.md | 391 +++++ .../09-safety-score-and-tui.md | 799 ++++++++++ .../10-peer-updates-and-trust.md | 340 ++++ .../11-engine-alternatives.md | 650 ++++++++ docs/review-2026-11-13/12-fork-management.md | 359 +++++ .../13-premortem-and-ideas.md | 370 +++++ .../14-synthesis-and-rulings.md | 352 +++++ docs/review-2026-11-13/README.md | 43 + .../checks/v1-paper-sources.md | 187 +++ docs/review-2026-11-13/checks/v2-guide-map.md | 212 +++ docs/review-2026-11-13/checks/v3-plans-nix.md | 121 ++ .../checks/v4-code-engine.md | 135 ++ .../checks/v5-android-forks.md | 91 ++ .../checks/v6-safety-trust-pm.md | 196 +++ 21 files changed, 10664 insertions(+) create mode 100644 docs/review-2026-11-13/01-response-paper.md create mode 100644 docs/review-2026-11-13/02-response-guide.md create mode 100644 docs/review-2026-11-13/03-response-map.md create mode 100644 docs/review-2026-11-13/04-response-plans.md create mode 100644 docs/review-2026-11-13/05-response-code.md create mode 100644 docs/review-2026-11-13/06-sources-check.md create mode 100644 docs/review-2026-11-13/07-android-landscape.md create mode 100644 docs/review-2026-11-13/08-nix-ecosystem.md create mode 100644 docs/review-2026-11-13/09-safety-score-and-tui.md create mode 100644 docs/review-2026-11-13/10-peer-updates-and-trust.md create mode 100644 docs/review-2026-11-13/11-engine-alternatives.md create mode 100644 docs/review-2026-11-13/12-fork-management.md create mode 100644 docs/review-2026-11-13/13-premortem-and-ideas.md create mode 100644 docs/review-2026-11-13/14-synthesis-and-rulings.md create mode 100644 docs/review-2026-11-13/checks/v1-paper-sources.md create mode 100644 docs/review-2026-11-13/checks/v2-guide-map.md create mode 100644 docs/review-2026-11-13/checks/v3-plans-nix.md create mode 100644 docs/review-2026-11-13/checks/v4-code-engine.md create mode 100644 docs/review-2026-11-13/checks/v5-android-forks.md create mode 100644 docs/review-2026-11-13/checks/v6-safety-trust-pm.md 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..b058086 --- /dev/null +++ b/docs/review-2026-11-13/01-response-paper.md @@ -0,0 +1,1406 @@ +# 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. §9.19 asks the question. + +**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 +> (§9.19). 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", and [6] (a 2014 book) is not the formalising source. Burgess's 2005 autonomy papers are. The sources reviewer should check [6]. The sources check treats the same sentence as 06 P-§2.3-s21 (weight `improves`); this item follows it, and the two should merge as one text. +**Evidence:** paper lines 379-383; reference [6] at line 1969. Not checked against the book. 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 underlies CFEngine, an agent can promise only its +> own behaviour and cannot be obliged by another [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; the sources reviewer should check [6] and consider citing Burgess 2005 +**Checked:** not checked (source); inferred from general knowledge of Promise Theory; independently checked 2026-11-13: weakened, 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). + +**Merge:** replace the paragraph; needs the operator's ruling on how cf-agent runs on Android (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). + +**Merge:** needs the operator's ruling first (how the score is computed: the mechanical ceiling, provenance counting and never showing 100% in the proposed text are not in G4); then 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. + +**Merge:** needs the operator's ruling first (whether a different-model reviewer is required, preferred or only disclosed); insert after that sentence once ruled +**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. + +**Merge:** needs the operator's ruling first (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. + +**Merge:** needs the operator's ruling first (how the score is computed: the cap by mechanical findings and never showing 100% are not in G4); then insert as a new item +**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. + +**Merge:** insert as a new item +**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. + +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. + +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..8892755 --- /dev/null +++ b/docs/review-2026-11-13/02-response-guide.md @@ -0,0 +1,1197 @@ +# 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. + +**Merge:** replace the paragraph; needs the operator's ruling to amend D12 in the map at the same time (the map's §0.2 and D12 say "equal") +**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. + +**Merge:** needs the operator's ruling first (scope of "carry over") +**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. + +**Merge:** replace "Frontends, supervisor renderers and one-shot importers ... never on a device."; needs the operator's ruling (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. + +**Merge:** replace the first paragraph of §5; needs the operator's ruling first: what the handshake authenticates (the release, the sender, or both) +**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.) + +**Merge:** needs the operator's ruling first (G7: is cf-serverd the peer transport; and what the handshake covers, G-§5-01) +**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). + +**Merge:** insert after the Android paragraph; the profile-and-domain naming needs the operator's ruling +**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) but may never loosen (100% 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 confidence out of 100%**, an explanation of 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: an owner may set a floor below which a diff is refused +> without asking, but no score, however high, applies a diff the owner has +> not been shown. A fixed rule's finding caps the score; an AI reviewer can +> lower the score, never raise it past a rule. 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. + +**Merge:** insert after the semantic-layer paragraph; the cap/lower-only rule and the owner-set auto-refuse floor need the operator's ruling +**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. + +**Merge:** needs the operator's ruling first (does G4 admit an operator-tier exception); then replace the §7 clause, the §4 parenthesis, and the §14 "Consent" row +**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). + +**Merge:** replace "None of this surface is built yet (§18)."; the scaffold needs the operator's ruling +**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). + +**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 is inferred from https://github.com/thejaustin/ShizukuPlus ("a privileged process started with adb or root"), not fetched in full. +**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:** inferred (Shizuku start mechanics not verified against its docs); independently checked 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 | + +**Merge:** needs the operator's ruling first (what the handshake covers, G-§5-01); then 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)). + +**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 §0.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 §0.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. + +**Merge:** replace that clause; the map §0.3 change needs the operator's ruling +**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 are parked until state 2 (Steps 12–13), 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 | +> | --- | --- | --- | +> | 1 | **The fork on the Mac.** Build the pinned fork for macOS arm64 into `/opt/tendcf`; a root `cf-execd` under launchd; one canary launchd service enforced, dry-run for everything else (the Mac is the daily driver). | `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; 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 TUF subset of §7; 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; runit services via termux-services (a third bundle branch); the agent's validator and record in app-private storage; Island/Insular work profiles as separate domains; ShizukuPlus as the helper. | 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` and `monitor` roles, each a service record rendered through launchd; 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. | 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 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. | 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); the builder/cache; +> reproducible APK provenance; web-of-trust as advisor tools; +> out-of-tree plugins. +> +> On the daily-driver Mac, which cannot easily be reimaged, dry-run is the +> standing posture for everything but the canary and the server services +> it holds. 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, the D46 restructure, and one schema bump carrying whatever has been ruled by then. This proposal has no schema step. 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. +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). +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". +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. +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. + +**Merge:** needs the operator's ruling first. It supersedes D22 and the 2026-10-29 Linux-first ruling (`linux-targets.md`), defers D16's inference, and may amend D45 (the Android validator). Within it, rule on step order 3-7, in particular whether signing (step 4) may follow the validator (step 3). The map's §13 changes in the same commit. +**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.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..d96ef8b --- /dev/null +++ b/docs/review-2026-11-13/03-response-map.md @@ -0,0 +1,916 @@ +# 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. + +**Merge:** replace that item. Needs the operator's ruling first (D47, 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). + +**Merge:** needs the operator's ruling first (it rewrites an operator principle) +**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. + +**Merge:** replace that item. Needs the operator's ruling first (D48, D49). +**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:** needs the operator's ruling first (what the handshake covers, §16 Q17); then insert after it +**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. Needs the operator's ruling first (D48). +**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 needs the operator's ruling +**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. + +**Merge:** replace R5 +**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. + +**Merge:** insert after R13. Needs the operator's ruling first on what "the handshake" covers (§16 Q17). +**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. + +**Merge:** insert after R15. Needs the operator's ruling first (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). + +**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). + +**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. + +**Merge:** insert after R18. Needs the operator's ruling first (D49). +**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) has a natural answer: the archive service indexes every device, and per-device indexes off Android wait. +**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, and it is where the fleet-wide SQLite index lives (D45 item 7). The JSONL writer on macOS and on Android is therefore on the path to G8 state 1. + +**Merge:** insert after it; the clause placing the fleet-wide SQLite index with the archive answers D45 item 7, an open operator item (map:1130), so it needs his ruling first +**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 confidence from 0 to 100, 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 confidence is the **minimum** of the mechanical ceiling and the AI estimate. Each mechanical finding sets a ceiling: a privileged-region hunk or a `baseline`-class ceremony caps at a figure fixed in the schema, not by the scanner, and an integrity flag caps at 0. The explanation names every ceiling applied. An AI scanner can lower the figure, never raise it above a ceiling. + +**Merge:** insert after the "Output is one scan report" bullet of §9.12 once M-§9-02 is merged; needs the operator's ruling first on the cap values +**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. + +**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. + +**Merge:** replace that paragraph. Needs the operator's ruling first (§16 Q17). +**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 | + +**Merge:** replace that row. Needs the operator's ruling first. 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 | + +**Merge:** needs the operator's ruling first (what the handshake covers, §16 Q17); then insert after the Release row +**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 enforces. 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`. Dry-run remains the posture for any domain not yet named. Which Mac this is: §16 Q18. + +**Merge:** replace the first two sentences of the macOS paragraph. Needs the operator's ruling first (which Mac; whether the daily driver may enforce). +**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. + +**Merge:** insert after that sentence. The CI part needs the operator's ruling first (macOS CI policy). +**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. + +**Merge:** replace that paragraph +**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. Whether a profile is its own host (key, baseline, goal file), a domain of its device's goal file, or a field on entries is open (§16 Q20) and is a schema decision. + +**Merge:** insert after the Android paragraph. Needs the operator's ruling first. +**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: v5 has landed (`"const": 5`), so an id change now costs v6. 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: schema v5 has landed, so changing the `agent` id now costs v6 and a baseline ceremony per device; decide it with the Android profile ruling (§16 Q20), so that one bump carries both. Items 5–6: on macOS, likely a bundled interpreter of at least 3.11 with `rfc8785` vendored, invoked by absolute path with `-I`. Item 7: the index lives with the log archive (§8). Item 8: Linux only, moved to G8 state 2. + +**Merge:** insert before item 1. Needs the operator's ruling first (items 2 and 3 are his open items). +**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:** + +> Open under G5 (§16 Q21): whether Android runs `tendcf-validate` itself inside Termux's Python, leaving tendcf-agent the privileged-helper, index and notification roles, instead of a Kotlin port of the validator. + +**Merge:** needs the operator's ruling first (amends D45 (1)-(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, freeze Linux-only design work + +**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 honest consequence is that Linux-only work becomes state-2 work: the s5 detector design (873 lines), the Linux validate build and the systemd renderer in the compiler. 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) waits for G8 state 2. + +**Merge:** replace that paragraph. Needs the operator's ruling first (D48). +**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 v5, 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; the D46 restructure (`tendcf compile`, `plugins/`). Schema additions in one bump: 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. 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 (ruling), 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.** 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 (agent or Termux, ruling), ShizukuTendCF, profiles, APK build; owner review on the device. | 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. | 1 | +> | 8 | **AI scanner and TUI.** AI scanners under §9.12's ceilings; the TUI on the borrowed scaffold; both modes complete. | 1→2 | +> | 9 | **macOS as client.** Further Macs; nix-darwin passthrough (§14.1 for the workstation); pull and self-update; the `monitor` role. | 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, operator's ruling), 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, one schema bump). 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 bump, it argues against bumping before Q19 and Q20 are ruled, which the corrected Step 0 now respects. +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 ("1→2"); the guide puts all scanning, AI included, and the TUI at its Step 7 inside state 1. G4 names AI among the scanners, so this state 1 ships a partial G4; the "1→2" label is ambiguous. +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). +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). +11. **macOS CI.** Here Step 2 names a macOS CI job (ruling); the guide's Step 1 says only "the CI build action". +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. + +**Merge:** replace the section. Needs the operator's ruling first (it rests on D47–D50); also amends D16 (inference) and D22. +**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). **Proposed, not ruled:** 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. | + +**Merge:** needs the operator's ruling first (the "Proposed, not ruled" clause supersedes D8 wording) +**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". **Proposed, not ruled:** 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), and Linux-only design work waits for G8 state 2. | + +**Merge:** needs the operator's ruling first (supersedes D22 and 2026-10-29) +**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. **Proposed, not ruled:** this amends D12 (Nix is first, not one of two equals). 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. | + +**Merge:** needs the operator's ruling first (amends D12) +**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. **Proposed, not ruled:** this confirms D33, amends D14's git-synced policy, and amends §9.11's push rule (peer delivery, R14). Open: what the handshake covers (§16 Q17). | + +**Merge:** needs the operator's ruling first: it amends D14 and §9.11's push rule, and the handshake definition is open (§16 Q17) +**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 marked "Proposed, not ruled"); 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) +> 18. **Which Mac is the G8 state-1 server**, and may the daily driver enforce under the minimal-claim rule? (M-§12-01) +> 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) +> 20. **How are Android profiles modelled** (Island/Insular): own host, domain, or entry field? A schema bump. (M-§12-04) +> 21. **Does Android run `tendcf-validate` in Termux** instead of a Kotlin port? (M-§12-06) +> 22. **Which TUI scaffold** is borrowed? (R18) +> 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) +> 26. **What root threshold does a one-operator G8 state 1 use?** (M-§9-04) +> 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) + +**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, 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, so an id change now costs v6 and a baseline ceremony per device; it should ride the same bump as the Android profile model (§16 Q20). + +**Merge:** replace those sentences +**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:** needs the operator's ruling first (which document owns the build order; guide-wins rule) +**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..5098e88 --- /dev/null +++ b/docs/review-2026-11-13/04-response-plans.md @@ -0,0 +1,894 @@ +# 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 (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 is paused (G5 places Linux fourth and fifth). + +**Merge:** needs the operator's ruling first (which Mac, which Android device) +**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). 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) +**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 +**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. + +**Merge:** insert after the path 2 paragraph; needs the operator's ruling first (whether the Nix frontend accepts modular services as one input shape; one choice with 08's X-nix-02, a one-shot carry-over import, and X-nix-05, nix-darwin option names) +**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. + +**Merge:** replace item 2; needs the operator's ruling first (map §14.1) +**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 +**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 +**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. + +**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. + +**Merge:** needs the operator's ruling first (Nix on the release path vs change-process §2 and map R5/D6); then 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). + +**Merge:** insert in the §2 tree and table; needs the operator's ruling first (Android adapter shape) +**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. 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 +**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. + +**Merge:** insert after the ruling paragraph; needs the operator's ruling first +**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`](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`](docs/review-2026-11-13/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`](linux-targets.md) and [`nixos-passthrough-plan.md`](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`](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 +**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 paused Linux work. + +**Merge:** insert after "Live hosts …"; needs the operator's ruling first ("paused": G5 orders the platforms, and no ruling pauses Linux work) +**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. + +**Merge:** needs the operator's ruling first (Nix on the release path vs change-process §2 and map R5/D6); then replace item 3 +**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 +**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) +**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. +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. +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. +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. +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 paused, but `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..e9015b5 --- /dev/null +++ b/docs/review-2026-11-13/05-response-code.md @@ -0,0 +1,892 @@ +# 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) | 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. + +**(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. + +**(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), 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. + +**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/