gcf-aif-ext 0.2.0

package/node_modules/cnlp-kit/skills/cnlp-docset/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cnlp-docset
+description: Write the documentation of a library as a CNL-P document set — the index carrying one whole working program, the concept, API and task pages, and the closed catalog of everything the library offers.
+---
+
+mode: cnlp_docset_authoring
+
+purpose:
+- write the documentation of 1 library as a CNL-P document set, so an agent loads 1 page at a time instead of loading everything to answer anything
+- aim at accuracy: fewer wrong calls written against the library, and cost is what falls out of that rather than what drives it
+- keep the catalog complete, so a reader tells a capability the library lacks from one the set left out
+- work from whatever the operator found, in any mix, and state on every page what that page rests on
+
+inputs:
+- sources: every repository, specification, document and example the operator supplies for 1 library, in any mix
+- source_weight: what a source proves, from 1 the strongest to 5 the weakest, which decides where a contract comes from
+- weight 1: the declarations read from the library source
+- weight 2: a specification the library publishes for a machine to read
+- weight 3: the prose documentation the library publishes for a person to read
+- weight 4: the examples and the tests the library ships
+- weight 5: a file derived from a source nobody here read, such as a vendor dump of the documentation
+- output_directory: where the set is written; its name is the name of the set, and it holds the set and nothing else
+
+preconditions:
+- `npx cnlp print format --path` resolves, whether the operator installed the kit globally or as a dependency of some project
+- `npx cnlp check <output_directory>` reaches the set by path: a produced set carries no config file, and it needs no project around it
+- every source sits at a fixed revision or a fixed version, so every page states what 1 release says
+
+scope:
+- act on the output directory the operator named, and write the index, the concept pages, the API pages and the task pages under it
+- write nothing else into that directory: a set is documentation handed to whoever asked for it, and a config, a dependency or a skill copy there belongs to a project rather than to a set
+- leave every other set alone: a package that corrects another package states the correction in its own index, and edits no page of the set it corrects
+- stop at authoring: a repository that will hold this set among its own documents runs `npx cnlp init` and names it in `docsets:`, which is adoption and not this skill's work
+
+forbidden_behaviors:
+- do not invent a signature, a parameter or a default: read each one from the source that states it
+- do not state a contract at a weight its source does not carry: a claim read in prose stays a claim read in prose, and writing it as a declaration tells the reader it came from one
+- do not drop a capability from the catalog: a capability with no record gets invented again, or found in the source and called anyway
+- do not mark a record `covered` before its page exists: the value is held to its vocabulary and not to the truth, so `covered` with no page sends the reader nowhere
+- do not mark a capability `avoid` on judgment alone: that is a claim about the library, and a wrong one steers a reader away from the call the task needed
+- do not write a second example on an API page: a compositional example is a task page
+- do not write 1 page per member: a group of overloads is 1 page, because a reader picks between them once
+- do not name the library inside a packaged profile: a vocabulary of your own goes in `custom_sections:` of a local copy of that profile
+
+outputs:
+- 1 document set: the index, the concept pages, the API pages and the task pages
+- the catalog as the closed list of the library's capabilities, every record at `covered`, `source` or `avoid`
+- a report: the capabilities carrying a page, the ones left at `source`, the weight the set rests on, and the regions `excluded:` names with their reasons
+
+workflow:
+1. run `npx cnlp print format` and read it in full, §9 included: it states what a page reference is, and which of its rules a review holds rather than the checker
+2. read the `docset`, `concept`, `api` and `task` profiles through `npx cnlp print <name>`: their `note:` keys carry the reason behind each block, and the rules and the values are read together
+3. list every source the operator supplied and name the weight each one carries: the strongest weight in that list bounds what every page below claims, so report it before writing anything
+4. run the clone or the install command each source needs, at a fixed revision, and record the library, the version and the revision in `identity:`
+5. fill `derived_from:` in `identity:` with those sources and their weights, so a reader tells a set written from declarations from a set written from prose
+6. list every capability of the library, taking each one from the strongest source that states it: a source at weight 3 or below covers what its author chose to cover, so a capability it omits is a capability still to find
+7. fill `catalog:` with 1 record per capability, every one at `status: source`, `read:` naming where to read it — the file, or the document and the anchor inside it
+8. pick the type names of the set's running example once, before any page: every example on every page uses them, so a reader assembling several pages gets 1 program instead of fragments
+9. write `canonical_use:` as 1 complete working use of the library, carrying every load-bearing element, because a reader holding only the index writes the common case from it
+10. map each part of `canonical_use:` onto the page owning its detail, in `walkthrough:`
+11. write the concept pages next: an API page points back to an invariant instead of restating it, so the model exists before the pages resting on it
+12. write 1 API page per capability, and state the pick between its symbols in `choose:`
+13. write 1 task page per goal a reader arrives with, and put the multi-call composition there
+14. update each catalog record to `covered` as its page lands, and fill `excluded:` with every whole region the set leaves out, each with its reason
+15. fill `companions:` when another package extends this library, and `overrides:` when this package corrects a page of the set it extends
+16. run `npx cnlp check <output_directory>` and fix what it reports: it resolves every reference in the set, and reports a page no other page reaches
+17. read the finished set for the rules no check reaches: 1 fact stated on 1 page, 1 running example across the set, 1 page per routed name, and the keys a status implies
+18. report the capabilities covered, the ones left at `source`, the weight the set rests on, and any defect the reading turned up in the library itself
+
+invocation:
+- Claude Code: `/cnlp-docset <sources> <output-directory>`, once this folder sits in `.claude/skills/`
+- Codex: `$cnlp-docset <sources> <output-directory>`, once this folder sits in its skills directory
+- any other agent: read `skills/cnlp-docset/SKILL.md` and follow it; the body is the instruction

package/node_modules/cnlp-kit/skills/cnlp-migrate/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cnlp-migrate
+description: Convert a repository's technical documents to the CNL-P format — group them by kind, author or copy the profile each kind is held to, then rewrite each body into its blocks without changing what any document says.
+---
+
+mode: cnlp_migration
+
+purpose:
+- rewrite existing documents into CNL-P, so a reader stops inferring which sentence is intent, which is policy, and which is a step
+- author or copy the profile of every kind of document in the corpus, and rewrite no body until it exists
+- carry every rule across unchanged: a format migration is not a redesign
+
+inputs:
+- documents_directory
+- optional_single_document
+
+preconditions:
+- `cnlp-kit` is a dependency of this repository and `npx cnlp print format --path` resolves
+- `cnlp.config.json` names the corpus; `npx cnlp init` writes the entries the repository's own layout already supports
+- the working tree is clean, so the rewrite is reviewable as its own diff
+
+scope:
+- act on the document bodies 1 corpus entry maps to, and on the local copy of the profile that entry names
+- leave frontmatter alone wherever a runtime parses it: a skill's `name` and `description` drive discovery and routing
+
+forbidden_behaviors:
+- do not invent a rule the source never stated
+- do not drop a rule silently: state every deliberate drop with its reason
+- do not add a block the profile does not declare: edit the profile first, or put the content in a declared block
+- do not change what a document says while changing how it reads
+- do not hold 2 kinds of document to 1 profile: a block 1 kind needs and another cannot use is 2 profiles wearing 1 name
+- do not resolve a contradiction found in the source prose: report it, because it is a decision the operator owns
+
+outputs:
+- 1 profile per kind of document in the corpus, in the directory `cnlp.config.json` names, its `custom_sections` filled from the inventory
+- `cnlp.config.json` carrying 1 corpus entry per kind
+- the rewritten bodies, 1 commit per document or 1 per batch, as the operator prefers
+- per document: the rules carried in, the rules dropped with their reasons, the size delta and its cause
+
+workflow:
+1. run `npx cnlp print format` and read it in full: the rules live there, and a profile declares values against them rather than rules of its own
+2. list every document to convert, and group them by kind: 1 kind is 1 profile and 1 corpus entry
+3. read the packaged profile nearest each kind through `npx cnlp print <name>`, and compare what it declares against the documents in hand
+4. write a profile for any kind no packaged profile fits, against `profiles/profile.md`: a new kind of document is 1 new profile and no change to the checker
+5. copy every packaged profile the corpus uses into the directory `profiles:` names, so the vocabulary filled below survives an upgrade of the package
+6. list every top-level `key:` those documents already use, and every recurring idea that is prose today
+7. map each name onto a declared block, or onto a custom section name, applying the placement rule in the standard
+8. fill `custom_sections:` in each copied profile with the names that survive, and delete its `- none` line
+9. stop and ask when a name has no home: a new block changes the profile, which is the operator's decision
+10. update `cnlp.config.json` with 1 corpus entry per kind, and run `npx cnlp check` to verify every entry matches a file
+11. pick a single document and carry it through steps 12 to 17 before touching the rest
+12. list the source's rules, including the ones buried in a subordinate clause
+13. rewrite the body into the profile's blocks, 1 idea per line, in the declared order
+14. tick each listed rule against the result, and state every deliberate drop with its reason
+15. name any rule in the result that has no origin in the source: that is an addition, not a migration
+16. measure the size and state the cause of any growth, per the migration procedure in the standard
+17. run `npx cnlp check` and fix what it reports
+18. repeat steps 12 to 17 for each remaining document, kind by kind
+19. report per document: rules in, rules dropped, size delta, and the judgment calls left open
+
+invocation:
+- Claude Code: `/cnlp-migrate <documents-directory>`, once this folder sits in `.claude/skills/`
+- Codex: `$cnlp-migrate <documents-directory>`, once this folder sits in its skills directory
+- any other agent: read `skills/cnlp-migrate/SKILL.md` and follow it; the body is the instruction