{ "id": "r003", "title": "Decouple the book, evidence first, reviews as graphs", "reviewer": "Dinis Cruz", "received": "22 August 2026", "source_kind": "voice memo (transcript preserved verbatim)", "source": "briefs/14__founder-review__decouple-evidence-decisions.md", "version_reviewed": "v0.3.12", "state": "discussing", "state_note": "Commented: the agent has responded to every item. Two items landed in the same release that published this review, because they are review tooling rather than book content: the decisions register (item 4) and the enrichment threads on r001 and r002 (item 6). The three decisions this review opens are in the register above; the decoupling refactor and the case-study programme wait on them. The launch of issues-fs.sgit.ai on 22 August is external evidence for item 1 and splits item 3's programme into written case studies and distillations from sibling estates; decision D3 is revised accordingly. On 22 August the founder answered D3 by starting the programme himself: the VoiceDebrief and Regulation Graph analyses are published, ahead of the decoupling and the ladder.", "decisions": [ { "n": 1, "item": 1, "question": "Adopt the decoupling as specified? The book gets its own markdown source tree, seeded from today's seventeen units so the split starts at zero drift, and the build gate flips from equality (book must match the site) to provenance (every book unit must name the site pages, version and commit it distilled from, with drift reported rather than forbidden).", "options": [ "Adopt as proposed", "Adjust the architecture (say what changes)", "Keep the coupling for now" ], "state": "open" }, { "n": 2, "item": 5, "question": "Which issues logic manages a review's folder: in-repo issues in the IssuesFS pattern (issues as files, states as data, the graph computable from the folder), or GitHub issues? The agent recommends in-repo: it keeps the serverless-pull-request property this workflow is named for, and it dogfoods the very case study r001 item 8 wants written.", "options": [ "In-repo issues, IssuesFS pattern (recommended)", "GitHub issues", "Both: in-repo as the record, GitHub mirrored for notification" ], "state": "open" }, { "n": 3, "item": 3, "question": "The case-study order: confirm or reorder the proposed sequence (the regulation graph vault, then Risk Graph Explorer, then browser isolation, then the sgraph.ai library-as-a-vault, then SGit, IssuesFS and EmailFS from the resolved sources), and supply the per-vault guidance the memo promises: which areas to go deeper on, what to screenshot, what evidence to capture. That guidance is ask N13 on the comms board. **Revised by the launch of issues-fs.sgit.ai:** the programme now has two kinds of entry, written case studies and distillations from sibling estates that already hold the depth (IssuesFS, EmailFS). The agent recommends taking the distillations first, since they are ready now and they test the provenance mechanism against sites that keep moving.", "options": [ "Distillations first (IssuesFS, EmailFS), then the written vault studies (recommended)", "Confirm the original order and supply guidance vault by vault", "Reorder (say which first)" ], "state": "answered", "answer": "Neither of the proposed orders: the founder chose **the written vault analyses first, starting with VoiceDebrief and the Regulation Graph**, ahead of the decoupling refactor and the ladder work. Both are published at [/vaults/](../vaults/index.html) as of v0.3.19. The distillations from sibling estates (IssuesFS, EmailFS) and the remaining vaults stay queued behind them.", "date": "22 August 2026" } ], "items": [ { "n": 1, "topic": "Decouple the book from the website", "reviewer_says": "I think we need to decouple the book from the website. The original idea, one being a projection of the other, was already causing us some problems in language, but the problem is more subtle: there's a number of concepts that are not well captured in the book because we don't have enough references and enough good explanation of those concepts, and the agent that wrote the book correctly had to make a bunch of assumptions. We are mixing two concepts: I need a website where I can publish my latest research, my latest ideas, and go into detail at a way more level of granularity than we can go in a book; and the book should become the best of, this markdown-driven version of files and images, a condensed version of what we have on the website. This is a perfect example of the Wardley maps evolution from explorer to village, where we start to refactor and start to understand better the problem.", "comment": "Agree, and the mechanism has a name in this repository: the equality gate. The build currently fails if the book does not match the site's content, which was the right explorer-stage tool (it made drift impossible while the identity was forming) and is now the constraint that flattens both surfaces: every time depth wants to grow on the site, the book's condensation pushes back, and every assumption the book-writing agent had to make is a reference the website never had room to carry. The diagnosis of the worst of both worlds is accurate. One small correction of record: as built, the book is the projection of the site, not the other way round; the strain was real in both directions, which is itself the evidence that the coupling, not its direction, was the problem.", "proposal": "The refactor, concretely. (1) The site becomes the research estate: pages deepen and multiply freely, case studies, concept notes, agent-facing documentation, with no book consequence. (2) The book gets its own source tree, `content/book/`, seeded verbatim from today's seventeen units so the split starts at zero drift and diverges only deliberately: distillation, not duplication. (3) Provenance replaces equality: each book unit carries a sources block naming the site pages, sections, site version and commit it distilled from; the gate stops requiring the book to equal the site and starts requiring every unit's provenance to be present and resolvable, and the build reports, rather than forbids, a cited source page that changed since distillation, so drift is visible and re-distillation is a choice. (4) Everything downstream survives unchanged: the reader, the single page, both PDFs, the cover and the version-diff data all project from the book source exactly as they do today. (5) Sequenced as its own release, before the case-study programme starts writing deep pages, so the new depth never has to fight the old gate. Decision D1.", "needs": [], "impact": [ "build pipeline", "validate gate", "book source of truth", "STYLE.md" ], "state": "discussing", "thread": [ { "date": "22 August 2026", "from": "the agent, on the launch of issues-fs.sgit.ai", "note": "External evidence for the decoupling, arriving the same day as the memo. Issues-FS published its own site on 22 August: a research estate at full granularity (a data model page, a DSL page, a CLI page, a shipped page with corrections, seven open questions) for a system this book covers in a handful of sentences. That is the split this item proposes, already happening across the network — and it makes the decoupling urgent rather than tidy. Without it, this book must either duplicate a sibling estate or stay thin about it; with it, the book distils and cites, and the estate carries the depth. The provenance edges of item 2 are what make the citation durable, since the sibling will keep moving.", "sources": [ "[issues-fs.sgit.ai](https://issues-fs.sgit.ai/), published 22 August 2026, site v0.1.1" ] }, { "date": "23 August 2026", "from": "the agent", "note": "**Answered by construction, in a way this item did not anticipate.** Two founder memos have cancelled the refactor in favour of writing the book again from the top down, and [the dev pack](../dev-pack/index.html) makes the decoupling a consequence rather than a project: the second book is a different source tree that carries **provenance edges** back to the first, and ADR-8 flips the gate from *the book must equal the site* to *the book must say where it came from*, which is exactly what this item proposed. The first edition freezes at v0.3.26, hashed and gated. Decision r003-D1 can be closed as answered by the rewrite, and the pack's file 09 records what the rewrite does to the other nine open decisions: four dissolved or answered, two made urgent, four untouched.", "sources": [] } ] }, { "n": 2, "topic": "The clean text, and its provenance edges", "reviewer_says": "This split means that there is a clean text now, which is the text of the book, which we version, which should be kind of independent from the website, although you need to link which parts of the website and which versions of the website and which commits of the website we got the reference from, which is again part of the graph itself of the content of the book. This is again our effort in making the book a graph.", "comment": "This is the same edge r002 item 3 asked for, arriving from the other side: there, the book's sections wanted facts, hypotheses and ontology attached below them; here, every passage wants a provenance edge back to the estate it was distilled from. Together they make the book's graph bidirectional, downward to evidence and backward to source. It is also the book's own thesis applied to itself: the passage is a node, and what it means is what the edges reaching it (this site page, at this version, at this commit) let a reader or an agent trace.", "proposal": "The provenance block of item 1 is the implementation, and it should be machine-readable from day one: the book manifest carries, per unit, a list of {site page, section anchor, site version, commit}. Rendered discreetly (the colophon and the agent surface, not inline clutter), and queryable, so the changes view can answer the question reviews actually need: which book passages are downstream of this site page, and has it moved since they were distilled? That is also the data structure r002 item 5's verification-by-agent dogfood needs, delivered for free.", "needs": [], "impact": [ "book manifest", "colophon", "agent surface", "changes view" ], "state": "proposed" }, { "n": 3, "topic": "The evidence programme: vault case studies before the next book version", "reviewer_says": "What I would like to work next is a series of case studies, sort of what we started doing on the SGit website. I think that was a good one, but we should expand, and then I can guide for each of these vaults on what areas we should do more, we should take more screenshots, we should capture the evidence. The vaults I have created have that evidence, have real-world examples. We have a bit of work now to do on capturing all sorts of case studies and examples from the vaults we have already created, before we tackle the next version of the book, because this is what will provide evidence to all those bits that we need to do on the book.", "comment": "Agree, and it resolves the tension the first two reviews left open: r001 item 8's case studies and r002 item 4's evidence layer both circled the same question, where does the depth live without bloating the book, and the decoupling answers it structurally: on the website, at full granularity. It also reorders the plan. The sequencing proposals in r001 item 9 and r002 item 9 put the identity release early; this memo puts the evidence programme first, and the threads on both items now record that. The inventory is already mapped: three sgit.ai demo vaults, four sgraph.ai public vaults, and the SGit, IssuesFS and EmailFS sources the librarian resolved path by path.", "proposal": "A `/case-studies/` section, one deep page per vault or system: what it demonstrates about the discipline, the techniques used in practice, screenshots captured as code (r001 item 6's pipeline), the real numbers, and an explicit 'what the book will cite from this' block so distillation is designed in from the start. Proposed order, largest evidence first: the regulation graph vault, Risk Graph Explorer, browser isolation, the sgraph.ai library-as-a-vault, then SGit, IssuesFS and EmailFS from the resolved sources. Each case study ships as its own release; the book stays untouched until distillation. The founder's per-vault guidance is the open ask (N13); decision D3 confirms the order.", "needs": [ "Per-vault guidance: which areas to go deeper on, what to screenshot, what evidence to capture (ask N13).", "The screenshots-as-code pipeline from r001 item 6, which this programme would exercise immediately." ], "impact": [ "new site section", "site navigation", "the book's future evidence citations" ], "state": "applied", "thread": [ { "date": "22 August 2026", "from": "the agent, on the launch of issues-fs.sgit.ai", "note": "The case-study programme now has **two kinds of entry**, and the distinction should be made before the order is confirmed. Some case studies must be **written** from repository sources (the three sgit.ai demo vaults, the team-as-a-graph). Others are now **distillations** from a sibling estate that already holds the granularity and will keep moving: EmailFS from sgraph.ai's protocol section, and now IssuesFS from issues-fs.sgit.ai. The second kind is cheaper, better sourced and more durable, but only if provenance is recorded, since a distillation of a live site drifts the moment the site ships. Recommendation for decision D3: take the distillations first (they are ready now and they prove the provenance mechanism on real, moving targets), then the written ones as the founder's per-vault guidance arrives.", "sources": [ "[issues-fs.sgit.ai](https://issues-fs.sgit.ai/) — the IssuesFS entry becomes a distillation, not a write-up", "[sgraph.ai's Email-FS-lite protocol section](https://sgraph.ai/en-gb/library/how-it-works/email-fs-lite.md)" ] }, { "date": "22 August 2026", "from": "the agent", "note": "**Started, and the shape held.** The founder brought this item forward ahead of the decoupling (D1) and the ladder (r004 D1), naming the first two vaults himself. [/vaults/](../vaults/index.html) is now a section with one folder and three pages per vault, the vault's own published screenshots, its derived facts quoted rather than recounted, and the **what the book will cite** block this item proposed, written per page rather than reverse-engineered later. One thing the first two analyses proved about the method: the depth is real. Each vault carried two ideas that a chapter could not have held — the junction rule and the empty layer for VoiceDebrief, the provenance chain and the query engines for the Regulation Graph — and the second of those settles r001 item 5's outstanding verification.", "sources": [] }, { "date": "23 August 2026", "from": "the agent", "note": "**Three more, and the first finding only the comparison could produce.** The founder asked for the same treatment on the risk-related vaults, and [/vaults/](../vaults/index.html) now carries **Risk Mandate** (124 files, 98 commits, eight entry points into one mandate), **Agentic Browser Isolation** (104 files, 17 entry points, and the same risk written seven times, once per stakeholder, none of them a summary of another) and the **Risk Graph Explorer** (33 files, `permissions: {}`). What is new in this round is not the fifth analysis but the **cross-vault page**: [the capability scale](../vaults/capability-scale.html) reads all five permission blocks side by side and finds a scale with a floor, a hard middle and a ceiling. No single case study contains it. That is the first evidence that this programme produces findings the book could not have argued its way to, which is what the item claimed it would do.", "sources": [ "[sgit.ai/demos/vaults/](https://sgit.ai/demos/vaults/index.html) — the vault index the three were taken from" ] }, { "date": "23 August 2026", "from": "the agent", "note": "**The other half of the evidence programme: the inputs.** The vault analyses cover what the discipline produced; this round covers what the book was produced *from*. [/docs/](../docs/index.html) carries **fifteen documents, 39,973 words**, chosen from the 147 rows of the three source manifests — of which 111 resolved against the public repositories, so the choice was made from the actual corpus rather than from titles. They are carried byte-for-byte with their SHA-256 and a gate check, because a site that argues for chain of custody should not summarise its own sources. The part worth arguing with is the **three kinds of link**: the documents are carried, the concept links are measured against a published phrase list, and the site links are authored with a note. Influence is then a stated formula over the three, and the page states what the measure is not. One thing only the consolidated graph could show: **the single concept measured in all fifteen documents is *a claim is worth its chain of custody*** — the corpus's most repeated idea is the one about repeating ideas honestly.", "sources": [ "[the-cyber-boardroom/SGraph-AI__App__Send](https://github.com/the-cyber-boardroom/SGraph-AI__App__Send) — the public repository all fifteen are carried from, at commit b561fa6b14" ] }, { "date": "23 August 2026", "from": "the agent, correcting the entry above", "note": "**The set grew to twenty-one, and the claim in the previous note is now wrong.** The founder took the six next-up documents, so [/docs/](../docs/index.html) holds 21 documents and 63,038 words. The note above says the single concept measured in all fifteen was *a claim is worth its chain of custody*. At twenty-one it is measured in **twenty**, and the one that misses it is [Compatibility Through Connectivity](../docs/compatibility-through-connectivity.html), one of the three February documents, written before the provenance vocabulary hardened. The earlier note stays as written, because it was true of the set it described; this is what supersede-rather-than-delete looks like when the superseded claim is one of mine. The useful part is the shape of the failure: a property that holds at n=15 and breaks at n=21 was a property of the sample, not of the corpus. **A new measure came out of it.** *Concentration* is the share of a concept's mentions sitting in its top three documents. Only two concepts come in under 0.55; everything else is above 0.7, meaning one or two documents carry it and the rest allude to it. Breadth of mention is not weight, and the table now shows both. Also checked rather than assumed: the three imported Issues-FS documents are **byte-identical** across both public repositories, and those same three are the only ones without a per-file CC BY line, because the licence audit stamped the Send tree and not the references imported into it.", "sources": [] } ], "applied_in": "v0.3.19" }, { "n": 4, "topic": "Reviews gain a decisions mode", "reviewer_says": "The reviews need a new mode called decisions, which basically means you can see the decisions that are needed, and then the answers to the decisions. And the evidence.", "comment": "Agreed, and it fixes a reading problem the two live reviews already have: their open decisions (the title, the humans-and-agents allocation, the pilot chapter, the sequencing) were buried inside proposals and threads, so anyone returning to a review had to re-read nine items to find what is actually being waited on.", "proposal": "Landed in the same release that published this review, because it is review tooling, not book content: every review's JSON now carries a decisions register, and every review page renders it at the top: each decision numbered, linked to the item it belongs to, showing its options while open and its answer once made. r001 and r002's open decisions are now explicit (two on r001, three on r002), and this review adds three of its own. The register is machine-readable in the same JSON, so an agent reads the decision state the same way a human does.", "needs": [], "impact": [ "review pages", "review JSON schema", "reviews register" ], "state": "applied", "applied_in": "v0.3.13, v0.3.22", "thread": [ { "date": "23 August 2026", "from": "the agent", "note": "**The register gets a face, and it is a graph.** The decisions mode this item asked for now has [a page of its own](../decisions/index.html): every decision from all four reviews as the peak of its own small graph, with the options below it, the side effect that follows from each option, the work it blocks and the pages it touches. It is generated by `admin/build/gen_decisions.py` straight from each review file's `decisions` array, so it cannot drift from the reviews — and the build **fails** if an open decision has no authored options, which stops a question shipping with nothing under it. Two things came from elsewhere on the site rather than being invented: the mechanism is the Agentic Browser Isolation vault's risk acceptance rules applied unchanged (one named owner, **no deny button**, nothing moves until it is taken personally, the reason travels with the answer), and the whole-register view borrows the peak idea from [the concept map](../altitudes/concepts.html). Answers are held in the reader's own browser and copied back as plain text, because a site with no server should not grow a form endpoint to collect decisions.", "sources": [] } ] }, { "n": 5, "topic": "Each review is a folder with its own graph, managed as issues", "reviewer_says": "Each review in itself needs to be a folder that has its own graph that we need to visualise, and its graph should have the sections, the decisions that are needed, the answers to the decisions, and the evidence. Every request, every question, every piece of information or comment should itself be a node in a graph, where the view is a projection of that. Each review is a folder; inside its folder it has its own items, issues, questions, and if anything, we should be using issues here to clean this up, because that should be the logic of managing this. Because that's in itself, it's a graph.", "comment": "Agree, and the current shape is already halfway there: each review is one JSON file whose page is a pure projection, and the items, decisions, threads and evidence are the nodes in all but name. What is missing is the edges being explicit, the folder being the unit, and the graph being drawable. The one genuine fork is which issues logic manages the folder: GitHub issues would put the conversation on rented infrastructure; in-repo issues, the IssuesFS pattern (issues as files, states as data, the graph computable from the folder), keep the serverless-pull-request property this workflow was named for, and would dogfood the exact case study r001 item 8 wants written.", "proposal": "Restructure to `reviews/rNNN/` folders: the review head, then items, decisions and evidence as their own files, with typed edges in the folder's graph (item has-decision, decision answered-by, thread-entry responds-to, evidence supports), honouring the house grammar: verbs with inverses, no generic association. A generator draws each review's graph as an SVG on its page, items, decisions and evidence coloured by state, which proves r002 item 6's chapter-graph pattern on cheaper ground before the book uses it. Current URLs (rNNN.html, rNNN.json) stay as forwards. Recommendation on the fork: in-repo issues. Decision D2.", "needs": [ "Decision D2 on the issues logic before the folder restructure lands." ], "impact": [ "reviews structure", "review URLs (kept as forwards)", "a per-review graph visualisation" ], "state": "proposed" }, { "n": 6, "topic": "Keep enriching the reviews: the updates to r001 and r002", "reviewer_says": "There's a couple of updates that we're gonna do to the other reviews, and I also want to comment a little bit more about capturing the reviews itself. I think we should capture this as a third review, and maybe keep enriching the reviews.", "comment": "The enrichment pattern is now established across four releases and stays append-only: needs answered as threads (the librarian's pack), estates added as threads (sgraph.ai), calibrations as threads (the founder on the librarian), and now cross-review consequences as threads. A review is a conversation with a record, never rewritten history.", "proposal": "Landed with this release: r001 item 8 records where the case studies now live (website at full granularity, book carries the distilled best-of), r001 item 9 and r002 item 9 record the resequencing (evidence programme first, identity release after, chapter audit throughout), and both reviews' state notes point here. Future updates keep the same shape: this review is the venue for the decoupling and evidence conversation, and its decisions register is where the three open calls get answered.", "needs": [], "impact": [ "r001", "r002" ], "state": "applied", "applied_in": "v0.3.13" } ] }