gcf-aif-ext 0.2.0

package/node_modules/cnlp-kit/profiles/api.md

@@ -0,0 +1,87 @@
+---
+name: api
+description: The CNL-P profile of an API page — one capability of a library, the symbols that spell it, its contract, and 1 example.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: an API page is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: an API page is reached through the index, which already carries its name
+
+lexicon_exempt:
+- none: an API page has no frontmatter, so nothing is exempt
+
+sections:
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the capability is for, and the question a reader arrives with
+
+- key: symbols
+  form: bullet-list
+  required: yes
+  note: the exact symbols covered; a group of overloads is 1 page, because a reader picks between them once and then stops reading
+
+- key: signature
+  form: keyed-block
+  required: yes
+  note: the declarations verbatim in a fenced block, in the language of the library
+
+- key: parameters
+  form: record-list
+  required: no
+  record_keys: name, means
+  optional_record_keys: type, default
+  note: only what a reader cannot read off the signature; a parameter whose name states its meaning costs a line and adds nothing
+
+- key: returns
+  form: bullet-list
+  required: no
+  note: what comes back, and what a caller does with it
+
+- key: errors
+  form: bullet-list
+  required: no
+  note: what fails, and the condition that causes it
+
+- key: constraints
+  form: bullet-list
+  required: no
+  note: what a caller cannot violate, each as a limit or as a state that holds before the call
+
+- key: choose
+  form: record-list
+  required: no
+  record_keys: when, use
+  note: the rule for picking between the symbols above; a page covering 1 symbol deletes this block
+
+- key: example
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: 1 canonical use, with shows stating what it demonstrates, written in the names the set's running example uses; a compositional example is a task page, not a second example here
+
+- key: pitfalls
+  form: bullet-list
+  required: no
+  note: what a reader writes wrong, each with what to write instead
+
+- key: see_also
+  form: record-list
+  required: yes
+  record_keys: page, relation, reason
+  record_values: relation = needs, next, alternative, detail, supersedes
+  note: relation is needs, next, alternative, detail or supersedes; reason lets a reader decide without opening the page, and supersedes names a page of another docset that replaces this one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own API pages already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: an API page is read as the contract of a call a reader is about to write
+- `npx cnlp check` resolves every `page:` value, and reports a page no other page reaches, once the project declares `docsets:`

package/node_modules/cnlp-kit/profiles/concept.md

@@ -0,0 +1,70 @@
+---
+name: concept
+description: The CNL-P profile of a concept page — one model a reader holds before the API pages that rest on it read correctly.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: a concept page is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: a concept page is reached through the index, which already carries its name
+
+lexicon_exempt:
+- none: a concept page has no frontmatter, so nothing is exempt
+
+sections:
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the model explains, and which pages stop reading correctly without it
+
+- key: model
+  form: bullet-list
+  required: yes
+  note: what the thing is, 1 statement per line, in the reader's terms rather than in the library's internals
+
+- key: terms
+  form: record-list
+  required: no
+  record_keys: term, means
+  note: a word the library uses in its own sense; a word that means what it usually means costs a line and adds nothing
+
+- key: invariants
+  form: bullet-list
+  required: yes
+  note: what a caller cannot violate, and what breaks when it does; this is the block an API page points back to instead of restating
+
+- key: lifecycle
+  form: numbered-list
+  required: no
+  note: the order of states, for a thing a caller creates, drives and releases
+
+- key: example
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: 1 canonical use, with shows stating what it demonstrates, written in the names the set's running example uses so the 2 compose
+
+- key: pitfalls
+  form: bullet-list
+  required: no
+  note: what a reader gets wrong about the model, each with what holds instead
+
+- key: see_also
+  form: record-list
+  required: yes
+  record_keys: page, relation, reason
+  record_values: relation = needs, next, alternative, detail, supersedes
+  note: relation is needs, next, alternative, detail or supersedes; reason lets a reader decide without opening the page, and supersedes names a page of another docset that replaces this one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own concept pages already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: a concept page is what every API page resting on it points to
+- `npx cnlp check` resolves every `page:` value, and reports a page no other page reaches, once the project declares `docsets:`

package/node_modules/cnlp-kit/profiles/docset.md

@@ -0,0 +1,103 @@
+---
+name: docset
+description: The CNL-P profile of a docset index — the entry page of a library's agent documentation, and the closed list of what that library offers.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: an index is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: an index is read by path, so it carries no routing contract to restate
+
+lexicon_exempt:
+- none: an index has no frontmatter, so nothing is exempt
+
+sections:
+- key: identity
+  form: keyed-block
+  required: yes
+  record_keys: library, version, source
+  optional_record_keys: derived_from
+  note: the library covered and the revision it was read at; derived_from names what the pages were written from, because a page written from prose carries less weight than one written from a signature
+
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the library does, and the kind of task a reader reaches for it with
+
+- key: read_protocol
+  form: numbered-list
+  required: yes
+  note: how to walk this docset: the common case is written from `canonical_use:`, a page opens for any call whose contract the reader lacks, and a step telling the reader to stop reading is the defect
+
+- key: install
+  form: bullet-list
+  required: no
+  note: how a project takes the dependency; delete the block when the docset covers a dependency the project already carries
+
+- key: canonical_use
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: 1 complete working use of the library, carrying every load-bearing element; a reader holding only the index writes the common case from this block, and an index without one is a table of contents, which is enough for nothing
+
+- key: walkthrough
+  form: record-list
+  required: yes
+  record_keys: part, page
+  note: each part of `canonical_use:` and the page owning its detail; a record and not a comment inside the fence, because a fence is opaque and a link inside one reaches no reader and no check
+
+- key: concepts
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the models a reader holds before any page reads correctly; a record and not a line, so every link in a docset is a `page:` value and a resolver guesses at none of them
+
+- key: tasks
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the goals a reader arrives with; a catalog keyed on capability routes a reader holding a symbol and leaves one holding a goal to guess
+
+- key: catalog
+  form: record-list
+  required: yes
+  record_keys: capability, does, status
+  optional_record_keys: page, read, instead, fingerprint
+  record_values: status = covered, source, avoid
+  note: "every capability the library offers, in 1 record each; status is covered, source or avoid, and a symbol absent here is a symbol the library lacks; fingerprint changes when the source does, so a record without one cannot report drift"
+
+- key: excluded
+  form: bullet-list
+  required: yes
+  note: a whole region the docset leaves out, with the reason; a region named in neither this block nor the catalog reads as an omission nobody decided
+
+- key: companions
+  form: record-list
+  required: yes
+  record_keys: docset, when, owns
+  note: another docset covering what this library does not; `when:` is "always" once its index carries `overrides:`, since a reader loading it on demand misses the correction; "- none" when the library stands alone
+
+- key: overrides
+  form: record-list
+  required: no
+  record_keys: page, by, reason
+  note: "a page of another docset that stops holding once this package is present, and the page here that replaces it; `page:` names the foreign page and carries its docset prefix, `by:` names the local one and carries none"
+
+- key: version_notes
+  form: bullet-list
+  required: no
+  note: what changed in the covered version, for a reader arriving from an older one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own docsets already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: an index routes every other page, so a wrong index misroutes the whole docset
+- `npx cnlp check` resolves every `page:`, `by:` and `docset:` value once the project declares `docsets:`
+- `npx cnlp check` holds `status` to covered, source and avoid; what a status implies — a `read:` on source, an `instead:` on avoid — is caught by review

package/node_modules/cnlp-kit/profiles/guide.md

@@ -0,0 +1,51 @@
+---
+name: guide
+description: The CNL-P profile of a repository guide — the sections AGENTS.md uses to tell an agent how to edit this repository, in order.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: a guide is one flat run of sections, and the file name carries the title
+
+frontmatter_fields:
+- none: a guide is read by path, so it carries no routing contract to restate
+
+lexicon_exempt:
+- none: a guide has no frontmatter, so nothing is exempt
+
+sections:
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the file governs, and when to read it
+
+- key: read_first
+  form: bullet-list
+  required: no
+  note: what an editor has to understand before the first edit, such as which file is the authority on what
+
+- key: workflow
+  form: numbered-list
+  required: no
+  note: the order of work for the edit this guide governs
+
+- key: forbidden_behaviors
+  form: bullet-list
+  required: no
+  note: what an edit never does, each with the reason it breaks something
+
+- key: verification
+  form: bullet-list
+  required: no
+  note: the command that proves the edit conforms, and how its output is read
+
+custom_sections:
+- none: a project fills this from the vocabulary its own guide already uses
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: a guide is read before an agent edits the corpus, so a wrong guide corrupts every file that follows
+- a repository without Node holds this profile by review against the standard instead

package/node_modules/cnlp-kit/profiles/profile.md

@@ -0,0 +1,69 @@
+---
+name: profile
+description: The CNL-P profile of a profile — the blocks profiles/<name>.md declares, in order.
+---
+
+format: cnlp-format.md
+
+mood: declarative
+
+headings:
+- none: a profile is one flat run of blocks
+
+frontmatter_fields:
+- name
+- description
+
+lexicon_exempt:
+- none: a profile is read by whoever writes a document of the kind it describes
+
+sections:
+- key: format
+  form: scalar
+  required: yes
+  note: the standard this profile's documents obey, by path
+
+- key: mood
+  form: scalar
+  required: yes
+  note: imperative or declarative; the register the body is written in, and the value that gates the active-voice rule
+
+- key: headings
+  form: bullet-list
+  required: yes
+  note: the ## headings in order, or "- none" for a flat body
+
+- key: frontmatter_fields
+  form: bullet-list
+  required: yes
+  note: the fields the body may not restate
+
+- key: lexicon_exempt
+  form: bullet-list
+  required: yes
+  note: frontmatter fields the lexicon does not police; frontmatter is not checked, so this is for the reader
+
+- key: sections
+  form: record-list
+  required: yes
+  record_keys: key, form, required
+  optional_record_keys: heading, record_keys, optional_record_keys, record_values, note
+  note: the blocks in order, held to §7 of the format; form is one of the 5 in the format, required is yes or no, and record_values closes a record key to a vocabulary
+
+- key: custom_sections
+  form: bullet-list
+  required: yes
+  note: names a document of this kind may add, or "- none"
+
+- key: enforcement
+  form: bullet-list
+  required: yes
+  note: the command or test that checks this profile, and its severity
+
+custom_sections:
+- none: a profile declares values, so a block outside this list is a rule that escaped the format
+
+enforcement:
+- `npm test` (`test/profile.test.js`), over every file in `profiles/`
+- any issue is an error: a profile that is wrong makes every document of its kind wrong
+- this file is checked against itself; nothing checks that, and the recursion stops here

package/node_modules/cnlp-kit/profiles/reference.md

@@ -0,0 +1,61 @@
+---
+name: reference
+description: The CNL-P profile of a reference file — the sections a checklist or a protocol under references/ uses, in order.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: a reference file is one flat run of sections, and the file name carries the title
+
+frontmatter_fields:
+- none: a reference file is read by path, so it carries no routing contract to restate
+
+lexicon_exempt:
+- none: a reference file has no frontmatter, so nothing is exempt
+
+sections:
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the file is loaded for, and when
+
+- key: scope
+  form: bullet-list
+  required: no
+  note: what this file owns, and which file owns a neighbouring topic
+
+- key: read_first
+  form: bullet-list
+  required: no
+  note: the terms and gates a `checks:` item depends on, when reading an item alone would misfire
+
+- key: workflow
+  form: numbered-list
+  required: no
+  note: how to find the patterns, before the block that names them; a checklist with nothing to run deletes this block
+
+- key: checks
+  form: bullet-list
+  required: no
+  note: "a project states the line form a `checks:` item takes, and holds it by a test of its own until the format can declare it"
+
+- key: non_findings
+  form: bullet-list
+  required: no
+  note: patterns the reader would otherwise flag, each with the reason it is not a finding
+
+- key: forbidden_behaviors
+  form: bullet-list
+  required: no
+  note: when the file drives a change rather than a review
+
+custom_sections:
+- none: a project fills this from the vocabulary its own reference files already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: a reference file is read as executable instructions, so there is no draft state to warn about
+- a repository without Node holds this profile by review against the standard instead

package/node_modules/cnlp-kit/profiles/skill.md

@@ -0,0 +1,75 @@
+---
+name: skill
+description: The CNL-P profile of an agent skill — the sections a SKILL.md body uses, in order.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: a skill body is one flat run of sections, and frontmatter `name` carries the title
+
+frontmatter_fields:
+- name
+- description
+
+lexicon_exempt:
+- description: it feeds skill routing and needs the phrasing an operator would actually use
+
+sections:
+- key: mode
+  form: scalar
+  required: yes
+  note: a human label; no machine consumer reads it
+
+- key: purpose
+  form: bullet-list
+  required: yes
+
+- key: inputs
+  form: bullet-list
+  required: yes
+  note: "- none with the reason when the skill discovers its own"
+
+- key: preconditions
+  form: bullet-list
+  required: no
+  note: when state must hold before step 1
+
+- key: scope
+  form: bullet-list
+  required: no
+  note: only when workflow does not already bound it
+
+- key: forbidden_behaviors
+  form: bullet-list
+  required: no
+  note: when the skill has prohibitions
+
+- key: outputs
+  form: bullet-list
+  required: no
+  note: only when nothing else states what the run produces
+
+- key: quality_rules
+  form: bullet-list
+  required: no
+  note: the shared rubric, copied verbatim into every skill that carries it
+
+- key: workflow
+  form: numbered-list
+  required: yes
+  note: reference material states "- none" with the reason instead of carrying steps
+
+- key: invocation
+  form: bullet-list
+  required: yes
+
+custom_sections:
+- none: a project fills this from the inventory step of cnlp-migrate, before rewriting any skill
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: a skill ships as executable instructions, so there is no draft state to warn about
+- a repository without Node holds this profile by review against the standard instead

package/node_modules/cnlp-kit/profiles/task.md

@@ -0,0 +1,65 @@
+---
+name: task
+description: The CNL-P profile of a task page — how to reach one outcome with the library, in steps, with the compositional example the API pages leave out.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: a task page is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: a task page is reached through the index, which already carries its name
+
+lexicon_exempt:
+- none: a task page has no frontmatter, so nothing is exempt
+
+sections:
+- key: goal
+  form: scalar
+  required: yes
+  note: the outcome, in the words a reader arrives with rather than in the library's terms
+
+- key: preconditions
+  form: bullet-list
+  required: no
+  note: what holds before step 1; delete the block when the steps start from nothing
+
+- key: workflow
+  form: numbered-list
+  required: yes
+  note: the steps, each naming the call it makes and sending the reader to the API page for the contract
+
+- key: example
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: the composition the steps produce, whole and runnable, in the names the set's running example uses; this is where a multi-call example lives, so an API page stays small
+
+- key: verification
+  form: bullet-list
+  required: no
+  note: how a reader proves the result works, by a command or by an observable state
+
+- key: failure_modes
+  form: record-list
+  required: no
+  record_keys: symptom, cause, fix
+  note: what a reader sees when a step went wrong, keyed on the symptom because that is what the reader has in hand
+
+- key: see_also
+  form: record-list
+  required: yes
+  record_keys: page, relation, reason
+  record_values: relation = needs, next, alternative, detail, supersedes
+  note: relation is needs, next, alternative, detail or supersedes; reason lets a reader decide without opening the page, and supersedes names a page of another docset that replaces this one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own task pages already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: a task page ships as executable instructions, so there is no draft state to warn about
+- `npx cnlp check` resolves every `page:` value, and reports a page no other page reaches, once the project declares `docsets:`

package/node_modules/cnlp-kit/quality-rules.md

@@ -0,0 +1,69 @@
+# The shared rubric — a seed, not a standard
+
+`quality_rules:` is the one block a repository copies **verbatim** into every skill that
+carries it. There is no include mechanism in the skill runtime, so the duplication is
+deliberate, and a byte-identity test you write in your own repository — the last section
+says how — is what keeps the copies from drifting until 2 skills judge the same work by
+different rules.
+
+This file is a starting point. Prune it before use: a rule that names an artifact your skills
+do not have teaches the agent to look for nothing. Nothing here is part of the standard, and
+no check reads it.
+
+## The long variant
+
+```
+quality_rules:
+- measure every option by what serves the project best over its lifetime
+- state delivery cost, risk, and timeline explicitly for the operator
+- do not let your own convenience in this session stand in for them
+- name the project invariants the change touches: module boundaries, public APIs, data schemas, and the decision records in force
+- cite the concrete rule, decision record, architecture document, or code location each judgment rests on
+- no ground named, no recommendation: research until you can name it, never fill the gap with a guess
+- present at least 2 viable approaches when the change touches a module boundary, public API, data schema, or architectural invariant
+- if only 1 approach is viable, say so and why the others are not
+- give per approach: consequences over the next 6–12 months of project evolution, effect on coupling, hidden risks
+- reject each alternative in its strongest version, and name the reason
+- do not accept "faster to write", "easier", or "smaller diff for me now" as justification for violating an invariant or an established convention of the codebase
+- justify any divergent local pattern explicitly: two ways of doing one thing is a real cost
+- name a large blast radius — many call sites, data migrations, compatibility breaks — as the genuine risk and cost it is
+- prefer the smaller change at equal architectural correctness, and add no abstractions for hypothetical needs
+- an obligation costs what it takes to satisfy: name the failure each one prevents, and drop the obligation whose cost is above that failure
+- count effort already sunk into existing code as nothing by itself; the compatibility and migration cost of replacing it does count
+- when the correct option costs more, present it alongside the cheap one, each with its cost, risk, and reversibility
+- demand stronger grounds for hard-to-reverse choices such as data schemas and public APIs
+- end with exactly 1 explicit recommendation; the operator decides, never silently downgrade to the cheap option
+- revise a recommendation only on a new fact, a new constraint, a found reasoning error, a clarified goal, or an explicit operator decision, and name what changed
+- disagreement alone is not new information: a flip with no new grounds means the original was ungrounded
+```
+
+Carried by the skills that choose between options and recommend one.
+
+## The short variant
+
+```
+quality_rules:
+- the decision is already made: do not re-litigate it
+- ground every verdict in a concrete rule, a decision record, a plan step, or a code location
+- no ground named, no verdict: research until you can name it, never guess
+- report code diverging from the decision as a deviation, with evidence
+- do not resolve a deviation by reshaping the judgment to fit it
+- do not excuse a deviation because fixing it would be laborious
+- follow the project's existing conventions and invariants for tactical choices
+- do not accept agent convenience — "faster", "easier" for this session — as an argument
+- revise a verdict only on a new fact, a found reasoning error, or an explicit operator decision, and name what changed
+- disagreement alone is not new information
+```
+
+Carried by the skills that check work against a decision already taken.
+
+## Keeping the copies identical
+
+The rubric only stays shared if something asserts it. Write a test in your own repository that
+lists which skills carry which variant and asserts the block is byte-identical within each
+group. Without it, the first hand-edit to one copy goes unnoticed and the rubric stops being
+shared — which is exactly what happened to the first project that adopted this file and never
+ported the test.
+
+`cnlp check` does not do this for you: the checker reads the profile, and the profile declares
+that `quality_rules:` is a bullet-list, not what the bullets say.