@supersuit/hyperspec 0.4.0 → 0.5.0

package/bin/hyperspec.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { existsSync, statSync, writeFileSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
@@ -14,6 +14,8 @@ import { regenerate } from "../src/regenerate.mjs";
 import { compare } from "../src/compare.mjs";
 import { splitSegments } from "../src/segments.mjs";
 import { sha256 } from "../src/hash.mjs";
+import { readScope, measureFeatures, writeFeatures, scopeTemplate, GOLDENS_README } from "../src/dna.mjs";
+import { str } from "../src/placeholder.mjs";
 
 const HELP = `hyperspec <command> [options]
 
@@ -43,6 +45,23 @@ const HELP = `hyperspec <command> [options]
                                with nothing in it, an --out folder that does not exist, or a --by
                                outside paragraph/sentence
 
+  dna init <scope-dir> --writer W --form F --audience A --purpose P
+                               write a new writer-DNA scope: scope.md (writer, form, audience,
+                               purpose) and an empty goldens/ folder holding a README on the
+                               golden file shape (why, approved_by, source, optional approved_on;
+                               the body is the passage, verbatim); refuses to overwrite an
+                               existing scope.md; exit 2 on a missing parent folder, a missing
+                               flag, or a flag value that looks like a placeholder (todo, ..., a
+                               bare -), never a stack trace
+  dna measure <scope-dir> [--json]
+                               read every golden in <scope-dir>/goldens/, check its required
+                               fields, and write <scope-dir>/features.json: deterministic style
+                               features measured from the goldens' text, never judged and never
+                               run through a model
+                               exit 0 wrote features.json, 1 a golden (or the scope itself) fails
+                               a required-field check, so a hollow golden is never measured into
+                               the DNA, 2 usage
+
   recipe check <output-or-recipe> [--json]
                                check a recipe's completeness (a path not ending .recipe.json
                                means <path>.recipe.json)
@@ -146,6 +165,93 @@ if (cmd === "segments") {
   process.exit(2);
 }
 
+if (cmd === "dna") {
+  const sub = argv[1];
+
+  if (sub === "init") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--writer", "--form", "--audience", "--purpose"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna init needs a scope-dir path"); process.exit(2); }
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!parsed.values[flagName]) { console.error(`dna init needs ${flagName} <value>`); process.exit(2); }
+    }
+    // A placeholder-looking value (todo, tbd, ..., ???, ...) is caught here rather than left
+    // for the next `dna measure` to catch on scope.md's own fields; str() is the one place that
+    // pattern is defined (src/placeholder.mjs), reused rather than re-checked.
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!str(parsed.values[flagName])) {
+        console.error(`dna init ${flagName} "${parsed.values[flagName]}" looks like a placeholder; give it real content`);
+        process.exit(2);
+      }
+    }
+    const writer = parsed.values["--writer"];
+    const form = parsed.values["--form"];
+    const audience = parsed.values["--audience"];
+    const purpose = parsed.values["--purpose"];
+
+    const scopeAbs = resolve(scopeDir);
+    const parent = dirname(scopeAbs);
+    if (!existsSync(parent) || !statSync(parent).isDirectory()) {
+      console.error(`the folder ${dirname(scopeDir)} does not exist; create it first`);
+      process.exit(2);
+    }
+    if (existsSync(scopeAbs) && !statSync(scopeAbs).isDirectory()) {
+      console.error(`${scopeDir} is not a directory`);
+      process.exit(2);
+    }
+    // scopeMdPath (absolute, resolved from the cwd) is for filesystem operations only. Every
+    // message uses scopeMdDisplay, built from scopeDir exactly as given (relative, if that is how
+    // the operator typed it): a path the operator did not resolve themselves must never appear
+    // resolved in output, the same rule every other finding in this linter already follows.
+    const scopeMdPath = join(scopeAbs, "scope.md");
+    const scopeMdDisplay = join(scopeDir, "scope.md");
+    if (existsSync(scopeMdPath)) { console.error(`refusing to overwrite ${scopeMdDisplay}`); process.exit(2); }
+
+    mkdirSync(join(scopeAbs, "goldens"), { recursive: true });
+    writeFileSync(scopeMdPath, scopeTemplate({ writer, form, audience, purpose }));
+    // An operator's own goldens/README.md is theirs: write the guidance only where none exists.
+    try {
+      writeFileSync(join(scopeAbs, "goldens", "README.md"), GOLDENS_README, { flag: "wx" });
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    console.log(`wrote ${scopeMdDisplay} and ${scopeDir}/goldens/. Add goldens, then run: hyperspec dna measure ${scopeDir}`);
+    process.exit(0);
+  }
+
+  if (sub === "measure") {
+    const parsed = parseArgs(argv.slice(2), { boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna measure needs a scope-dir path"); process.exit(2); }
+    const json = parsed.values["--json"];
+
+    const { scope, goldens, findings } = readScope(scopeDir);
+    const hasFail = findings.some((x) => x.severity === "fail");
+    if (hasFail) {
+      if (json) console.log(JSON.stringify({ scope: scopeDir, findings }, null, 2));
+      else for (const x of findings) console.log(`fail [${x.test}] ${x.message}\n  fix: ${x.fix}`);
+      process.exit(1);
+    }
+
+    const features = measureFeatures(goldens.map((g) => g.text));
+    const { path: featuresPath } = writeFeatures(scopeDir, { scope, goldens, features });
+    if (json) {
+      console.log(JSON.stringify({ scope: scopeDir, goldens: goldens.length, features, wrote: featuresPath }, null, 2));
+    } else {
+      console.log(`${scopeDir}: measured ${goldens.length} golden${goldens.length === 1 ? "" : "s"}`);
+      console.log(`  word_count ${features.word_count}, sentence length mean ${features.sentence_length.mean} median ${features.sentence_length.median} p90 ${features.sentence_length.p90}`);
+      console.log(`  signature words: ${features.signature_words.join(", ") || "(none)"}`);
+      console.log(`wrote ${featuresPath}`);
+    }
+    process.exit(0);
+  }
+
+  console.error(`unknown dna subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
 if (cmd === "lint") {
   const json = argv.includes("--json");
   // Lint takes one flag, --json, and no flag takes a value, so a flag is dropped on its own and

package/examples/writing/dna/essay-new-managers-teach/features.json

@@ -0,0 +1,56 @@
+{
+  "dna": "0.1",
+  "scope": {
+    "writer": "example-author",
+    "form": "essay",
+    "audience": "new managers",
+    "purpose": "teach"
+  },
+  "goldens": [
+    {
+      "path": "goldens/close.md",
+      "sha256": "a90291714fc3bd79a16c613deb536b34c4ef577e56083c0c6b17142fbc4b871f"
+    },
+    {
+      "path": "goldens/opening.md",
+      "sha256": "395c7c37d604e255a07603276bac0d2f0915bc80d9acea45e3a30a6fe248b44e"
+    },
+    {
+      "path": "goldens/status.md",
+      "sha256": "891c34d9134380e5c752e69036ec9707729b7e30c9f2b3f2789b8d3ee3f311ed"
+    }
+  ],
+  "features": {
+    "word_count": 118,
+    "sentence_length": {
+      "mean": 13.111,
+      "median": 15,
+      "p90": 25
+    },
+    "paragraph_length": {
+      "mean_sentences": 3,
+      "mean_words": 39.333
+    },
+    "rates_per_1000_words": {
+      "comma": 33.898,
+      "semicolon": 0,
+      "colon": 8.475,
+      "em_dash": 0,
+      "en_dash": 0,
+      "exclamation": 0,
+      "question_mark": 0,
+      "parentheses": 0,
+      "quotation_marks": 0
+    },
+    "contraction_rate": 0,
+    "first_person_singular_rate": 0,
+    "first_person_plural_rate": 0,
+    "second_person_rate": 59.322,
+    "mean_word_length": 3.831,
+    "signature_words": [
+      "first",
+      "report",
+      "tracker"
+    ]
+  }
+}

package/examples/writing/dna/essay-new-managers-teach/goldens/README.md

@@ -0,0 +1,14 @@
+# Goldens
+
+Each file in this folder except this one is a golden: a passage the writer marked as right,
+filed under this scope.
+
+Frontmatter:
+- why (required): what makes it golden, the move it teaches.
+- approved_by (required): a person slug. Golden means a human approved it; agent:* is refused.
+- source (required): where the passage came from.
+- approved_on (optional): a date.
+
+The body is the passage, verbatim.
+
+Run `hyperspec dna measure <scope-dir>` once every golden here has why, approved_by and source.

package/examples/writing/dna/essay-new-managers-teach/goldens/close.md

@@ -0,0 +1,9 @@
+---
+why: ends on an instruction and gives the reason for it in the same sentence
+approved_by: example-author
+source: first draft of this essay's closing paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/dna/essay-new-managers-teach/goldens/opening.md

@@ -0,0 +1,9 @@
+---
+why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+approved_by: example-author
+source: first draft of this essay's opening paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.

package/examples/writing/dna/essay-new-managers-teach/goldens/status.md

@@ -0,0 +1,10 @@
+---
+why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+approved_by: example-author
+source: an earlier newsletter essay for new managers by the same writer, its middle section
+approved_on: "2026-09-18"
+---
+
+If you can read it in the tracker, do not ask for it in the room. Status already has a home,
+and your report is the one who put it there. Spend the half hour on what the tracker cannot
+hold: how the work looks from their side of it.

package/examples/writing/dna/essay-new-managers-teach/scope.md

@@ -0,0 +1,11 @@
+---
+writer: example-author
+form: essay
+audience: new managers
+purpose: teach
+---
+
+# Writer DNA scope
+
+Goldens live in goldens/. Run `hyperspec dna measure <scope-dir>` once every golden there has
+why, approved_by and source.

package/examples/writing/essay.hyperspec.md

@@ -28,7 +28,7 @@ requirements:
     fails_when: a reader shown only the first two sentences cannot say who should set the agenda
     check:
       rubric: show the simulated reader the first two sentences and ask who sets the agenda; pass only on "the report"
-    source: essay/goldens/opening.md
+    source: dna/essay-new-managers-teach/goldens/opening.md
     author: example-author
   - id: r2
     text: the three questions appear word for word as the voice memo states them
@@ -71,8 +71,8 @@ rejects:
   - any claim about what most managers do that the survey does not support
   - the walking one-on-one aside from the voice memo
 examples:
-  - path: essay/goldens/opening.md
-    why: the claim lands in the first sentence, and the second sentence turns it into an instruction
+  - path: dna/essay-new-managers-teach/goldens/opening.md
+    why: the claim lands in the first sentence, and the two short sentences after it turn it into an instruction
 resume:
   next_action: outline the four spine claims against the form's required parts, citing the segments each claim points at
 feedback:
@@ -110,18 +110,21 @@ writing:
     author: agent:claude
   dna:
     writer: example-author
+    scope_dir: dna/essay-new-managers-teach
     scope:
       form: essay
       audience: new managers
       purpose: teach
     rules: style-rules.md
     goldens:
-      - path: essay/goldens/opening.md
-        why: one plain claim, then a second sentence that turns it into something to do
-      - path: essay/goldens/close.md
+      - path: dna/essay-new-managers-teach/goldens/opening.md
+        why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+      - path: dna/essay-new-managers-teach/goldens/status.md
+        why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+      - path: dna/essay-new-managers-teach/goldens/close.md
         why: ends on an instruction and gives the reason for it in the same sentence
     check:
-      rubric: blind lineup within this scope; a judge shown the generated opening beside the two goldens cannot pick it out
+      rubric: blind lineup within this scope; a judge shown a generated passage beside the scope's three goldens cannot pick it out
     source: goldens marked on the review page
     author: example-author
   persona:
@@ -218,3 +221,8 @@ fiction: false
 A worked example of the writing profile: an essay for new managers, specified before a word of
 it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
 yet, because the claims ledger is written during drafting.
+
+The writer's voice for this piece comes from a scope folder, `dna/essay-new-managers-teach/`:
+the goldens this writer approved for essays that teach new managers, and the features measured
+from them. Another essay by the same writer, for the same readers and the same purpose, would
+point at the same folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A hyperspec is a spec written for an agent: every decision accounted for, every requirement failable and checked, every field traced. The standard and its linter.",
   "type": "module",
   "bin": {