@nurix/etna 0.20.35 → 0.20.37

package/data/harnesses/code/skills/documentation/references/frontmatter.md

@@ -2,11 +2,11 @@
 
 Load when: creating a document that carries frontmatter, updating one whose subject moved, or running a baseline or reconcile pass over many documents.
 
-This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect.
+This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect; where a repository carries no such design, this file is the authority.
 
 ## The model
 
-A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document.
+A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document. The harness's ownership scan reads one edge, the transitional `owns:` region glob (§ `owns:` — transitional); principles 2 and 3 are the edges it switches to, and the header pointer is written alongside it so the switch needs no second pass over the code.
 
 ### Principles
 
@@ -30,14 +30,14 @@ A document names the product objects it designs. Every other edge between a docu
 | Acceptance criteria | `type`, `description`, `status` |
 | Every other genre | `type`, `description`, plus its template's own keys |
 
-Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), and `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal). Sessions preserve them on edits and never narrate or inject them. The `maintenance` agent stamps `type:` where it is missing.
+Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal), `last-updated:` (an Architecture Decision's revision stamp, bumped with each Decision Changelog entry) and `harness-version:` (stamped on `docs/structure.md` by the `maintenance` agent). Sessions preserve them on edits, stamp `last-reviewed:` and `last-updated:` where their genre says so, and never narrate them. The `maintenance` agent stamps `type:` where it is missing.
 
 ## Keys
 
 ### `description:`
 
 - **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
-- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry's one-line summary is its row in `CHANGELOG.md`). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole; `docs/operations/bookkeeping.md`, which the hooks write from a fixed header; and a tree a generator owns (`docs/dna/`, the product-dna skill's). A release note under `docs/operations/release-notes/` is a record, frozen at publication.
+- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry has none: its heading line is its summary). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole; `docs/operations/bookkeeping.md`, which the hooks write from a fixed header; and a tree a generator owns (`docs/dna/`, the product-dna skill's). A release note under `docs/operations/release-notes/` is a record, frozen at publication.
 - **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
 - **Upkeep:** an edit that changes what a document settles updates its description in the same edit.
 
@@ -50,7 +50,7 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 ### `status:`
 
-- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents.
+- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents. An Architecture Decision keeps its own lifecycle, `Proposed`, `Accepted` or `Deprecated` (`templates/architecture-decision.md`).
 
 ### `module:`
 
@@ -63,7 +63,7 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 ### `owns:` — transitional
 
-- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. Until then the key keeps the session's ownership index and the doc-debt detectors working.
+- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. The key is what keeps the session's ownership index and the doc-debt detectors working.
 - **Form:** region globs only, one per region the document speaks for: `packages/{name}/**` on a package document, the machine's subtrees on a system document, a feature's own directory on a feature document. Never a list of individual files, and never a shared file several features import.
 - **Growth:** none. A new document carries the region glob its genre needs and nothing more; an edit never adds file-level entries.
 - **Retirement:** removed from every document in the same change that switches the scan, and this section with it.
@@ -72,8 +72,8 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 | Key | Retired because | What replaces it |
 | --- | --- | --- |
-| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section names its governing doctrine and what each settles |
-| `keywords:` | An object's name and aliases are its discovery terms | `objects:` |
+| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section (a UX document's Purpose) names its governing doctrine and what each settles |
+| `keywords:` | An object's name and aliases are its discovery terms | `objects:`. The ownership scan shows a document's `keywords:` in the index when it names no `objects:`, so removing the key without adding `objects:` empties that entry |
 | A file-level `owns:` list | The header pointers and the object closure compute it | Region globs only, until the scan switches (above) |
 
 An edit to a document that carries a retired key removes the key in the same edit.

package/data/harnesses/code/skills/documentation/references/instruction-style.md

@@ -1,4 +1,4 @@
-# Instruction-File Style
+# Instruction-file style
 
 The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
 
@@ -6,11 +6,11 @@ The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an age
 
 An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and unscoped rules load on **every turn of every session** — the most expensive prose in a repo per word; a `paths:`-scoped rule loads on those same terms from its first matching file read on; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
 
-**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+**On a rewrite, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
 
 ## Coherence
 
-A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+A rewrite is not only a trim. Read the file as one artifact and fix what disagrees or is missing:
 
 - **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
 - **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.

package/data/harnesses/code/skills/documentation/references/source-comments.md

@@ -0,0 +1,19 @@
+# Source comments — what stays in the file and what moves to docs
+
+Load when: writing or sweeping source-file comments, or cutting a comment whose claim belongs in a document. Not needed to write a document.
+
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the canonical shape is the harness's `CLAUDE.md` § File Structure. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+
+**Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
+
+| The claim is | What it earns |
+| --- | --- |
+| Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
+| Already stated in its doc | Nothing, once you **open that doc and find the sentence**. An assumed duplicate is how a claim is lost |
+| History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
+
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so an unaccounted drop shows as a number. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+
+**The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](../scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
+
+**Never convert a booby trap into a one-liner.** A comment whose subject is a danger on an edge that looks safe — a pinned dependency's limitation, a measurement that justifies a narrow allowlist, a two-clock interaction — is load-bearing where it sits, because the reader who needs it is mid-edit and will not go looking. Compress it if it rambles; do not relocate it. The tell is that the comment names a version, a measurement, or a condition under which it expires.

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -1,9 +1,9 @@
 <!-- doc-lint-disable: date-in-truth-doc, history-narration, stale-tripwire, progress-marker, temporal-hedge, predecessor-frame, status-glyph -->
 <!-- reason: the style authority quotes the forbidden constructions verbatim in its ❌ columns; each match is an example of what not to write. -->
 
-# Documentation Style Guide
+# Documentation style guide
 
-This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it. [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean; each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections of this guide are enough to write a correct document; the sections after them are the detail each principle unfolds into, and a reader who stops early holds a coarse picture that is still true.
+This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it: [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean, and each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections are enough to write a correct document; the sections after them are the detail each principle unfolds into, so a reader who stops early holds a coarse picture that is true.
 
 ## The model
 
@@ -11,7 +11,7 @@ A document is read by a person who wants to understand something or to act on it
 
 ### Principles
 
-1. **Two natures:** every document is a truth document (what is, now, rewritten in place) or a record (what happened, dated and frozen). A truth document never narrates history and a record is never edited to match the present, because a reader must be able to trust each without the other.
+1. **Three natures:** every document is a truth document (what is, now, rewritten in place), a record (what happened, dated and frozen) or a queue (work not done yet, rows appended and deleted when resolved). A truth document never narrates history, a record is never edited to match the present, and a queue holds only open rows, because a reader must be able to trust each without the others.
 2. **The outside-in shape:** an explaining document opens on the question it answers and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser the next section completes.
 3. **The stability test:** a sentence that would have to change when a function is renamed, a file moves, a route, column, error code or cookie attribute changes, or a constant is retuned without the design changing belongs to the code, which the code graph computes on demand (`docs/architecture/systems/knowledge-layer.md`), and not to the document. A copy typed into a document is at best a duplicate of the code and at worst a stale one.
 4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose.
@@ -32,9 +32,10 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 | Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |
 | Reference (API reference, environment registry) | Truth | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
 | Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point |
-| Record (plan, changelog entry, journal, memory) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
+| Record (plan, changelog entry, runbook) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
+| Queue (backlog, journal, bookkeeping, memory) | Queue | One row per open item, in its template's row grammar | Nothing. A row may carry its own date; a resolved row is deleted |
 
-- **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them.
+- **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them. A UX document also speaks for a surface's components where none of the three does; its sections are its own genre's (`templates/ux-behavior.md`).
 - **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
 - **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents).
 - **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
@@ -51,6 +52,16 @@ Every truth document a person reads to understand something is written from the
 4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with why the part exists, never with how it is built.
 5. **The genre's deepest layer:** the row for the genre in § The genres, and nothing deeper.
 
+An owning or doctrine document's fixed sections carry these layers; nothing is added beside them to hold a layer:
+
+| Layer | Feature | System | Package | Doctrine |
+| --- | --- | --- | --- | --- |
+| The question and its boundary | Goal line, Scope | Opening paragraph, Scope | Identity and goal lines, Scope | Opening paragraph |
+| The model | Scope's Covers bullet | Flow's opening | Usage's opening | The model |
+| The parts | Flows | Flow | Ownership, Usage | The parts |
+| Each part's decisions | Decisions | Decisions | Decisions | The parts in depth |
+| The deepest layer | Promises | Promises | Promises | — |
+
 ### The stability test
 
 The test (principle 3) decides what a sentence may say. These survive it:
@@ -62,7 +73,9 @@ The test (principle 3) decides what a sentence may say. These survive it:
 - **Cross-component contracts:** what no single file shows, such as two clients that must classify the same answer identically.
 - **Decided-but-unbuilt intent:** what the code cannot reveal because it does not yet do it, wrapped in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->` in plain words. A design decided *against* carries no marker.
 
-The authority split (principle 4) is stated in the opening of any document whose readers include agents, so a reader who finds the code and the document disagreeing knows which way to resolve it.
+Unbuilt work has one home per kind. Decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
+
+The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its opening, as the authority sentence (`templates/doctrine.md`), where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
 
 ### Diagrams and length by layer
 
@@ -118,7 +131,7 @@ A feature, package or system document is scanned more than read (principle 6). I
 | System | Opening paragraph (the machine defined) · Scope · Flow · Decisions · Promises · Gaps · For the agent |
 | Package | Identity line · Goal line · Scope · Ownership · Usage · Decisions · Promises · Gaps · For the agent |
 
-Nothing else. "Why it exists" is retired; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
+Nothing else. A "Why it exists" section has no place; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
 
 ### The body
 
@@ -144,11 +157,12 @@ A feature adds its pages, because an address is what a person points at; a packa
 
 ## The Two Natures — tense and history
 
-Every document is a truth document or a record (principle 1); `SKILL.md` § The Two Natures gives the split, the folders and the lifecycle. The tense rules follow directly.
+Every document is a truth document, a record or a queue (principle 1); `SKILL.md` § The three natures gives the split and the genre registry (`templates/Readme.md`) gives each genre's nature. The tense rules follow directly.
 
-- **Truth documents:** everything outside `docs/history/`, `docs/research/` and `docs/memory/` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records.
+- **Truth documents:** every genre the registry marks `truth` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records.
 - **The one bridge:** an Architecture Decision's **Decision Changelog** tail carries that decision's dated revision history while its body stays current-truth-only; head is truth, tail is provenance. No other truth document carries a dated line, apart from the frontmatter's tooling keys and a dated path inside a link or code span, which cites a record rather than claiming a date. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail.
 - **Records:** never edited to match the present. A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
+- **Queues:** a row is appended when the work appears and deleted when it is done, drained or promoted, never marked done in place. A row may carry its date; nothing else in a queue is edited.
 
 | ❌ Historical narration (a record's) | ✅ Present-tense fact (the truth document's) |
 | --- | --- |
@@ -239,7 +253,7 @@ flowchart LR
 - **Retrieval keys:** search and agents retrieve a section out of context, where a bare `### Failures` reads identically across every document. A generic `###` heading, and every heading in an untemplated document, is qualified by its topic (`### Sign-in failures`, `### Merge rules — data sync`) so it stands alone when retrieved. A short document whose H1 disambiguates can keep bare headings.
 - **Sentence case:** headings are sentence case; a product, a proper name or a named concept (`The Two Natures`) keeps its own casing.
 - **No hard-wrapped prose:** a paragraph is one line in the source (`.prettierrc.json` keeps `proseWrap: never`); the renderer wraps it.
-- **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § The Two Natures).
+- **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § Truth documents).
 - **No file rosters:** a file list belongs in no document. The ownership index and the code graph answer "which file" for every genre, and a folder index describes directories, never files.
 - **The reference-document layout:** a document that is not an owning genre and whose content is the contract itself (an API reference, an environment registry, a procedure's appendix) opens on its goal, as a `**Goal:**` line or one sentence, and proceeds straight to its contract or procedure sections:
 
@@ -255,7 +269,7 @@ flowchart LR
 
 ## Reference documents
 
-A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol nowhere but its footer, and then only as a seam.
+A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol only as a seam (§ Owning documents — the body and the footer).
 
 ### Function signatures
 

package/data/harnesses/code/skills/documentation/references/untemplated.md

@@ -1,27 +1,28 @@
-# Writing an Untemplated Document
+# Writing an untemplated document
 
 Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".
 
 A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.
 
-## 1. Decide the nature — truth or record
+## 1. Decide the nature — truth, record or queue
 
-Every document is exactly one (`SKILL.md` § The Two Natures). Ask: *when reality changes, is this file rewritten, or is it frozen?*
+Every document is exactly one of the three (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
 
-- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § Present tense, always.
-- Frozen or append-only → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout.
+- Frozen → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+- Loses a row when work is resolved → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
 
 When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
 
 ## 2. Place and name it
 
 - `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
-- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
-- A new topic *folder* gets a `Readme.md` landing page that introduces and indexes it.
+- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift. Link, don't copy.
+- A new topic *folder* gets a `Readme.md` landing page that describes what the folder holds and how its files are named, never a row per file (`type: folder-index`).
 
 ## 3. Shape it
 
-- **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Open with the goal.** The first line under the H1 states what the document is for and who reads it, so a reader landing cold decides in one sentence whether to keep reading.
 - **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
@@ -35,6 +36,6 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 ## 5. With a human in the loop — the co-authoring workflow
 
-**Stage 1 — context gathering.** Ask: audience? purpose? existing format to match? Have the user dump all the context they hold, then ask 5–10 clarifying questions before proposing anything.
+**Stage 1 — context gathering.** Read what already exists on the topic, then draft the structure from §1–3 with sensible defaults for audience, purpose and format. Ask only the questions whose answer the repository cannot give and a default would get wrong (usually one to three), each with your recommended answer, in one message.
 
-**Stage 2 — structure & draft.** Propose the section structure from §1–3 above, then draft section by section. The user indicates changes — learn their style from their edits; don't silently rewrite them.
+**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. Learn the user's style from the changes they make, and **never** silently rewrite their edits.