@magnusekdahl/parallix 1.0.0 → 1.0.2

package/lib/review/review-loop.js

@@ -33,14 +33,45 @@ const { resolveStageTelemetry } = require('../agents/stage-telemetry');
 // guarantees at most one of implementer/reviewer is codex); other families
 // record honest zeros (task-1251).
 //
-// Codex writes a fresh-counter rollout per round, so we sum total_token_usage
-// across every rollout since the review loop started (`sinceMs`). This is
-// recomputed from the rollout files each round — idempotent across the workflow
-// process being resumed mid-mission — and the per-(mission,stage) upsert leaves
-// the codex role's full multi-round total. `result.telemetry` is used only as a
-// signal that codex ran this round, so the window-sum is attributed to the right
-// role and never double-counted onto the non-codex stage.
-function recordStageStatsSafe(kind, { slug, rootDir, worktree, implementer, reviewer, result, sinceMs, log, error }) {
+// Codex writes a fresh-counter rollout per launch, so we sum total_token_usage
+// across every rollout since the FIRST launch for this stored mission phase and
+// agent family. For non-Codex families we accumulate launcher-attached telemetry
+// one launch at a time, de-duped via review-state metadata, so Claude/Qwen rows
+// are cumulative too. A family switch creates a separate row instead of mixing
+// agents in one record.
+function stageLaunchFingerprint(agentFamily, result) {
+  return [
+    String(agentFamily || '').trim().toLowerCase(),
+    result && result.sessionId ? String(result.sessionId) : '',
+    result && result.startedAt ? String(result.startedAt) : '',
+    result && result.endedAt ? String(result.endedAt) : '',
+    result && result.status !== undefined && result.status !== null ? String(result.status) : '',
+  ].join('|');
+}
+
+function markStageLaunchRecorded(state, { stage, agentFamily, result, slug, worktree, writeReviewStateFn = writeReviewState } = {}) {
+  if (!state || !agentFamily) return true;
+  const key = stageWindowKey(stage, agentFamily);
+  const fingerprint = stageLaunchFingerprint(agentFamily, result);
+  const recordedStageLaunches = state.metadata && typeof state.metadata === 'object'
+    ? (state.metadata.recordedStageLaunches || {})
+    : {};
+  const recorded = Array.isArray(recordedStageLaunches[key]) ? recordedStageLaunches[key] : [];
+  if (recorded.includes(fingerprint)) {
+    return false;
+  }
+  if (!state.metadata || typeof state.metadata !== 'object') {
+    state.metadata = {};
+  }
+  state.metadata.recordedStageLaunches = {
+    ...(state.metadata.recordedStageLaunches || {}),
+    [key]: [...recorded, fingerprint].slice(-20),
+  };
+  writeReviewStateFn(slug, state, worktree);
+  return true;
+}
+
+function recordStageStatsSafe(kind, { stage, slug, rootDir, worktree, implementer, reviewer, result, sinceMs, log, error, state, writeReviewStateFn = writeReviewState }) {
   let durationMinutes = 0;
   if (result && result.startedAt && result.endedAt) {
     durationMinutes = (Date.parse(result.endedAt) - Date.parse(result.startedAt)) / 60000;
@@ -51,8 +82,18 @@ function recordStageStatsSafe(kind, { slug, rootDir, worktree, implementer, revi
   // (task-1274), bounded to this stage by sinceMs (task-1285 F6).
   const telemetry = resolveStageTelemetry({ worktree, result, sinceMs });
   try {
-    const fn = kind === 'review' ? stats.recordReviewStats : stats.recordActiveStats;
-    fn({ slug, rootDir, implementer, reviewer, telemetry, durationMinutes });
+    const actorFamily = kind === 'review' ? reviewer : implementer;
+    if (state && !markStageLaunchRecorded(state, {
+      stage,
+      agentFamily: actorFamily,
+      result,
+      slug,
+      worktree,
+      writeReviewStateFn
+    })) {
+      return;
+    }
+    stats.accumulateStageStats({ stage, slug, rootDir, implementer, reviewer, telemetry, durationMinutes });
   } catch (err) {
     // Best-effort: never escalate to the fatal `error` channel.
     log(fmt.status('WARN', `Could not record ${kind} stats for ${slug}: ${err.message}`));
@@ -135,6 +176,25 @@ function persistNormalizedPhaseRepair(slug, state, worktree, { log = fmt.log.pla
   state.phaseOriginal = null;
 }
 
+function stageWindowKey(stage, agentFamily) {
+  const normalizedStage = String(stage || 'default').trim().toLowerCase() || 'default';
+  const normalizedAgent = String(agentFamily || '').trim().toLowerCase();
+  return `${normalizedStage}:${normalizedAgent}`;
+}
+
+// Window the Codex telemetry read to the CURRENT launch's start so each round
+// contributes only its own rollouts. Earlier rounds' rollouts have an mtime
+// strictly before this launch's startedAt and are excluded, so the per-round
+// deltas accumulate (via accumulateStageStats) to the family's true total
+// instead of re-summing a cumulative-since-first-launch window every round.
+// Resume-idempotency is provided separately by the launch fingerprint in
+// markStageLaunchRecorded, so the window itself does not need to persist.
+function stageLaunchSinceMs(result) {
+  const startedAt = result && result.startedAt ? String(result.startedAt) : '';
+  const startedMs = startedAt ? Date.parse(startedAt) : NaN;
+  return Number.isFinite(startedMs) ? startedMs : 0;
+}
+
 // ============================================================================
 // Main Review Loop
 // ============================================================================
@@ -200,7 +260,8 @@ async function startReviewLoop(slug, opts = {}) {
     gitFn = git,
     isReviewProviderEnabledFn = undefined,
     legacyIsForgejoReviewEnabledFn = null,
-    isForgejoReviewEnabledFn = null
+    isForgejoReviewEnabledFn = null,
+    recordStageStatsSafeFn = () => {}
   } = opts;
   let prNumber = null;
   isContinue = Boolean(isContinue || continueFlag);
@@ -635,13 +696,14 @@ async function startReviewLoop(slug, opts = {}) {
 
             // Record review-stage telemetry immediately after the reviewer runs,
             // so the worktree's newest codex rollout is this reviewer's session.
-            // Codex sessions are resumed across rounds, so total_token_usage is
-            // cumulative for the reviewer role; the per-round upsert overwrites,
-            // leaving the final row = the reviewer's full-mission usage.
-            recordStageStatsSafe('review', {
-              slug, rootDir: worktree, worktree, reviewer, implementer,
+            // The window is bounded to this round's launch so each round adds
+            // only its own usage; accumulateStageStats sums the rounds into one
+            // cumulative row per reviewer family.
+            const reviewSinceMs = stageLaunchSinceMs(reviewerLaunchResult && reviewerLaunchResult.result);
+            recordStageStatsSafeFn('review', {
+              stage: 'review', slug, rootDir: worktree, worktree, reviewer, implementer,
               result: reviewerLaunchResult && reviewerLaunchResult.result,
-              sinceMs: state.startedAt ? Date.parse(state.startedAt) : 0, log, error
+              sinceMs: reviewSinceMs, log, error, state, writeReviewStateFn
             });
           }
 
@@ -850,13 +912,15 @@ async function startReviewLoop(slug, opts = {}) {
           state, slug, worktree, taskResolution, log, writeReviewStateFn, enforceTaskAssigneeFn
         });
 
-        // Record active-stage telemetry immediately after the implementer runs.
-        // Same cumulative-session semantics as the review stage above; the final
-        // round's upsert leaves the implementer's full-mission usage.
-        recordStageStatsSafe('active', {
-          slug, rootDir: worktree, worktree, implementer, reviewer,
+        // Record follow-up telemetry immediately after the implementer runs.
+        // This is intentionally a separate stored phase from the initial
+        // execute/active launch. The window is bounded to this round's launch
+        // so each act-on-review round adds only its own usage.
+        const followUpSinceMs = stageLaunchSinceMs(implementerLaunchResult && implementerLaunchResult.result);
+        recordStageStatsSafeFn('active', {
+          stage: 'follow-up', slug, rootDir: worktree, worktree, implementer, reviewer,
           result: implementerLaunchResult && implementerLaunchResult.result,
-          sinceMs: state.startedAt ? Date.parse(state.startedAt) : 0, log, error
+          sinceMs: followUpSinceMs, log, error, state, writeReviewStateFn
         });
       }
 
@@ -1000,5 +1064,7 @@ module.exports = {
   rebaseBeforeReviewRound,
   applyAgentFallback,
   persistNormalizedPhaseRepair,
-  startReviewLoop
+  stageLaunchSinceMs,
+  startReviewLoop,
+  recordStageStatsSafe
 };

package/lib/review/review.js

@@ -16,7 +16,7 @@ const { POLL_TIMEOUT, delay, resolvePollIntervalMs, resolvePollTimeoutMs, format
 const { buildMetadataFooter, reviewArtifactPath, readArtifactFile, deleteArtifactFile, normalizeReviewVerdict, normalizeDisposition, postWorkflowComment, postWorkflowReview, consumeReviewerArtifacts, consumeImplementerArtifacts } = require('./review-artifacts');
 
 // Re-export from review-loop module
-const { maybeUpdateGraphifyBeforeReview, commitSafeMissionArtifacts, rebaseBeforeReviewRound, applyAgentFallback, persistNormalizedPhaseRepair, startReviewLoop } = require('./review-loop');
+const { maybeUpdateGraphifyBeforeReview, commitSafeMissionArtifacts, rebaseBeforeReviewRound, applyAgentFallback, persistNormalizedPhaseRepair, startReviewLoop, recordStageStatsSafe } = require('./review-loop');
 
 // Re-export from review-commands module
 const {

package/lib/tools/backlog.js

@@ -3,15 +3,18 @@ const path = require('path');
 const { git } = require('../core/git');
 const { WORKFLOW_AGENT_NAMES } = require('../agents/agents');
 const fmt = require('../core/fmt');
+const { resolveTaskStorage } = require('../core/product-config');
 
 function getSupportedAgents() {
   return WORKFLOW_AGENT_NAMES;
 }
 
+function getTaskStorage(rootDir = process.cwd()) {
+  return resolveTaskStorage(rootDir);
+}
+
 function findTaskFiles(slug, rootDir = process.cwd()) {
-  const tasksDir = path.join(rootDir, 'backlog', 'tasks');
-  const completedDir = path.join(rootDir, 'backlog', 'completed');
-  const archivedDir = path.join(rootDir, 'backlog', 'archive', 'tasks');
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
   const sortByBacklogState = (filePath) => {
     if (filePath.startsWith(tasksDir + path.sep)) return 0;
     if (filePath.startsWith(completedDir + path.sep)) return 1;
@@ -35,7 +38,7 @@ function findTaskFiles(slug, rootDir = process.cwd()) {
 function resolveTaskFile(slug, rootDir = process.cwd()) {
   let matches = findTaskFiles(slug, rootDir);
   const normalizedId = slug.toUpperCase();
-  const archivedDir = path.join(rootDir, 'backlog', 'archive', 'tasks');
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
   const preferSameTaskInHigherPriorityDir = (candidateMatches) => {
     if (candidateMatches.length < 2) return null;
     const [preferred, ...rest] = candidateMatches;
@@ -56,8 +59,6 @@ function resolveTaskFile(slug, rootDir = process.cwd()) {
 
   if (matches.length === 0) {
     // Hardening: If no prefix match, search ALL task files for an exact ID match
-    const tasksDir = path.join(rootDir, 'backlog', 'tasks');
-    const completedDir = path.join(rootDir, 'backlog', 'completed');
     const allFiles = [
       ...(fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir).map(f => path.join(tasksDir, f)) : []),
       ...(fs.existsSync(completedDir) ? fs.readdirSync(completedDir).map(f => path.join(completedDir, f)) : []),
@@ -121,6 +122,9 @@ function findTaskFile(slug, rootDir = process.cwd()) {
 
 function reportTaskResolution(result, slug, log = fmt.log.plain) {
   if (result.ok) return;
+  const { tasksDir, completedDir } = getTaskStorage(process.cwd());
+  const taskHint = path.relative(process.cwd(), tasksDir).split(path.sep).join('/');
+  const completedHint = path.relative(process.cwd(), completedDir).split(path.sep).join('/');
 
   if (result.reason === 'ambiguous') {
     log(fmt.status('FAIL', `Backlog task resolution is ambiguous for slug: ${fmt.slug(slug)}`));
@@ -128,21 +132,32 @@ function reportTaskResolution(result, slug, log = fmt.log.plain) {
     result.matches.forEach(m => log(`  - ${m}`));
     log(fmt.status('INFO', 'Repair: Ensure only one task has the filename prefix or matching "id:" frontmatter.'));
   } else {
-    log(fmt.status('FAIL', `Backlog task for ${fmt.slug(slug)} not found in backlog/tasks/ or backlog/completed/.`));
+    log(fmt.status('FAIL', `Backlog task for ${fmt.slug(slug)} not found in ${fmt.path(taskHint)}/ or ${fmt.path(completedHint)}/.`));
     log(fmt.status('INFO', 'Create the task file first.'));
-    log(fmt.status('INFO', 'Repair: px draft requires an existing Backlog.md-style task file.'));
-    log(fmt.status('INFO', `If Backlog.md is installed, create one with ${fmt.command(`backlog_task_create --title "Mission: ${slug}"`)}.`));
-    log(fmt.status('INFO', `Without Backlog.md, create ${fmt.path(`backlog/tasks/${slug} - <title>.md`)} with frontmatter id ${fmt.bold(slug.toUpperCase())}.`));
+    log(fmt.status('INFO', 'Repair: create the task with your task adapter, or add a markdown task file manually.'));
+    log(fmt.status('INFO', `Manual fallback: create ${fmt.path(`${taskHint}/${slug} - <title>.md`)} with frontmatter id ${fmt.bold(slug.toUpperCase())}.`));
   }
 }
 
+function taskIdFromFilename(file) {
+  // Extract ID from filename prefix (e.g., task-093 or task-093.01)
+  const filenameMatch = file.match(/^(task-\d+(?:\.\d+)?)/i);
+  return filenameMatch ? filenameMatch[1].toUpperCase() : null;
+}
+
 function checkBacklogIntegrity(rootDir = process.cwd(), slug = null) {
-  const tasksDir = path.join(rootDir, 'backlog', 'tasks');
-  const completedDir = path.join(rootDir, 'backlog', 'completed');
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
   const issues = [];
   const normalizedSlug = slug ? slug.toLowerCase() : null;
 
-  const scan = (dir) => {
+  // Track where each task id lives so we can detect the same id appearing in
+  // both backlog/tasks/ and backlog/completed/ (or backlog/archive/) — the
+  // reorder-recreates-completed-task defect (TASK-1343). The completed/archive
+  // copy is canonical; a backlog/tasks/ copy alongside it is stale.
+  const tasksLocations = new Map();      // id -> rel path in tasks/
+  const canonicalLocations = new Map();  // id -> rel path in completed|archive
+
+  const scan = (dir, { canonical = false } = {}) => {
     if (!fs.existsSync(dir)) return;
     const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
     for (const file of files) {
@@ -150,22 +165,26 @@ function checkBacklogIntegrity(rootDir = process.cwd(), slug = null) {
         continue;
       }
       const filePath = path.join(dir, file);
+      const filenameId = taskIdFromFilename(file);
+      if (!filenameId) continue;
+      const relPath = path.relative(rootDir, filePath);
+
+      if (canonical) {
+        if (!canonicalLocations.has(filenameId)) canonicalLocations.set(filenameId, relPath);
+      } else if (!tasksLocations.has(filenameId)) {
+        tasksLocations.set(filenameId, relPath);
+      }
+
       try {
         const content = fs.readFileSync(filePath, 'utf8');
 
-        // Extract ID from filename prefix (e.g., task-093 or task-093.01)
-        const filenameMatch = file.match(/^(task-\d+(?:\.\d+)?)/i);
-        if (!filenameMatch) continue;
-
-        const filenameId = filenameMatch[1].toUpperCase();
-
         // Extract ID from frontmatter
         const idMatch = content.match(/^id:\s*([^\r\n]+)/m);
         if (idMatch) {
           const frontmatterId = idMatch[1].trim().toUpperCase();
           if (frontmatterId !== filenameId) {
             issues.push({
-              file: path.relative(rootDir, filePath),
+              file: relPath,
               type: 'id-mismatch',
               filenameId,
               frontmatterId
@@ -179,10 +198,51 @@ function checkBacklogIntegrity(rootDir = process.cwd(), slug = null) {
   };
 
   scan(tasksDir);
-  scan(completedDir);
+  scan(completedDir, { canonical: true });
+  scan(archivedDir, { canonical: true });
+
+  for (const [id, taskPath] of tasksLocations) {
+    const canonicalPath = canonicalLocations.get(id);
+    if (canonicalPath) {
+      issues.push({
+        file: taskPath,
+        type: 'duplicate-completed',
+        taskId: id,
+        canonicalFile: canonicalPath
+      });
+    }
+  }
+
   return issues;
 }
 
+/**
+ * Drop backlog/tasks/ copies of task ids whose canonical record already lives
+ * in backlog/completed/ or backlog/archive/. Used to make any board mutation
+ * (reorder / ordinal write) completed- and archive-aware: the completed copy is
+ * treated as canonical and the stale backlog/tasks/ copy is removed. Returns
+ * the list of removed { taskId, file, canonicalFile } records. See TASK-1343.
+ */
+function pruneStaleBacklogDuplicates(rootDir = process.cwd()) {
+  const removed = [];
+  const duplicates = checkBacklogIntegrity(rootDir)
+    .filter(issue => issue.type === 'duplicate-completed');
+
+  for (const dup of duplicates) {
+    const absPath = path.join(rootDir, dup.file);
+    try {
+      if (fs.existsSync(absPath)) {
+        fs.rmSync(absPath);
+        removed.push({ taskId: dup.taskId, file: dup.file, canonicalFile: dup.canonicalFile });
+      }
+    } catch (_) {
+      // ignore removal errors; the integrity gate will still surface the duplicate
+    }
+  }
+
+  return removed;
+}
+
 function getTaskStatus(taskFilePath) {
   if (!taskFilePath || !fs.existsSync(taskFilePath)) return null;
   const content = fs.readFileSync(taskFilePath, 'utf8');
@@ -233,8 +293,7 @@ function completeTask(slug, rootDir = process.cwd()) {
 
   const taskFilePath = resolution.taskFile;
   const fileName = path.basename(taskFilePath);
-  const tasksDir = path.join(rootDir, 'backlog', 'tasks');
-  const completedDir = path.join(rootDir, 'backlog', 'completed');
+  const { tasksDir, completedDir } = getTaskStorage(rootDir);
 
   if (!taskFilePath.includes(tasksDir)) {
     // Already in completed or somewhere else
@@ -501,6 +560,7 @@ function getTaskClassification(taskFilePath) {
       .map(s => s.toLowerCase());
     if (labels.includes('ai_sdlc')) matches.add('ai_sdlc');
     if (labels.includes('user_value')) matches.add('user_value');
+    if (labels.includes('unknown')) matches.add('unknown');
   }
 
   const inlineMatch = content.match(/^labels:[ \t]*\[(.*?)\]/m);
@@ -510,6 +570,7 @@ function getTaskClassification(taskFilePath) {
       .map(s => s.toLowerCase());
     if (labels.includes('ai_sdlc')) matches.add('ai_sdlc');
     if (labels.includes('user_value')) matches.add('user_value');
+    if (labels.includes('unknown')) matches.add('unknown');
   }
 
   return matches.size === 1 ? [...matches][0] : null;
@@ -662,6 +723,8 @@ module.exports = {
   resolveTaskFile,
   reportTaskResolution,
   checkBacklogIntegrity,
+  pruneStaleBacklogDuplicates,
+  getTaskStorage,
   getTaskStatus,
   setTaskStatus,
   transitionTask,

package/lib/tools/gatekeeper.js

@@ -3,7 +3,7 @@ const path = require('path');
 const fmt = require('../core/fmt');
 
 const { findMissionDir, findCheckpoints, missionDirForSlug, missionBranchName } = require('../core/mission-utils');
-const { resolveTaskFile } = require('./backlog');
+const { resolveTaskFile, getTaskStorage } = require('./backlog');
 const { readToken, postReview } = require('./forgejo');
 
 const DEFAULT_GATEKEEPER_USER = 'forgejo-gatekeeper';
@@ -42,8 +42,11 @@ function checkMandatoryFiles(slug, options = {}) {
   }
 
   const taskResolution = resolveTaskFileFn(slug, rootDir);
-  if (!taskResolution || !taskResolution.ok) {
-    missing.push('backlog/tasks/' + slug + ' - *.md');
+  const missionArtifactsPresent = Boolean(missionPath && fs.existsSync(missionPath) && missionDir && findCheckpointsFn(missionDir).length > 0);
+  if ((!taskResolution || !taskResolution.ok) && !missionArtifactsPresent) {
+    const { tasksDir } = getTaskStorage(rootDir);
+    const taskDirRel = path.relative(rootDir, tasksDir).split(path.sep).join('/');
+    missing.push(`${taskDirRel}/${slug} - *.md`);
   }
 
   return { ok: missing.length === 0, missing };

package/lib/tools/setup-review.js

@@ -90,7 +90,7 @@ function detectPrimaryBranchDefault(rootDir = process.cwd(), options = {}) {
 
 function standardLayoutDescription() {
   return [
-    'standard = Backlog.md task storage in `backlog/`',
+    'standard = markdown task storage in `backlog/`',
     'missions in `docs/missions/`',
     'mission/* branches with auto-detected `main`/`master` primary',
     'worktrees in `../<repo>-<slug>`',
@@ -613,7 +613,7 @@ async function collectWizardAnswers(rootDir = process.cwd(), options = {}) {
     || defaultProductName(rootDir);
   log(fmt.status('INFO', `Standard workflow layout: ${standardLayoutDescription()}`));
   const useDefaults = parseYesNo(
-    await promptFn('Use the standard Backlog.md-style workflow layout and defaults? [Y/n]: '),
+    await promptFn('Use the standard markdown task workflow layout and defaults? [Y/n]: '),
     true
   );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magnusekdahl/parallix",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AI mission workflow toolkit with a px CLI — local-first, human-in-the-loop multi-agent development",
   "license": "AGPL-3.0-or-later",
   "private": false,

package/prompts/draft.md

@@ -9,7 +9,7 @@ Drafting requirements:
 - fill every scaffolded section in `{{missionPath}}` with concrete, non-generic content (no placeholders, no "TBD")
 - include a Goal, Why now, Scope, Out of scope, Success criteria, Risks/assumptions, Checkpoints, Gates, Restricted areas, and Stop rules
 - success criteria must be specific enough to derive a goal-check table during execution
-- 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.
+- {{classificationInstructions}}
 - preserve `{{taskPath}}`: update content as needed but do not delete, rename, or move the file
 - do not edit the backlog `assignee` field; the workflow records ownership itself