@orkestrel/scaffold 0.0.55 → 0.0.57

package/dist/src/core/index.d.cts

@@ -108,6 +108,8 @@ export declare const ARTIFACT_TEMPLATES: Readonly<{
     }>;
     docs: Readonly<{
         readme: "# {{package}}\n\n{{description}}\n\n## Development\n\n```sh\nnpm install\nnpm test\n```\n";
+        agents: "# AGENTS.md\n\nThe `@orkestrel/scaffold` package is this repository's coding and orchestration authority. This\nfile points at it and states no law of its own.\n\nRead these before working: the `AGENTS.md` coding contract, the `.agents/orchestration.md`\nagent-operation contract, every applicable rule the contract's rule map names under\n`.claude/rules/`, and the dispatch-named skill under `.agents/skills/` with the references it\nrequires.\n\nResolve every one of those paths against scaffold, never against this repository:\n\n- When a scaffold checkout sits beside this repository, read `../scaffold/AGENTS.md`, the\n  `../scaffold/.agents/orchestration.md` file, the `../scaffold/.claude/rules/` directory, and\n  the `../scaffold/.agents/skills/` directory.\n- Otherwise read the installed copy, whose paths drop the dot that opens each segment: the\n  `node_modules/@orkestrel/scaffold/dist/host/AGENTS.md` file, the\n  `node_modules/@orkestrel/scaffold/dist/host/agents/orchestration.md` file, the\n  `node_modules/@orkestrel/scaffold/dist/host/claude/rules/` directory, and the\n  `node_modules/@orkestrel/scaffold/dist/host/agents/skills/` directory.\n\nEvery path a scaffold-supplied file names resolves the same way. The files this repository carries\n— the `.claude/agents/orkestrel.md` catalog file, the `.claude/settings.json` permission file,\nand the bench scripts under `scripts/` — are this repository's own copies and resolve here.\n\nEdit none of the scaffold-owned files here. The `scaffold repair` command restores them, so a\nchange to one is a commit in the scaffold repository followed by a release.\n";
+        claude: "# CLAUDE.md\n\nRead the `AGENTS.md` file in this repository first. It names the coding and orchestration\nauthority and where to read each contract.\n\nThis file imports nothing. An `@path` import inlines the imported file into every context that\nloads it, which is the cost this pointer removes.\n";
     }>;
     guides: Readonly<{
         readme: "# Guides\n\n## By concept\n\n- Package\n  - Spec: Not created. Create this file when the workspace has a public surface:\n    `guides/{{guide}}.md`\n  - Source:\n{{source}}\n  - Tests:\n{{tests}}\n\n## By directory\n\n{{directories}}\n";
@@ -343,7 +345,22 @@ export declare function blueprintToDevDependencies(blueprint: Blueprint): Readon
  * Compile the generated workspace's root documentation.
  *
  * @param blueprint - The workspace specification.
- * @returns One birth-owned package front page.
+ * @returns The birth-owned package front page and the content-owned `AGENTS.md`
+ * and `CLAUDE.md` pointers.
+ *
+ * @remarks
+ * The front page is the workspace's own prose, so it is written once and left
+ * alone from then on. The pointers are scaffold's, so they are content-owned and
+ * restored whenever they drift.
+ *
+ * A pointer is planned here rather than vendored because `stageHost` refuses two
+ * vendored paths at one storage name, and `AGENTS.md` and `CLAUDE.md` already
+ * store the canon a release ships. Planning them as this package's own content
+ * leaves each path with one claimant.
+ *
+ * Neither pointer carries a varying span, so neither is filled: a workspace's
+ * name never reaches the text, and the paths a reader follows are the same in
+ * every target.
  */
 export declare function blueprintToDocumentArtifacts(blueprint: Blueprint): readonly ContentArtifact[];
 
@@ -674,13 +691,52 @@ export declare type BuildFormat = 'es' | 'cjs';
  */
 export declare function bytesToHex(bytes: Uint8Array): string;
 
+/**
+ * The instruction-canon paths staged for reading rather than for a target, frozen.
+ *
+ * @remarks
+ * The root instruction documents, the orchestration contract every harness
+ * bridge points at, the rule map's rules, the skills, the templates, the
+ * transport contracts, the agent roles each harness dispatches, the bench
+ * configuration, and the MCP registrations. A directory entry covers everything
+ * beneath it.
+ *
+ * Staging walks these beside {@link HOST_PATHS}, so a release ships them and a
+ * reader reaches them two ways: a scaffold checkout sitting beside the
+ * repository, or the `node_modules/@orkestrel/scaffold/dist/host/` root inside
+ * the installed package. The `AGENTS.md` and `CLAUDE.md` pointers scaffold plans
+ * are what name each location.
+ *
+ * The lists are disjoint by prefix in either direction: no member of either
+ * equals or sits beneath a member of the other. Staging depends on that, because
+ * the walk covers the union and a path it discovers twice claims one storage
+ * name twice, which refuses the stage.
+ *
+ * The plan claims paths inside the canon deliberately, and each has a reason.
+ * `blueprintToDocumentArtifacts` claims `AGENTS.md` and `CLAUDE.md` as this
+ * package's own template pointers. `nameToHostArtifacts` claims
+ * {@link CATALOG_AGENT_PATH}, because the catalog verb refuses a target that
+ * lacks the file and repair restores its absence.
+ *
+ * A target therefore holds a file at a canon path only where the plan claims it.
+ * That is the rule every verb obeys, and it is what makes a copy found anywhere
+ * else superseded.
+ */
+export declare const CANON_PATHS: readonly string[];
+
 /**
  * The agent file whose marker-bounded package table the catalog verb alone owns.
  *
  * @remarks
- * It is vendored like every other host artifact but claimed by presence rather
- * than content, so a consumer's own edits to the file survive every verb and
- * only the catalog verb rewrites the region inside the markers.
+ * A plan claims it at a canon path, because the catalog verb refuses a target
+ * that lacks the file. `nameToHostArtifacts` appends it to the vendored
+ * selection, and it reaches a release through the `.claude/agents` directory in
+ * {@link CANON_PATHS} rather than through {@link HOST_PATHS}, which is what
+ * keeps the two lists disjoint.
+ *
+ * It is claimed by presence rather than content, so a consumer's own edits to
+ * the file survive every verb and only the catalog verb rewrites the region
+ * inside the markers.
  */
 export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
 
@@ -1485,18 +1541,24 @@ export declare class Compiler implements CompilerInterface {
        export declare const HOST_INVENTORY_PATH = "host.json";
 
        /**
-        * The paths byte-copied from the vendored data root, frozen.
+        * The paths a target receives from the vendored data root, frozen.
         *
         * @remarks
-        * These are the files the fleet shares verbatim: the root instruction
-        * documents, the licence, the canonical orchestration contract every harness
-        * bridge points at, the harness directories, the session hook scripts,
-        * the shared policy register, the byte-identical root dotfiles, and the
-        * guide mirrors a generated workspace starts from. A directory entry vendors
+        * These are the files the fleet shares verbatim and every target holds a copy
+        * of: the licence, the harness permission file, the session hook scripts, the
+        * shared policy register, the byte-identical root dotfiles, and the guide
+        * mirrors a generated workspace starts from. A directory entry vendors
         * everything beneath it.
         *
         * A plan carries the subset its target selects, which is why the list is a
         * candidate set rather than a plan: a workspace never mirrors its own guide.
+        *
+        * Neither the instruction canon nor the harness wiring is here. A target reads
+        * its rules, its skills, its agent roles, its bench configuration, and its MCP
+        * registrations from {@link CANON_PATHS} inside the installed package, so no
+        * file scaffold leaves in a target names a path the target does not hold.
+        * `nameToHostArtifacts` appends {@link CATALOG_AGENT_PATH} to what this list
+        * selects, which is what keeps the list itself disjoint from the canon.
         */
        export declare const HOST_PATHS: readonly string[];
 
@@ -1686,6 +1748,34 @@ export declare class Compiler implements CompilerInterface {
         */
        export declare const isBlueprint: Guard<Blueprint>;
 
+       /**
+        * Checks whether a path belongs to the instruction canon a target reads rather than holds.
+        *
+        * @param path - The target-relative path to test.
+        * @returns `true` for a {@link CANON_PATHS} member and for any path beneath a
+        * member that is a directory; `false` otherwise.
+        *
+        * @remarks
+        * The one reading of canon membership, so the live overlay and the executable's
+        * fetch list never disagree about what a path is. The match runs to a segment
+        * boundary, so a sibling whose name opens with a member's name —
+        * `.claude/rulesets` beside `.claude/rules` — stays outside.
+        *
+        * Membership answers where a path's bytes are staged, not whether a plan claims
+        * it. A plan claims `AGENTS.md`, `CLAUDE.md`, and {@link CATALOG_AGENT_PATH} at
+        * canon paths deliberately, so a consumer deciding whether to write, restore, or
+        * remove a path reads the plan rather than this predicate.
+        *
+        * @example
+        * ```ts
+        * import { isCanonPath } from '@orkestrel/scaffold'
+        *
+        * isCanonPath('.claude/rules/names.md') // true
+        * isCanonPath('.claude/settings.json') // false
+        * ```
+        */
+       export declare function isCanonPath(path: string): boolean;
+
        /**
         * Narrow a value to a {@link CatalogEntry}.
         *
@@ -2361,7 +2451,8 @@ export declare class Compiler implements CompilerInterface {
         * Compile the vendored host artifacts a named workspace plans.
         *
         * @param name - The target workspace's own bare package name.
-        * @returns One artifact per vendored path, in `HOST_PATHS` order.
+        * @returns One artifact per vendored path in `HOST_PATHS` order, then the
+        * catalog file.
         *
         * @remarks
         * Every artifact is claimed by presence, which is the strongest claim a pure
@@ -2375,11 +2466,21 @@ export declare class Compiler implements CompilerInterface {
         * are classified by one rule and a plan never disagrees with the audit beside
         * it.
         *
+        * {@link CATALOG_AGENT_PATH} is appended rather than listed, and it is the canon
+        * path this compiler claims. The catalog verb refuses a target that lacks the
+        * file, so the plan has to carry it; repair restores its absence from the
+        * staged bytes; and the `.claude/agents` directory in `CANON_PATHS` is what
+        * stages those bytes, so listing the file in `HOST_PATHS` as well would claim one
+        * storage name twice and refuse the stage. The rest of the canon a target reads
+        * from the installed package, at the locations the `AGENTS.md` and `CLAUDE.md`
+        * pointers {@link blueprintToDocumentArtifacts} emits name.
+        *
         * @example
         * ```ts
         * import { nameToHostArtifacts } from '@orkestrel/scaffold'
         *
-        * nameToHostArtifacts('router').some((artifact) => artifact.path === 'AGENTS.md') // true
+        * nameToHostArtifacts('router').some((artifact) => artifact.path === '.claude/settings.json') // true
+        * nameToHostArtifacts('router').some((artifact) => artifact.path === '.claude/agents/orkestrel.md') // true
         * nameToHostArtifacts('router').some((artifact) => artifact.path === 'guides/router.md') // false
         * ```
         */

package/dist/src/core/index.d.ts

@@ -108,6 +108,8 @@ export declare const ARTIFACT_TEMPLATES: Readonly<{
     }>;
     docs: Readonly<{
         readme: "# {{package}}\n\n{{description}}\n\n## Development\n\n```sh\nnpm install\nnpm test\n```\n";
+        agents: "# AGENTS.md\n\nThe `@orkestrel/scaffold` package is this repository's coding and orchestration authority. This\nfile points at it and states no law of its own.\n\nRead these before working: the `AGENTS.md` coding contract, the `.agents/orchestration.md`\nagent-operation contract, every applicable rule the contract's rule map names under\n`.claude/rules/`, and the dispatch-named skill under `.agents/skills/` with the references it\nrequires.\n\nResolve every one of those paths against scaffold, never against this repository:\n\n- When a scaffold checkout sits beside this repository, read `../scaffold/AGENTS.md`, the\n  `../scaffold/.agents/orchestration.md` file, the `../scaffold/.claude/rules/` directory, and\n  the `../scaffold/.agents/skills/` directory.\n- Otherwise read the installed copy, whose paths drop the dot that opens each segment: the\n  `node_modules/@orkestrel/scaffold/dist/host/AGENTS.md` file, the\n  `node_modules/@orkestrel/scaffold/dist/host/agents/orchestration.md` file, the\n  `node_modules/@orkestrel/scaffold/dist/host/claude/rules/` directory, and the\n  `node_modules/@orkestrel/scaffold/dist/host/agents/skills/` directory.\n\nEvery path a scaffold-supplied file names resolves the same way. The files this repository carries\n— the `.claude/agents/orkestrel.md` catalog file, the `.claude/settings.json` permission file,\nand the bench scripts under `scripts/` — are this repository's own copies and resolve here.\n\nEdit none of the scaffold-owned files here. The `scaffold repair` command restores them, so a\nchange to one is a commit in the scaffold repository followed by a release.\n";
+        claude: "# CLAUDE.md\n\nRead the `AGENTS.md` file in this repository first. It names the coding and orchestration\nauthority and where to read each contract.\n\nThis file imports nothing. An `@path` import inlines the imported file into every context that\nloads it, which is the cost this pointer removes.\n";
     }>;
     guides: Readonly<{
         readme: "# Guides\n\n## By concept\n\n- Package\n  - Spec: Not created. Create this file when the workspace has a public surface:\n    `guides/{{guide}}.md`\n  - Source:\n{{source}}\n  - Tests:\n{{tests}}\n\n## By directory\n\n{{directories}}\n";
@@ -343,7 +345,22 @@ export declare function blueprintToDevDependencies(blueprint: Blueprint): Readon
  * Compile the generated workspace's root documentation.
  *
  * @param blueprint - The workspace specification.
- * @returns One birth-owned package front page.
+ * @returns The birth-owned package front page and the content-owned `AGENTS.md`
+ * and `CLAUDE.md` pointers.
+ *
+ * @remarks
+ * The front page is the workspace's own prose, so it is written once and left
+ * alone from then on. The pointers are scaffold's, so they are content-owned and
+ * restored whenever they drift.
+ *
+ * A pointer is planned here rather than vendored because `stageHost` refuses two
+ * vendored paths at one storage name, and `AGENTS.md` and `CLAUDE.md` already
+ * store the canon a release ships. Planning them as this package's own content
+ * leaves each path with one claimant.
+ *
+ * Neither pointer carries a varying span, so neither is filled: a workspace's
+ * name never reaches the text, and the paths a reader follows are the same in
+ * every target.
  */
 export declare function blueprintToDocumentArtifacts(blueprint: Blueprint): readonly ContentArtifact[];
 
@@ -674,13 +691,52 @@ export declare type BuildFormat = 'es' | 'cjs';
  */
 export declare function bytesToHex(bytes: Uint8Array): string;
 
+/**
+ * The instruction-canon paths staged for reading rather than for a target, frozen.
+ *
+ * @remarks
+ * The root instruction documents, the orchestration contract every harness
+ * bridge points at, the rule map's rules, the skills, the templates, the
+ * transport contracts, the agent roles each harness dispatches, the bench
+ * configuration, and the MCP registrations. A directory entry covers everything
+ * beneath it.
+ *
+ * Staging walks these beside {@link HOST_PATHS}, so a release ships them and a
+ * reader reaches them two ways: a scaffold checkout sitting beside the
+ * repository, or the `node_modules/@orkestrel/scaffold/dist/host/` root inside
+ * the installed package. The `AGENTS.md` and `CLAUDE.md` pointers scaffold plans
+ * are what name each location.
+ *
+ * The lists are disjoint by prefix in either direction: no member of either
+ * equals or sits beneath a member of the other. Staging depends on that, because
+ * the walk covers the union and a path it discovers twice claims one storage
+ * name twice, which refuses the stage.
+ *
+ * The plan claims paths inside the canon deliberately, and each has a reason.
+ * `blueprintToDocumentArtifacts` claims `AGENTS.md` and `CLAUDE.md` as this
+ * package's own template pointers. `nameToHostArtifacts` claims
+ * {@link CATALOG_AGENT_PATH}, because the catalog verb refuses a target that
+ * lacks the file and repair restores its absence.
+ *
+ * A target therefore holds a file at a canon path only where the plan claims it.
+ * That is the rule every verb obeys, and it is what makes a copy found anywhere
+ * else superseded.
+ */
+export declare const CANON_PATHS: readonly string[];
+
 /**
  * The agent file whose marker-bounded package table the catalog verb alone owns.
  *
  * @remarks
- * It is vendored like every other host artifact but claimed by presence rather
- * than content, so a consumer's own edits to the file survive every verb and
- * only the catalog verb rewrites the region inside the markers.
+ * A plan claims it at a canon path, because the catalog verb refuses a target
+ * that lacks the file. `nameToHostArtifacts` appends it to the vendored
+ * selection, and it reaches a release through the `.claude/agents` directory in
+ * {@link CANON_PATHS} rather than through {@link HOST_PATHS}, which is what
+ * keeps the two lists disjoint.
+ *
+ * It is claimed by presence rather than content, so a consumer's own edits to
+ * the file survive every verb and only the catalog verb rewrites the region
+ * inside the markers.
  */
 export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
 
@@ -1485,18 +1541,24 @@ export declare class Compiler implements CompilerInterface {
        export declare const HOST_INVENTORY_PATH = "host.json";
 
        /**
-        * The paths byte-copied from the vendored data root, frozen.
+        * The paths a target receives from the vendored data root, frozen.
         *
         * @remarks
-        * These are the files the fleet shares verbatim: the root instruction
-        * documents, the licence, the canonical orchestration contract every harness
-        * bridge points at, the harness directories, the session hook scripts,
-        * the shared policy register, the byte-identical root dotfiles, and the
-        * guide mirrors a generated workspace starts from. A directory entry vendors
+        * These are the files the fleet shares verbatim and every target holds a copy
+        * of: the licence, the harness permission file, the session hook scripts, the
+        * shared policy register, the byte-identical root dotfiles, and the guide
+        * mirrors a generated workspace starts from. A directory entry vendors
         * everything beneath it.
         *
         * A plan carries the subset its target selects, which is why the list is a
         * candidate set rather than a plan: a workspace never mirrors its own guide.
+        *
+        * Neither the instruction canon nor the harness wiring is here. A target reads
+        * its rules, its skills, its agent roles, its bench configuration, and its MCP
+        * registrations from {@link CANON_PATHS} inside the installed package, so no
+        * file scaffold leaves in a target names a path the target does not hold.
+        * `nameToHostArtifacts` appends {@link CATALOG_AGENT_PATH} to what this list
+        * selects, which is what keeps the list itself disjoint from the canon.
         */
        export declare const HOST_PATHS: readonly string[];
 
@@ -1686,6 +1748,34 @@ export declare class Compiler implements CompilerInterface {
         */
        export declare const isBlueprint: Guard<Blueprint>;
 
+       /**
+        * Checks whether a path belongs to the instruction canon a target reads rather than holds.
+        *
+        * @param path - The target-relative path to test.
+        * @returns `true` for a {@link CANON_PATHS} member and for any path beneath a
+        * member that is a directory; `false` otherwise.
+        *
+        * @remarks
+        * The one reading of canon membership, so the live overlay and the executable's
+        * fetch list never disagree about what a path is. The match runs to a segment
+        * boundary, so a sibling whose name opens with a member's name —
+        * `.claude/rulesets` beside `.claude/rules` — stays outside.
+        *
+        * Membership answers where a path's bytes are staged, not whether a plan claims
+        * it. A plan claims `AGENTS.md`, `CLAUDE.md`, and {@link CATALOG_AGENT_PATH} at
+        * canon paths deliberately, so a consumer deciding whether to write, restore, or
+        * remove a path reads the plan rather than this predicate.
+        *
+        * @example
+        * ```ts
+        * import { isCanonPath } from '@orkestrel/scaffold'
+        *
+        * isCanonPath('.claude/rules/names.md') // true
+        * isCanonPath('.claude/settings.json') // false
+        * ```
+        */
+       export declare function isCanonPath(path: string): boolean;
+
        /**
         * Narrow a value to a {@link CatalogEntry}.
         *
@@ -2361,7 +2451,8 @@ export declare class Compiler implements CompilerInterface {
         * Compile the vendored host artifacts a named workspace plans.
         *
         * @param name - The target workspace's own bare package name.
-        * @returns One artifact per vendored path, in `HOST_PATHS` order.
+        * @returns One artifact per vendored path in `HOST_PATHS` order, then the
+        * catalog file.
         *
         * @remarks
         * Every artifact is claimed by presence, which is the strongest claim a pure
@@ -2375,11 +2466,21 @@ export declare class Compiler implements CompilerInterface {
         * are classified by one rule and a plan never disagrees with the audit beside
         * it.
         *
+        * {@link CATALOG_AGENT_PATH} is appended rather than listed, and it is the canon
+        * path this compiler claims. The catalog verb refuses a target that lacks the
+        * file, so the plan has to carry it; repair restores its absence from the
+        * staged bytes; and the `.claude/agents` directory in `CANON_PATHS` is what
+        * stages those bytes, so listing the file in `HOST_PATHS` as well would claim one
+        * storage name twice and refuse the stage. The rest of the canon a target reads
+        * from the installed package, at the locations the `AGENTS.md` and `CLAUDE.md`
+        * pointers {@link blueprintToDocumentArtifacts} emits name.
+        *
         * @example
         * ```ts
         * import { nameToHostArtifacts } from '@orkestrel/scaffold'
         *
-        * nameToHostArtifacts('router').some((artifact) => artifact.path === 'AGENTS.md') // true
+        * nameToHostArtifacts('router').some((artifact) => artifact.path === '.claude/settings.json') // true
+        * nameToHostArtifacts('router').some((artifact) => artifact.path === '.claude/agents/orkestrel.md') // true
         * nameToHostArtifacts('router').some((artifact) => artifact.path === 'guides/router.md') // false
         * ```
         */