@nurix/etna 0.19.33 → 0.19.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/data/harness-index.json +5 -1
- package/data/harnesses/code/harness.json +1 -1
- package/data/harnesses/delivery/.prettierignore +29 -0
- package/data/harnesses/delivery/.prettierrc.json +3 -0
- package/data/harnesses/delivery/.vscode/settings.json +19 -0
- package/data/harnesses/delivery/CLAUDE.md +123 -0
- package/data/harnesses/delivery/agents/brainstorm.md +144 -0
- package/data/harnesses/delivery/agents/data-generator.md +23 -0
- package/data/harnesses/delivery/agents/eval-runner.md +23 -0
- package/data/harnesses/delivery/agents/judge.md +23 -0
- package/data/harnesses/delivery/agents/lld-mode.md +56 -0
- package/data/harnesses/delivery/agents/maintenance.md +229 -0
- package/data/harnesses/delivery/agents/prompt-iterator.md +23 -0
- package/data/harnesses/delivery/agents/red-team.md +23 -0
- package/data/harnesses/delivery/agents/regression-runner.md +28 -0
- package/data/harnesses/delivery/agents/retro.md +46 -0
- package/data/harnesses/delivery/codex/agents/brainstorm.toml +142 -0
- package/data/harnesses/delivery/codex/agents/data-generator.toml +22 -0
- package/data/harnesses/delivery/codex/agents/eval-runner.toml +22 -0
- package/data/harnesses/delivery/codex/agents/judge.toml +22 -0
- package/data/harnesses/delivery/codex/agents/lld-mode.toml +52 -0
- package/data/harnesses/delivery/codex/agents/maintenance.toml +228 -0
- package/data/harnesses/delivery/codex/agents/prompt-iterator.toml +22 -0
- package/data/harnesses/delivery/codex/agents/red-team.toml +22 -0
- package/data/harnesses/delivery/codex/agents/regression-runner.toml +27 -0
- package/data/harnesses/delivery/codex/agents/retro.toml +45 -0
- package/data/harnesses/delivery/harness.json +11 -0
- package/data/harnesses/delivery/hooks/generate-ownership-index.mjs +148 -0
- package/data/harnesses/delivery/hooks/hooks.json +16 -0
- package/data/harnesses/delivery/rules/changelog.md +19 -0
- package/data/harnesses/delivery/rules/evals.md +23 -0
- package/data/harnesses/delivery/rules/model-tiers.md +18 -0
- package/data/harnesses/delivery/rules/nomenclature.md +34 -0
- package/data/harnesses/delivery/rules/prompting.md +23 -0
- package/data/harnesses/delivery/skills/brainstorm/README.md +56 -0
- package/data/harnesses/delivery/skills/brainstorm/SKILL.md +173 -0
- package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md +98 -0
- package/data/harnesses/delivery/skills/brainstorm/references/harvest.md +86 -0
- package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md +186 -0
- package/data/harnesses/delivery/skills/brainstorm/scripts/detector.mjs +460 -0
- package/data/harnesses/delivery/skills/cost-report/SKILL.md +24 -0
- package/data/harnesses/delivery/skills/documentation/SKILL.md +129 -0
- package/data/harnesses/delivery/skills/documentation/references/examples.md +279 -0
- package/data/harnesses/delivery/skills/documentation/references/frontmatter.md +44 -0
- package/data/harnesses/delivery/skills/documentation/references/style-guide.md +340 -0
- package/data/harnesses/delivery/skills/documentation/references/untemplated.md +38 -0
- package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs +140 -0
- package/data/harnesses/delivery/skills/documentation/templates/Readme.md +31 -0
- package/data/harnesses/delivery/skills/documentation/templates/api-reference.md +20 -0
- package/data/harnesses/delivery/skills/documentation/templates/architecture-decision.md +121 -0
- package/data/harnesses/delivery/skills/documentation/templates/backlog.md +33 -0
- package/data/harnesses/delivery/skills/documentation/templates/changelog-entry.md +57 -0
- package/data/harnesses/delivery/skills/documentation/templates/changelog-index.md +41 -0
- package/data/harnesses/delivery/skills/documentation/templates/docs-readme.md +72 -0
- package/data/harnesses/delivery/skills/documentation/templates/domain-model.md +30 -0
- package/data/harnesses/delivery/skills/documentation/templates/environment-registry.md +15 -0
- package/data/harnesses/delivery/skills/documentation/templates/feature.md +149 -0
- package/data/harnesses/delivery/skills/documentation/templates/glossary.md +11 -0
- package/data/harnesses/delivery/skills/documentation/templates/memory-main.md +25 -0
- package/data/harnesses/delivery/skills/documentation/templates/migration-runbook.md +34 -0
- package/data/harnesses/delivery/skills/documentation/templates/non-goals.md +11 -0
- package/data/harnesses/delivery/skills/documentation/templates/operations-procedure.md +36 -0
- package/data/harnesses/delivery/skills/documentation/templates/plan.md +64 -0
- package/data/harnesses/delivery/skills/documentation/templates/protected-files.md +37 -0
- package/data/harnesses/delivery/skills/documentation/templates/root-readme.md +104 -0
- package/data/harnesses/delivery/skills/documentation/templates/security-overview.md +27 -0
- package/data/harnesses/delivery/skills/documentation/templates/structure.md +65 -0
- package/data/harnesses/delivery/skills/documentation/templates/system-overview.md +32 -0
- package/data/harnesses/delivery/skills/documentation/templates/testing-strategy.md +29 -0
- package/data/harnesses/delivery/skills/escalate/SKILL.md +25 -0
- package/data/harnesses/delivery/skills/prompt-eval/SKILL.md +22 -0
- package/data/harnesses/delivery/skills/prompt-library/SKILL.md +36 -0
- package/data/harnesses/delivery/skills/route/SKILL.md +21 -0
- package/data/harnesses/etna/harness.json +1 -1
- package/data/harnesses/hr/harness.json +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
|
|
2
|
+
|
|
3
|
+
Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
|
|
4
|
+
|
|
5
|
+
The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# {Feature Name}
|
|
9
|
+
|
|
10
|
+
**Status:** Draft | In Progress | Complete | Abandoned
|
|
11
|
+
**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
|
|
12
|
+
**Started:** YYYY-MM-DD
|
|
13
|
+
**Completed:** YYYY-MM-DD <!-- fill when status flips to Complete -->
|
|
14
|
+
|
|
15
|
+
## Background
|
|
16
|
+
|
|
17
|
+
Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.
|
|
18
|
+
|
|
19
|
+
## Proposed Changes
|
|
20
|
+
|
|
21
|
+
### New Files
|
|
22
|
+
|
|
23
|
+
- `src/path/new-file.js` — purpose
|
|
24
|
+
|
|
25
|
+
### Modified Files
|
|
26
|
+
|
|
27
|
+
- `src/path/existing.js` — what changes and why
|
|
28
|
+
|
|
29
|
+
### New Entities / State
|
|
30
|
+
|
|
31
|
+
- `entities.foo` — new Redux slice / DB table / persisted shape
|
|
32
|
+
- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)
|
|
33
|
+
|
|
34
|
+
### API Changes
|
|
35
|
+
|
|
36
|
+
- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
|
|
37
|
+
- `PUT /api/bar` — request shape changes; see Migration
|
|
38
|
+
|
|
39
|
+
### Cross-Module Contracts Affected
|
|
40
|
+
|
|
41
|
+
- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
|
|
42
|
+
- "None" is a valid answer and means the `boundary` check will pass cleanly
|
|
43
|
+
|
|
44
|
+
## Implementation Steps
|
|
45
|
+
|
|
46
|
+
1. Concrete, ordered, testable
|
|
47
|
+
2. Each step ends with something verifiable
|
|
48
|
+
3. ...
|
|
49
|
+
|
|
50
|
+
## Done Criteria
|
|
51
|
+
|
|
52
|
+
- [ ] Implementation complete and verified
|
|
53
|
+
- [ ] Affected docs updated (use the injected ownership index to find them)
|
|
54
|
+
- [ ] Changelog entry created in `docs/history/changelog/`
|
|
55
|
+
- [ ] Plan marked `Status: Complete`, **Completed:** date filled
|
|
56
|
+
|
|
57
|
+
## Open Questions
|
|
58
|
+
|
|
59
|
+
- Question — who decides, by when
|
|
60
|
+
|
|
61
|
+
## Risks
|
|
62
|
+
|
|
63
|
+
- Risk — likelihood / impact / mitigation
|
|
64
|
+
```
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Protected Files
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: documenting critical files that need approval before modification.
|
|
4
|
+
|
|
5
|
+
This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# Protected Files
|
|
9
|
+
|
|
10
|
+
Critical files requiring approval before modification.
|
|
11
|
+
|
|
12
|
+
## File List
|
|
13
|
+
|
|
14
|
+
# Category 1 - Description
|
|
15
|
+
path/to/critical/file1.js
|
|
16
|
+
path/to/critical/file2.js
|
|
17
|
+
|
|
18
|
+
# Category 2 - Description
|
|
19
|
+
path/to/another/file.js
|
|
20
|
+
|
|
21
|
+
## Risk Summary
|
|
22
|
+
|
|
23
|
+
| Category | Risk if Broken |
|
|
24
|
+
|------------|-----------------|
|
|
25
|
+
| Category 1 | Specific impact |
|
|
26
|
+
| Category 2 | Specific impact |
|
|
27
|
+
|
|
28
|
+
## Why Protected
|
|
29
|
+
|
|
30
|
+
### Category 1: [Name]
|
|
31
|
+
|
|
32
|
+
**Purpose:** What these files do, one or two lines
|
|
33
|
+
**Owning doc:** [docs/features/{feature}.md] — canonical reference for how this code works
|
|
34
|
+
**Invariants:**
|
|
35
|
+
- The behavior that must not break, stated as a constraint (not a function tour)
|
|
36
|
+
- Important point 2
|
|
37
|
+
```
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Project Root README
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
|
|
4
|
+
|
|
5
|
+
### Strategy
|
|
6
|
+
|
|
7
|
+
The root README answers, in order:
|
|
8
|
+
|
|
9
|
+
1. **What is this?** — one to two sentences, no marketing claims
|
|
10
|
+
2. **What do I get if I install it?** — capability families
|
|
11
|
+
3. **What's it built on?** — terse stack list with versions
|
|
12
|
+
4. **How do I run it?** — the three or four scripts that matter
|
|
13
|
+
5. **How is it laid out?** — directory tree, one-liner per significant folder
|
|
14
|
+
6. **How do I extend it?** — numbered contribution checklist
|
|
15
|
+
7. **What state is it in?** — pre-publish, beta, stable, internal
|
|
16
|
+
|
|
17
|
+
Skip any section that doesn't apply. Don't pad to fill the template.
|
|
18
|
+
|
|
19
|
+
### Writing rules
|
|
20
|
+
|
|
21
|
+
- **Sentence-case headings.** "Getting started", not "Getting Started".
|
|
22
|
+
- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
|
|
23
|
+
- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
|
|
24
|
+
- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
|
|
25
|
+
- **Directory tree as a code block**, not a nested markdown list.
|
|
26
|
+
- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
|
|
27
|
+
- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
|
|
28
|
+
- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
|
|
29
|
+
|
|
30
|
+
### Template
|
|
31
|
+
|
|
32
|
+
```markdown
|
|
33
|
+
# {package-name}
|
|
34
|
+
|
|
35
|
+
{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
|
|
36
|
+
|
|
37
|
+
## What's in the box
|
|
38
|
+
|
|
39
|
+
- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
|
|
40
|
+
- **{Family 2}** — {what's in it.}
|
|
41
|
+
- **{Family 3}** — {what's in it.}
|
|
42
|
+
|
|
43
|
+
The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
|
|
44
|
+
|
|
45
|
+
## Stack
|
|
46
|
+
|
|
47
|
+
- {Framework} {version} · {Language} {version}
|
|
48
|
+
- {Build tool} {version}
|
|
49
|
+
- {Other load-bearing deps}
|
|
50
|
+
|
|
51
|
+
## Getting started
|
|
52
|
+
|
|
53
|
+
\`\`\`bash
|
|
54
|
+
{pm} install
|
|
55
|
+
{pm} run dev # what it does (port, URL)
|
|
56
|
+
{pm} run build # what it does
|
|
57
|
+
{pm} run preview # what it does (omit if not applicable)
|
|
58
|
+
\`\`\`
|
|
59
|
+
|
|
60
|
+
{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
|
|
61
|
+
|
|
62
|
+
## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
|
|
63
|
+
|
|
64
|
+
{Brief description of the dev/runtime surface.}
|
|
65
|
+
|
|
66
|
+
| {Thing} | {What it shows / does} |
|
|
67
|
+
| -------------------- | ---------------------- |
|
|
68
|
+
| `{route or command}` | {description} |
|
|
69
|
+
|
|
70
|
+
## Layout
|
|
71
|
+
|
|
72
|
+
\`\`\`
|
|
73
|
+
src/
|
|
74
|
+
├── {entry-file} # {purpose}
|
|
75
|
+
├── {folder}/ # {purpose}
|
|
76
|
+
│ └── ...
|
|
77
|
+
└── {folder}/ # {purpose}
|
|
78
|
+
\`\`\`
|
|
79
|
+
|
|
80
|
+
## Adding a {primary unit}
|
|
81
|
+
|
|
82
|
+
1. {Drop the source under the right family/folder.}
|
|
83
|
+
2. {Re-export from the public surface.}
|
|
84
|
+
3. {Wire into the playground / example app / test harness so reviewers can see it render.}
|
|
85
|
+
4. {Document any divergence from upstream in `docs/{...}`.}
|
|
86
|
+
|
|
87
|
+
## Styling ← optional; replace with whichever cross-cutting concern matters most
|
|
88
|
+
|
|
89
|
+
{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
|
|
90
|
+
|
|
91
|
+
## Status
|
|
92
|
+
|
|
93
|
+
{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}
|
|
94
|
+
|
|
95
|
+
## License
|
|
96
|
+
|
|
97
|
+
{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Baseline scaffolding behavior
|
|
101
|
+
|
|
102
|
+
The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
|
|
103
|
+
|
|
104
|
+
**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Security Overview (docs/architecture/security.md)
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
|
|
4
|
+
|
|
5
|
+
Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# Security Overview
|
|
9
|
+
|
|
10
|
+
## Assets
|
|
11
|
+
|
|
12
|
+
- {What's worth protecting — data classes, credentials, tenant isolation}
|
|
13
|
+
|
|
14
|
+
## Trust boundaries
|
|
15
|
+
|
|
16
|
+
- {Boundary} — {what crosses it, and what checks the crossing}
|
|
17
|
+
|
|
18
|
+
## Controls
|
|
19
|
+
|
|
20
|
+
| Control | Protects against | Implemented in |
|
|
21
|
+
| ------- | ---------------- | -------------- |
|
|
22
|
+
| {control} | {threat} | `{file/module}` |
|
|
23
|
+
|
|
24
|
+
## Accepted risks
|
|
25
|
+
|
|
26
|
+
- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
|
|
27
|
+
```
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# docs/structure.md (Authority Map)
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: defining which folder owns which topic and how docs are maintained.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
---
|
|
7
|
+
harness-version: 1.0.0
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Documentation Structure
|
|
11
|
+
|
|
12
|
+
> This file is the entry point for understanding the docs folder.
|
|
13
|
+
> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
|
|
14
|
+
|
|
15
|
+
## Authority Map
|
|
16
|
+
|
|
17
|
+
Each topic has one canonical location. Read from here, not from plans or changelogs.
|
|
18
|
+
|
|
19
|
+
| Topic | Authority | Key Files |
|
|
20
|
+
| ----- | --------- | --------- |
|
|
21
|
+
| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
|
|
22
|
+
| System overview | `docs/architecture/` | system-design.md |
|
|
23
|
+
| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
|
|
24
|
+
| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
|
|
25
|
+
| API surface | `docs/architecture/` | api.md |
|
|
26
|
+
| Security | `docs/architecture/` | security.md |
|
|
27
|
+
| Feature behavior | `docs/features/` | {key files} |
|
|
28
|
+
| Setup & development | `docs/operations/` | {key files} |
|
|
29
|
+
| Environment / config surface | `docs/operations/` | environment.md |
|
|
30
|
+
| Testing strategy | `docs/tests/` | strategy.md |
|
|
31
|
+
| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
|
|
32
|
+
| Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
|
|
33
|
+
| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
|
|
34
|
+
| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
|
|
35
|
+
| Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
|
|
36
|
+
| Backlog | `docs/history/` | backlog.md |
|
|
37
|
+
|
|
38
|
+
## The Two Natures
|
|
39
|
+
|
|
40
|
+
Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
|
|
41
|
+
|
|
42
|
+
- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
|
|
43
|
+
- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
|
|
44
|
+
- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
|
|
45
|
+
|
|
46
|
+
## Folder Rules
|
|
47
|
+
|
|
48
|
+
- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
|
|
49
|
+
- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
|
|
50
|
+
- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
|
|
51
|
+
- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
|
|
52
|
+
- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
|
|
53
|
+
- `docs/history/changelog/`: Records. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
|
|
54
|
+
- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
|
|
55
|
+
- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
|
|
56
|
+
- `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
|
|
57
|
+
- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
|
|
58
|
+
|
|
59
|
+
## Health Log
|
|
60
|
+
|
|
61
|
+
<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
|
|
62
|
+
| Date | Review Summary |
|
|
63
|
+
| ---- | -------------- |
|
|
64
|
+
| {today} | Initial baseline — v{harness-version} structure established |
|
|
65
|
+
```
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# System Overview (docs/architecture/system-design.md)
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
|
|
4
|
+
|
|
5
|
+
Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# System Overview
|
|
9
|
+
|
|
10
|
+
## What this is
|
|
11
|
+
|
|
12
|
+
{Two or three sentences: what the system does, for whom, in what environment it runs.}
|
|
13
|
+
|
|
14
|
+
## Subsystem map
|
|
15
|
+
|
|
16
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
17
|
+
│ Frontend │────▶│ API │────▶│ DB │
|
|
18
|
+
└──────────┘ └──────────┘ └──────────┘
|
|
19
|
+
{One box per subsystem; label the arrows with the contract that crosses them.}
|
|
20
|
+
|
|
21
|
+
- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
|
|
22
|
+
|
|
23
|
+
## Key flows
|
|
24
|
+
|
|
25
|
+
{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
|
|
26
|
+
|
|
27
|
+
## Where the truth lives
|
|
28
|
+
|
|
29
|
+
| Area | Canonical doc |
|
|
30
|
+
| ---- | ------------- |
|
|
31
|
+
| {area} | [{doc}](path) |
|
|
32
|
+
```
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Testing Strategy (docs/tests/strategy.md)
|
|
2
|
+
|
|
3
|
+
Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
|
|
4
|
+
|
|
5
|
+
Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# Testing Strategy
|
|
9
|
+
|
|
10
|
+
## Levels
|
|
11
|
+
|
|
12
|
+
| Layer | Runner | Lives in | Covers |
|
|
13
|
+
| ----- | ------ | -------- | ------ |
|
|
14
|
+
| Unit / integration | {runner} | `tests/` | {what} |
|
|
15
|
+
| E2E | {runner} | `e2e/` | {what} |
|
|
16
|
+
|
|
17
|
+
## Running
|
|
18
|
+
|
|
19
|
+
- `{pm} test` — the whole unit suite (CI gate)
|
|
20
|
+
- `{pm} run test:e2e` — {when to run}
|
|
21
|
+
|
|
22
|
+
## Deliberately untested
|
|
23
|
+
|
|
24
|
+
- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
|
|
25
|
+
|
|
26
|
+
## Adding a test
|
|
27
|
+
|
|
28
|
+
1. {Where the file goes, what it's named, where fixtures live}
|
|
29
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: escalate
|
|
3
|
+
description: Use when a task's routed tier isn't good enough — a prompt keeps failing its evals at the tier the routing table assigns. The evidence-gated promotion procedure - demands the failing eval, writes the escalation changelog entry, records the new tier. Triggers on /escalate, "this needs a stronger model", "bump this to frontier", "the cheap model can't do this".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Escalate — evidence-gated tier promotion
|
|
7
|
+
|
|
8
|
+
Promotion is earned by a failing eval, never by intuition. This skill is the only legitimate path to running a task above its routed tier — and it is deliberately fast: one eval run of evidence, one entry, done. No approvals theater.
|
|
9
|
+
|
|
10
|
+
## Procedure
|
|
11
|
+
|
|
12
|
+
1. **Demand the evidence.** A completed `prompt-eval` run at the currently routed tier, failing the family threshold. No run ⇒ run it now (that is the whole gate). An old run doesn't count — the evidence is for the current prompt version.
|
|
13
|
+
2. **Write the escalation entry** — this skill owns the format; `cost-report` parses these entries, so the shape is a contract:
|
|
14
|
+
- File: `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, standard changelog-entry template, plus its `docs/history/CHANGELOG.md` row.
|
|
15
|
+
- **`Class: escalation`** — the fixed rendezvous keyword. Exactly this word; `cost-report` and `retro` match on it.
|
|
16
|
+
- `Change:` names the task type, the family, the failing score vs. threshold, and the tier movement (`standard → frontier`).
|
|
17
|
+
- `Discovered:` what the failure teaches about the tier's capability ceiling — this is the routing table's tuning signal.
|
|
18
|
+
3. **Record the promotion scope**: one-off (this task runs high once) or standing (the routing row itself is wrong). A standing promotion also appends an out-of-scope discovery proposing the routing-table row change — the table is policy and moves by its own edit, not silently.
|
|
19
|
+
4. **Dispatch at the new tier** and finish the work.
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
|
|
23
|
+
- **The entry precedes the dispatch.** An escalation with no entry is an unevidenced promotion — the routing guardrails prohibit it.
|
|
24
|
+
- **Escalation is symmetric.** When `regression-runner`'s demotion experiment passes a tier down, that result is recorded the same way (`Class: escalation`, direction down) — the table tunes on both signals.
|
|
25
|
+
- **Frequency is signal, not failure.** Many escalations from one row mean the row is wrong; that is `retro`'s finding to make, from these entries. Never suppress one to keep the table looking right.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: prompt-eval
|
|
3
|
+
description: Use when a prompt needs its quality measured — after drafting or revising a prompt, before certifying a library entry, or when comparing prompt variants. Runs the golden-set eval loop with rubric grading and reports deltas. Triggers on /prompt-eval, "eval this prompt", "does this variant score better", "run the golden set", "certify this prompt".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Prompt Eval — the golden-set loop
|
|
7
|
+
|
|
8
|
+
A prompt's quality claim is its eval result, nothing else. This skill runs the loop; conventions for golden sets, rubrics, and thresholds are `.claude/rules/evals.md`.
|
|
9
|
+
|
|
10
|
+
## Procedure
|
|
11
|
+
|
|
12
|
+
1. **Locate the family's golden set** at `evals/{family}/` — the owning feature doc names the family. A prompt with no golden set gets one *first* (eval-first: the set ships with the prompt, and `data-generator` drafts edge-case items for human review).
|
|
13
|
+
2. **Run the set** against the prompt via `eval-runner` — every item, not a sample. Batch variants in one run so scores are comparable.
|
|
14
|
+
3. **Grade with the family's rubric.** Mechanical checks (format, required fields, refusal correctness) grade in code; judgment dimensions grade against the rubric's anchors. Report per-dimension scores and the delta against the incumbent prompt's certified score.
|
|
15
|
+
4. **Gate:** meeting the family's threshold on iteration is a *candidate*; certification for the library additionally requires the `judge` ship gate (frontier, one dispatch — the only frontier call in the loop).
|
|
16
|
+
5. **Record:** the winning variant's scores go into its `prompt-library` entry; the losing variants' deltas belong in the changelog entry's refinement context.
|
|
17
|
+
|
|
18
|
+
## Rules
|
|
19
|
+
|
|
20
|
+
- **Iteration stays cheap.** The draft → eval → revise loop runs on economy (`eval-runner`) and standard (`prompt-iterator`) tiers; the frontier judge appears once, at the gate — never inside the loop.
|
|
21
|
+
- **Never weaken a rubric to pass a prompt.** A rubric change is a design change to the family's eval suite: it goes through the owning feature doc, re-runs the whole family, and re-certifies every entry.
|
|
22
|
+
- **A failing eval is a result, not an obstacle.** Report it honestly; if the family genuinely needs a stronger tier, that is the `escalate` skill's evidence.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: prompt-library
|
|
3
|
+
description: Use when creating, versioning, retrieving, or auditing a production prompt — any write into prompts/{family}/, any "which prompt do we use for X", any certification question. Owns the library entry format - tier certification, eval score, date. Triggers on /prompt-library, "add this to the library", "what's our prompt for", "is this prompt certified", "bump the prompt version".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Prompt Library — versioned, certified entries
|
|
7
|
+
|
|
8
|
+
`prompts/{family}/` is a library of certified production artifacts, not a scratchpad. Every entry is versioned, eval-scored, and tier-certified; scratch iterations live outside until they pass.
|
|
9
|
+
|
|
10
|
+
## The entry format
|
|
11
|
+
|
|
12
|
+
Each prompt is one file at `prompts/{family}/{name}.md` with frontmatter:
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
---
|
|
16
|
+
version: 3 # integer, bumped on every content change
|
|
17
|
+
tier: standard # the tier this prompt is certified for (economy | standard | frontier)
|
|
18
|
+
eval-score: 0.94 # the certified golden-set score at this version
|
|
19
|
+
certified: 2026-07-26 # date of the certifying run
|
|
20
|
+
status: active # active | candidate | retired
|
|
21
|
+
---
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The body is the prompt itself, verbatim — no narration, no history (the journey lives in changelog entries). A `candidate` has passed its family threshold but not the `judge` gate; `retired` entries stay in place for provenance (consumers must never load them — status is the filter).
|
|
25
|
+
|
|
26
|
+
## Procedure
|
|
27
|
+
|
|
28
|
+
- **Create / update**: a content change bumps `version`, resets `status` to `candidate`, and goes through `prompt-eval` → `judge` before flipping back to `active` with fresh `eval-score` and `certified` values. The owning feature doc's `owns:` glob covers the family — read it first.
|
|
29
|
+
- **Retrieve**: match by family + status `active`; the entry's `tier` names the tier it runs on — dispatch accordingly, never stronger (that is an unevidenced promotion).
|
|
30
|
+
- **Audit** (on demand, and by `regression-runner` after a model-generation change): every `active` entry whose `certified` date precedes the current `model-tiers` mapping is stale — re-certify or flag.
|
|
31
|
+
|
|
32
|
+
## Rules
|
|
33
|
+
|
|
34
|
+
- **Certification is per tier.** A prompt certified on standard says nothing about economy; a demotion experiment that passes produces a *new* certification at the lower tier.
|
|
35
|
+
- **One prompt, one entry.** Variants under comparison are `candidate` siblings; only one `active` per name.
|
|
36
|
+
- **Never hand-edit `eval-score`** — it is written by the certifying run or not at all.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: route
|
|
3
|
+
description: Use when starting any piece of prompt work — drafting, evaluating, generating test data, probing, or judging — before dispatching any agent or choosing any tier. The entry point that classifies the task into a task type, reads the routing table, and dispatches the pinned agent. Triggers on /route, "work on this prompt", "run the evals", "which model should this use", or any prompt task whose tier hasn't been routed yet.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Route — classify, look up, dispatch
|
|
7
|
+
|
|
8
|
+
The model decision belongs to the routing table in `CLAUDE.md` § The Routing Policy, not to you and not to the user. This skill is the single entry point that applies it.
|
|
9
|
+
|
|
10
|
+
## Procedure
|
|
11
|
+
|
|
12
|
+
1. **Classify the task into exactly one task type** from the routing table's rows. Classification is mechanical work — do it inline at the cheapest capable tier, never by dispatching a frontier agent to think about it. When a task spans types (e.g. "draft a prompt and evaluate it"), decompose: each leg routes separately.
|
|
13
|
+
2. **Read the row**: task type → tier → executing agent.
|
|
14
|
+
3. **Dispatch the named agent.** The agent's own pin enforces the tier — never override the model at dispatch time. Work with no matching row is new: route it provisionally to the standard tier, do the work, and record the missing row as an out-of-scope discovery so the table gains it.
|
|
15
|
+
4. **Never route around a failing eval.** If the routed tier's output fails its evals, the answer is the `escalate` skill (evidence-gated promotion), not a quiet re-dispatch on a stronger agent.
|
|
16
|
+
|
|
17
|
+
## What this skill refuses
|
|
18
|
+
|
|
19
|
+
- Naming a model. Tiers only; the mapping lives in `.claude/rules/model-tiers.md` and the agents' pins.
|
|
20
|
+
- Frontier dispatch for mechanical work (eval runs, data generation, classification) — the routing guardrails in `CLAUDE.md` prohibit it regardless of who asks.
|
|
21
|
+
- Skipping the table because the task "obviously" needs the strongest model — that intuition is exactly what the escalation ladder exists to test.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nurix/etna",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.34",
|
|
4
4
|
"description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|