@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/context-pack.js

@@ -52,8 +52,9 @@ const { TASK_CLASS_BUDGETS, resolveBudget, getRegisteredHarnessIds, getRegistere
 const { createDeliveryEntry, readDeliveryEntry, recordDelivery, makeTokenRecord } = require('./context/delivery-store.js');
 const { boundedAcquire } = require('./task-state.js');
 const pointerTools = require('./context/pointer.js');
+const { arbitrate, emitContext } = require('./context/arbitrate.js');
 const { updateTaskState } = require('./task-state.js');
-const { taskStoreDir } = require('./task-scope.js');
+const { taskRecord } = require('./task-scope.js');
 
 let correctiveTrimFallbackCount = 0;
 function getCorrectiveTrimFallbackCount()         { return correctiveTrimFallbackCount; }
@@ -114,6 +115,8 @@ function sourcesChanged(root        , sources                        )
 
 function classifyStoreFailure(error     )         {
   if (error?.code === 'store-locked' || error?.message === 'store-locked') return 'store-locked';
+  // Another writer reclaimed the lock mid-write; nothing was recorded and the store is intact.
+  if (error?.code === 'lock-lost') return 'lock-lost';
   if (error?.code === 'store-unreadable') return 'store-unreadable';
   if (['EACCES', 'EROFS', 'EPERM', 'ENOSPC'].includes(error?.code)) return 'store-unwritable';
   return 'store-unwritable';
@@ -126,10 +129,9 @@ function profileRetention(harnessId               , profiles              )
 }
 
 function appendPointerExpansion({ projectRoot, taskId, slug, key, expansion, fsImpl = fs }     )       {
-  const dir = taskStoreDir({ projectRoot, store: 'delivery', taskId, slug });
-  const file = path.join(dir, `${taskId}.json`);
+  const { file, seed } = taskRecord({ projectRoot, store: 'delivery', taskId, slug, fsImpl });
   updateTaskState({
-    fsImpl, file,
+    fsImpl, file, prepare: seed,
     acquire: (impl     , target        ) => boundedAcquire(impl, target, { retries: 3, waitMs: 5 }),
     build(disk     ) {
       const deliveries = Array.isArray(disk?.deliveries) ? disk.deliveries : [];
@@ -366,8 +368,12 @@ class ContextPackCompiler {
     const selfRefWidth = Math.max(budgetOverrides.selfRefWidth ?? this.options.selfRefWidth ?? 0, reservedHarnessWidth);
     const longestHarnessId = registeredHarnessIds.reduce((longest        , id        ) => id.length > longest.length ? id : longest, 'unstated');
     const envelopeBudget = {
-      ...resolvedBudget,
+      maxBytes: resolvedBudget.maxBytes,
+      source: resolvedBudget.source,
       harness: { ...resolvedBudget.harness, id: longestHarnessId },
+      capacity: { value: null, basis: 'unknown:values belong to 085 (A-19)' },
+      toolResultLimitBytes: null,
+      ...(resolvedBudget.startupTokens ? { startupTokens: resolvedBudget.startupTokens } : {}),
     };
 
     const { envelopeMd, envelopeJson } = computeEnvelopes({
@@ -478,7 +484,7 @@ class ContextPackCompiler {
         taskClass: effectiveTaskClass,
         compiledAt: new Date().toISOString(),
         mode: bare ? 'bare' : (paramMode || 'full'),
-        budget: resolvedBudget,
+        budget: envelopeBudget,
         overflow: isOverflow ? {
           cause,
           mandatoryBytes: packMandatoryBytes,
@@ -874,7 +880,11 @@ class ContextPackCompiler {
  * @param {string} [options.objective]
  * @param {boolean} [options.json=false]
  * @param {string} [options.stateRoot]
+ * @param {string} [options.sourceRoot] the checkout the verb runs in (default stateRoot)
  * @param {string} [options.slug] feature slug, when the task id is not the feature's own
+ * @param {string|null} [options.explicitSlug] the `--slug` the caller typed, if any (default `slug`).
+ *   Only this selects a run for the stage-pack link: a branch-derived `slug` still keys the delivery
+ *   store, but the branch name alone never picks a run (docs/specs/orchestrator-context-modes.md).
  * @returns {number} exit code
  */
 function handleContextPackCommand({
@@ -883,7 +893,9 @@ function handleContextPackCommand({
   objective,
   json = false,
   stateRoot,
+  sourceRoot,
   slug,
+  explicitSlug,
   mandatoryFile,
   harness = null,
   maxBytes,
@@ -895,6 +907,9 @@ function handleContextPackCommand({
   profiles = null,
 }      = {}) {
   const root = stateRoot || process.cwd();
+  // 115 IC-004/IC-007: records live under `root`; the feature folder, its plan and pointers, and the
+  // source files a delivery hashes are read in the checkout the verb runs in.
+  const source = sourceRoot || root;
   const effectiveTaskClass = (!taskClass || typeof taskClass !== 'string' || taskClass.trim() === '') ? 'feature' : taskClass.trim();
 
   // IC-001 Usage errors
@@ -934,10 +949,8 @@ function handleContextPackCommand({
 
   const budget = resolveBudget({ taskClass: effectiveTaskClass, maxBytes: parsedMaxBytes, harnessFlag: harness, profiles });
 
-  const feature = resolveFeature({ projectRoot: root, slug: slug || null });
+  const feature = resolveFeature({ projectRoot: source, slug: slug || null });
 
-  let sinceEntry      = null;
-  let deltaRefused                = null;
   let deltaExpansions        = [];
   if (parsedMaxBytes !== undefined) {
     if (!baseBudget) {
@@ -947,24 +960,16 @@ function handleContextPackCommand({
       deltaExpansions.push({ at: new Date().toISOString(), kind: 'cap-raised', target: null, reason, bytesAdded: null });
     }
   }
-  let retention = profileRetention(budget.harness?.id || null, profiles);
-  if (since && !expand) {
-    sinceEntry = readDeliveryEntry({ projectRoot: root, taskId, slug, packDigest: since });
-    if (!sinceEntry) deltaRefused = 'since-unknown';
-    else if (sourcesChanged(root, sinceEntry.sources || {})) deltaRefused = 'sources-changed';
-    else if (!budget.harness?.id) deltaRefused = 'harness-unstated';
-    else if (retention?.value !== 'supported') deltaRefused = 'retention-unproven';
-    if (deltaRefused) {
-      deltaExpansions.push({ at: new Date().toISOString(), kind: 'delta-widened', target: null, reason: deltaRefused, bytesAdded: null });
-    }
-  }
+  const basis = resolveDeltaBasis({ root, source, taskId, slug, since: expand ? null : since, budget, profiles });
+  const { sinceEntry, deltaRefused, retention } = basis;
+  if (basis.expansion) deltaExpansions.push(basis.expansion);
 
   if (expand) {
     const prior = readDeliveryEntry({ projectRoot: root, taskId, slug, packDigest: since });
     if (!prior) return usageError('context-pack', `Unknown digest '${since}'`, json);
     const pointer = (prior.pointers || []).find((candidate     ) => candidate.id === expand);
     if (!pointer) return usageError('context-pack', `Unknown pointer '${expand}' in digest '${since}'`, json);
-    const current = pointerTools.readPointerSlice({ projectRoot: root, pointer });
+    const current = pointerTools.readPointerSlice({ projectRoot: source, pointer });
     if (!current) return usageError('context-pack', `Unknown pointer '${expand}' in digest '${since}'`, json);
     const compiler = new ContextPackCompiler();
     const pack = compiler.compileContextPack({ taskId, taskClass: effectiveTaskClass, objective: '', mandatory: { fields: {}, provenance: {} }, budget,
@@ -1018,55 +1023,7 @@ function handleContextPackCommand({
     return finishRuntime(EXIT.OK);
   }
 
-  let reqText                = null;
-  let reqPath = 'requirement.md';
-  if (!feature.error && feature.featureDir) {
-    reqPath = feature.paths?.requirement
-      ? path.resolve(feature.repoRoot || root, feature.paths.requirement)
-      : path.join(feature.featureDir, 'intention', 'requirement.md');
-    try {
-      if (fs.existsSync(reqPath)) {
-        reqText = fs.readFileSync(reqPath, 'utf8');
-      }
-    } catch {
-      reqText = null;
-    }
-  }
-
-  let taskStories           = [];
-  if (!feature.error && feature.featureDir && taskId) {
-    let planPath                = null;
-    if (feature.paths?.plan) {
-      planPath = path.resolve(feature.repoRoot || root, feature.paths.plan);
-    } else {
-      const nestedPlan = path.join(feature.featureDir, 'plan', 'plan.md');
-      const flatPlan = path.join(feature.featureDir, 'plan.md');
-      if (fs.existsSync(nestedPlan)) planPath = nestedPlan;
-      else if (fs.existsSync(flatPlan)) planPath = flatPlan;
-    }
-    if (planPath && fs.existsSync(planPath)) {
-      try {
-        const planText = fs.readFileSync(planPath, 'utf8');
-        const { parsePlan } = require('./scaffold/artifacts.js');
-        const parsedPlan = parsePlan(planText);
-        const matchedTask = (parsedPlan.tasks || []).find(
-          (t     ) => t.id === taskId || t.id.toLowerCase() === taskId.toLowerCase()
-        );
-        if (matchedTask && Array.isArray(matchedTask.stories)) {
-          taskStories = matchedTask.stories;
-        }
-      } catch {
-        taskStories = [];
-      }
-    }
-  }
-
-  let mandatory = extractMandatory({
-    text: reqText,
-    path: reqPath,
-    featureError: feature.error ? (feature.message || feature.error) : null,
-    taskStories,
-  });
+  let mandatory = gatherMandatory({ root: source, taskId, feature });
 
   if (mandatoryFile) {
     try {
@@ -1088,6 +1045,34 @@ function handleContextPackCommand({
     }
   }
 
+  const { pack, output } = deliverPack({
+    root, source, taskId, slug, effectiveTaskClass, objective, mandatory, budget, harness, parsedMaxBytes, bare, noRecord,
+    json, reason, since, sinceEntry, deltaRefused, deltaExpansions, expand, retention, feature,
+  });
+  // Issue #9 stage 3: a recorded delivery is named on the run stage active now (best effort, never fails the verb).
+  if (pack.delivery?.recorded === true) {
+    try {
+      require('./workflow-orchestrator.js').recordStagePack({ stateRoot: root, sourceRoot: source, taskId, slug: (explicitSlug === undefined ? slug : explicitSlug) || null, digest: pack.delivery.packDigest,
+        checkout: !feature.error && feature.paths?.repo_root ? { repoRoot: feature.paths.repo_root, branch: feature.paths.branch || null } : null });
+    } catch { /* an unrecorded link is unknown, not a failure */ }
+  }
+  if (console.log !== nativeConsoleLog) {
+    console.log(output);
+  } else {
+    process.stdout.write(output);
+  }
+  return finishRuntime(pack.exitCode);
+}
+
+/**
+ * The context-pack verb's compile, fit, render and delivery-record steps for a full or delta pack,
+ * with no output: `handleContextPackCommand()` prints the result and `packForEmission()` hands it
+ * to `emitContext()`. Returns the final pack and its rendered text in the requested form.
+ */
+function deliverPack({
+  root, source = root, taskId, slug, effectiveTaskClass, objective, mandatory, budget, harness, parsedMaxBytes, bare, noRecord,
+  json, reason, since, sinceEntry, deltaRefused, deltaExpansions, expand, retention, feature,
+}     )                                {
   const ledger = new EvidenceLedger({ repoRoot: root, slug });
   ledger.load(taskId);
   const claims = new ClaimsManager({ evidenceLedger: ledger, repoRoot: root, slug });
@@ -1115,11 +1100,11 @@ function handleContextPackCommand({
     deltaSinceEntry: since && !deltaRefused && !expand ? sinceEntry : null,
     deltaRefused,
     expand,
-    pointers: pointerTools.collectPointers({ projectRoot: root, feature }),
+    pointers: pointerTools.collectPointers({ projectRoot: source, feature }),
     evidenceLedger: ledger,
     claimsManager: claims,
     researchRequests,
-    decisions: loadLiveDecisions({ projectRoot: root, slug: slug || null }),
+    decisions: loadLiveDecisions({ projectRoot: source, slug: slug || null }),
   });
 
   let deliverySources      = null;
@@ -1136,7 +1121,7 @@ function handleContextPackCommand({
     pack.omissions = pack.mode === 'bare' ? pack.omissions : compose.groupOmissions(pack.deliveryOmissions, !noRecord);
   }
   if (!noRecord) {
-    deliverySources = hashSourceFiles(root, pack.relevantFiles || []);
+    deliverySources = hashSourceFiles(source, pack.relevantFiles || []);
     deliveryRetention = retention?.value === 'supported' || retention?.value === 'unsupported'
       ? { status: retention.value, basis: `declared:${retention.source || 'profile'}` }
       : { status: 'unknown', basis: retention?.unverified || 'contextProfile.retention is unverified' };
@@ -1260,18 +1245,109 @@ function handleContextPackCommand({
     pack.packEnd.bytes = emittedBytes;
     pack.size.totalBytes = emittedBytes;
   }
-  if (console.log !== nativeConsoleLog) {
-    console.log(output);
-  } else {
-    process.stdout.write(output);
+  return { pack, output };
+}
+
+/** The delta basis of a `since` digest: its delivery entry, or why a delta was refused (widened to full). */
+function resolveDeltaBasis({ root, source = root, taskId, slug, since, budget, profiles }     ) {
+  const retention = profileRetention(budget.harness?.id || null, profiles);
+  let sinceEntry      = null;
+  let deltaRefused                = null;
+  let expansion      = null;
+  if (since) {
+    sinceEntry = readDeliveryEntry({ projectRoot: root, taskId, slug, packDigest: since });
+    if (!sinceEntry) deltaRefused = 'since-unknown';
+    else if (sourcesChanged(source, sinceEntry.sources || {})) deltaRefused = 'sources-changed';
+    else if (!budget.harness?.id) deltaRefused = 'harness-unstated';
+    else if (retention?.value !== 'supported') deltaRefused = 'retention-unproven';
+    if (deltaRefused) {
+      expansion = { at: new Date().toISOString(), kind: 'delta-widened', target: null, reason: deltaRefused, bytesAdded: null };
+    }
   }
-  return finishRuntime(pack.exitCode);
+  return { sinceEntry, deltaRefused, retention, expansion };
+}
+
+/** The mandatory fields of a task from its feature's requirement.md and the task's plan stories. */
+function gatherMandatory({ root, taskId, feature }     ) {
+  let reqText                = null;
+  let reqPath = 'requirement.md';
+  if (!feature.error && feature.featureDir) {
+    reqPath = feature.paths?.requirement
+      ? path.resolve(feature.repoRoot || root, feature.paths.requirement)
+      : path.join(feature.featureDir, 'intention', 'requirement.md');
+    try {
+      if (fs.existsSync(reqPath)) {
+        reqText = fs.readFileSync(reqPath, 'utf8');
+      }
+    } catch {
+      reqText = null;
+    }
+  }
+
+  let taskStories           = [];
+  if (!feature.error && feature.featureDir && taskId) {
+    let planPath                = null;
+    if (feature.paths?.plan) {
+      planPath = path.resolve(feature.repoRoot || root, feature.paths.plan);
+    } else {
+      const nestedPlan = path.join(feature.featureDir, 'plan', 'plan.md');
+      const flatPlan = path.join(feature.featureDir, 'plan.md');
+      if (fs.existsSync(nestedPlan)) planPath = nestedPlan;
+      else if (fs.existsSync(flatPlan)) planPath = flatPlan;
+    }
+    if (planPath && fs.existsSync(planPath)) {
+      try {
+        const planText = fs.readFileSync(planPath, 'utf8');
+        const { parsePlan } = require('./scaffold/artifacts.js');
+        const parsedPlan = parsePlan(planText);
+        const matchedTask = (parsedPlan.tasks || []).find(
+          (t     ) => t.id === taskId || t.id.toLowerCase() === taskId.toLowerCase()
+        );
+        if (matchedTask && Array.isArray(matchedTask.stories)) {
+          taskStories = matchedTask.stories;
+        }
+      } catch {
+        taskStories = [];
+      }
+    }
+  }
+
+  return extractMandatory({
+    text: reqText,
+    path: reqPath,
+    featureError: feature.error ? (feature.message || feature.error) : null,
+    taskStories,
+  });
+}
+
+/**
+ * 078 IC-001: the context pack `emitContext()` delivers on `launch` and `delta`, compiled by
+ * compileContextPack() through the verb's own steps, with `maxBytes` as the budget and `since` the
+ * unit's last delivered pack digest (a delta when its entry qualifies, else widened to full).
+ * `noRecord` (peek) leaves the delivery store untouched. Rendered as markdown.
+ */
+function packForEmission({ root, stateRoot = root, taskId = 'default', taskClass = 'feature', slug = null, harness = null, maxBytes, since = null, noRecord = false, env = process.env }     )                                {
+  const budget = resolveBudget({ taskClass, maxBytes, harnessFlag: harness, env });
+  const feature = resolveFeature({ projectRoot: root, slug: slug || null });
+  // 115 C-2: the delivery record goes where `context-pack` puts it, under the state root; the feature
+  // folder, the plan and the hashed source files are read in `root`, the checkout emitting.
+  const basis = resolveDeltaBasis({ root: stateRoot, source: root, taskId, slug, since, budget, profiles: null });
+  return deliverPack({
+    root: stateRoot, source: root, taskId, slug, effectiveTaskClass: taskClass, objective: undefined, mandatory: gatherMandatory({ root, taskId, feature }),
+    budget, harness, parsedMaxBytes: maxBytes, bare: false, noRecord, json: false, reason: null, since,
+    sinceEntry: basis.sinceEntry, deltaRefused: basis.deltaRefused, deltaExpansions: basis.expansion ? [basis.expansion] : [],
+    expand: null, retention: basis.retention, feature,
+  });
 }
 
 module.exports = {
+  classifyStoreFailure,
   ContextPackCompiler,
+  arbitrate,
+  emitContext,
   TASK_CLASS_BUDGETS,
   handleContextPackCommand,
   loadLiveDecisions,
+  packForEmission,
   getCorrectiveTrimFallbackCount,
 };

package/src/runtime/decision-register.js

@@ -30,7 +30,12 @@ const REF_RE = /^[A-Za-z]+-?[0-9]+$/;
 const DEC_RE = /^DEC-[0-9]{3,}$/;
 const STAGES = ['discovery', 'design', 'planning', 'implementation', 'verification', 'review'];
 /** Channel -> who decided. The caller names the channel; `decidedBy` follows from it. */
-const CHANNEL_DECIDED_BY                         = { question: 'user', gate: 'user', prompt: 'user', default: 'agent', resolution: 'agent' };
+const CHANNEL_DECIDED_BY                         = { question: 'user', gate: 'user', prompt: 'user', default: 'agent', resolution: 'agent', policy: 'autopilot' };
+/** IC-005: `policy` records an evaluated gate, never a caller's claimed identity, so only the
+ * in-process `orchestrate decide-gate --policy` path writes it; every caller-facing path refuses it. */
+const RESERVED_CHANNEL = 'policy';
+const CHANNEL_RESERVED = `channel-reserved: ${RESERVED_CHANNEL} is set only by orchestrate decide-gate --policy`;
+const isReservedChannel = (channel     )          => typeof channel === 'string' && channel.trim() === RESERVED_CHANNEL;
 const ITEM_KEYS = ['topic', 'statement', 'channel', 'stage', 'rationale', 'supersedes', 'refs', 'source'];
 const REQUIRED_KEYS = ['topic', 'statement', 'channel', 'stage', 'rationale'];
 
@@ -204,7 +209,7 @@ function normalizeItem(raw     , label        )      {
   }
   const channel = raw.channel.trim();
   if (!Object.prototype.hasOwnProperty.call(CHANNEL_DECIDED_BY, channel)) {
-    throw new DecisionUsageError(`${label}: channel '${channel}' must be one of ${Object.keys(CHANNEL_DECIDED_BY).join(', ')}`);
+    throw new DecisionUsageError(`${label}: channel '${channel}' must be one of ${Object.keys(CHANNEL_DECIDED_BY).filter((c) => c !== RESERVED_CHANNEL).join(', ')}`);
   }
   const stage = raw.stage.trim();
   if (!STAGES.includes(stage)) throw new DecisionUsageError(`${label}: stage '${stage}' must be one of ${STAGES.join(', ')}`);
@@ -406,16 +411,17 @@ function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, no
   let resolved      = null;
   try {
     if (!VALID_ACTIONS.includes(act)) throw new DecisionUsageError(`unknown --action '${action}'. Valid: ${VALID_ACTIONS.join(', ')}`);
+    if (isReservedChannel(flags.channel)) throw new DecisionUsageError(CHANNEL_RESERVED);
     const feature = resolveActiveFeature({ projectRoot, slug });
     if (feature.error) throw new DecisionUsageError(feature.message);
-    resolved = { featureDir: feature.featureDir, slug: feature.paths.feature_slug };
+    resolved = { featureDir: feature.featureFolder, slug: feature.paths.feature_slug };
     let result     ;
     if (act === 'init') {
       result = initRegister({ ...resolved, fsImpl });
     } else if (act === 'list') {
       result = listDecisions({ ...resolved, all: Boolean(flags.all), fsImpl });
     } else if (act === 'compact') {
-      result = compactDecisions({ ...resolved, repoRoot: feature.repoRoot, paths: feature.paths, now, fsImpl });
+      result = compactDecisions({ ...resolved, repoRoot: feature.featureRoot, paths: feature.paths, now, fsImpl });
     } else {
       let items     ;
       if (flags.batch) {
@@ -430,6 +436,7 @@ function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, no
         }
         items = [single];
       }
+      if (Array.isArray(items) && items.some((item     ) => isReservedChannel(item?.channel))) throw new DecisionUsageError(CHANNEL_RESERVED);
       result = addDecisions({ ...resolved, items, now, fsImpl });
     }
     return { exitCode: result.finding ? 1 : 0, result };
@@ -489,5 +496,7 @@ module.exports = {
   archiveFile,
   STAGES,
   CHANNEL_DECIDED_BY,
+  CHANNEL_RESERVED,
+  isReservedChannel,
   STATEMENT_MAX,
 };