@orkestrel/scaffold 0.0.55 → 0.0.56

package/dist/host/tests/policy.test.ts

@@ -1,7 +1,10 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
 	BRIDGE_POLICY_CONTROLS,
 	createPolicyScratch,
+	createSkillMetadata,
 	FUNCTION_SOURCE_FILES,
 	GENERIC_POLICY_SOURCES,
 	inspectPolicyControl,
@@ -23,6 +26,8 @@ import {
 	readPolicyPaths,
 	readSkillFamily,
 	RULES_POLICY_CONTROLS,
+	SKILL_BRIDGE_ROOT,
+	SKILL_FAMILY_ROOT,
 	SKILL_POLICY_APOSTROPHE,
 	SKILL_POLICY_BACKTICKED,
 	SKILL_POLICY_CONTROLS,
@@ -30,6 +35,7 @@ import {
 	SKILL_POLICY_FENCED,
 	SKILL_POLICY_FOLDED,
 	SKILL_POLICY_PARAGRAPHS,
+	SKILL_POLICY_TEXT,
 	stemToPolicyCandidates,
 	testToPolicyStem,
 } from './setupPolicy.js'
@@ -345,10 +351,29 @@ describe('instrument negative controls', () => {
 })
 
 describe('skill family policy', () => {
-	it('discovers a non-empty family containing orkestrel-falsify', () => {
+	// The family is read from the workspace it runs in, so a membership literal would
+	// bind this file to one workspace. The relationship binds in every workspace: a
+	// direct `node:fs` read of the canonical root is a second mechanism that reports
+	// the same directories, and reports none where the root is absent.
+	//
+	// The root is spelled here as literal segments rather than read from
+	// `SKILL_FAMILY_ROOT`, and that literal is what makes this read a second
+	// mechanism. Both sides reading the constant would move together when it drifts,
+	// so the case would stay green for every value the constant ever holds. Against
+	// the literal, a drifted constant desyncs the sides and reddens this case in a
+	// workspace that has the tree, while a workspace without one still passes on
+	// both readings being empty.
+	it('discovers exactly the directories the canonical skill root holds', () => {
+		const root = join(process.cwd(), '.agents', 'skills')
+		const held = existsSync(root)
+			? readdirSync(root, { withFileTypes: true })
+					.filter((entry) => entry.isDirectory())
+					.map((entry) => entry.name)
+					.sort()
+			: []
 		const family = readSkillFamily(process.cwd())
-		expect(family.length).toBeGreaterThan(0)
-		expect(family).toContain('orkestrel-falsify')
+		expect(family.length > 0).toBe(held.length > 0)
+		expect([...family]).toEqual(held)
 	})
 
 	it('requires every discovered skill file, metadata token, and reference', () => {
@@ -490,10 +515,52 @@ describe('repository policy', () => {
 		expect(inspectPolicyWorkspace(process.cwd())).toEqual([])
 	})
 
+	// A target reads the canon from the installed package, so its tree carries the
+	// pointer pair and no `.agents/` directory, no rule map, and no skill bridges.
+	// This vendored suite runs there, and every inspector it routes through has to
+	// stay silent on that shape.
+	it('accepts a target holding the pointer pair and no canon tree', () => {
+		const scratch = createPolicyScratch({ prefix: 'orkestrel-policy-pointer-' })
+		try {
+			scratch.write(
+				'AGENTS.md',
+				'# AGENTS.md\n\nRead `node_modules/@orkestrel/scaffold/dist/host/AGENTS.md` for the canon.\n',
+			)
+			scratch.write(
+				'CLAUDE.md',
+				'# Claude Code bridge\n\nRead the `AGENTS.md` file beside this one first.\n',
+			)
+			scratch.write('.claude/settings.json', '{\n\t"permissions": {\n\t\t"allow": []\n\t}\n}\n')
+			scratch.write(
+				'.claude/agents/orkestrel.md',
+				'# Orkestrel\n\nThe agent carrying the package catalog.\n',
+			)
+			scratch.write(
+				'package.json',
+				'{\n\t"name": "target",\n\t"private": true,\n\t"scripts": {\n\t\t"test": "vitest run"\n\t}\n}\n',
+			)
+			expect(inspectPolicyWorkspace(scratch.path)).toEqual([])
+			// The control: the same workspace with one canonical skill planted and no
+			// bridge beside it reports the twin violation, so the empty result above is a
+			// sweep that ran rather than a sweep with nothing it could report.
+			scratch.write(`${SKILL_FAMILY_ROOT}/sample/SKILL.md`, SKILL_POLICY_TEXT)
+			scratch.write(`${SKILL_FAMILY_ROOT}/sample/agents/openai.yaml`, createSkillMetadata('sample'))
+			expect(inspectPolicyWorkspace(scratch.path)).toEqual([
+				{
+					rule: 'bridge',
+					path: `${SKILL_BRIDGE_ROOT}/sample`,
+					message: 'canonical skill has a matching provider bridge directory',
+				},
+			])
+		} finally {
+			scratch.destroy()
+		}
+	})
+
 	it('reaches every branch of the workspace-authored path population', () => {
 		const paths = readPolicyPaths(process.cwd())
 		expect(paths).toContain('tests/setupPolicy.ts')
-		expect(paths).toContain('.claude/rules/names.md')
+		expect(paths).toContain('.claude/settings.json')
 		expect(paths).toContain('package.json')
 		expect(paths).toContain('.gitattributes')
 	})

package/dist/src/core/index.cjs

@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
 let _orkestrel_emitter = require("@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",
@@ -206,36 +206,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",
@@ -255,6 +247,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";
 /**
@@ -316,9 +355,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. */
@@ -2508,7 +2553,8 @@ describe('workspace integration', () => {
 })
 `
 	}),
-	docs: Object.freeze({ readme: `# {{package}}
+	docs: Object.freeze({
+		readme: `# {{package}}
 
 {{description}}
 
@@ -2518,7 +2564,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
@@ -3375,6 +3458,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.
@@ -5137,22 +5249,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: (0, _orkestrel_template.fillTemplate)(ARTIFACT_TEMPLATES.docs.readme, {
-			package: name,
-			description
-		})
-	}];
+	return [
+		{
+			path: "README.md",
+			group: "docs",
+			ownership: "birth",
+			origin: "template",
+			content: (0, _orkestrel_template.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.
@@ -5180,7 +5323,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
@@ -5194,16 +5338,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",
@@ -6535,6 +6689,7 @@ exports.ARTIFACT_TEMPLATES = ARTIFACT_TEMPLATES;
 exports.BASE_DEV_DEPENDENCIES = BASE_DEV_DEPENDENCIES;
 exports.BIN_CONFIGS = BIN_CONFIGS;
 exports.BIN_ENTRY_PATH = BIN_ENTRY_PATH;
+exports.CANON_PATHS = CANON_PATHS;
 exports.CATALOG_AGENT_PATH = CATALOG_AGENT_PATH;
 exports.CONFIG_TEMPLATES = CONFIG_TEMPLATES;
 exports.CONFORMANCE_TEST_PATH = CONFORMANCE_TEST_PATH;
@@ -6625,6 +6780,7 @@ exports.inferGroup = inferGroup;
 exports.isArtifact = isArtifact;
 exports.isAudit = isAudit;
 exports.isBlueprint = isBlueprint;
+exports.isCanonPath = isCanonPath;
 exports.isCatalogEntry = isCatalogEntry;
 exports.isCollection = isCollection;
 exports.isCompilerHooks = isCompilerHooks;