dorfl 0.14.1 → 0.14.3

package/src/install-ci-core.ts

@@ -25,10 +25,21 @@
  * `DORFL_*` env block, NOT a new config knob minted here.
  */
 
-import {readFileSync, writeFileSync, mkdirSync, readdirSync} from 'node:fs';
+import {
+	readFileSync,
+	writeFileSync,
+	mkdirSync,
+	readdirSync,
+	existsSync,
+} from 'node:fs';
 import {dirname, join, relative} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import type {HarnessAdapter} from './config.js';
+import {
+	ACTION_PINS,
+	pinnedUses,
+	preserveExistingPins,
+} from './install-ci-action-pins.js';
 
 // ─── Config model ──────────────────────────────────────────────────────────
 
@@ -141,6 +152,44 @@ export interface ResolvedCIConfig {
 	projectSetup?: Record<string, unknown>;
 	/** See {@link CIConfigFile.maxParallel}. Always resolved (default applied). */
 	maxParallel: number;
+	/**
+	 * The repo's visibility, DETECTED at generation time through the provider
+	 * seam ({@link CIProviderContext.getRepoVisibility}); never read from or
+	 * written to a config file (it is a fact about the repo, not a choice).
+	 * `undefined` ⇒ unknown, which keeps the conservative output. See
+	 * {@link shouldDropCheckoutCredentials}.
+	 */
+	repoVisibility?: RepoVisibility;
+}
+
+/**
+ * A repository's visibility on its CI provider. Used ONLY to decide whether the
+ * read-only jobs (verify, close-job) may check out with
+ * `persist-credentials: false`: on a PUBLIC repo every git read works without a
+ * token, so dropping the persisted token cannot break a fetch; on a private or
+ * internal repo (or when visibility is unknown) a fetch may need it.
+ */
+export type RepoVisibility = 'public' | 'private' | 'internal';
+
+/** Parse a provider's visibility answer (`PUBLIC`, `private`, ...); unknown ⇒ `undefined`. */
+export function parseRepoVisibility(raw: string): RepoVisibility | undefined {
+	const v = raw.trim().toLowerCase();
+	return v === 'public' || v === 'private' || v === 'internal' ? v : undefined;
+}
+
+/**
+ * Whether the read-only jobs (verify, close-job) should check out with
+ * `persist-credentials: false`. True ONLY when the repo is KNOWN to be public:
+ * then the persisted token adds nothing a git read needs (those jobs have
+ * `contents: read`, so they cannot push either way), while leaving it in
+ * `.git/config` hands it to every later step, including the project-setup
+ * hook's dependency installs. Unknown or non-public ⇒ keep today's checkout, so
+ * a project gate that runs `git fetch` on a private repo keeps working.
+ */
+export function shouldDropCheckoutCredentials(
+	config: Pick<ResolvedCIConfig, 'repoVisibility'>,
+): boolean {
+	return config.repoVisibility === 'public';
 }
 
 /** The default harness the composite setup action installs. */
@@ -222,6 +271,13 @@ export interface CIProviderContext {
 	 * no default-branch concept.
 	 */
 	getDefaultBranch?(): Promise<string | undefined>;
+	/**
+	 * OPTIONALLY report the repo's VISIBILITY (GitHub:
+	 * `gh repo view --json visibility`). Read-only. Returns `undefined` when the
+	 * lookup fails; absent on a provider with no such concept. Drives
+	 * {@link shouldDropCheckoutCredentials}.
+	 */
+	getRepoVisibility?(): Promise<RepoVisibility | undefined>;
 	/**
 	 * OPTIONALLY create/replace a branch RULESET (GitHub:
 	 * `POST /repos/{owner}/{repo}/rulesets`) carrying the deadlock-guard
@@ -673,6 +729,75 @@ function indent(text: string, spaces: number): string {
 		.join('\n');
 }
 
+/**
+ * The npm package the composite setup action installs for the `pi` harness.
+ *
+ * Upstream moved the harness from `@mariozechner/pi-coding-agent` (deprecated,
+ * frozen at 0.73.1) to this name. The binary is still `pi` and it still reads
+ * `~/.pi/agent/` (models.json / auth.json), so nothing else in the generated
+ * action changes.
+ */
+export const PI_HARNESS_PACKAGE = '@earendil-works/pi-coding-agent';
+
+/**
+ * The EXACT `pi` harness version the composite setup action installs.
+ *
+ * Pinned because the install runs in jobs that hold `contents: write` and a
+ * provider API key: an unpinned `npm install -g` resolves whatever `latest` is
+ * at RUN time, so a compromised or broken release would reach those
+ * credentials with no review and no lockfile to catch it.
+ *
+ * It is a constant dorfl DECLARES (not an install-ci parameter) because the
+ * harness is coupled to dorfl, not to the consumer: dorfl drives `pi` through
+ * its CLI flags and reads its session files (`session-path.ts`,
+ * `watch-session.ts`), so the harness version that works is a property of the
+ * dorfl release. Bump it here, with a changeset, when a dorfl release needs a
+ * newer harness; every consumer picks it up on their next `install-ci` run.
+ *
+ * 0.80.6 is the version dorfl is exercised against day to day (the maintainer's
+ * installed `pi`), not the newest release: a harness upgrade should be a
+ * deliberate, tested bump. It requires Node >= 22.19.0, which the action's
+ * `node-version: '22'` satisfies (setup-node resolves the latest 22.x).
+ */
+export const PI_HARNESS_VERSION = '0.80.6';
+
+/**
+ * The version of THIS dorfl package, read at runtime from its own
+ * `package.json` (the single source changesets bumps on release). The composite
+ * setup action installs `dorfl@<this version>` so a consumer's CI runs the SAME
+ * CLI that generated its workflows, instead of whatever `latest` is at run time.
+ *
+ * Resolved relative to this module (`dist/install-ci-core.js` or
+ * `src/install-ci-core.ts` → `../package.json`), so it works from the built CLI
+ * and under tsx. Throws when the version cannot be read: silently falling back
+ * to an unpinned install would reintroduce exactly the risk the pin removes.
+ */
+export function dorflPackageVersion(): string {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const pkgPath = join(here, '..', 'package.json');
+	let version: unknown;
+	try {
+		version = (JSON.parse(readFileSync(pkgPath, 'utf8')) as {version?: unknown})
+			.version;
+	} catch (err) {
+		throw new Error(
+			`install-ci: cannot read dorfl's own version from ${pkgPath} ` +
+				`(needed to pin \`npm install -g dorfl@<version>\`): ` +
+				(err instanceof Error ? err.message : String(err)),
+		);
+	}
+	if (
+		typeof version !== 'string' ||
+		!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/.test(version)
+	) {
+		throw new Error(
+			`install-ci: dorfl's package.json at ${pkgPath} has no usable semver ` +
+				`"version" (got ${JSON.stringify(version)}); cannot pin the CI install.`,
+		);
+	}
+	return version;
+}
+
 /**
  * The install step for the configured harness (the `pi` CLI; `''` ⇒ none).
  * `registry` mode installs via `npm install -g`; `workspace` mode installs via
@@ -684,11 +809,15 @@ function harnessInstallStep(
 	installSource: InstallSource,
 ): string {
 	if (harness === 'pi') {
+		const spec = `${PI_HARNESS_PACKAGE}@${PI_HARNESS_VERSION}`;
 		const run =
 			installSource === 'workspace'
-				? 'pnpm add -g @mariozechner/pi-coding-agent'
-				: 'npm install -g @mariozechner/pi-coding-agent';
+				? `pnpm add -g ${spec}`
+				: `npm install -g ${spec}`;
 		return `
+    # Pinned to the exact harness version this dorfl release declares
+    # (PI_HARNESS_VERSION): the job holds write access and a provider key, so the
+    # version must not move on its own. Re-run \`dorfl install-ci\` to upgrade.
     - name: Install agent harness (pi)
       shell: bash
       run: ${run}`;
@@ -807,7 +936,7 @@ ${indent(modelsJsonStr, 8)}
 	if (config.installSource === 'workspace') {
 		installSteps = `\
     - name: Setup pnpm
-      uses: pnpm/action-setup@v5
+      uses: ${pinnedUses(ACTION_PINS.pnpmSetup)}
 
     - name: Add pnpm global bin to PATH
       shell: bash
@@ -815,17 +944,25 @@ ${indent(modelsJsonStr, 8)}
         pnpm setup
         echo "$HOME/.local/share/pnpm" >> "$GITHUB_PATH"
 
+    # \`--ignore-scripts\`: nothing here needs an install-time script. The build is
+    # explicit (\`pnpm -r build\` below; the root \`prepare\` would only repeat it),
+    # and verify runs on fork pull requests, where a lifecycle script would run
+    # the fork's code before any gate does.
     - name: Install dependencies and build dorfl
       shell: bash
       run: |
-        pnpm install
+        pnpm install --ignore-scripts
         pnpm -r build
         cd packages/dorfl && pnpm link --global${installHarness}`;
 	} else {
 		installSteps = `\
+    # Pinned to the dorfl version that generated this action, so CI runs the
+    # same CLI that wrote these workflows (and never an unreviewed \`latest\` in a
+    # job holding write access and a provider key). Re-run \`dorfl install-ci\`
+    # after upgrading dorfl to move the pin.
     - name: Install dorfl
       shell: bash
-      run: npm install -g dorfl${installHarness}`;
+      run: npm install -g dorfl@${dorflPackageVersion()}${installHarness}`;
 	}
 
 	// NO bespoke CI resolver shim (task install-ci-shim-converges-on-dorfl-cmd,
@@ -895,15 +1032,16 @@ runs:
   using: composite
   steps:
 ${projectSetupBlock}    - name: Setup Node.js
-      uses: actions/setup-node@v5
+      uses: ${pinnedUses(ACTION_PINS.setupNode)}
       with:
         node-version: '22'
-        # setup-node@v5 auto-enables package-manager caching, which probes the
-        # project package manager DURING its own run when a lockfile is present,
-        # before that manager is on PATH, so the probe crashes ("Unable to
-        # locate executable file"). dorfl provisions ONLY its own runtime and
-        # leaves the project package-manager cache to the project (toolchain
-        # boundary), so disable it explicitly.
+        # setup-node (v5 and later) auto-enables package-manager caching. In v5
+        # it probed whatever manager package.json's packageManager named, during
+        # its own run and before that manager was on PATH, and crashed ("Unable
+        # to locate executable file"). Since v6 it only fires when package.json
+        # declares npm, and then fails if there is no npm lockfile. Either way
+        # it is the project's cache, not dorfl's: dorfl provisions ONLY its own
+        # runtime (toolchain boundary), so disable it explicitly.
         package-manager-cache: false
 
     - name: Configure git identity
@@ -1069,6 +1207,13 @@ export function outputBaseName(fake: boolean): string {
  * Write the artifacts under `<workDir>/<base>/` (base = `.fake` when `fake`, else
  * `.github`). Returns the repo-relative paths actually written. Pure filesystem
  * I/O — no secrets, no git. Creates parent dirs as needed.
+ *
+ * PIN PRESERVATION. Before writing a YAML artifact, any `uses:` of an action the
+ * repository's EXISTING `.github/<path>` already pins to a full commit SHA keeps
+ * that reference and its trailing comment (see {@link preserveExistingPins}),
+ * so a Dependabot bump survives regeneration and a pin is never swapped for a
+ * tag. The existing file is always read from `.github/`, also in `--fake` mode,
+ * so the `.fake/` preview shows what a real run would write.
  */
 export function writeArtifacts(options: {
 	workDir: string;
@@ -1079,8 +1224,15 @@ export function writeArtifacts(options: {
 	const written: string[] = [];
 	for (const file of options.files) {
 		const abs = join(options.workDir, base, file.path);
+		let content = file.content;
+		if (/\.ya?ml$/.test(file.path)) {
+			const current = join(options.workDir, outputBaseName(false), file.path);
+			if (existsSync(current)) {
+				content = preserveExistingPins(content, readFileSync(current, 'utf8'));
+			}
+		}
 		mkdirSync(dirname(abs), {recursive: true});
-		writeFileSync(abs, file.content, 'utf8');
+		writeFileSync(abs, content, 'utf8');
 		written.push(relative(options.workDir, abs));
 	}
 	return written;

package/src/install-ci-github.ts

@@ -16,7 +16,11 @@
 
 import {run, type RunResult} from './git.js';
 import {DEFAULT_GH_BIN} from './github.js';
-import type {CIProviderContext} from './install-ci-core.js';
+import {
+	parseRepoVisibility,
+	type CIProviderContext,
+	type RepoVisibility,
+} from './install-ci-core.js';
 
 /**
  * The provider id this adapter exposes through {@link CIProviderContext.providerId}.
@@ -265,6 +269,32 @@ export class GitHubCIContext implements CIProviderContext {
 		return name === '' ? undefined : name;
 	}
 
+	/**
+	 * Detect the repo's VISIBILITY via
+	 * `gh repo view --json visibility --jq .visibility` (GitHub answers
+	 * `PUBLIC` / `PRIVATE` / `INTERNAL`). Returns `undefined` when `gh` is
+	 * unavailable / the repo is unknown / the call fails / the answer is not one
+	 * of those three, so the caller keeps the conservative (credential-persisting)
+	 * checkout. Read-only.
+	 */
+	async getRepoVisibility(): Promise<RepoVisibility | undefined> {
+		if (!this.repo) {
+			return undefined;
+		}
+		const result = this.runGh([
+			'repo',
+			'view',
+			'--json',
+			'visibility',
+			'--jq',
+			'.visibility',
+		]);
+		if (result === undefined || result.status !== 0) {
+			return undefined;
+		}
+		return parseRepoVisibility(result.stdout);
+	}
+
 	/**
 	 * Create the deadlock-guard RULESET via
 	 * `POST /repos/{owner}/{repo}/rulesets`. The `ruleset` body is JSON-piped on
@@ -388,6 +418,8 @@ export class MemoryCIProviderContext implements CIProviderContext {
 	private readonly adminScope: boolean | undefined;
 	/** What `getDefaultBranch()` should return (tests configure). */
 	private readonly defaultBranch: string | undefined;
+	/** What `getRepoVisibility()` should return (tests configure). */
+	private readonly visibility: RepoVisibility | undefined;
 	/** Whether `setBranchProtection` should throw (tests configure). */
 	private readonly branchProtectionError: string | undefined;
 	/** Whether `setBranchRuleset` should throw (tests configure). */
@@ -404,6 +436,8 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		 * exercises its `main` fallback (models a `gh` that could not resolve it).
 		 */
 		defaultBranch?: string;
+		/** Fixture repo visibility; `undefined` ⇒ unknown (lookup failed / no gh). */
+		visibility?: RepoVisibility;
 		/** When set, `setBranchProtection` throws with this message (failure path). */
 		branchProtectionError?: string;
 		/** When set, `setBranchRuleset` throws with this message (failure path). */
@@ -421,6 +455,7 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		this.ghAvailable = options.ghAvailable ?? false;
 		this.adminScope = options.adminScope;
 		this.defaultBranch = options.defaultBranch;
+		this.visibility = options.visibility;
 		this.branchProtectionError = options.branchProtectionError;
 		this.branchRulesetError = options.branchRulesetError;
 		this.providerId = options.providerId ?? GITHUB_PROVIDER_ID;
@@ -446,6 +481,10 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		return this.defaultBranch;
 	}
 
+	async getRepoVisibility(): Promise<RepoVisibility | undefined> {
+		return this.visibility;
+	}
+
 	async setBranchProtection(branch: string, spec: unknown): Promise<void> {
 		if (this.branchProtectionError !== undefined) {
 			throw new Error(this.branchProtectionError);

package/src/install-ci.ts

@@ -193,6 +193,31 @@ export async function installCI(
 		}
 	}
 
+	// 2c. Detect the repo's VISIBILITY (read-only; also in --fake, like the repo
+	//     slug detection). It decides whether the read-only jobs (verify,
+	//     close-job) check out with `persist-credentials: false`, which is only
+	//     provably safe on a PUBLIC repo (every git read works without a token).
+	//     Detected AFTER the export early-return: it is a fact about the repo,
+	//     never a config value, so it is not baked into an exported config.
+	if (options.ctx.getRepoVisibility) {
+		const visibility = await options.ctx
+			.getRepoVisibility()
+			.catch(() => undefined);
+		if (visibility !== undefined) {
+			config.repoVisibility = visibility;
+		}
+	}
+	if (config.repoVisibility === 'public') {
+		log(
+			'🔒 Public repository: verify + close-job check out with persist-credentials: false (no token left in .git/config).',
+		);
+	} else {
+		log(
+			`🔒 Repository visibility ${config.repoVisibility ?? 'unknown'}: verify + close-job keep the checkout token ` +
+				'(a git fetch in your gate or project-setup hook may need it). Re-run install-ci if the repo becomes public.',
+		);
+	}
+
 	// 3. Orchestrate secrets — SKIPPED in --fake mode (no real secret touched).
 	let secrets: SecretSetResult[] = [];
 	if (fake) {

package/src/intake-trigger-template.ts

@@ -68,6 +68,7 @@
  */
 
 import {brand} from './brand.js';
+import {ACTION_PINS, pinnedUses} from './install-ci-action-pins.js';
 import type {ResolvedCIConfig} from './install-ci-core.js';
 import {providerSecretsWithBlock} from './install-ci-core.js';
 
@@ -365,7 +366,7 @@ jobs:
     if: \${{ github.event.issue.number && !github.event.issue.pull_request }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: ${pinnedUses(ACTION_PINS.checkout)}
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup${setupWith}
@@ -463,13 +464,23 @@ jobs:
         # lone-task review/edit loop and posts its findings as questions back into
         # THIS issue thread (insertion point E) through the issue-comment seam —
         # CI surfaces E by invoking intake; it adds no new review mechanism.
+        #
+        # Every value reaches the shell through \`env:\` as DATA and is read back as a
+        # quoted variable, never as \`\${{ }}\` text spliced into the script
+        # (GitHub's script-injection guidance). The issue number is an integer and
+        # the policy outputs are fixed flags today; routing them through env anyway
+        # keeps "no \`\${{ }}\` inside \`run:\`" a rule with no exceptions.
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          ISSUE_NUMBER: \${{ github.event.issue.number }}
+          SPEC_FLAG: \${{ steps.policy.outputs.spec_flag }}
+          TASK_FLAG: \${{ steps.policy.outputs.task_flag }}
+          ORIGIN_TRUST_FLAG: \${{ steps.policy.outputs.origin_trust_flag }}
         run: |
-          dorfl intake "\${{ github.event.issue.number }}" \\
-            "\${{ steps.policy.outputs.spec_flag }}" \\
-            "\${{ steps.policy.outputs.task_flag }}" \\
-            "\${{ steps.policy.outputs.origin_trust_flag }}" \\
+          dorfl intake "\${ISSUE_NUMBER}" \\
+            "\${SPEC_FLAG}" \\
+            "\${TASK_FLAG}" \\
+            "\${ORIGIN_TRUST_FLAG}" \\
             --arbiter origin
 `;
 }
@@ -521,10 +532,20 @@ export function validateIntakeWorkflow(text: string): IntakeTriggerValidation {
 		'schedules).');
 	// The issue number rides the explicit positional — never a bare slug, and the
 	// number comes from the event payload (the issue under intake).
-	require('intake-explicit-issue-number', /dorfl intake "?\$\{\{\s*github\.event\.issue\.number/.test(
+	require('intake-explicit-issue-number', /ISSUE_NUMBER:\s*\$\{\{\s*github\.event\.issue\.number\s*\}\}[\s\S]*?dorfl intake "\$\{ISSUE_NUMBER\}"/.test(
 		operative,
 	), 'the intake invocation must pass the explicit issue NUMBER ' +
-		'(`github.event.issue.number`), never a bare slug.');
+		'(`github.event.issue.number`, via the step env as `ISSUE_NUMBER`), never a bare slug.');
+	// No `${{ }}` spliced into the intake `run:` script (script injection): the
+	// number and the policy flags reach the shell through the step `env:`.
+	require('intake-args-not-spliced-into-run', !/dorfl intake "?\$\{\{/.test(
+		operative,
+	) &&
+		!/"\$\{\{\s*steps\.policy\.outputs\./.test(
+			operative,
+		), 'the intake invocation must NOT interpolate `${{ github.event.issue.number }}` ' +
+		'or `${{ steps.policy.outputs.* }}` into its `run:` script: pass them through ' +
+		'the step `env:` and quote the variables.');
 	// CI owns ONLY the trigger/policy/delivery — it must NOT invoke a build/task
 	// verb (that is the build/task tick), nor re-implement the transform.
 	require('no-build-verbs', !/dorfl (?:do|advance)\b/.test(

package/src/intake.ts

@@ -3,6 +3,7 @@ import {dirname, join} from 'node:path';
 import {runAsync, type RunResult} from './git.js';
 import {workFolderRel, workFolderPrefix} from './work-layout.js';
 import {paramCase} from './brand.js';
+import {ensureSafeSlug} from './slug-safety.js';
 import {
 	performIntegration,
 	type IntegrationCoreResult,
@@ -1714,28 +1715,32 @@ async function postCompletionComment(params: {
  * Resolve a content-derived slug from the verdict — NEVER a counter (spec `issue-intake` US #8).
  * Prefer the drafted `taskSlug`, else derive from the drafted title; both go
  * through `paramCase` (the brand case-transform) so the result is a clean
- * lowercase-`-`-joined slug. An empty result (no slug AND no title) signals the
- * caller to refuse (a counter fallback is forbidden).
+ * lowercase-`-`-joined slug, and then through {@link ensureSafeSlug}: the draft
+ * comes from issue content, and `paramCase` alone keeps characters like `$(`,
+ * `"`, `;` and `/` that must never reach a file name, a git ref or a CI command
+ * line. An empty result (no slug AND no title) signals the caller to refuse (a
+ * counter fallback is forbidden).
  */
 function resolveSlug(verdict: IntakeVerdict): string {
 	const candidate =
 		verdict.taskSlug && verdict.taskSlug.trim() !== ''
 			? verdict.taskSlug
 			: (verdict.taskTitle ?? '');
-	return paramCase(candidate);
+	return ensureSafeSlug(paramCase(candidate));
 }
 
 /**
  * Resolve a content-derived slug for the spec outcome — NEVER a counter (spec `issue-intake` US #8).
  * Prefer the drafted `specSlug`, else derive from the drafted spec title; both go
- * through `paramCase`. An empty result signals the caller to refuse.
+ * through `paramCase` and {@link ensureSafeSlug} (see {@link resolveSlug}). An
+ * empty result signals the caller to refuse.
  */
 function resolveSpecSlug(verdict: IntakeVerdict): string {
 	const candidate =
 		verdict.specSlug && verdict.specSlug.trim() !== ''
 			? verdict.specSlug
 			: (verdict.specTitle ?? '');
-	return paramCase(candidate);
+	return ensureSafeSlug(paramCase(candidate));
 }
 
 /**

package/src/mint-adr.ts

@@ -7,6 +7,7 @@ import {
 	type CreateItemThroughCasResult,
 } from './advancing-lock.js';
 import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
+import {ensureSafeSlug} from './slug-safety.js';
 
 /**
  * The **ADR-MINT route** (spec
@@ -185,7 +186,9 @@ export async function mintAdr(options: MintAdrOptions): Promise<MintAdrResult> {
 	const note = options.note ?? (() => {});
 
 	const {slug: obsSlug} = resolveSidecarIdentity(item);
-	const adrSlug = (options.adrSlug ?? obsSlug).trim();
+	// The drafted slug comes from an agent verdict: an unsafe one (a `/`, `..`,
+	// shell metacharacters) is sanitised, a safe one is kept exactly as drafted.
+	const adrSlug = ensureSafeSlug(options.adrSlug ?? obsSlug);
 	if (adrSlug === '') {
 		return {
 			outcome: 'usage-error',

package/src/slug-namespace.ts

@@ -1,4 +1,5 @@
 import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
+import {isSafeSlug, MAX_SLUG_LENGTH} from './slug-safety.js';
 
 /**
  * The **§3a slug-namespace resolver** (`docs/adr/command-surface-and-
@@ -44,8 +45,8 @@ import {ledgerRead, type LedgerReadStrategy} from './ledger-read.js';
  *
  * HARD CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
  * contract step): the legacy ''prd'' member is GONE — the parent-spec namespace
- * is `'spec'` only. A ''prd:<slug>'' arg no longer parses to a namespace (it falls
- * through to a bare literal slug), and a `work/prd-<slug>` branch ref no longer
+ * is `'spec'` only. A ''prd:<slug>'' arg no longer parses to a namespace (the
+ * resolvers refuse it by the safe-slug check: `:` is not a slug character), and a `work/prd-<slug>` branch ref no longer
  * parses. No back-compat alias (the clean-break stance).
  */
 export type SlugNamespace = 'task' | 'spec' | 'observation';
@@ -155,8 +156,8 @@ const TASK_PREFIX = 'task:';
 /**
  * The parent-spec namespace prefix: `spec:<slug>` → `{explicit: 'spec'}`. HARD
  * CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`): the
- * legacy ''prd:'' prefix is GONE — a ''prd:<slug>'' arg falls through to a bare
- * literal slug (no namespace), the clean-break stance.
+ * legacy ''prd:'' prefix is GONE: a ''prd:<slug>'' arg carries no namespace and
+ * is refused by the safe-slug check (`:` is not a slug character), the clean-break stance.
  */
 const SPEC_PREFIX = 'spec:';
 /**
@@ -185,7 +186,8 @@ export class SlugResolutionError extends Error {
  * `spec:foo` → explicit spec, `foo` → bare (`explicit: undefined`). The prefix
  * match is case-sensitive and exact (`task:`/`spec:`); a slug like `tasked` is
  * NOT a prefix and stays bare. HARD CUTOVER: the legacy ''prd:'' prefix is not a
- * namespace prefix anymore — ''prd:foo'' stays a bare literal slug.
+ * namespace prefix anymore: ''prd:foo'' parses as a bare slug, which the
+ * resolvers then refuse by the safe-slug check (`:` is not a slug character).
  */
 export function parseSlugArg(arg: string): ParsedSlugArg {
 	if (arg.startsWith(TASK_PREFIX)) {
@@ -206,6 +208,29 @@ export function parseSlugArg(arg: string): ParsedSlugArg {
 	return {explicit: undefined, slug: arg};
 }
 
+/**
+ * Refuse a slug outside the safe set ({@link isSafeSlug}) before any verb acts on
+ * it. Producers sanitise the slugs they mint, but a slug can also arrive from a
+ * hand-written frontmatter `slug:` or a file name, and every resolved slug goes
+ * on to name files, git refs and CI command lines. Loud, like every other
+ * resolution error: an unsafe item is never acted on, and the message says how
+ * to fix it.
+ */
+function assertSafeSlug(arg: string, slug: string): void {
+	if (!isSafeSlug(slug)) {
+		throw new SlugResolutionError(
+			`'${arg}' does not name a usable slug: a slug must be 1-${MAX_SLUG_LENGTH} ` +
+				`letters, digits, '.', '_' or '-', start and end with a letter or digit, ` +
+				`and not contain '..'. Rename the item's file (and its frontmatter ` +
+				`\`slug:\`, if set) to a safe slug.` +
+				(slug.includes(':')
+					? ` (The only namespace prefixes are \`task:\`, \`spec:\`, \`obs:\` ` +
+						`and \`observation:\`; a legacy prefix such as \`prd:\` is not one.)`
+					: ''),
+		);
+	}
+}
+
 /** What the resolver needs to perform the existence checks. */
 export interface ResolveSlugInput {
 	/** The raw CLI slug argument (bare, `task:<slug>`, or `spec:<slug>`). */
@@ -261,6 +286,7 @@ function specExists(
 export function resolveSlug(input: ResolveSlugInput): ResolvedSlug {
 	const read = input.read ?? ledgerRead;
 	const parsed = parseSlugArg(input.arg);
+	assertSafeSlug(input.arg, parsed.slug);
 
 	if (parsed.explicit === 'observation') {
 		// `do` spans the task/spec namespaces ONLY (build a task OR task a spec).
@@ -313,6 +339,7 @@ export function resolveSlug(input: ResolveSlugInput): ResolvedSlug {
 export function resolveAdvanceArg(input: ResolveSlugInput): ResolvedSlug {
 	const read = input.read ?? ledgerRead;
 	const parsed = parseSlugArg(input.arg);
+	assertSafeSlug(input.arg, parsed.slug);
 
 	if (parsed.explicit !== undefined) {
 		// Explicit prefix (task / spec / observation): unambiguous by construction.
@@ -348,6 +375,7 @@ export function resolveAdvanceArg(input: ResolveSlugInput): ResolvedSlug {
  */
 export function resolveTaskOnlyArg(arg: string): string {
 	const parsed = parseSlugArg(arg);
+	assertSafeSlug(arg, parsed.slug);
 	if (parsed.explicit === 'spec') {
 		throw new SlugResolutionError(
 			`this command operates on tasks, not specs — '${arg}' names a spec. ` +