dorfl 0.14.0 → 0.14.2

package/src/install-ci-core.ts

@@ -141,6 +141,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 +260,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 +718,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 +798,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}`;
@@ -815,17 +933,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,

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

@@ -463,13 +463,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 +531,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. ` +

package/src/slug-safety.ts

@@ -0,0 +1,83 @@
+/**
+ * The SAFE-SLUG character set, and the one sanitiser every slug-producing path
+ * shares.
+ *
+ * A slug is not just a label: it becomes a file name (`work/<folder>/<slug>.md`),
+ * part of a git ref (`work/<slug>`, `work/intake-task-<slug>`), a command-line
+ * argument (`dorfl advance "task:<slug>"`, one per CI matrix leg) and text in
+ * commit messages. Several producers draft slugs from content an outsider can
+ * influence: `intake` from an issue's title and thread, the triage and apply
+ * rungs from an agent verdict. Before this module the only transform was
+ * `paramCase`, which keeps `$(`, backticks, quotes, `;`, `|` and `/`, and the
+ * triage/ADR paths only `trim()`med, so a drafted `../x` escaped its folder.
+ *
+ * Two functions, two jobs:
+ *
+ *   - {@link toSafeSlug} is for PRODUCERS: it turns any drafted text into a slug
+ *     made only of ASCII letters, digits and single hyphens. Its output always
+ *     passes {@link isSafeSlug}.
+ *   - {@link isSafeSlug} is for CONSUMERS: the slug resolvers refuse any slug
+ *     outside the safe set, which covers slugs no producer here minted (a
+ *     frontmatter `slug:` a human or agent wrote by hand). It is deliberately a
+ *     little wider than what {@link toSafeSlug} emits (it also allows `.` and
+ *     `_` and mixed case) so every slug already in use in a real `work/` tree
+ *     keeps resolving: those characters are inert in a file name, a ref and a
+ *     quoted shell word. `..` is still refused (path traversal), as is a leading
+ *     `-` (it would read as a command-line option) or `.` (a hidden file), and so
+ *     is a `.lock` suffix (git refuses it in a ref component).
+ */
+
+/**
+ * The longest slug either function accepts. Real slugs in this repo top out
+ * around 105 characters; 120 leaves room without letting a drafted essay become
+ * a file name or ref component.
+ */
+export const MAX_SLUG_LENGTH = 120;
+
+/** Letters, digits, `.`, `_`, `-`; starts and ends with a letter or digit. */
+const SAFE_SLUG_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+
+/** Git refuses a ref component ending in `.lock` (its lock-file suffix). */
+const GIT_LOCK_SUFFIX_RE = /\.lock$/i;
+
+/**
+ * Whether `slug` is safe to use as a file name, a git ref component and a
+ * command-line argument (see the module doc for the exact set).
+ */
+export function isSafeSlug(slug: string): boolean {
+	return (
+		slug.length > 0 &&
+		slug.length <= MAX_SLUG_LENGTH &&
+		SAFE_SLUG_RE.test(slug) &&
+		!slug.includes('..') &&
+		!GIT_LOCK_SUFFIX_RE.test(slug)
+	);
+}
+
+/**
+ * Turn drafted text into a safe slug: accents are folded to their base letter,
+ * every run of anything other than an ASCII letter or digit becomes ONE hyphen,
+ * leading/trailing hyphens are dropped, and the result is capped at
+ * {@link MAX_SLUG_LENGTH}. Case is preserved (callers that want lower case, like
+ * `intake`, `paramCase` first). Returns `''` when nothing usable is left, so the
+ * caller's existing "no slug to derive" refusal fires instead of a junk name.
+ */
+export function toSafeSlug(input: string): string {
+	return input
+		.normalize('NFKD')
+		.replace(/[\u0300-\u036f]/g, '')
+		.replace(/[^A-Za-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, MAX_SLUG_LENGTH)
+		.replace(/-+$/, '');
+}
+
+/**
+ * Keep a slug that is already safe EXACTLY as it is, and sanitise one that is
+ * not. The producers use this so every input that worked before still yields
+ * the same slug, and only an unsafe one changes.
+ */
+export function ensureSafeSlug(input: string): string {
+	const trimmed = input.trim();
+	return isSafeSlug(trimmed) ? trimmed : toSafeSlug(trimmed);
+}

package/src/triage-persist.ts

@@ -11,6 +11,7 @@ import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
 import type {TriageAutoKind} from './triage-gate.js';
 import {renderTaskBody, renderSpecBody} from './buildable-body.js';
 import {setFrontmatterMarker} from './frontmatter.js';
+import {ensureSafeSlug} from './slug-safety.js';
 
 /**
  * The engine-owned TRIAGE PERSIST (spec `advance-loop`, task `advance-rung-triage`,
@@ -433,7 +434,9 @@ export async function promoteObservation(
 	const note = options.note ?? (() => {});
 
 	const {slug: obsSlug} = resolveSidecarIdentity(item);
-	const newSlug = (options.newSlug ?? 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 newSlug = ensureSafeSlug(options.newSlug ?? obsSlug);
 	const artifact = options.artifact ?? 'task';
 	if (newSlug === '') {
 		return {
@@ -460,13 +463,16 @@ export async function promoteObservation(
 	// review-nits back-pointer); this is the triage-promote lineage. Matching on this
 	// explicit field — not the slug — is what keeps an unrelated same-slug task from
 	// false-positiving into a benign skip.
+	// A drafted `stubContent` carries its own frontmatter, and the ledger reads
+	// `slug:` before the file name, so stamp the SAFE slug over whatever the
+	// draft said: otherwise a drafted `slug: ../x` would become the item's
+	// identity even though the file name was sanitised.
+	const drafted =
+		options.stubContent !== undefined
+			? setFrontmatterMarker(options.stubContent, 'slug', newSlug)
+			: buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env));
 	const content = setFrontmatterMarker(
-		ensureTaskDispatchable(
-			artifact,
-			newSlug,
-			options.stubContent ??
-				buildPromotedBody(artifact, newSlug, readItem(cwd, itemPath, env)),
-		),
+		ensureTaskDispatchable(artifact, newSlug, drafted),
 		'promotedFrom',
 		item,
 	);

package/src/verify-workflow-template.ts

@@ -22,6 +22,7 @@
  */
 
 import type {ResolvedCIConfig} from './install-ci-core.js';
+import {shouldDropCheckoutCredentials} from './install-ci-core.js';
 
 /**
  * The required-status-check CONTEXT install-ci sets via branch protection AND the
@@ -47,7 +48,18 @@ export const VERIFY_WORKFLOW_PATH = 'workflows/verify.yml';
  * so the GitHub check it produces matches the required-status `context` install-ci
  * configures on `main` — by construction, not by hand-typed agreement.
  */
-export function generateVerifyWorkflow(_config: ResolvedCIConfig): string {
+export function generateVerifyWorkflow(config: ResolvedCIConfig): string {
+	// `persist-credentials: false` ONLY on a repo KNOWN to be public (see
+	// {@link shouldDropCheckoutCredentials}): this job has `contents: read`, so
+	// the persisted token can only ever read, and on a public repo reads need
+	// no token. Unknown / private / internal ⇒ today's checkout, unchanged.
+	const checkoutCredentials = shouldDropCheckoutCredentials(config)
+		? `
+          # Public repository: every git read works without a token, and this
+          # job cannot push, so do not leave the token in .git/config for later
+          # steps (the project-setup hook's installs, the gate) to read.
+          persist-credentials: false`
+		: '';
 	return `\
 # dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; spec
 # land-time-reverify-and-parallel-merge-ceiling, task
@@ -102,7 +114,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
-          fetch-depth: 0
+          fetch-depth: 0${checkoutCredentials}
       - uses: ./.github/actions/dorfl-setup
       - name: run the repo verify gate
         run: dorfl verify