gcf-aif-ext 0.5.0 → 0.5.2

package/README.md

@@ -50,6 +50,17 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
 
+### 0.5.2
+
+- Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
+- With `cnlp-kit` 3.9 or later, the `AGENTS.md` block between `<!-- gcf:start -->` and `<!-- gcf:end -->` is a marked region that the project's guide profile does not shape: the `custom_sections` entries 0.5.1 asked for are no longer needed. Update the `cnlp-kit` your project runs `npx cnlp check` with.
+
+### 0.5.1
+
+- A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.
+- An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
+- The `AGENTS.md` block has no `##` heading any more: a CNL-P guide is flat. A project that checks `AGENTS.md` with `cnlp check` adds `gcf_context`, `gcf_work`, `gcf_forbidden` and `gcf_skills` to `custom_sections` of its guide profile.
+
 ### 0.5.0
 
 The run layer of the methodology. Update both extensions together — `gcf-harness-aif-ext` 0.6.0 requires this core — and run `ai-factory gcf init` to refresh the agent block in `AGENTS.md`. New commands:

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/design-check.js

@@ -121,12 +121,14 @@ function itemsIn(text, key) {
 export const recordsIn = (text, key) =>
   readRecords(itemsIn(text, key)).records.map((r) => r.values);
 
-/** `blocks:` of open-questions.md: every reference, and the D1 ones per blocked id. */
+/** open-questions.md: every record id, every `blocks:` reference, the D1 ones per blocked id. */
 export function questionBlocks(text) {
   /** @type {Map<string, string[]>} */
   const d1 = new Map();
   const refs = [];
-  for (const rec of String(text ?? '').split(/\n(?=- id:)/)) {
+  const src = String(text ?? '');
+  const qids = new Set([...src.matchAll(/^\s*- id:\s*(\S+)/gm)].map((m) => m[1]));
+  for (const rec of src.split(/\n(?=- id:)/)) {
     const qid = rec.match(/^- id:\s*(\S+)/)?.[1];
     const ids = listOf(rec.match(/^\s+blocks:\s*(.+)$/m)?.[1] ?? '');
     if (!qid || ids === 'TBD' || !ids.length) continue;
@@ -135,7 +137,7 @@ export function questionBlocks(text) {
     for (const id of ids) d1.set(id, [...(d1.get(id) ?? []), qid]);
   }
 
-  return { d1, refs };
+  return { d1, refs, qids };
 }
 
 /** Everything outside a unit that its references resolve against. */
@@ -296,7 +298,15 @@ function recordProblem(r, ctx) {
   }
 
   if (r.answer) return /^(q-\d+|manual)$/.test(r.answer) ? null : 'answer is q-NNN or manual';
-  if (r.assumed) return /^q-\d+$/.test(r.assumed) ? null : 'assumed is q-NNN';
+  if (r.assumed) {
+    if (!/^q-\d+$/.test(r.assumed)) return 'assumed is q-NNN';
+
+    // The D2 record is what the readset and the human's skim list see: it outlives its citation.
+    return ctx.questions.qids.has(r.assumed)
+      ? null
+      : `assumed: ${r.assumed} is not in open-questions.md - a D2 record stays until its ` +
+          `until: fires; once the human confirms the value, cite answer: ${r.assumed} instead`;
+  }
 
   return 'a record carries src + quote, answer, or assumed';
 }
@@ -326,6 +336,9 @@ function uncovered(values, records) {
 export const isDrift = (problem) =>
   /^(quote is not verbatim|GDD#\S+ is not an anchor)/.test(problem ?? '');
 
+/** The D2 record an `assumed:` cites left open-questions.md. */
+const isGone = (problem) => /^assumed: q-\d+ is not in open-questions/.test(problem ?? '');
+
 /** M9: provenance records are well formed, quotes verbatim, every GDD-sourced slot backed. */
 function provenanceIssues(u, values, ctx) {
   const records = provenanceOf(u.body);
@@ -446,11 +459,16 @@ async function checkItem(item, ctx, ledger) {
   const values = slotValues(item.body, profile).filter((v) => !OPERATOR_BLOCKS.includes(v.block));
   for (const v of values.filter((x) => isTbd(x.value)))
     add('M1', v.line, `a unit in work carries no TBD: ${v.block}`);
-  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m);
+  // An unplayed body is frozen (§5.4): a later glossary word or unit, or a gone question, cannot
+  // be fixed there, only reported until a tune or a kill takes the item back.
+  const frozen = item.data.status === 'unplayed' ? 'report' : 'block';
+  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m, frozen);
   for (const r of provenanceOf(item.body)) {
     const problem = recordProblem(r, ctx);
     // An item's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
-    if (problem) add('M9', r.line, problem, isDrift(problem) ? 'report' : 'block');
+    // A gone question is outside the frozen body too; a malformed record was malformed at close.
+    const sev = isDrift(problem) ? 'report' : isGone(problem) ? frozen : 'block';
+    if (problem) add('M9', r.line, problem, sev);
   }
 
   return issues;

package/lib/systems-doc.js

@@ -9,11 +9,15 @@ import { scalarIn } from './design.js';
 
 const NONE_LINE = '- none: no item of this subsystem has collapsed yet';
 
+/**
+ * The raw lines of a `key:` block. `prose`, not `lines`: cnlp-kit 3.9 blanks HTML comments in
+ * `lines`, and upsertBlock rewrites the block from these — a `gcf:allow` pragma must survive.
+ */
 export function blockLines(body, key) {
-  const { lines, sections } = parseBlocks(body);
+  const { prose, sections } = parseBlocks(body);
   const at = sections.find((s) => s.key === key);
 
-  return at ? itemsOf(lines, at.line).map((i) => i.text) : [];
+  return at ? itemsOf(prose, at.line).map((i) => i.text) : [];
 }
 
 /**

package/node_modules/cnlp-kit/CHANGELOG.md

@@ -4,6 +4,213 @@ The format has its own version from here on. It used to be stamped with the rele
 an ADR extension, which made a breaking change to the format invisible inside that project's
 patch release.
 
+## 3.9.1
+
+### Added
+
+- **`cnlp --version`** writes the version of the installed package, alone on 1 line, and exits 0.
+  Before it the only answer was `npm ls cnlp-kit`, and `--version` printed the usage and exited 1.
+
+## 3.9.0
+
+An agent file that several tools write into could not pass the check. Each tool keeps its own block
+between `<!-- <name>:start -->` and `<!-- <name>:end -->`, and `cnlp check` read the marker as an
+item of the block above it and the tool's keys as unknown blocks of the file. Neither the tool nor
+the project could fix that honestly: moving a marker moves the issue to another block, and naming a
+tool's keys in `custom_sections:` breaks §7, which keeps that block for content that is not a rule.
+
+### Changed
+
+- **§3: an HTML comment is markup, not structure.** A line that is 1 whole comment, and every line
+  of a comment that runs over several, is no item of the block above it and no section key. A line
+  carrying text beside a comment is still read, a comment that never closes hides nothing, and the
+  §4 and §5 line rules still read comment text, because an agent reads the raw file.
+- **§3: a marked region belongs to the tool that wrote it.** The lines between
+  `<!-- <name>:start -->` and `<!-- <name>:end -->` are not shaped by the file's profile: no key in
+  them is unknown, repeated or out of order, no heading in them is unknown, and nothing in them
+  supplies a block the profile requires. §4 and §5 still hold on every line. An end closes the
+  latest start of its own name; a start with no end marks nothing, so it cannot exempt the rest of
+  a file.
+- **`cnlp check` lists every region it did not shape**, by file, line range and name, the way it
+  lists the files the lexicon did not reach: a region is an exemption any author can write.
+- **A page reference inside a region is not resolved**, and does not reach a page. It belongs to
+  the tool's own corpus, not to this one.
+- **`parseBlocks` changed what it returns.** `lines`, which `itemsOf` and every structural check
+  read, now blanks comments and regions as well as fences. `prose` is new: it blanks fences only,
+  and the lexicon reads it. `regions` is new: `{ name, line, end }` for each marked region.
+
+### Fixed
+
+- **A reported line is a line of the file.** `parseBlocks` stripped the frontmatter, so every line
+  number in a document carrying one counted from the end of it: an issue on line 13 of a skill read
+  as line 10. The frontmatter is now blanked in place, so `<file>:<line>` opens the line it names.
+
+## 3.8.1
+
+2 things a consumer of a produced set ran into. A registry that keeps a pre-release as
+`2.0.0-[rc]` could not check it by path, and `identity:` `version:` had no stated shape, so the
+kit's own skill wrote `0.9.2, read at commit a741e91` where a tool comparing versions expects `0.9.2`.
+
+### Fixed
+
+- **`cnlp check <dir>` reads a set whose directory names carry `[`, `*` or `?`.** `configForPath`
+  put the directory names into the corpus glob as they were, so `2.0.0-[rc]` read as a character
+  class that matches no directory, and the set was reported as holding no document. Each name now
+  goes in as a glob matching only itself. A `{` still opens a brace set: `fs.glob` offers no escape
+  for it, and a set directory named with braces needs a config.
+
+### Changed
+
+- **`profiles/docset.md`: `version:` opens with the version alone.** The `identity:` note says so,
+  and why: a tool comparing the version reads it up to the first comma. Anything after that comma
+  stays a note for a reader, which is the shape `examples/dragonecs-unity` already has.
+- **`skills/cnlp-docset/SKILL.md`, step 4:** it records the version alone in `version:`, then a comma
+  and the revision, instead of leaving the 2 to be written in any order. An installed copy of the
+  skill reports as stale until `cnlp init` runs again.
+
+## 3.8.0
+
+A set that crosses into a companion could not be checked on its own. `configForPath(dir)` built a
+corpus of the 1 set it was pointed at, so `cnlp check examples/dragonecs-unity` reported 14
+references that resolve the moment both sets are read together, and a registry keeping sets as
+`<set>/<version>/` had no root holding both at all.
+
+### Added
+
+- **`configForPath(dir, { name, companions })`.** `name` names the checked set when its directory
+  does not; `companions` is a list of `{ name, dir }`, each a set whose pages resolve references and
+  whose files are never checked. The returned config always carries `companions` (absolute dirs,
+  `[]` when none) and `rename`, so a caller detects a kit that ignores the option by the field's
+  absence. A name that is empty or carries `:`, `/` or `\`, a companion with no `index.md`, a
+  companion named like the checked set or named twice, a companion that is the checked set's own
+  directory, and either option on a directory that is not 1 set each fail with the fix. The checked
+  directory is read by its spelling on disk, so a path typed in another case does not read the set
+  as its own sibling.
+- **`cnlp check <dir> --name <set> --companion <set>=<dir>`.** `--companion` repeats and splits at
+  its first `=`. Each companion prints `resolving against <name> at <dir>`: a caller passing
+  companions detects an executable older than 3.8.0 by that line's absence, so its wording is kept
+  stable. Both flags fail with a config run, which already reads every set under its root, and in
+  the `--flag=value` form, which would otherwise be ignored and print no `resolving` line. A value
+  flag followed directly by another flag now reads as having no value, for every value flag.
+- **`linkIssues(docs, docsets, { context, rename })` and `setSizes(docs, docsets, rename)`.** A
+  companion's pages resolve a `page:` or `by:` value, its name resolves a `docset:` value, and its
+  references count toward reach; its own references and its unreached pages are never reported,
+  and it is in no count. A call with 2
+  arguments behaves as before.
+
+### Changed
+
+- **A set checked by path resolves against the sets beside it.** When `<dir>` holds an `index.md`
+  and its name is the directory's name, every sibling directory holding an `index.md` joins as a
+  companion. `cnlp check <set>` and `configForPath(<set>)` report fewer issues where a sibling answers
+  a reference; `cnlp check examples/dragonecs-unity` and `examples/dragonecs` both conform now. An
+  explicit companion of the same name wins over a sibling.
+- **`cnlp check <dir>` prints its `reading` line before the check runs**, with the `resolving` lines
+  after it, so a check that throws still says what it was reading.
+- **`cnlp-format.md` §9** says a directory checked by path reaches the reference rules with no
+  config, and that a set checked on its own resolves against its companions.
+- **`skills/cnlp-docset/SKILL.md`**: a new step 16 names the sets a crossing reaches that do not sit
+  beside the output directory, and step 17 passes each as `--companion`. The old steps 16 to 19 are
+  17 to 20. An installed copy of the skill reports as stale until `cnlp init` runs again.
+
+## 3.7.0
+
+The upgrade path reached the skills and nothing else. A project holds 2 more copies of what this
+package declares — a local profile, and the block `cnlp init` prints for an agent file — and both
+are files the project owns, so neither can be overwritten on an upgrade. They are reported instead.
+
+### Added
+
+- **`cnlp check` names a local profile the packaged one has outgrown.** `profileDrift` in
+  `src/config.js` reads the copy and the packaged profile of the same name and reports what the
+  package declares and the copy does not: a section, its form, a record key, a required block, a
+  heading, a frontmatter field, the mood. What a copy adds is the vocabulary it was copied for and
+  is never reported, so a filled `custom_sections:` stays silent. Until now `profileFor` preferred
+  the copy and said nothing about its age: a profile copied at 3.1 held the corpus to a declaration
+  3 versions old, and the run reported it conformant.
+- **`cnlp check` names an agent file carrying an earlier copy of the pasted block.** The block is 1
+  value now — `AGENT_BLOCK` in `src/config.js` — read by the `init` that prints it and by the check
+  that watches it. `agentBlockDrift` reads `AGENTS.md` and `CLAUDE.md` at the project root and finds
+  the copy by its own opening bullet, the one naming `npx cnlp print format`. A file that never took
+  the block stays silent. It answers half of `docs/BACKLOG.md` item 9: the copy is watched, writing
+  it is still open.
+
+Both are reports and not issues, like the stale-skill line: a copy the project owns is not a defect
+in a document the corpus names, and neither decides the exit code.
+
+## 3.6.0
+
+A bug report from a project writing its corpus in Russian. The item rule read an ASCII letter, so
+every bullet of every non-Latin script reported as an item carrying no word, and the fix is 1
+character class. What the report turned up behind it is the release: the checker was answering
+`conform` over a corpus half of §5 never touched.
+
+### Fixed
+
+- **An item states its claim in a letter of any script.** `§5`'s "the item carries no word" rule read
+  `/[a-z]/i`, which reports every bullet written in Cyrillic, Greek, Hebrew or a CJK script and
+  passes the moment the line names a Latin identifier. It reads `/\p{L}/u` now. What the rule was
+  written for — `- 4`, `- —`, `- ...`, the residue of a mechanical split — is rejected unchanged,
+  because a digit and a punctuation mark are letters in no script.
+
+### Added
+
+- **`cnlp check` names the files the §5 word rules did not reach.** Every word list in §5 — the deny
+  list, the spelled thresholds, the open limits, the comparatives, the light verbs, the passive — is
+  English. Against a body in another script they raise no false issue; they silently match nothing,
+  which made a run report a conformant corpus over rules that never ran. `lexiconApplies` in
+  `src/cnlp.js` decides it from the prose — the line with its section key, its heading marker and its
+  quoted spans taken off, so this format's own English vocabulary and a Latin identifier do not
+  count as English prose — and `bin/cnlp.js` prints the count and the paths. It is a report and not
+  an issue: nothing in such a file is wrong, and the exit code does not change.
+
+### Changed
+
+- **`§5` states that its word rules are English**, which rules still hold for a document in another
+  script — §3 block forms, §4 line rules, quoted text — and that the checker reports the coverage it
+  lost rather than staying silent about it.
+
+## 3.5.0
+
+The first release shaped by a measurement rather than by a reading. `docs/PROBE-behaviour.md` holds
+the run: 4 arms, 14 tasks, 5 repetitions, against a falsifier committed before the first cell. A
+document set halved the wrong-call rate against the library's own documentation, 7% against 16%, and
+beat an arm carrying all 19 documentation pages and the whole declaration surface in context — 3.3
+times the tokens for more wrong calls, not fewer.
+
+Nothing here changes the standard or a checker rule. The run produced 1 loss and 1 cost, and each
+gets the smallest answer that fits it.
+
+The cost: a set is dearer per question than the documentation it replaces, 22172 tokens a call
+against 19236, and the difference is the index. A reader loads the index to answer any question and
+a page to answer 1, so those are different kinds of cost, and nothing in the kit made the split
+visible to whoever was growing one of them.
+
+The loss: on 1 task of 14 the set scored worse than the prose. The task wanted the `Scene` value a
+load returned; the set documents the manager's lookup members in full, because `catalog:` is closed
+and they are part of the library, and the agent went looking a scene up instead. A task page's
+preference lost to an API page's completeness, and nothing ranks them. That is `docs/BACKLOG.md`
+item 10, left open on purpose: 1 task in 1 set does not buy a vocabulary.
+
+### Added
+
+- **`cnlp check` reports each set's index bytes against its page bytes**, as
+  `<set>: index N B fixed, M page(s) K B on demand`. `checkProject` computes it from the documents
+  it has already read, so the report costs no second read, and `bin/cnlp.js` prints it. It is a
+  report and not a rule: the numbers say nothing about what a set may weigh.
+- **A step in `skills/cnlp-docset/SKILL.md`** for the 1 rule the run turned up that no check reaches:
+  a member a task page steers a reader away from carries that in its own `pitfalls:`. Step 18; the
+  old step 18 is 19.
+
+### Changed
+
+- **`profiles/docset.md` `read_protocol:` states what the index costs.** The index is the cost of
+  every question and a page the cost of 1. It is a value rather than a rule, so it sits in the
+  profile, and §6 keeps it in exactly 1 note.
+- **`docs/DOCSETS.md` carries what the probe measured about behaviour**, including the result the
+  totals hide: both reading arms averaged 4.4 turns, and on the task whose contract no documentation
+  page carries, the documentation arm read *more* than anywhere else and still failed every run.
+
 ## 3.4.1
 
 A record-list of multi-key records read as a wall. The only boundary between 2 records was a line

package/node_modules/cnlp-kit/README.md

@@ -46,6 +46,9 @@ Nothing else about your config moves on that second run.
   config records, and installs for every agent when there is no config yet.
 - `cnlp check` reports skills left behind by an upgrade, and its exit code stays the corpus's own
   answer: a stale copy is not a defect in a document.
+- **An upgrade reaches the skills and nothing else, because nothing else is the package's to
+  rewrite.** A local profile and the pasted agent-file block are files you own, so `cnlp check`
+  reports what each one is missing against the installed version and leaves both where they are.
 
 On the first run `cnlp init` also looks at what the repository already has — `AGENTS.md`,
 `CLAUDE.md`, `skills/*/SKILL.md`, `docs/adr/*.md`, `docs/references/*.md`, `docs/docsets/*/…` — and
@@ -66,7 +69,11 @@ you say otherwise. Edit the entries it wrote, or add your own:
 
 `profiles` is optional and names a directory of your own profiles. A profile there resolves
 **before** the packaged one of the same name, which is how a project adds its own vocabulary:
-copy `profiles/skill.md` into it and fill `custom_sections:`.
+copy `profiles/skill.md` into it and fill `custom_sections:`. The copy is yours and no command
+here rewrites it, so `cnlp check` names what the packaged profile declares and the copy does not
+— a section, a form, a record key, a required block — which is how an upgrade reaches a file it
+must not overwrite. What the copy adds is the vocabulary it was copied for, and is never
+reported.
 
 `cnlp init` also prints the block to paste into `AGENTS.md`, `CLAUDE.md` or whatever file your
 agent reads. Three lines, and they are the rules no skill announces: an installed skill states
@@ -94,9 +101,27 @@ set is a folder of markdown and nothing else — **no config file, no dependency
 it** — and `cnlp check <dir>` reads it by path:
 
 ```sh
-cnlp check ./nanoid-docset     # 12 file(s) conform
+cnlp check ./nanoid-docset
+# 12 file(s) conform
+# nanoid-docset: index 5603 B fixed, 11 page(s) 25778 B on demand
 ```
 
+The 2 sizes are reported apart because they are different costs. A reader loads the index to answer
+any question and a page to answer 1, so an index that grows is paid on every question.
+
+**Checking 1 set of a pair.** A set that extends another names it in `companions:` or `overrides:`,
+and its references cross into it. Checked by path, a set resolves those against the sets beside it,
+so `cnlp check examples/dragonecs-unity` conforms on its own. A companion kept elsewhere is named,
+and a set whose directory is a version rather than its name is named too:
+
+```sh
+cnlp check docsets/dragonecs-unity/0.9.2 --name dragonecs-unity --companion dragonecs=docsets/dragonecs/1.1.17
+# reading 4 entr(ies) under …/docsets
+# resolving against dragonecs at …/docsets/dragonecs/1.1.17
+```
+
+A companion is read to resolve a reference and never checked: its own defects are not this run's.
+
 That is the producing side. **Adopting** a set is the other half and a separate act: a repository
 that will hold one among its own documents runs `cnlp init`, adds the `docsets` key and the four
 corpus entries shown under [Document sets](#document-sets), and checks it with everything else from
@@ -111,6 +136,10 @@ that states it. What the set rests on lands in `identity:` `derived_from:`, so a
 page written from a signature from one written from prose, and the skill will not quietly write a
 prose claim as though it came from a declaration.
 
+`identity:` `version:` opens with the version alone, and the revision the pages were read at follows
+a comma — `version: 0.9.2, read at commit a741e91`. A tool that compares the set against the version
+a project resolves, such as a registry or a version-guard test, reads up to that first comma.
+
 It builds in the order that keeps a half-finished set honest: the closed catalog of every public
 capability first, every record at `status: source`, so the set itself says what has no page yet; then
 the type names of one running example; then `canonical_use:`, one whole working program in the index;
@@ -122,11 +151,12 @@ other page reaches. `cnlp docs` is the single command you point your agent at.
 | | |
 |---|---|
 | `cnlp init [<dir>] [--agents <a,b>]` | install or update: config, profiles directory, skills for the agents you pick |
-| `cnlp check [<dir>] [--config <path>]` | hold every document to its profile: a directory read by path, or every corpus entry of the config. Exit non-zero on any issue |
+| `cnlp check [<dir>] [--config <path>] [--name <set>] [--companion <set>=<dir>]` | hold every document to its profile: a directory read by path, or every corpus entry of the config. A set read by path resolves its references against the sets beside it and the companions you name. Reports each set's index bytes against its page bytes, names any file the §5 word rules did not reach and any marked region its profile did not shape, and names a local profile or a pasted agent-file block left behind by an upgrade. Exit non-zero on any issue |
 | `cnlp docs [<set>]` | write every document set's index, in reading order |
 | `cnlp print [<doc>] [--path]` | write the standard, or a profile, to stdout |
 | `cnlp scaffold <profile> <data.json>` | write a document from data, in the blocks and forms the profile declares |
 | `cnlp diff <profile> <doc> <data.json>` | report what moved between a document and a fresh read of its sources |
+| `cnlp --version` | write the version of the installed package, alone on 1 line |
 
 ## The ownership rule
 
@@ -167,6 +197,13 @@ and the inventory step of `cnlp-migrate` is where it comes from. `adr` declares
 block list and no custom section, because an ADR block outside that list is prose looking
 for a home.
 
+The §5 word rules are English — the deny list, the spelled thresholds, the open limits, the
+comparatives, the light verbs, the passive are lists of English words. A document written in
+another script matches none of them, so it is held to the rules that read shape — block forms,
+line rules, quoted text — and `cnlp check` names it rather than reporting a corpus as conformant
+against rules that never ran. The check reads script and not language, so a Latin-script document
+in another language still reads as English to it.
+
 Severity is the caller's. The checker returns issues; `cnlp check` treats every issue as an
 error. A project that gates on a lifecycle status — a warning while a decision is a draft, an
 error once it is accepted — applies that policy in its own validator, calling `bodyIssues`

package/node_modules/cnlp-kit/bin/cnlp.js

@@ -9,16 +9,19 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { PACKAGE_ROOT, recordDrift, renderBody, resolveDoc } from '../src/cnlp.js';
-import { AGENTS, CONFIG_NAME, STAMP_NAME, checkProject, configForPath, docsetsOf, findConfig, profileFor, proposeCorpus, readConfig, readingOrder, skillDrift, skillsDirFor } from '../src/config.js';
+import { AGENTS, AGENT_BLOCK, CONFIG_NAME, STAMP_NAME, agentBlockDrift, checkProject, configForPath, docsetsOf, findConfig, profileDrift, profileFor, proposeCorpus, readConfig, readingOrder, skillDrift, skillsDirFor } from '../src/config.js';
 
 const USAGE = `cnlp — the CNL-P checker
 
   cnlp init [<dir>] [--agents <a,b>]   install or update this kit in a project
   cnlp check [<dir>] [--config <path>] check a directory of documents, or every corpus entry
+             [--name <set>] [--companion <set>=<dir>]...
+                                       name the set <dir> holds, and the sets it crosses into
   cnlp docs [<set>]                    write the index of every document set, or of one
   cnlp print [<doc>] [--path]          write a shipped document to stdout, or its path
   cnlp scaffold <profile> <data>       write a document from a JSON file, in the profile's shape
   cnlp diff <profile> <doc> <data>     report what moved between a document and a fresh read
+  cnlp --version                       write the version of this package
 
   <doc> is "format" for the standard, or a profile name such as "skill".
   <a,b> is a comma list of ${AGENTS.map((a) => a.value).join(', ')}.
@@ -36,12 +39,18 @@ const STARTER = {
 const VERSION = JSON.parse(await readFile(fileURLToPath(new URL('package.json', PACKAGE_ROOT)), 'utf8')).version;
 
 const argv = process.argv.slice(2);
-const VALUE_FLAGS = ['--config', '--agents', '--out'];
+const VALUE_FLAGS = ['--config', '--agents', '--out', '--name', '--companion'];
 const flag = (name) => argv.includes(name);
 const value = (name) => {
   const at = argv.indexOf(name);
-  return at >= 0 ? argv[at + 1] : undefined;
+  return at >= 0 ? valueAt(at + 1) : undefined;
 };
+// A flag right after a flag is no value: `--name --companion x=y` would name the set `--companion`.
+function valueAt(i) {
+  return argv[i]?.startsWith('--') ? undefined : argv[i];
+}
+// A flag that repeats: `value` returns the first occurrence only.
+const values = (name) => argv.flatMap((a, i) => (a === name ? [valueAt(i + 1)] : []));
 const positional = argv.filter((a, i) => !a.startsWith('--') && !VALUE_FLAGS.includes(argv[i - 1]));
 
 const fail = (message) => {
@@ -94,6 +103,12 @@ function multiSelect(message, choices, checked) {
 
 const [command] = positional;
 
+// The version alone on stdout, so a script compares it without parsing a sentence.
+if (flag('--version')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 if (!command || flag('--help') || flag('-h')) {
   console.log(USAGE);
   // An asked-for usage is a success; a missing command is not.
@@ -108,16 +123,39 @@ if (command === 'check') {
   if (!target && !configPath) {
     fail(`no ${CONFIG_NAME} found here or above ${process.cwd()} — name a directory to check, or run \`cnlp init\` to write a config`);
   }
+  const name = value('--name');
+  const companionUsage = 'usage: cnlp check <dir> [--name <set>] [--companion <set>=<dir>]...';
+  // `--companion=a=b` read as no flag at all would print no `resolving` line, which a caller reads
+  // as an executable older than 3.8.0: refuse the form instead of ignoring it.
+  if ((flag('--name') && !name) || argv.some((a) => /^--(name|companion)=/.test(a))) fail(companionUsage);
+  // The first `=` splits the value, so a dir may carry `=` and a Windows drive letter.
+  const companions = values('--companion').map((v) => {
+    const cut = v?.indexOf('=') ?? -1;
+    if (cut <= 0 || cut === v.length - 1) fail(`--companion ${v ?? ''}: expected <set>=<dir>
+${companionUsage}`);
+    return { name: v.slice(0, cut), dir: v.slice(cut + 1) };
+  });
+  if (!target && (flag('--name') || companions.length)) {
+    fail('--name and --companion apply to a <dir>: a config run already reads every set under its root');
+  }
   let result;
   let config;
   try {
-    config = target ? await configForPath(target) : await readConfig(configPath);
-    result = await checkProject(config);
+    config = target ? await configForPath(target, { name, companions }) : await readConfig(configPath);
   } catch (e) {
     fail(e.message);
   }
-  // Paths below are relative to a root the caller never named, so name it once.
+  // Paths below are relative to a root the caller never named, so name it once. Printed before the
+  // check runs, so a caller seeing no `resolving` line concludes an old executable, not a crash.
   if (target) console.log(`reading ${config.corpus.length} entr(ies) under ${config.root}`);
+  // The wording is a contract: a caller passing companions detects an executable older than 3.8.0
+  // by this line's absence. Keep it stable.
+  for (const c of config.companions ?? []) console.log(`resolving against ${c.name} at ${c.dir}`);
+  try {
+    result = await checkProject(config);
+  } catch (e) {
+    fail(e.message);
+  }
   for (const { file, line, message } of result.issues) {
     console.error(`${file}:${line}: ${message}`);
   }
@@ -128,10 +166,35 @@ if (command === 'check') {
     const from = held ? `are from ${held}` : 'carry no version';
     console.error(`${path.relative(config.root, dir) || dir}: skills ${from}, this package is ${VERSION} — run \`cnlp init\``);
   }
+  // A copied profile and a pasted agent block are the 2 artifacts an upgrade cannot reach: the
+  // project owns both, so neither is overwritten and both are reported. Like a stale skill, a copy
+  // left behind is not a defect in a document the corpus names, and it decides no exit code.
+  for (const { file, profile, missing } of await profileDrift(config)) {
+    console.error(`${file}: the packaged ${profile} profile declares ${missing.join(', ')}, which this copy does not — compare them with \`npx cnlp print ${profile} --path\``);
+  }
+  for (const name of await agentBlockDrift(config.root)) {
+    console.error(`${name}: carries an earlier copy of the block \`cnlp init\` prints — paste the block that run ends with`);
+  }
+  // Every word list in §5 is English, so a body in another script matches none of them. Reporting
+  // which files the lexicon never reached is the difference between a partial check and a check
+  // that claims to be whole.
+  if (result.foreign.length) {
+    console.log(`${result.foreign.length} file(s) carry no English prose — the §5 word rules (deny list, thresholds, limits, comparatives, nominalizations, passive) did not apply to them`);
+    for (const rel of result.foreign) console.log(`  ${rel}`);
+  }
+  if (result.regions.length) {
+    console.log(`${result.regions.length} marked region(s) the file's profile did not shape — the §4 and §5 line rules read them`);
+    for (const r of result.regions) console.log(`  ${r.file}:${r.line}-${r.end}: ${r.name}`);
+  }
   if (result.issues.length) {
     fail(`\n${result.issues.length} issue(s) in ${result.checked.length} file(s)`);
   }
   console.log(`${result.checked.length} file(s) conform`);
+  // A reader loads the index to answer any question and a page to answer 1, so an author sees
+  // which of the 2 they are growing. `profiles/docset.md` states why they are different costs.
+  for (const set of result.sets) {
+    console.log(`${set.name}: index ${set.indexBytes} B fixed, ${set.pages} page(s) ${set.pageBytes} B on demand`);
+  }
   process.exit(0);
 }
 
@@ -324,10 +387,8 @@ if (command === 'init') {
   // decision about how that project's agent works. The operator pastes it where their agent reads.
   // 3 lines and not 5: an installed skill announces its own task through its description, so the
   // block states only what a skill cannot — a standing rule answers to no task description.
-  console.log(`\nPaste this into AGENTS.md, CLAUDE.md, or whatever file your agent reads:\n
-- the CNL-P standard is the authority on document form: read it with \`npx cnlp print format\`
-- run \`npx cnlp check\` before a commit that touches a document the corpus names
-- load a library's documentation with \`npx cnlp docs\`, which writes every set's index in reading order`);
+  console.log(`\nPaste this into AGENTS.md, CLAUDE.md, or whatever file your agent reads:\n`);
+  console.log(AGENT_BLOCK.join('\n'));
   process.exit(0);
 }
 

package/node_modules/cnlp-kit/cnlp-format.md

@@ -124,6 +124,22 @@ never carries sub-bullets to hold a second thought — that is two bullets.
 document, not CNL-P sections. Anything reading this format skips fenced regions before
 looking for section keys.
 
+**An HTML comment is markup, not structure.** A line that is 1 whole `<!-- … -->` comment, and
+every line of a comment opening a line and running over several, is not an item of the block above
+it and not a section key. A line carrying text beside a comment carries that text, and is read. A
+comment that never closes hides nothing, because it would otherwise hide the rest of the file. §4
+and §5 still read comment text: the rendered file hides it, and an agent reads the raw file.
+
+**A marked region belongs to the tool that wrote it.** A file several tools write into gives each
+tool its own lines between `<!-- <name>:start -->` and `<!-- <name>:end -->`, so the tool finds and
+rewrites its own block and leaves the rest alone. `<name>` is ASCII letters, digits, `_`, `.` and
+`-`. The file's profile does not shape a region: its keys and headings are not the file's blocks, so
+none of them is unknown, repeated or out of order, and nothing in it supplies a block the profile
+requires. §4 and §5 still hold on every line of it — a region is exempt from the file's shape, not
+from its language. An end closes the latest start of its own name. A start with no end marks
+nothing, because it would otherwise exempt the rest of the file. The checker lists every region it
+did not shape, because a region is an exemption any author can write.
+
 **An empty block.** A required block with nothing in it carries `- none` and the reason:
 `- none: no alternative was viable at this scale`. That single line is the whole content and
 replaces the form the block would otherwise take, so a record-list or a keyed-block says it
@@ -166,6 +182,14 @@ A block whose content is a fenced region is not empty — the fence is opaque, n
 - A short concrete verb over an abstract one.
 - Define a specialized term once, then reuse it verbatim.
 
+**The word rules are English, and a check says when they did not run.** The 7 bullets above hold
+in any language. Every table and every list below is a list of English words — the deny-list, the
+spelled thresholds, the open limits, the comparatives, the light verbs, the passive — so a body
+written in another script matches none of them and is held only to the rules that read shape:
+§3 block forms, §4 line rules, and the quoted-text rule below. The checker reports every such file
+by name, because a corpus reported as conformant against rules that never ran is worse than a
+corpus nobody checked.
+
 **`check the corpus` and `run the check` are 2 terms.** One term per concept fixes which word names a
 thing; one part of speech fixes which job that word does — here the action, and the program that
 performs the action. Keep the part of speech the term already carries and rename the other use:
@@ -443,9 +467,18 @@ The rules a checker holds:
 - every document except a set's `index` is the target of at least 1 reference. A page nothing
   reaches is a page nobody reads, and it goes stale unobserved.
 
-**The checker reads this only when a project says where its sets live**, with a `docsets` key in
-`cnlp.config.json` naming the directory whose immediate subdirectories are one set each. A project
-with no such key has no document set, and none of this applies to it.
+**The checker reads this only where it knows a set lives**: a project names the directory whose
+immediate subdirectories are one set each with a `docsets` key in `cnlp.config.json`, and a
+directory checked by path is a set, or the root of several, by the `index.md` it holds. A project
+with no such key and no such directory has no document set, and none of this applies to it.
+
+**A set checked on its own resolves its crossings against its companions**: the sets the caller
+names, and the sets beside it. A reference into `toolkit` from a set that extends it resolves
+when `toolkit` is a companion. A companion is read to resolve a reference and is never checked: a
+reference inside it is not reported, and a page of it nothing reaches is not reported, but a
+reference from it into the checked set counts as reaching that page. The sets beside a set join
+only when its name is the name of its directory; a set named apart from its directory sits in a
+layout whose neighbours are not sets, and the caller names every companion.
 
 The rules a review holds. They are the same kind of rule as the four above and no checker reaches
 them, the way §5 splits the enforced half of a limit from the reviewed half:

package/node_modules/cnlp-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cnlp-kit",
-  "version": "3.4.1",
+  "version": "3.9.1",
   "description": "CNL-P — a format for documents an agent has to read precisely. The standard, its profiles, and the checker that holds them.",
   "type": "module",
   "license": "MIT",