@orkestrel/scaffold 0.0.55 → 0.0.56

package/dist/src/core/index.js

@@ -3,7 +3,7 @@ import { fillTemplate } from "@orkestrel/template";
 import { Emitter } from "@orkestrel/emitter";
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.55",
+	version: "0.0.56",
 	description: "Scaffold workspaces with five commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -205,36 +205,28 @@ var BIN_CONFIGS = Object.freeze(["configs/src/vite.bin.config.ts", "configs/src/
 /** The executable entry whose presence makes a workspace `bin`. */
 var BIN_ENTRY_PATH = "src/bin/main.ts";
 /**
-* 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.
 */
 var HOST_PATHS = Object.freeze([
-	"AGENTS.md",
-	"CLAUDE.md",
 	"LICENSE",
-	".agents/orchestration.md",
-	".agents/skills",
-	".agents/templates",
-	".agents/transports",
-	".claude/agents",
-	".claude/rules",
-	".claude/skills",
 	".claude/settings.json",
-	".codex/agents",
-	".codex/config.toml",
-	".cursor/mcp.json",
-	".cursor/rules",
-	".mcp.json",
 	"scripts/deps.sh",
 	"scripts/cursor.sh",
 	"scripts/codex.sh",
@@ -254,6 +246,53 @@ var HOST_PATHS = Object.freeze([
 	"guides/guide.md",
 	"guides/scaffold.md"
 ]);
+/**
+* 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.
+*/
+var CANON_PATHS = Object.freeze([
+	"AGENTS.md",
+	"CLAUDE.md",
+	".mcp.json",
+	".agents/orchestration.md",
+	".agents/skills",
+	".agents/templates",
+	".agents/transports",
+	".claude/agents",
+	".claude/rules",
+	".claude/skills",
+	".codex/agents",
+	".codex/config.toml",
+	".cursor/mcp.json",
+	".cursor/rules"
+]);
 /** The repository-relative path where the committed vendored-file inventory is served. */
 var HOST_INVENTORY_PATH = "host.json";
 /**
@@ -315,9 +354,15 @@ var ORCHESTRATION_PATH_NAMES = Object.freeze([".mcp.json"]);
 * 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.
 */
 var CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
 /** The provisioner skeleton a workspace with declared service vendors is given once. */
@@ -2507,7 +2552,8 @@ describe('workspace integration', () => {
 })
 `
 	}),
-	docs: Object.freeze({ readme: `# {{package}}
+	docs: Object.freeze({
+		readme: `# {{package}}
 
 {{description}}
 
@@ -2517,7 +2563,44 @@ describe('workspace integration', () => {
 npm install
 npm test
 \`\`\`
-` }),
+`,
+		agents: `# AGENTS.md
+
+The \`@orkestrel/scaffold\` package is this repository's coding and orchestration authority. This
+file points at it and states no law of its own.
+
+Read these before working: the \`AGENTS.md\` coding contract, the \`.agents/orchestration.md\`
+agent-operation contract, every applicable rule the contract's rule map names under
+\`.claude/rules/\`, and the dispatch-named skill under \`.agents/skills/\` with the references it
+requires.
+
+Resolve every one of those paths against scaffold, never against this repository:
+
+- When a scaffold checkout sits beside this repository, read \`../scaffold/AGENTS.md\`, the
+  \`../scaffold/.agents/orchestration.md\` file, the \`../scaffold/.claude/rules/\` directory, and
+  the \`../scaffold/.agents/skills/\` directory.
+- Otherwise read the installed copy, whose paths drop the dot that opens each segment: the
+  \`node_modules/@orkestrel/scaffold/dist/host/AGENTS.md\` file, the
+  \`node_modules/@orkestrel/scaffold/dist/host/agents/orchestration.md\` file, the
+  \`node_modules/@orkestrel/scaffold/dist/host/claude/rules/\` directory, and the
+  \`node_modules/@orkestrel/scaffold/dist/host/agents/skills/\` directory.
+
+Every path a scaffold-supplied file names resolves the same way. The files this repository carries
+— the \`.claude/agents/orkestrel.md\` catalog file, the \`.claude/settings.json\` permission file,
+and the bench scripts under \`scripts/\` — are this repository's own copies and resolve here.
+
+Edit none of the scaffold-owned files here. The \`scaffold repair\` command restores them, so a
+change to one is a commit in the scaffold repository followed by a release.
+`,
+		claude: `# CLAUDE.md
+
+Read the \`AGENTS.md\` file in this repository first. It names the coding and orchestration
+authority and where to read each contract.
+
+This file imports nothing. An \`@path\` import inlines the imported file into every context that
+loads it, which is the cost this pointer removes.
+`
+	}),
 	guides: Object.freeze({ readme: `# Guides
 
 ## By concept
@@ -3374,6 +3457,35 @@ function isDeferredPath(path) {
 	return path === ".claude/agents/orkestrel.md" || path.startsWith("guides/") && path.endsWith(".md");
 }
 /**
+* 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
+* ```
+*/
+function isCanonPath(path) {
+	return CANON_PATHS.some((canon) => path === canon || path.startsWith(`${canon}/`));
+}
+/**
 * Infer the {@link Group} a path belongs to.
 *
 * @param path - The target-relative path to classify.
@@ -5136,22 +5248,53 @@ function blueprintToGuideArtifacts(blueprint) {
 * 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.
 */
 function blueprintToDocumentArtifacts(blueprint) {
 	const publishes = blueprint.src.length > 0;
 	const name = publishes ? `@orkestrel/${blueprint.name}` : blueprint.name;
 	const description = blueprint.description ?? (publishes ? `The ${name} package.` : `The ${name} application.`);
-	return [{
-		path: "README.md",
-		group: "docs",
-		ownership: "birth",
-		origin: "template",
-		content: fillTemplate(ARTIFACT_TEMPLATES.docs.readme, {
-			package: name,
-			description
-		})
-	}];
+	return [
+		{
+			path: "README.md",
+			group: "docs",
+			ownership: "birth",
+			origin: "template",
+			content: fillTemplate(ARTIFACT_TEMPLATES.docs.readme, {
+				package: name,
+				description
+			})
+		},
+		{
+			path: "AGENTS.md",
+			group: "docs",
+			ownership: "content",
+			origin: "template",
+			content: ARTIFACT_TEMPLATES.docs.agents
+		},
+		{
+			path: "CLAUDE.md",
+			group: "docs",
+			ownership: "content",
+			origin: "template",
+			content: ARTIFACT_TEMPLATES.docs.claude
+		}
+	];
 }
 /**
 * Compile the blueprint-dependent orchestration artifacts.
@@ -5179,7 +5322,8 @@ function blueprintToOrchestrationArtifacts(blueprint) {
 * 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
@@ -5193,16 +5337,26 @@ function blueprintToOrchestrationArtifacts(blueprint) {
 * 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
 * ```
 */
 function nameToHostArtifacts(name) {
-	return selectHostPaths(HOST_PATHS, name).map((path) => ({
+	return [...selectHostPaths(HOST_PATHS, name), CATALOG_AGENT_PATH].map((path) => ({
 		path,
 		group: inferGroup(path),
 		ownership: "presence",
@@ -6526,6 +6680,6 @@ var Compiler = class {
 	}
 };
 //#endregion
-export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONFORMANCE_TEST_PATH, CONTROL_CHARACTER_PATTERN, Compiler, DECLARATION_DEV_DEPENDENCIES, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_RANGE_PATTERN, FLOOR_RANGE_PATTERN, FOREIGN_NAME_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_INVENTORY_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MANIFEST_PATH, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_SCRIPT_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, PRINT_WIDTH, RELEASE_PROOF_COMMAND, SERVICE_SCRIPT_PATH, SERVICE_SETUP_PATH, SERVICE_TEST_INCLUDE, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, TAB_WIDTH, VERSION_PATTERN, WORKSPACE_OWNED_PATHS, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, blueprintToWritableScripts, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, dependenciesToQuestions, extractRangeMajor, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDeferredPath, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isManifestScript, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesPrintWidth, matchesRange, nameToGuide, nameToHostArtifacts, nameToRewrite, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, replaceManifestRanges, replaceManifestScripts, replacePlanRanges, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
+export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CANON_PATHS, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONFORMANCE_TEST_PATH, CONTROL_CHARACTER_PATTERN, Compiler, DECLARATION_DEV_DEPENDENCIES, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_RANGE_PATTERN, FLOOR_RANGE_PATTERN, FOREIGN_NAME_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_INVENTORY_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MANIFEST_PATH, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_SCRIPT_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, PRINT_WIDTH, RELEASE_PROOF_COMMAND, SERVICE_SCRIPT_PATH, SERVICE_SETUP_PATH, SERVICE_TEST_INCLUDE, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, TAB_WIDTH, VERSION_PATTERN, WORKSPACE_OWNED_PATHS, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, blueprintToWritableScripts, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, dependenciesToQuestions, extractRangeMajor, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCanonPath, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDeferredPath, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isManifestScript, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesPrintWidth, matchesRange, nameToGuide, nameToHostArtifacts, nameToRewrite, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, replaceManifestRanges, replaceManifestScripts, replacePlanRanges, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
 
 //# sourceMappingURL=index.js.map