@nurix/etna 0.20.26 → 0.20.28

package/data/harnesses/discussion/harness.json

@@ -10,5 +10,9 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
+  "mount": {
+    "origin": "https://cdn.nustack.io",
+    "track": "latest"
+  },
   "digest": "ed9548ee592a"
 }

package/data/harnesses/etna/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.27",
+  "version": "1.5.28",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,9 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "bbde0394df6d"
+  "mount": {
+    "origin": "https://cdn.nustack.io",
+    "track": "latest"
+  },
+  "digest": "6a10dd14cf28"
 }

package/data/harnesses/etna/skills/documentation/SKILL.md

@@ -7,7 +7,7 @@ description: "Use when creating or substantively editing ANY markdown doc — in
 
 **This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
-Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). A diagram sits beside the prose and never replaces it: ASCII for structure at rest, mermaid for behaviour over time (`references/style-guide.md` § Diagrams). Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
 
 ---
 
@@ -42,9 +42,9 @@ Document contracts and architecture, not implementation details. Signatures and
 | "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
 | "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
 
-The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
+The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — tense and history.
 
-**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The four exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, `docs/structure.md`'s **Health Log** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present.
+**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The three exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail on a truth document.
 
 **Cite a record by what it is, never by when it was.** `the dev reset runbook` links to the file; "the 2026-09-13 reset" states a date the reader must now keep in their head and that goes stale as soon as a second reset happens. The link carries the date in its path, where it belongs, and the prose stays true forever.
 
@@ -74,9 +74,9 @@ The two guarantees are complementary and both break on mixing: a reader holding
 - **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
-**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is read by people** — plain English a newcomer reads top to bottom, with code named only at a cross-cutting seam the graph would not lead a reader to from the feature's own files (a middleware, a gate, a hook, a shared store) and every other identifier in the closing **For the agent** footer; the owning genres read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent (`references/style-guide.md` § Documents are read by people; `doc-lint` warns `body-identifier`, `list-not-prose`, `formula-run`).
+**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).
 
-**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document is the authority on *why*, and a disagreement on *why* is a defect to raise. The layers, the test and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after.
+**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document is the authority on *why*, and a disagreement on *why* is a defect to raise. **Every heading and every bold bullet label is a noun phrase** — it names; it has no verb, so it carries no tense, person or voice ("Decisions", never "What was decided"; "Organization user:", never "You already belong to an organization:"), and the sentence after it is third person ("user lands…", never "you land…"). The layers, the test, the label rule and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after, and § Labels.
 
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
@@ -186,7 +186,7 @@ update, and the `maintenance` agent's baseline pass, route there.
 | File | Use For |
 | --- | --- |
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
-| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/style-guide.md` | The writing-style authority: the eight principles, depth per genre, the outside-in shape and stability test, noun-phrase labels and third-person voice, the owning document's body and footer, the two-natures tense rules, diagrams, headings, reference-document detail |
 | `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
 | `references/frontmatter.md` | Deriving a feature doc's `objects:` / `owns:` / `module:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |

package/data/harnesses/etna/skills/documentation/references/examples.md

@@ -146,37 +146,41 @@ Replaced change-tracking merge with version-based conflict resolution.
 
 ---
 
-## Example 4: Data Flow
+## Example 4: Flow
 
-### ❌ Bad: Prose Description
+### ❌ Bad: Mechanism narrated in a paragraph
 
 ```markdown
+## Data Flow
+
 When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
 ```
 
-### ✅ Good: Diagram + Key Points
+**Problems:** names a hook, a function and a store that a rename would invalidate (the stability test); runs parallel cases together in one paragraph; gives a scanning reader no label to land on; "Data Flow" is a retired mechanism section.
 
-```markdown
-## Data Flow
+### ✅ Good: Labelled bullets, a role-level diagram beside them
 
-┌─────────────────────────────────────────┐
-│               DATA SYNC                 │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌──────┐     ┌──────┐     ┌──────┐    │
-│   │Server│────▶│Merge │────▶│Redux │    │
-│   │ API  │     │      │     │Store │    │
-│   └──────┘     └──────┘     └──────┘    │
-│        │                                │
-│        ▼                                │
-│   Version Check                         │
-│                                         │
-└─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load
-
-**Version Rule:** Match → local wins, Mismatch → server wins
+````markdown
+## Flows
+
+### Page load
+
+- **Fresh data:** the page fetches the server's copy and the local copy on every load; nothing is cached between visits.
+- **Matching versions:** local changes win and are kept.
+- **Mismatched versions:** the server's copy wins and local changes are dropped.
+
+```mermaid
+sequenceDiagram
+  participant Page
+  participant Server
+  participant Store
+  Page->>Server: fetch the server's copy
+  Page->>Store: read the local copy
+  Page->>Store: write the merged copy
 ```
+````
+
+**Why it works:** every fact is in the bullets, so a reader who greps finds it without the diagram; the labels are noun phrases a scanning reader lands on; the diagram names roles, never a function or a file, so no rename touches it.
 
 ---
 
@@ -242,7 +246,7 @@ The feature doc states only what is:
 ```markdown
 ## Export Pipeline
 
-`src/export/run.js` renders every export format from one job queue. Output is
+The exporter renders every export format from one job queue. Output is
 buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
 ```
 
@@ -272,8 +276,8 @@ Extracted export logic from the `reports` worker into `src/export/`.
 | ---------- | -------------------- | --------------------------- |
 | Code       | Full implementations | Signatures + contracts      |
 | State      | Every occurrence     | Persistence points only     |
-| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Flows      | Paragraphs naming functions | Labelled bullets in plain words, a role-level diagram beside them |
 | Changelogs | "Updated X"          | Function names + migrations |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
 | History    | Narrated in the doc  | Present-tense doc + dated record |
-| Length     | 100+ lines           | 20-40 lines                 |
+| Length     | Padded with mechanism | The genre's own expectation; length is a signal, never a target |