@magnusekdahl/parallix 1.0.0 → 1.0.2

package/README.md

@@ -1,30 +1,29 @@
 # Parallix
 
-**Parallix is a CLI for a local-first, human-in-the-loop developer workflow that runs several supported AI coding agents against one repository as isolated, resumable, reviewable missions — instead of one agent improvising in your working tree.**
+**Parallix is a local-first Git workflow CLI for running AI coding agents in isolated, reviewable missions instead of letting one long-lived agent session mutate your main checkout.**
 
-It is built for solo maintainers and small-team leads who already drive AI coding agents such as Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral and have hit the real problems: two agents fighting over one checkout, a run dying when a provider hits its usage cap, no clean way to resume a long task where it stopped, and the agent that wrote the code also being the one that declares it done.
+It is for engineers who already use Git and terminal-first coding agents such as Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral, and want branch isolation, resumable checkpoints, agent-family failover, and a forced review step without building that harness by hand.
 
-It wraps your AI coding workflow without replacing it: Parallix turns each piece of work into a *mission* with its own branch and its own git worktree, fails over to another agent family when one hits its usage limit, checkpoints long runs so they resume deterministically, and forces a second coding agent review step plus your own repo-configured verification gates before anything is integrated. A human still chooses the task, launches each phase, reads the review, and decides whether the work should land.
+It wraps your existing AI coding workflow without replacing it: each mission gets its own branch and worktree, long runs checkpoint to markdown, review is a separate phase, and integration still goes through your repo's own verification command. A human still chooses the mission, launches each phase, reads the output, and decides what lands.
 
-**Why not just use Claude Code, Codex, or OpenCode directly?** Those are the agents — Parallix is the harness around them. It does not replace your agent or your model. It coordinates several of them as one multi-agent coding workflow with isolation, automatic failover, deterministic checkpoints, and a forced review pass that a single agent session does not give you.
-
-**The first concrete thing you can do** is install the px CLI, create one Backlog.md-style task, and draft it:
+**The first concrete thing you can do** is install the CLI and run one complete mission:
 
 ```sh
-npm pack && npm install -g ./magnusekdahl-parallix-*.tgz
-px draft task-001
+npm install -g @magnusekdahl/parallix
+px draft "create a hello world program"
+px active
+px review
+px integrate
 ```
 
-`px draft` does not accept free-text slugs like `my-first-task`, and it does not create the task for you. It expects an existing Backlog.md-style task key such as `task-001`.
-
-Everything below is the longer version, with the proof and the caveats kept honest.
+That path shows the whole value: isolate the work on its own branch and worktree, let an agent execute it with checkpoints, run a separate review phase, and only then integrate it back.
 
 ## Why Parallix?
 
 Running AI coding agents one session at a time hits a ceiling fast:
 
 - **One working tree, many agents.** Point two agents at the same checkout and they fight over the index, the branch, and uncommitted files. You either serialize them — one idle while the other runs — or hand-manage `git worktree` and branch names yourself.
-- **Runs die on usage caps.** An agent prints "usage limit reached", the run stops, and you babysit it: restart later, or hand-switch to a different model.
+- **Runs die on usage caps.** An agent prints "usage limit reached", the run stops, and you babysit it: restart later or hand-switch to a different model.
 - **Long tasks lose their place.** A crashed or context-exhausted agent leaves you reconstructing what was already done by re-reading diffs.
 - **The author grades its own homework.** The agent that wrote the change also declares it done. Nobody independent looks before it lands.
 
@@ -59,32 +58,53 @@ In practice: a human drafts a mission, Parallix creates the branch and worktree,
 
 ## Quick start
 
-The current install path is a **local npm tarball** built from this repository. A **scoped npm package** (`@magnusekdahl/parallix`) will be available after publication (see [Current status](#current-status)).
+Install from the public npm registry and run a complete mission:
 
 ```sh
-# Build and install from the local tarball
-npm pack
-npm install -g ./magnusekdahl-parallix-*.tgz
-
-# Confirm which px is on PATH
+npm install -g @magnusekdahl/parallix
 px --version
+px draft "hello world"
+px active
+px review
+px integrate
+```
+
+`px draft` creates the mission branch, sibling worktree, mission file, and task record. Then `cd` into the mission worktree and run `px active`, `px review`, and `px integrate` there with no slug; the CLI infers the mission from the current branch/worktree.
+
+Other draft entry points are available when you need them:
+
+```sh
+# Draft from the current repository directory name
+px draft .
+
+# Draft from an existing structured task file
+px draft task-001
 ```
 
+Optional but useful: run `px setup` if you want help creating `workflow.config.json`, appending workflow entries to `.gitignore`, or bootstrapping Forgejo review wiring.
+
 Optional but useful: add `px shell-init` to your shell rc so mission transitions can `cd` your terminal into the next worktree:
 
 ```sh
 echo 'eval "$(px shell-init bash)"' >> ~/.bashrc
 ```
 
-**Post-publish install:** Once published to the npm registry, Parallix can be installed with a single command:
+Alternatively, install from a local tarball (useful for development or when offline):
 
 ```sh
-npm install -g @magnusekdahl/parallix
+npm pack
+npm install -g ./magnus-parallix-*.tgz
 ```
 
-`px setup` is an optional convenience wizard that writes `workflow.config.json` and appends workflow entries to `.gitignore`. Parallix runs on built-in defaults without it — `px setup` becomes useful when you want to configure your verification command, customize the mission layout, or bootstrap the Forgejo review surface (repo, token files, and `review` remote). Forgejo is the PR viewer and publication surface here, not the authority for local branch ancestry or integration.
+Parallix runs on built-in defaults without setup. `px setup` becomes useful when you want to configure your verification command, customize the mission layout, or bootstrap the Forgejo review surface (repo, token files, and `review` remote). Forgejo is the PR viewer and publication surface here, not the authority for local branch ancestry or integration.
+
+`px draft` now works without a pre-existing task file. If the input is free text or a directory path, Parallix creates a synthetic markdown task with classification `unknown` so the later phases, stats, and preflight checks still have a consistent record to work from.
+
+If you already use Backlog.md-style task files, that still works. `px draft task-001` remains valid, and Parallix will use the existing task metadata and classification when it is present.
+
+## Optional task files
 
-Before `px draft`, create a task first. If you already use Backlog.md, create it there. If you do not, create the markdown file yourself under `backlog/tasks/`:
+Structured markdown task files are now optional. They are still useful when you want stable IDs, explicit labels, or an external task-management flow.
 
 ```md
 backlog/tasks/task-001 - my-first-task.md
@@ -98,7 +118,7 @@ dependencies: []
 ---
 ```
 
-Then draft and run it with the actual workflow command:
+Then run the mission by slug:
 
 ```sh
 px draft task-001
@@ -154,7 +174,7 @@ The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md
 
 **Alpha, local-first, and best suited to operators comfortable with Git and CLI workflows.**
 
-- **Distribution:** Local `npm pack` + global install is the current install path. The scoped package `@magnusekdahl/parallix` will be available on the public npm registry after the operator publishes (ADR 0044, ADR 0046). No Homebrew, no Docker image, no standalone binary, and no CI/release automation today.
+- **Distribution:** Published to the public npm registry as `@magnusekdahl/parallix`. Local tarball install (`npm pack`) is also supported. No Homebrew, no Docker image, no standalone binary, and no CI/release automation today.
 - **Review surface:** Forgejo is supported as the hosted PR viewer/publication surface, but the workflow remains local-first and can run without Forgejo when that provider is disabled.
 - **Versioning:** `CHANGELOG.md` is the versioning authority; PATCH bumps are the release discipline.
 - **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-Qwen and mistral paths record honest zeros by design rather than fabricated numbers.

package/docs/authority-reference.md

@@ -116,11 +116,38 @@ Each locked mission may add gates (staging validation, manual QA, ADR creation,
 
 External review by a different agent is mandatory before integration. Valid review: surface exists; reviewer inspects `<primary-branch>..HEAD`; findings cite file references; zero-finding reviews for non-trivial missions include explicit searched-and-found-none evidence.
 
-### 4.4 Integration gate
+### 4.4 Backlog integrity gate (completed/archive-aware board mutations)
+
+A task that has been integrated and moved to `backlog/completed/` (status `done`)
+must not reappear in `backlog/tasks/` with `status: backlog`. Board mutations that
+enumerate and rewrite tasks — notably the reorder / ordinal write path that
+produces the recurring "Reorder tasks in backlog" commits — can otherwise
+regenerate a `backlog/tasks/` copy for a task id whose canonical record now lives
+in `completed/` (or `backlog/archive/`), so the board shows shipped work as
+un-started and `task_list` surfaces the stale backlog copy (TASK-1343).
+
+Parallix enforces the invariant **"never keep a `backlog/tasks/` file for a task
+id that already exists in `backlog/completed/` or `backlog/archive/`"** in two
+places, both in `lib/tools/backlog.js`:
+
+- **Guard / gate:** `checkBacklogIntegrity()` emits a `duplicate-completed` issue
+  for any task id present in both `backlog/tasks/` and a canonical
+  (`completed/` or `archive/`) location. The gate is exercised by
+  `test/backlog_gate.test.js` (fails when a recurrence ships) and by the `px draft`
+  preflight (`lib/commands/draft.js`), which refuses to draft while the duplicate
+  exists. This is in addition to the existing filename-vs-frontmatter id check.
+- **Mutation hygiene:** `pruneStaleBacklogDuplicates()` treats the completed/archive
+  copy as canonical and removes the stale `backlog/tasks/` copy, so a board
+  mutation does not leave a recreated `status: backlog` duplicate behind.
+
+Regression coverage for the reorder-recreates-completed-task scenario lives in
+`test/backlog_reorder_completed_duplicate.test.js`.
+
+### 4.5 Integration gate
 
 Complete when: mission reviewed, landing from the correct integration checkout, Backlog state updated, mission branch and worktree cleanup done.
 
-#### 4.4.1 Integration-time pipeline gates (ADR 0041)
+#### 4.5.1 Integration-time pipeline gates (ADR 0041)
 
 `px integrate` runs integration-time gates before the squash-merge lands. These gates are configured via a repo-side config file and invoked per changed top-level area.
 

package/lib/agents/opencode.js

@@ -14,25 +14,104 @@ function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
 function __setExportCaptureForTest(fn) { _captureExport = fn || captureOpencodeExport; }
 function __setSessionsForTest(mod) { _sessions = mod || sessions; }
 
-// Opencode outputs "Continue  opencode -s ses_<id>" at the end.
-// Telemetry: after session completion, `opencode export` is invoked to extract
-// token-usage data. See opencode-telemetry.js for the parser.
-// Stats hooks in active.js and review-loop.js call recordStageStats which
-// defaults to '0' for tokens when telemetry is null.
+// Test hook: override the cached feature-detect for `--format json` support.
+// Set to true/false to force inclusion/exclusion of the flag regardless of
+// the real binary.  Pass null to reset to the live detect.
+function __setJsonFormatSupportForTest(val) {
+  _jsonFormatSupported = val;
+  _jsonFormatDetectFn = null;
+}
+
+// Test hook: inject a feature-detect function for tests.  This replaces the
+// live shell-out with a stubbed function, making tests hermetic.
+function __setJsonFormatDetectForTest(fn) {
+  _jsonFormatDetectFn = fn;
+  _jsonFormatSupported = null;  // invalidate cache so the detect fn runs
+}
+
+// Session-id recovery for telemetry. After session completion `opencode export`
+// is invoked to extract token-usage data (see opencode-telemetry.js), so the
+// session id MUST be recoverable from the launcher's stdout. Stats hooks in
+// active.js and review-loop.js call recordStageStats which defaults to '0' for
+// tokens when telemetry is null.
+//
+// Two shapes are recognized:
+//   1. Legacy footer:  "Continue  opencode -s ses_<id>"  (older opencode TUI).
+//   2. JSON stream:     `"sessionID":"ses_<id>"`           (opencode v2.0.0
+//      `run --format json`). v2.0.0's plain `run` no longer prints the footer,
+//      so without the JSON field the id is lost and qwen telemetry drops to all
+//      zeros (task-1339). We request `--format json` in buildOpencodeInvocation
+//      so this field is always present.
 const OPENCODE_SESSION_ID_RE = /opencode\s+-s\s+(ses_\S+)/i;
+const OPENCODE_JSON_SESSION_ID_RE = /"sessionID"\s*:\s*"(ses_[^"]+)"/;
 
 function extractOpencodeSessionId(stdout) {
   if (!stdout) return null;
-  const m = OPENCODE_SESSION_ID_RE.exec(stdout);
-  return m ? m[1] : null;
+  const footer = OPENCODE_SESSION_ID_RE.exec(stdout);
+  if (footer) return footer[1];
+  const json = OPENCODE_JSON_SESSION_ID_RE.exec(stdout);
+  return json ? json[1] : null;
 }
 
+// Cached feature-detect for `--format json` support. Set to `false` only when
+// a real invocation proves the flag is rejected (older opencode versions).
+// Tests can inject a canned result via __setJsonFormatSupportForTest.
+let _jsonFormatSupported = null;
+
+// Injectable feature-detect function for tests.  When set, checkJsonFormatSupport()
+// calls this function instead of shelling out, making tests hermetic.
+let _jsonFormatDetectFn = null;
+
 function resolveOpencodeCommand() {
   return 'opencode';
 }
 
-function buildOpencodeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null }) {
+// Lightweight feature-detect: try `opencode --format json --help`.
+// Returns true if the flag is accepted (exit 0 or non-zero for unrelated reasons),
+// false if the flag itself is rejected ("unrecognized" / "unknown option").
+// Results are cached so the check runs at most once in production.
+// Tests can inject a canned result via __setJsonFormatSupportForTest.
+function checkJsonFormatSupport() {
+  if (_jsonFormatSupported !== null) return _jsonFormatSupported;
+  if (_jsonFormatDetectFn) {
+    _jsonFormatSupported = _jsonFormatDetectFn();
+    return _jsonFormatSupported;
+  }
+  try {
+    const { spawnSync } = require('node:child_process');
+    const result = spawnSync('opencode', ['--format', 'json', '--help'], {
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stderr = (result.stderr && result.stderr.toString()) || '';
+    const combined = stderr;
+    // Flag rejected → fallback to legacy invocation.
+    if (/unrecognized|unknown option|no such option|invalid option/i.test(combined)) {
+      _jsonFormatSupported = false;
+      return false;
+    }
+    _jsonFormatSupported = true;
+    return true;
+  } catch (_) {
+    // ENOENT or other spawn errors → assume legacy (no JSON flag).
+    _jsonFormatSupported = false;
+    return false;
+  }
+}
+
+function buildOpencodeInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null, preferJson = true }) {
+  // `--format json` makes opencode stream NDJSON events that each carry a
+  // "sessionID":"ses_..." field. opencode v2.0.0's default `run` output no
+  // longer prints the "Continue  opencode -s ses_..." footer, so JSON is the
+  // only reliable way to recover the session id needed for `opencode export`
+  // telemetry capture (task-1339).
+  //
+  // Compatibility guard: feature-detect the flag on first call; older opencode
+  // versions that reject `--format json` will silently fall back to the legacy
+  // invocation, preserving launch behaviour at the cost of telemetry.
+  const useJson = preferJson && checkJsonFormatSupport();
   const args = ['run', '--pure', '--dangerously-skip-permissions'];
+  if (useJson) args.push('--format', 'json');
   if (model) args.push('-m', model);
   // Only resume when the marker explicitly says so (resume=true).
   // sessionId from a stale cross-family marker must be ignored when resume=false.
@@ -164,6 +243,16 @@ function startOpencodeAgent({
     return result;
   }
 
+  // Detect whether `--format json` was rejected at runtime (e.g. older opencode
+  // that wasn't caught by the feature-detect).  If so, retry the invocation
+  // without the flag so the prompt still runs (telemetry will be lost but the
+  // agent won't fail outright).
+  function isJsonFlagError(result) {
+    if (!result) return false;
+    const text = failureText(result);
+    return (/\bunrecognized option\b|\bunknown option\b|\bno such option\b|\binvalid option\b|\bunrecognized flag\b|\bunknown flag\b/i).test(text);
+  }
+
   async function processResult(result) {
     if (result && result.stdout) {
       result.sessionId = extractOpencodeSessionId(result.stdout);
@@ -186,14 +275,29 @@ function startOpencodeAgent({
     return result;
   }
 
-  async function staleSessionHandler(invocation) {
+  async function runWithJsonFallback(invocation) {
     let result = await runInvocationWithRetry(invocation);
+    // Runtime fallback: if the first invocation used --format json but the
+    // binary rejected it, retry without the flag so the prompt still executes.
+    if (isJsonFlagError(result) && invocation.args.includes('--format')) {
+      const legacyInv = buildOpencodeInvocation({
+        prompt, worktree, env, resume, sessionId, model, preferJson: false,
+      });
+      result = await runInvocationWithRetry(legacyInv);
+      // Mark that we fell back so callers know telemetry may be absent.
+      if (result) result._jsonFallback = true;
+    }
+    return result;
+  }
+
+  async function staleSessionHandler(invocation) {
+    let result = await runWithJsonFallback(invocation);
     if (isStaleSessionResult(result) && worktree && resume) {
       try {
         _sessions.clearSession(worktree, slug, role);
       } catch (_) { /* best-effort */ }
       const freshInv = buildOpencodeInvocation({ prompt, worktree, env, resume: false, sessionId: null, model });
-      result = await runInvocationWithRetry(freshInv);
+      result = await runWithJsonFallback(freshInv);
     }
     return processResult(result);
   }
@@ -214,5 +318,7 @@ module.exports = {
   shouldRetryOpencodeFailure,
   __setSpawnAndTeeForTest,
   __setExportCaptureForTest,
-  __setSessionsForTest
+  __setSessionsForTest,
+  __setJsonFormatSupportForTest,
+  __setJsonFormatDetectForTest,
 };

package/lib/agents/stage-telemetry.js

@@ -27,7 +27,16 @@ const { codexHomeRoot, extractCodexTelemetry } = require('./codex');
 function resolveStageTelemetry({ worktree, result, sinceMs = 0 } = {}) {
   if (!result || !result.telemetry) return null;
   try {
-    return extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: sinceMs || 0 }) || result.telemetry;
+    const codexT = extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: sinceMs || 0 });
+    // Guard against stale Codex rollouts bleeding into non-Codex stages:
+    // if the launcher attached telemetry with a provider that differs from
+    // what Codex would produce (e.g. anthropic vs openai), discard the Codex
+    // read and use the launcher-attached telemetry instead.
+    if (codexT && codexT.provider && result.telemetry.provider
+        && codexT.provider.toLowerCase() !== result.telemetry.provider.toLowerCase()) {
+      return result.telemetry;
+    }
+    return codexT || result.telemetry;
   } catch (_) {
     // Codex rollout unreadable: fall back to this stage's launcher telemetry.
     return result.telemetry;

package/lib/commands/active.js

@@ -461,7 +461,7 @@ async function runHandoffAndReview(slug, worktree, agent, {
   }
 
   log(`\nStarting autonomous review loop (implementer: ${fmt.agent(agent)})...`);
-  _startReviewLoop(slug, { implementer: agent, worktree });
+  _startReviewLoop(slug, { implementer: agent, worktree, recordStageStatsSafeFn: review.recordStageStatsSafe });
   return true;
 }
 

package/lib/commands/draft.js

@@ -1,9 +1,10 @@
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const fmt = require('../core/fmt');
 const { git, getWorktreeStatus } = require('../core/git');
 const { startDraftAgent, selectAgent, readAgentConfigOrExit } = require('../agents/agents');
-const { resolveTaskFile, enforceTaskAssignee, reportTaskResolution, checkBacklogIntegrity, transitionTask, getTaskClassification } = require('../tools/backlog');
+const { resolveTaskFile, enforceTaskAssignee, reportTaskResolution, checkBacklogIntegrity, transitionTask, getTaskClassification, getTaskStorage } = require('../tools/backlog');
 const { findMissionArea, findMissionDir, inferSlug, getMissionYear, resolveMainRepo, conventionalWorktreePath, squashTrailingBacklogNoiseIntoPreviousMission, resolveWorktree, getPrimaryBranch, missionBranchName, missionDirForSlug, detectLaunchBaseBranch } = require('../core/mission-utils');
 const { transitionVirtual } = require('../core/state-map');
 const stats = require('./stats');
@@ -14,6 +15,80 @@ const { unquoteGitStatusPath } = require('./active');
 
 const DRAFT_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'draft.md');
 const MISSION_SCAFFOLD_PATH = path.join(__dirname, '..', '..', 'templates', 'mission-scaffold.md');
+const SYNTHETIC_SLUG_PREFIX = 'adhoc-';
+
+function slugifyDraftIntent(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^[./\\]+/, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+    .slice(0, 64);
+}
+
+function syntheticTaskId(slug, seed) {
+  const hash = crypto.createHash('sha1').update(String(seed || slug)).digest('hex').slice(0, 8).toUpperCase();
+  const prefix = slug.startsWith(SYNTHETIC_SLUG_PREFIX) ? 'ADHOC' : 'TASK';
+  const base = slug
+    .replace(/^(task|adhoc)-/i, '')
+    .replace(/[^a-z0-9]+/gi, '-')
+    .toUpperCase();
+  return `${prefix}-${base}-${hash}`;
+}
+
+function resolveDraftTarget(rawInput, cwd = process.cwd()) {
+  const explicit = String(rawInput || '').trim();
+  if (!explicit) return null;
+
+  if (explicit.toLowerCase().startsWith('task-')) {
+    return {
+      slug: explicit.toLowerCase(),
+      syntheticTask: null,
+    };
+  }
+
+  if (explicit.toLowerCase().startsWith(SYNTHETIC_SLUG_PREFIX)) {
+    return {
+      slug: explicit.toLowerCase(),
+      syntheticTask: {
+        title: explicit,
+        intent: explicit,
+        id: syntheticTaskId(explicit.toLowerCase(), explicit),
+        source: 'synthetic-explicit-slug',
+      },
+    };
+  }
+
+  const absoluteCandidate = path.resolve(cwd, explicit);
+  if (fs.existsSync(absoluteCandidate) && fs.statSync(absoluteCandidate).isDirectory()) {
+    const baseName = path.basename(absoluteCandidate);
+    const normalizedBase = slugifyDraftIntent(baseName) || 'project';
+    const slug = `${SYNTHETIC_SLUG_PREFIX}${normalizedBase}`;
+    return {
+      slug,
+      syntheticTask: {
+        title: `Draft mission for ${baseName}`,
+        intent: `Directory input: ${explicit}`,
+        id: syntheticTaskId(slug, absoluteCandidate),
+        source: 'synthetic-directory',
+      },
+    };
+  }
+
+  const normalized = slugifyDraftIntent(explicit) || 'mission';
+  const slug = normalized.startsWith(SYNTHETIC_SLUG_PREFIX) ? normalized : `${SYNTHETIC_SLUG_PREFIX}${normalized}`;
+  return {
+    slug,
+    syntheticTask: {
+      title: explicit,
+      intent: explicit,
+      id: syntheticTaskId(slug, explicit),
+      source: 'synthetic-free-text',
+    },
+  };
+}
 
 async function runDraftCommand(args, {
   inferSlugFn = inferSlug,
@@ -47,8 +122,9 @@ async function runDraftCommand(args, {
   logFn = fmt.log.plain,
   errorFn = fmt.log.plainError
 } = {}) {
-  const explicitSlug = args[0];
-  const slug = inferSlugFn(explicitSlug);
+  const explicitInput = args[0];
+  const draftTarget = resolveDraftTarget(explicitInput) || { slug: inferSlugFn(explicitInput), syntheticTask: null };
+  const slug = draftTarget.slug;
   if (!slug) {
     errorFn(fmt.status('FAIL', 'Usage: px draft <slug> [--agent <family>]'));
     exitFn(1);
@@ -56,6 +132,7 @@ async function runDraftCommand(args, {
   }
 
   const normalizedSlug = slug.toLowerCase();
+  const syntheticTask = draftTarget.syntheticTask;
 
   // Allow operators to pin the agent family via CLI flag instead of WORKFLOW_AGENT env var.
   function flagValue(arr, flag, name) {
@@ -94,20 +171,24 @@ async function runDraftCommand(args, {
 
   // Preflight: Ensure Backlog task exists and is unambiguous before side effects
   const mainResolution = resolveTaskFileFn(normalizedSlug, mainRepo);
-  if (!mainResolution.ok) {
+  if (!mainResolution.ok && !syntheticTask) {
     reportTaskResolutionFn(mainResolution, normalizedSlug, errorFn);
     exitFn(1);
     return;
   }
 
   // Preflight: Backlog integrity check (filename vs frontmatter ID)
-  const relevantIssues = checkBacklogIntegrityFn(mainRepo, normalizedSlug);
+  const relevantIssues = syntheticTask ? [] : checkBacklogIntegrityFn(mainRepo, normalizedSlug);
   if (relevantIssues.length > 0) {
     errorFn(fmt.status('FAIL', `Backlog integrity issues detected for ${normalizedSlug}:`));
     relevantIssues.forEach(issue => {
-      logFn(`  - ${fmt.path(issue.file)}: filename ID (${fmt.bold(issue.filenameId)}) does not match frontmatter ID (${fmt.bold(issue.frontmatterId)})`);
+      if (issue.type === 'duplicate-completed') {
+        logFn(`  - ${fmt.path(issue.file)}: task ${fmt.bold(issue.taskId)} already has a canonical copy in ${fmt.path(issue.canonicalFile)}; this backlog/tasks copy is stale.`);
+      } else {
+        logFn(`  - ${fmt.path(issue.file)}: filename ID (${fmt.bold(issue.filenameId)}) does not match frontmatter ID (${fmt.bold(issue.frontmatterId)})`);
+      }
     });
-    logFn('Repair: Fix filename/id mismatch in backlog/ tasks before drafting.');
+    logFn('Repair: Fix filename/id mismatch, or remove the stale backlog/tasks copy of a completed/archived task, before drafting.');
     exitFn(1);
     return;
   }
@@ -156,11 +237,11 @@ async function runDraftCommand(args, {
   ensureMissionBaseBranchRecordedFn(missionFile, recordedBase, { logFn });
 
   logFn(fmt.bold('Step 4: Ensuring Backlog task exists in worktree...'));
-  if (!bootstrapBacklogTaskFn(targetWorktree, mainRepo, normalizedSlug, { logFn, errorFn })) {
-    errorFn(fmt.status('FAIL', `Backlog task for ${normalizedSlug} is missing in ${getPrimaryBranch()} and could not be bootstrapped.`));
-    logFn(`Repair: Create the task file in backlog/tasks/ on ${getPrimaryBranch()} before drafting the mission.`);
-    logFn(`If Backlog.md is installed: ${fmt.command(`backlog_task_create --title \"Mission: ${normalizedSlug}\"`)}`);
-    logFn(`Without Backlog.md: create ${fmt.path(`backlog/tasks/${normalizedSlug} - <title>.md`)} with frontmatter id ${fmt.bold(normalizedSlug.toUpperCase())}.`);
+  if (!bootstrapBacklogTaskFn(targetWorktree, mainRepo, normalizedSlug, { logFn, errorFn, syntheticTask })) {
+    const { tasksDir } = getTaskStorage(targetWorktree);
+    const taskDirHint = path.relative(targetWorktree, tasksDir).split(path.sep).join('/');
+    errorFn(fmt.status('FAIL', `Backlog task for ${normalizedSlug} could not be prepared in the mission worktree.`));
+    logFn(`Repair: create the task with your task adapter, or add ${fmt.path(`${taskDirHint}/${normalizedSlug} - <title>.md`)} manually.`);
     exitFn(1);
     return;
   }
@@ -507,7 +588,8 @@ function bootstrapBacklogTask(targetWorktree, mainRepo, slug, {
   reportTaskResolutionFn = reportTaskResolution,
   gitFn = git,
   logFn = fmt.log.plain,
-  errorFn = fmt.log.plainError
+  errorFn = fmt.log.plainError,
+  syntheticTask = null
 } = {}) {
   const taskResolution = resolveTaskFileFn(slug, targetWorktree);
   if (taskResolution.ok) {
@@ -520,6 +602,43 @@ function bootstrapBacklogTask(targetWorktree, mainRepo, slug, {
     return false;
   }
 
+  if (syntheticTask) {
+    const { tasksDir } = getTaskStorage(targetWorktree);
+    const taskPath = path.join(tasksDir, `${slug} - ${slugifyDraftIntent(syntheticTask.title || slug) || 'mission'}.md`);
+    const body = [
+      '---',
+      `id: ${syntheticTask.id || syntheticTaskId(slug, syntheticTask.intent || slug)}`,
+      `title: ${syntheticTask.title || slug}`,
+      'status: backlog',
+      'assignee: []',
+      "created_date: '" + new Date().toISOString().slice(0, 16).replace('T', ' ') + "'",
+      'labels: [unknown]',
+      'dependencies: []',
+      'source: synthetic',
+      '---',
+      '',
+      '## Description',
+      '',
+      syntheticTask.intent || `Synthetic task created for ${slug}.`,
+      ''
+    ].join('\n');
+
+    fs.mkdirSync(path.dirname(taskPath), { recursive: true });
+    fs.writeFileSync(taskPath, body, 'utf8');
+    logFn(fmt.status('PASS', `Created synthetic backlog task at ${fmt.path(path.relative(targetWorktree, taskPath))}.`));
+
+    try {
+      const relativePath = path.relative(targetWorktree, taskPath);
+      gitFn(['-C', targetWorktree, 'add', relativePath]);
+      gitFn(['-C', targetWorktree, 'commit', '-m', `backlog(${slug}): create synthetic task`]);
+      logFn(fmt.status('PASS', 'Committed synthetic task in worktree.'));
+    } catch (error) {
+      errorFn(fmt.status('FAIL', `Could not commit synthetic task: ${error.message}`));
+      return false;
+    }
+    return true;
+  }
+
   logFn(fmt.status('INFO', `Backlog task for ${fmt.slug(slug)} not found in worktree. Attempting to bootstrap from ${fmt.path(mainRepo)}...`));
   const mainResolution = resolveTaskFileFn(slug, mainRepo);
   if (!mainResolution.ok) {
@@ -559,6 +678,16 @@ function resolveTaskPath(slug, promptRoot) {
   return path.join(promptRoot, 'backlog', 'tasks', `<${slug}>.md`);
 }
 
+function resolveClassificationInstructions(taskPath) {
+  if (taskPath && fs.existsSync(taskPath)) {
+    const content = fs.readFileSync(taskPath, 'utf8');
+    if (/^source:\s*synthetic\s*$/mi.test(content)) {
+      return 'because this task was synthesized by the harness, preserve the `unknown` label unless you have concrete repo-specific evidence to replace it. Do not add a separate frontmatter field for mission type.';
+    }
+  }
+  return 'set exactly one of `ai_sdlc` or `user_value` in the Backlog task labels — no other value. Use `ai_sdlc` for workflow, prompt, or agent-fix work; use `user_value` for everything else (including code tech debt). Do not add a separate frontmatter field for mission type.';
+}
+
 function buildDraftPrompt(slug, { rootDir = process.cwd(), worktree = null } = {}) {
   const template = fs.readFileSync(DRAFT_PROMPT_PATH, 'utf8');
   const promptRoot = worktree || rootDir;
@@ -572,6 +701,7 @@ function buildDraftPrompt(slug, { rootDir = process.cwd(), worktree = null } = {
     .replaceAll('{{missionPath}}', missionPath)
     .replaceAll('{{missionDir}}', missionDir)
     .replaceAll('{{taskPath}}', taskPath)
+    .replaceAll('{{classificationInstructions}}', resolveClassificationInstructions(taskPath))
     .replaceAll('{{verifyCmd}}', resolveVerifyCmd(promptRoot));
 }
 
@@ -584,7 +714,11 @@ function validateDraftClassification(slug, worktree, {
   errorFn = fmt.log.plainError
 } = {}) {
   try {
-    const { classification } = resolveMissionClassificationFn(slug, worktree);
+    const { classification, error: classificationError } = resolveMissionClassificationFn(slug, worktree);
+    if (!classification) {
+      if (classificationError) errorFn(fmt.status('FAIL', classificationError));
+      return { ok: true, classification: null };
+    }
     return { ok: true, classification };
   } catch (error) {
     if (error.message.includes('Missing or invalid classification')) {
@@ -600,7 +734,11 @@ function normalizeDraftClassification(slug, worktree, {
   errorFn = fmt.log.plainError
 } = {}) {
   try {
-    const { classification } = resolveMissionClassificationFn(slug, worktree);
+    const { classification, error: classificationError } = resolveMissionClassificationFn(slug, worktree);
+    if (!classification) {
+      if (classificationError) errorFn(fmt.status('FAIL', classificationError));
+      return { ok: false, reason: 'missing-classification' };
+    }
     return { ok: true, classification };
   } catch (error) {
     if (error.message.includes('Missing or invalid classification')) {