openspecpm 0.1.0-alpha.0 → 1.0.1

package/cli/bin/openspecpm.js

@@ -1,198 +1,218 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import { audited } from '../src/audit.js';
-import { runInit } from '../src/commands/init.js';
-import { runDoctor } from '../src/commands/doctor.js';
-import { runPropose } from '../src/commands/propose.js';
-import { runDecompose } from '../src/commands/decompose.js';
-import { runSync } from '../src/commands/sync.js';
-import { runComment } from '../src/commands/comment.js';
-import { runReconcile } from '../src/commands/reconcile.js';
-import { runStatus } from '../src/commands/status.js';
-import { runStandup } from '../src/commands/standup.js';
-import { runNext } from '../src/commands/next.js';
-import { runBlocked } from '../src/commands/blocked.js';
-import { runValidate } from '../src/commands/validate.js';
-import { runSearch } from '../src/commands/search.js';
-import { runFanOut } from '../src/commands/fan-out.js';
-import { runBugReport } from '../src/commands/bug-report.js';
-import { runShip } from '../src/commands/ship.js';
-import { runHelp } from '../src/commands/help.js';
-import { runAssign } from '../src/commands/assign.js';
-import { runSyncAll, runShipAllReady } from '../src/commands/bulk.js';
-import { runWatch } from '../src/commands/watch.js';
-
-const program = new Command();
-
-program
-  .name('openspecpm')
-  .description('Spec-driven, BDD-shaped project management for AI agents.')
-  .version('0.1.0-alpha.0');
-
-program
-  .command('init')
-  .description('Interactive wizard: pick a PM tool and write .openspecpm/config.json')
-  .option('--non-interactive', 'Fail instead of prompting when input is required')
-  .action((opts) => audited('init', runInit)(opts).catch(fatal));
-
-program
-  .command('doctor [adapter]')
-  .description('Check auth + tooling health for one or all adapters')
-  .option('--install', 'Print OS-specific install commands for missing CLIs')
-  .option('--setup-auth', 'Print PAT/token URLs and required scopes')
-  .action((adapter, opts) => audited('doctor', runDoctor)({ adapter, install: opts.install, setupAuth: opts.setupAuth }).catch(fatal));
-
-program
-  .command('propose <feature>')
-  .description('Create an OpenSpec proposal (proposal.md, design.md, tasks.md, specs/) for <feature>')
-  .option('-p, --prompt <text>', 'One-line description for the AI to seed the proposal')
-  .option('-t, --type <type>', 'Change type: feature | bug | refactor | incident', 'feature')
-  .option('--offline', 'Scaffold from templates without calling the openspec CLI')
-  .action((feature, opts) => audited('propose', runPropose)({ feature, prompt: opts.prompt, type: opts.type, offline: opts.offline }).catch(fatal));
-
-program
-  .command('decompose <feature>')
-  .description('Extract tasks from proposal + BDD scenarios into tasks.md')
-  .option('--force', 'Merge into an existing tasks.md instead of refusing')
-  .action((feature, opts) => audited('decompose', runDecompose)({ feature, force: opts.force }).catch(fatal));
-
-program
-  .command('sync [feature]')
-  .description('Push an OpenSpec change to the configured PM tool (idempotent; BDD-linted)')
-  .option('--all', 'Sync every change under openspec/changes/')
-  .option('--dry-run', 'Print the call plan without making remote changes')
-  .option('--force', 'Bypass BDD lint errors')
-  .option('--diff', 'Show the call plan in detail')
-  .option('-y, --yes', 'Skip the confirmation prompt for --all')
-  .action((feature, opts) => {
-    if (opts.all) {
-      return audited('sync-all', runSyncAll)({ dryRun: opts.dryRun, force: opts.force, yes: opts.yes }).catch(fatal);
-    }
-    if (!feature) {
-      process.stderr.write('error: provide a <feature> or pass --all\n');
-      process.exit(1);
-    }
-    return audited('sync', runSync)({ feature, dryRun: opts.dryRun, force: opts.force, diff: opts.diff }).catch(fatal);
-  });
-
-program
-  .command('comment <feature> <task>')
-  .description('Post a progress comment to the PM tool work item')
-  .option('-m, --message <text>', 'Inline message (otherwise reads from local progress.md)')
-  .option('--dry-run', 'Print the comment instead of posting')
-  .action((feature, task, opts) =>
-    audited('comment', runComment)({ feature, task, message: opts.message, dryRun: opts.dryRun }).catch(fatal),
-  );
-
-program
-  .command('reconcile <feature>')
-  .description('Pull remote state back into local task frontmatter')
-  .option('--dry-run', 'Show drift without writing local changes')
-  .action((feature, opts) => audited('reconcile', runReconcile)({ feature, dryRun: opts.dryRun }).catch(fatal));
-
-program
-  .command('status')
-  .description('Local snapshot: configured adapter + per-change task counts')
-  .action(() => audited('status', runStatus)().catch(fatal));
-
-program
-  .command('standup')
-  .description('Show progress updates within a recent window')
-  .option('--since <window>', 'Time window: e.g. 12h, 2d, 1w', '24h')
-  .option('--broadcast', 'Also POST to configured Slack/Teams/generic webhooks')
-  .action((opts) => audited('standup', runStandup)({ since: opts.since, broadcast: opts.broadcast }).catch(fatal));
-
-program
-  .command('next')
-  .description('List tasks ready to start (no unmet dependencies)')
-  .option('-l, --limit <n>', 'Max items to show', (v) => parseInt(v, 10), 5)
-  .action((opts) => audited('next', runNext)({ limit: opts.limit }).catch(fatal));
-
-program
-  .command('blocked')
-  .description('List tasks waiting on unmet dependencies')
-  .action(() => audited('blocked', runBlocked)().catch(fatal));
-
-program
-  .command('validate')
-  .description('Schema + dependency + BDD-lint sweep across every change')
-  .action(() => audited('validate', runValidate)().catch(fatal));
-
-program
-  .command('search <query>')
-  .description('Grep across proposals, specs, tasks, and progress notes')
-  .option('-l, --limit <n>', 'Max matches to show', (v) => parseInt(v, 10), 50)
-  .option('--case-sensitive', 'Match case')
-  .action((query, opts) =>
-    audited('search', runSearch)({ query, limit: opts.limit, caseSensitive: opts.caseSensitive }).catch(fatal),
-  );
-
-program
-  .command('fan-out <feature>')
-  .description('Emit ready-to-paste agent prompts for parallel:true tasks')
-  .option('-l, --limit <n>', 'Max prompts to emit', (v) => parseInt(v, 10), 5)
-  .action((feature, opts) => audited('fan-out', runFanOut)({ feature, limit: opts.limit }).catch(fatal));
-
-program
-  .command('bug-report <feature> <task>')
-  .description('File a regression bug linked to a shipped task')
-  .option('-t, --title <text>', 'Bug title (required)')
-  .option('-b, --body <text>', 'Bug body')
-  .action((feature, task, opts) =>
-    audited('bug-report', runBugReport)({ feature, task, title: opts.title, body: opts.body }).catch(fatal),
-  );
-
-program
-  .command('assign <feature> <task>')
-  .description('Set assignee / sprint / iteration / area / story-points on a synced task')
-  .option('--assignee <id>', 'Assignee id (backend-specific)')
-  .option('--sprint <id>', 'Sprint / cycle / milestone id (whichever the backend supports)')
-  .option('--iteration <path>', 'Iteration path (Azure DevOps; alias for --sprint elsewhere)')
-  .option('--area <path>', 'Area path (Azure DevOps)')
-  .option('--story-points <n>', 'Story points / estimate / weight')
-  .action((feature, task, opts) =>
-    audited('assign', runAssign)({
-      feature, task,
-      assignee: opts.assignee, sprint: opts.sprint, iteration: opts.iteration,
-      area: opts.area, storyPoints: opts.storyPoints,
-    }).catch(fatal),
-  );
-
-program
-  .command('ship [feature]')
-  .description('Close all work items for <feature> and archive the OpenSpec change')
-  .option('--all-ready', 'Ship every change whose tasks are all synced (no pending/failed)')
-  .option('-y, --yes', 'Skip the confirmation prompt')
-  .option('--skip-archive', 'Close work items but leave openspec/changes/<feature>/ in place')
-  .action((feature, opts) => {
-    if (opts.allReady) {
-      return audited('ship-all-ready', runShipAllReady)({ yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
-    }
-    if (!feature) {
-      process.stderr.write('error: provide a <feature> or pass --all-ready\n');
-      process.exit(1);
-    }
-    return audited('ship', runShip)({ feature, yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
-  });
-
-program
-  .command('watch [feature]')
-  .description('Re-lint on file change. Use --all to validate the whole project on every change.')
-  .option('--all', 'Validate every change instead of linting one feature')
-  .option('--debounce <ms>', 'Debounce window in milliseconds', (v) => parseInt(v, 10), 300)
-  .action((feature, opts) =>
-    audited('watch', runWatch)({ feature, allChanges: opts.all, debounceMs: opts.debounce }).catch(fatal),
-  );
-
-program
-  .command('help-table [topic]')
-  .description('Context-aware help grouped by workflow phase')
-  .action((topic) => { runHelp({ topic }); });
-
-program.parseAsync(process.argv);
-
-function fatal(err) {
-  process.stderr.write(`\n✖ ${err.message}\n`);
-  if (err.remediation) process.stderr.write(`  → ${err.remediation}\n`);
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { audited } from '../src/audit.js';
+
+// Read version from package.json so `npm version` bumps and the CLI's
+// `--version` output stay in sync. package.json always ships in the
+// npm tarball, so this resolves correctly under `npx openspecpm`.
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+import { runInit } from '../src/commands/init.js';
+import { runDoctor } from '../src/commands/doctor.js';
+import { runPropose } from '../src/commands/propose.js';
+import { runDecompose } from '../src/commands/decompose.js';
+import { runSync } from '../src/commands/sync.js';
+import { runComment } from '../src/commands/comment.js';
+import { runReconcile } from '../src/commands/reconcile.js';
+import { runStatus } from '../src/commands/status.js';
+import { runStandup } from '../src/commands/standup.js';
+import { runNext } from '../src/commands/next.js';
+import { runBlocked } from '../src/commands/blocked.js';
+import { runValidate } from '../src/commands/validate.js';
+import { runSearch } from '../src/commands/search.js';
+import { runFanOut } from '../src/commands/fan-out.js';
+import { runBugReport } from '../src/commands/bug-report.js';
+import { runShip } from '../src/commands/ship.js';
+import { runHelp } from '../src/commands/help.js';
+import { runAssign } from '../src/commands/assign.js';
+import { runSyncAll, runShipAllReady } from '../src/commands/bulk.js';
+import { runWatch } from '../src/commands/watch.js';
+
+const program = new Command();
+
+program
+  .name('openspecpm')
+  .description('Spec-driven, BDD-shaped project management for AI agents.')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Interactive wizard: pick a PM tool and write .openspecpm/config.json')
+  .option('--non-interactive', 'Fail instead of prompting when input is required')
+  .action((opts) => audited('init', runInit)(opts).catch(fatal));
+
+program
+  .command('doctor [adapter]')
+  .description('Check auth + tooling health for one or all adapters')
+  .option('--install', 'Print OS-specific install commands for missing CLIs')
+  .option('--setup-auth', 'Print PAT/token URLs and required scopes')
+  .action((adapter, opts) => audited('doctor', runDoctor)({ adapter, install: opts.install, setupAuth: opts.setupAuth }).catch(fatal));
+
+program
+  .command('propose <feature>')
+  .description('Create an OpenSpec proposal (proposal.md, design.md, tasks.md, specs/) for <feature>')
+  .option('-p, --prompt <text>', 'One-line description for the AI to seed the proposal')
+  .option('-t, --type <type>', 'Change type: feature | bug | refactor | incident', 'feature')
+  .option('--offline', 'Scaffold from templates without calling the openspec CLI')
+  .option('--llm', 'Augment BDD soft-lint with the LLM judge (requires ANTHROPIC_API_KEY)')
+  .action((feature, opts) => audited('propose', runPropose)({ feature, prompt: opts.prompt, type: opts.type, offline: opts.offline, llm: opts.llm }).catch(fatal));
+
+program
+  .command('decompose <feature>')
+  .description('Extract tasks from proposal + BDD scenarios into tasks.md')
+  .option('--force', 'Merge into an existing tasks.md instead of refusing')
+  .action((feature, opts) => audited('decompose', runDecompose)({ feature, force: opts.force }).catch(fatal));
+
+program
+  .command('sync [feature]')
+  .description('Push an OpenSpec change to the configured PM tool (idempotent; BDD-linted)')
+  .option('--all', 'Sync every change under openspec/changes/')
+  .option('--dry-run', 'Print the call plan without making remote changes')
+  .option('--force', 'Bypass BDD lint errors')
+  .option('--diff', 'Show the call plan in detail')
+  .option('--llm', 'Augment BDD hard-lint with the LLM judge (requires ANTHROPIC_API_KEY)')
+  .option('-y, --yes', 'Skip the confirmation prompt for --all')
+  .action((feature, opts) => {
+    if (opts.all) {
+      return audited('sync-all', runSyncAll)({ dryRun: opts.dryRun, force: opts.force, yes: opts.yes }).catch(fatal);
+    }
+    if (!feature) {
+      process.stderr.write('error: provide a <feature> or pass --all\n');
+      process.exit(1);
+    }
+    return audited('sync', runSync)({ feature, dryRun: opts.dryRun, force: opts.force, diff: opts.diff, llm: opts.llm }).catch(fatal);
+  });
+
+program
+  .command('comment <feature> <task>')
+  .description('Post a progress comment to the PM tool work item')
+  .option('-m, --message <text>', 'Inline message (otherwise reads from local progress.md)')
+  .option('--dry-run', 'Print the comment instead of posting')
+  .action((feature, task, opts) =>
+    audited('comment', runComment)({ feature, task, message: opts.message, dryRun: opts.dryRun }).catch(fatal),
+  );
+
+program
+  .command('reconcile <feature>')
+  .description('Pull remote state back into local task frontmatter')
+  .option('--dry-run', 'Show drift without writing local changes')
+  .action((feature, opts) => audited('reconcile', runReconcile)({ feature, dryRun: opts.dryRun }).catch(fatal));
+
+program
+  .command('status')
+  .description('Local snapshot: configured adapter + per-change task counts')
+  .action(() => audited('status', runStatus)().catch(fatal));
+
+program
+  .command('standup')
+  .description('Show progress updates within a recent window')
+  .option('--since <window>', 'Time window: e.g. 12h, 2d, 1w', '24h')
+  .option('--broadcast', 'Also POST to configured Slack/Teams/generic webhooks')
+  .action((opts) => audited('standup', runStandup)({ since: opts.since, broadcast: opts.broadcast }).catch(fatal));
+
+program
+  .command('next')
+  .description('List tasks ready to start (no unmet dependencies)')
+  .option('-l, --limit <n>', 'Max items to show', (v) => parseInt(v, 10), 5)
+  .action((opts) => audited('next', runNext)({ limit: opts.limit }).catch(fatal));
+
+program
+  .command('blocked')
+  .description('List tasks waiting on unmet dependencies')
+  .action(() => audited('blocked', runBlocked)().catch(fatal));
+
+program
+  .command('validate')
+  .description('Schema + dependency + BDD-lint sweep across every change')
+  .option('--llm', 'Augment BDD lint with the LLM judge (requires ANTHROPIC_API_KEY)')
+  .action((opts) => audited('validate', runValidate)({ llm: opts.llm }).catch(fatal));
+
+program
+  .command('search <query>')
+  .description('Grep across proposals, specs, tasks, and progress notes')
+  .option('-l, --limit <n>', 'Max matches to show', (v) => parseInt(v, 10), 50)
+  .option('--case-sensitive', 'Match case')
+  .action((query, opts) =>
+    audited('search', runSearch)({ query, limit: opts.limit, caseSensitive: opts.caseSensitive }).catch(fatal),
+  );
+
+program
+  .command('fan-out <feature>')
+  .description('Emit ready-to-paste agent prompts for parallel:true tasks')
+  .option('-l, --limit <n>', 'Max prompts to emit', (v) => parseInt(v, 10), 5)
+  .action((feature, opts) => audited('fan-out', runFanOut)({ feature, limit: opts.limit }).catch(fatal));
+
+program
+  .command('bug-report <feature> <task>')
+  .description('File a regression bug linked to a shipped task')
+  .option('-t, --title <text>', 'Bug title (required)')
+  .option('-b, --body <text>', 'Bug body')
+  .action((feature, task, opts) =>
+    audited('bug-report', runBugReport)({ feature, task, title: opts.title, body: opts.body }).catch(fatal),
+  );
+
+program
+  .command('assign <feature> <task>')
+  .description('Set assignee / sprint / iteration / area / story-points on a synced task')
+  .option('--assignee <id>', 'Assignee id (backend-specific)')
+  .option('--sprint <id>', 'Sprint / cycle / milestone id (whichever the backend supports)')
+  .option('--iteration <path>', 'Iteration path (Azure DevOps; alias for --sprint elsewhere)')
+  .option('--area <path>', 'Area path (Azure DevOps)')
+  .option('--story-points <n>', 'Story points / estimate / weight')
+  .action((feature, task, opts) =>
+    audited('assign', runAssign)({
+      feature, task,
+      assignee: opts.assignee, sprint: opts.sprint, iteration: opts.iteration,
+      area: opts.area, storyPoints: opts.storyPoints,
+    }).catch(fatal),
+  );
+
+program
+  .command('ship [feature]')
+  .description('Close all work items for <feature> and archive the OpenSpec change')
+  .option('--all-ready', 'Ship every change whose tasks are all synced (no pending/failed)')
+  .option('-y, --yes', 'Skip the confirmation prompt')
+  .option('--skip-archive', 'Close work items but leave openspec/changes/<feature>/ in place')
+  .action((feature, opts) => {
+    if (opts.allReady) {
+      return audited('ship-all-ready', runShipAllReady)({ yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
+    }
+    if (!feature) {
+      process.stderr.write('error: provide a <feature> or pass --all-ready\n');
+      process.exit(1);
+    }
+    return audited('ship', runShip)({ feature, yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
+  });
+
+program
+  .command('watch [feature]')
+  .description('Re-lint on file change. Use --all to validate the whole project on every change.')
+  .option('--all', 'Validate every change instead of linting one feature')
+  .option('--debounce <ms>', 'Debounce window in milliseconds', (v) => parseInt(v, 10), 300)
+  .action((feature, opts) =>
+    audited('watch', runWatch)({ feature, allChanges: opts.all, debounceMs: opts.debounce }).catch(fatal),
+  );
+
+program
+  .command('help-table [topic]')
+  .description('Context-aware help grouped by workflow phase')
+  .action((topic) => { runHelp({ topic }); });
+
+// Sanitize uncaught errors so a future programming bug (TypeError, etc.)
+// doesn't dump a stack trace with absolute install / tmp paths to stderr.
+// fatal() is the normal path; these handlers are insurance for code paths
+// that don't reach Commander's .catch(fatal).
+process.on('uncaughtException', fatal);
+process.on('unhandledRejection', (reason) => {
+  fatal(reason instanceof Error ? reason : new Error(String(reason ?? 'unknown')));
+});
+
+program.parseAsync(process.argv);
+
+function fatal(err) {
+  const msg = err?.message ?? String(err ?? 'unknown error');
+  process.stderr.write(`\n✖ ${msg}\n`);
+  if (err?.remediation) process.stderr.write(`  → ${err.remediation}\n`);
+  process.stderr.write(`  See .openspecpm/audit.log for details.\n`);
+  process.exit(1);
+}

package/cli/src/adapters/azure.js

@@ -2,6 +2,11 @@ import { Adapter, AdapterError } from './base.js';
 import { HttpClient, basicAuth } from '../http.js';
 import { TokenBucket, PRESETS } from '../ratelimit.js';
 
+// User-controlled ids (from tasks.md frontmatter) MUST be encoded before
+// interpolation into URL paths or body URL values, or a value like
+// "1/../99" can reach unintended endpoints.
+const enc = (v) => encodeURIComponent(String(v));
+
 const API_VERSION = '7.1';
 const COMMENTS_API_VERSION = '7.1-preview.3';
 
@@ -151,11 +156,11 @@ export class AzureAdapter extends Adapter {
         path: '/relations/-',
         value: {
           rel: 'System.LinkTypes.Hierarchy-Reverse',
-          url: `${this.config.baseUrl ?? `https://dev.azure.com/${this.config.organization}`}/_apis/wit/workItems/${parent.id}`,
+          url: `${this.config.baseUrl ?? `https://dev.azure.com/${this.config.organization}`}/_apis/wit/workItems/${enc(parent.id)}`,
         },
       },
     ];
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${child.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(child.id)}`;
     await this.#req('PATCH', path, {
       query: { 'api-version': API_VERSION },
       body: ops,
@@ -164,7 +169,7 @@ export class AzureAdapter extends Adapter {
   }
 
   async addProgressComment(item, body) {
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workItems/${item.id}/comments`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workItems/${enc(item.id)}/comments`;
     await this.#req('POST', path, {
       query: { 'api-version': COMMENTS_API_VERSION },
       body: { text: body },
@@ -179,7 +184,7 @@ export class AzureAdapter extends Adapter {
     if (patch.iterationPath) ops.push({ op: 'add', path: '/fields/System.IterationPath', value: patch.iterationPath });
     if (patch.areaPath) ops.push({ op: 'add', path: '/fields/System.AreaPath', value: patch.areaPath });
     if (!ops.length) return;
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(item.id)}`;
     await this.#req('PATCH', path, {
       query: { 'api-version': API_VERSION },
       body: ops,
@@ -193,7 +198,7 @@ export class AzureAdapter extends Adapter {
   }
 
   async getWorkItem(item) {
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(item.id)}`;
     const data = await this.#req('GET', path, { query: { 'api-version': API_VERSION } });
     return {
       ref: { adapter: 'azure', id: String(data.id), url: data._links?.html?.href },
@@ -206,6 +211,17 @@ export class AzureAdapter extends Adapter {
 
   async listWorkItems(query = {}) {
     const tag = query.tag ?? `openspec`;
+    // Defense in depth: WIQL string-literal syntax means `'` is the only
+    // breakout char and we already double it. But there's no known WIQL
+    // feature that escapes a literal via other chars, so reject anything
+    // outside a known-safe set rather than trust escaping alone. Tags in
+    // this codebase are always `openspec` or `openspec:<feature>`; the
+    // feature side is validated by openspec-bridge.assertSafeFeatureName.
+    if (!/^[a-zA-Z0-9._:-]+$/.test(String(tag))) {
+      throw new AdapterError(`Unsafe tag for WIQL: "${tag}".`, {
+        remediation: 'Tag must match /^[a-zA-Z0-9._:-]+$/. Use a plain slug.',
+      });
+    }
     const wiql = `SELECT [System.Id], [System.Title], [System.State], [System.Tags], [System.AssignedTo] FROM workitems WHERE [System.TeamProject] = @project AND [System.Tags] CONTAINS '${tag.replace(/'/g, "''")}' ORDER BY [System.Id] DESC`;
     const path = `/${encodeURIComponent(this.#project())}/_apis/wit/wiql`;
     const res = await this.#req('POST', path, {

package/cli/src/adapters/gitlab.js

@@ -2,6 +2,11 @@ import { Adapter, AdapterError } from './base.js';
 import { HttpClient } from '../http.js';
 import { TokenBucket } from '../ratelimit.js';
 
+// User-controlled ids (from tasks.md frontmatter) MUST be encoded before
+// interpolation into URL paths, or a value like "1/../99" can reach
+// unintended project endpoints.
+const enc = (v) => encodeURIComponent(String(v));
+
 const STATE_TO_NORMALIZED = (s) => {
   const v = (s ?? '').toLowerCase();
   if (v === 'closed') return 'closed';
@@ -109,7 +114,7 @@ export class GitLabAdapter extends Adapter {
   }
 
   async linkWorkItems(parent, child, type = 'relates_to') {
-    await this.#req('POST', `/projects/${this.#project()}/issues/${child.id}/links`, {
+    await this.#req('POST', `/projects/${this.#project()}/issues/${enc(child.id)}/links`, {
       body: {
         target_project_id: this.config.projectId,
         target_issue_iid: parent.id,
@@ -119,7 +124,7 @@ export class GitLabAdapter extends Adapter {
   }
 
   async addProgressComment(item, body) {
-    await this.#req('POST', `/projects/${this.#project()}/issues/${item.id}/notes`, {
+    await this.#req('POST', `/projects/${this.#project()}/issues/${enc(item.id)}/notes`, {
       body: { body },
     });
   }
@@ -134,18 +139,18 @@ export class GitLabAdapter extends Adapter {
     if (patch.milestoneId) body.milestone_id = patch.milestoneId;  // sprint
     if (patch.weight !== undefined) body.weight = patch.weight;     // story points
     if (!Object.keys(body).length) return;
-    await this.#req('PUT', `/projects/${this.#project()}/issues/${item.id}`, { body });
+    await this.#req('PUT', `/projects/${this.#project()}/issues/${enc(item.id)}`, { body });
   }
 
   async closeWorkItem(item, resolution) {
-    await this.#req('PUT', `/projects/${this.#project()}/issues/${item.id}`, {
+    await this.#req('PUT', `/projects/${this.#project()}/issues/${enc(item.id)}`, {
       body: { state_event: 'close' },
     });
     if (resolution) await this.addProgressComment(item, resolution);
   }
 
   async getWorkItem(item) {
-    const data = await this.#req('GET', `/projects/${this.#project()}/issues/${item.id}`);
+    const data = await this.#req('GET', `/projects/${this.#project()}/issues/${enc(item.id)}`);
     return {
       ref: { adapter: 'gitlab', id: String(data.iid), url: data.web_url },
       title: data.title,