@khoavu882/doflow 2.0.0-beta.4 → 2.0.0-beta.5

package/src/cli/index.js

@@ -70,6 +70,8 @@ function parseArgs(argv          )      {
       case '--permissions': o.permissions = true; break;
       case '--statusline': o.statusline = true; break;
       case '--json': o.json = true; break;
+      case '--bare': o.bare = true; break;
+      case '--no-record': o.noRecord = true; break;
       case '--check': o.check = true; break;
       // decision --action list: every decision by id, not just the live ones.
       case '--all': o.all = true; break;
@@ -136,6 +138,7 @@ function parseArgs(argv          )      {
         o.node = val; i++; break;
       }
       case '--forced': o.forced = true; break;
+      case '--absence': o.absence = true; break;
       case '--decision': {
         const val = argv[i + 1];
         if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
@@ -258,6 +261,9 @@ const RUNTIME_STRING_FLAGS = new Map([
                                        // change scope, <path>[,<path>...], unioned with the plan's bound
   ['--invariants', 'invariants'],      // readiness: the invariants a refactor must preserve
   ['--objective', 'objective'],        // context-pack
+  ['--mandatory-file', 'mandatoryFile'], // context-pack: caller-supplied mandatory fields
+  ['--max-bytes', 'maxBytes'],         // context-pack: per-call cap in bytes
+  ['--expand', 'expand'],              // context-pack: pointer id to expand
   ['--stage-id', 'stageId'],           // research-request: active feature stage
   ['--question', 'question'],           // research-request: external question
   ['--blocking', 'blocking'],           // research-request: true | false
@@ -266,6 +272,7 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--gap', 'gap'],                     // research-request: unresolved reason
   ['--stage', 'stage'],                // retrieval-plan: the stage id declaring the plan;
                                        // outcome: the stage writing it, refused unless terminal
+  ['--status', 'attemptStatus'],       // retrieval-plan: attempt status (EMPTY|UNREACHED|UNVERIFIED)
   ['--state', 'state'],                // outcome: the terminal state being recorded
   ['--result', 'result'],              // orchestrate complete-stage: the stage's own outcome, passed | failed (omit → unverified)
   // outcome: the verdicts the run saw, stated by it and validated against the vocabulary the
@@ -281,6 +288,8 @@ const RUNTIME_STRING_FLAGS = new Map([
   ['--owner', 'owner'],                // brief-tools: the agent type the brief is for
   ['--tier', 'tier'],                  // brief-tools: the task line's tier (light | standard | frontier)
   ['--harness', 'harness'],            // brief-tools: the harness the brief is for
+  ['--policy', 'policy'],              // enforcement: lifecycle policy id
+  ['--profile', 'profile'],             // enforcement: coverage profile filter
   ['--heading-level', 'headingLevel'], // brief-tools: 2 (default) or 3
   ['--tasks', 'tasks'],               // brief-tools: comma-separated plan task ids for tier advice
   ['--plan-path', 'planPath'],         // verify: a feature plan.md whose doflow-verification
@@ -388,12 +397,13 @@ Commands:
   self-update          git pull + reinstall
   tools                Inspect or manage registered external tools
   capabilities         Show registered abstract capabilities and resolved providers
+  enforcement          Report lifecycle policy enforcement coverage (--harness, --policy)
   doctor               System health and capability smoke check diagnostics
   readiness            Evaluate task readiness contract (--task-class, --task-id, both required)
   evidence             Record a stage's evidence batch, or inspect what is recorded (--task-id)
   claim                Record a claim, link evidence to it, or list them (--task-id, --action)
   context-pack         Compile a task's evidence and claims into a context block (--task-id)
-  retrieval-plan       Declare a stage's information needs, then report every declared item
+  retrieval-plan       Declare a stage's information needs, attempt retrieval, then report every declared item
   outcome              Record a task's terminal state with its basis, or show it (--task-id)
   classify             Validate a proposed task class and return its workflow (--task-class)
   workflow             Resolve a task class to its stages, gates and readiness templates
@@ -453,7 +463,7 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --task-class     classify, workflow, readiness, context-pack, outcome --action record
       --task-id        readiness, evidence, claim, context-pack, retrieval-plan, outcome, verify, advise
       --action         claim: list|add|link|retract|supersede · evidence: list|add|supersede
-                       verify: report|contract · retrieval-plan: declare|report
+                       verify: report|contract · retrieval-plan: declare|report|attempt
                        outcome: record|show · advise: ask|outcome|configure · tools: see above
                        followup: add|list|take|settle|promote|report
                        task-attempt: claim|finish|release|status
@@ -470,7 +480,9 @@ Runtime verb arguments (accept --flag value or --flag=value):
       --statement, --claim-id,
       --evidence-id, --relation             claim
       --kind, --provenance, --provider,
-      --capability, --locator, --content    evidence --action add (one item)
+      --capability, --locator, --content,
+      --absence                             evidence --action add (one item)
+      --need <intent>                       evidence --action add (bind evidence to retrieval needs)
       --batch <file|->                      evidence --action add (a stage's JSON batch)
       --evidence-id, --replaced-by          evidence --action supersede (retire one item, point
                                             forward to the item that replaces it)
@@ -480,7 +492,7 @@ Runtime verb arguments (accept --flag value or --flag=value):
                                             evidence establishes; reported back as such
       --objective                           context-pack
       --need <intent[,intent]>,
-      --stage                               retrieval-plan (--need is repeatable), outcome
+      --stage, --status                     retrieval-plan (--need is repeatable), outcome
       --mcp-outcome <server>=<outcome>      orchestrate --action handoff, repeatable: used | nothing-usable |
                                             skipped:<reason> | unavailable (a server left out only warns)
       --state <COMPLETED|BLOCKED|
@@ -565,4 +577,4 @@ async function main(argv          )               {
   }
 }
 
-module.exports = { main, COMMANDS, commandName };
+module.exports = { main, COMMANDS, commandName, parseArgs };

package/src/cli/runtime-commands.js

@@ -24,6 +24,8 @@ const path = require('node:path');
 const {
   handleCapabilitiesCommand, handleReadinessCommand, handleEvidenceCommand,
 } = require('../runtime/cli.js');
+const { loadRegistry } = require('../registry/index.js');
+const { enforcementFor, UnknownEnforcementTarget } = require('../lifecycle/coverage.js');
 // `doctor` comes from the health module rather than src/runtime/cli.js: the health-probe report
 // (FR-013) supersedes the presence-check version, and one verb must have one implementation.
 const { handleDoctorCommand } = require('../runtime/health.js');
@@ -58,7 +60,7 @@ const { handleStorageCommand } = require('../runtime/storage/cli.js');
 function handleFailureCommand(options     )      { return require('../runtime/failure/cli.js').handleFailureCommand(options); }
 const { handleInventoryCommand } = require('../runtime/inventory/index.js');
 const { finishRuntime, usageError } = require('../runtime/cli-result.js');
-const { setDefaultSlug, invalidSlugRefusal, slugNamesNoFeature } = require('../runtime/task-scope.js');
+const { setDefaultSlug, invalidSlugRefusal, slugNamesNoFeature, resolveFeature } = require('../runtime/task-scope.js');
 const { listCheckouts } = require('../runtime/checkouts.js');
 const { featureSlugFor } = require('../runtime/implementation-gate.js');
 const { handleBriefToolsCommand } = require('../runtime/brief-tools.js');
@@ -111,6 +113,9 @@ function evidenceItemFromFlags(o     )      {
   if (o.locator !== undefined) item.locator = o.locator;
   if (o.content !== undefined) item.content = o.content;
   if (o.establishes !== undefined) item.establishes = o.establishes;
+  if (o.need !== undefined) item.need = o.need;
+  if (o.result !== undefined) item.result = o.result;
+  if (o.absence !== undefined) item.absence = o.absence;
   // Both halves of an observation travel together; a lone half must reach the write boundary as
   // the partial object it is, so the refusal names the missing field instead of dropping the pair.
   if (o.observedCommand !== undefined || o.observedExit !== undefined) {
@@ -128,9 +133,9 @@ function evidenceItemFromFlags(o     )      {
 /** Verbs that read or write per-task records, and so accept `--slug` (IC-002). */
 const TASK_STORE_VERBS = new Set(['evidence', 'claim', 'readiness', 'context-pack', 'research-request', 'outcome', 'retrieval-plan']);
 
-/** Verbs that build a task's readiness: run from a linked worktree whose feature folder lives only
- * in the main checkout, they keep the task's records there, beside the folder their evidence names. */
-const FEATURE_STORE_VERBS = new Set(['evidence', 'claim', 'readiness']);
+/** Verbs whose task records live beside the feature folder when run from a linked worktree that
+ * does not contain it. */
+const FEATURE_STORE_VERBS = new Set(['evidence', 'claim', 'readiness', 'retrieval-plan']);
 
 /**
  * The main checkout, when `o` runs one of FEATURE_STORE_VERBS in a linked worktree that lacks the
@@ -139,11 +144,16 @@ const FEATURE_STORE_VERBS = new Set(['evidence', 'claim', 'readiness']);
  * the readiness record written there is the one verify, orchestrate and the edit hook read from
  * the worktree.
  */
-function featureStoreRoot(o     )                                        {
+function featureStoreRoot(o     , checkouts     )                                        {
   if (!FEATURE_STORE_VERBS.has(o.cmd) || o.global) return null;
-  const checkouts = listCheckouts({ cwd: evidenceRoot(o) });
   if (!checkouts.isLinked) return null;
-  const slug = featureSlugFor({ projectRoot: checkouts.current, slug: o.slug });
+  let slug = o.slug || null;
+  if (!slug) {
+    try {
+      const feature = resolveFeature({ projectRoot: checkouts.current });
+      slug = !feature.error && feature.paths ? feature.paths.feature_slug : null;
+    } catch { /* a failed branch lookup cannot route state to a guessed feature */ }
+  }
   const folder = (root        ) => path.join(root, 'agent-docs', 'doflow', slug || '');
   if (!slug || fs.existsSync(folder(checkouts.current)) || !fs.existsSync(folder(checkouts.main))) return null;
   return { root: checkouts.main, slug };
@@ -169,8 +179,11 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
   // here so the verbs whose handlers build their own ledger (readiness, evidence) route the same
   // way as the ones that take `slug` directly. The orchestration journal is keyed by slug already.
   // Reset on every dispatch, so one invocation's slug can never carry into the next in-process call.
-  const featureStore = featureStoreRoot(o);
+  const checkouts = FEATURE_STORE_VERBS.has(o.cmd) && !o.global
+    ? listCheckouts({ cwd: evidenceRoot(o) }) : null;
+  const featureStore = featureStoreRoot(o, checkouts);
   const storeRoot = featureStore ? featureStore.root : evidenceRoot(o);
+  const attemptRoot = checkouts?.ok && !checkouts.sandbox ? (checkouts.main || checkouts.current || null) : null;
   // Use the same root resolver as the handler: task redirection, the nearest run ledger,
   // and lifecycle's shared main-worktree store are deliberately different scopes.
   try {
@@ -197,6 +210,7 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     // REPO_ROOT locates the capability registry; projectRoot is the tree whose index freshness
     // and build/test commands are being reported on, which follows the usual scope rules.
     case 'capabilities': return handleCapabilitiesCommand({ json: o.json, check: o.check, repoRoot: REPO_ROOT });
+    case 'enforcement': return handleEnforcementCommand(o);
     case 'doctor': return handleDoctorCommand({ json: o.json, repoRoot: REPO_ROOT, projectRoot: evidenceRoot(o), adapters: buildAdapterRegistry() });
     // REPO_ROOT locates the registry (templates ship with the package); stateRoot locates the
     // caller's evidence, which follows the same scope rules as every other command: -g means
@@ -211,8 +225,8 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     // than from evidence, so the gate had one reachable answer for every task. Forwarding is
     // all this does: the handler names them back under `callerAsserted` so a stated input is
     // never mistaken for a measured one.
-    case 'readiness': return handleReadinessCommand({ taskClass: requireTaskClass(o), taskId: requireTaskId(o), verificationPlan: o.verificationPlan, scopeClear: o.scope, invariants: o.invariants, userDecisionPending: o.userDecisionPending, mode: o.mode, slug: storeSlug, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot });
-    case 'evidence': return handleEvidenceCommand({ taskId: requireTaskId(o), action: o.action, item: evidenceItemFromFlags(o), batchPath: o.batchPath, evidenceId: o.evidenceId, replacedBy: o.replacedBy, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot });
+    case 'readiness': return handleReadinessCommand({ taskClass: requireTaskClass(o), taskId: requireTaskId(o), verificationPlan: o.verificationPlan, scopeClear: o.scope, invariants: o.invariants, userDecisionPending: o.userDecisionPending, mode: o.mode, slug: storeSlug, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot, sourceRoot: evidenceRoot(o) });
+    case 'evidence': return handleEvidenceCommand({ taskId: requireTaskId(o), action: o.action, item: evidenceItemFromFlags(o), batchPath: o.batchPath, evidenceId: o.evidenceId, replacedBy: o.replacedBy, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot, slug: storeSlug, sourceRoot: evidenceRoot(o), attemptRoot });
     // Run-ledger views. They resolve their own ledger the way the dispatcher does (nearest
     // `.doflow` walking up, or the global one) rather than assuming cwd is the project root, so
     // a view invoked from a subdirectory reads the runs that were actually recorded.
@@ -260,8 +274,8 @@ function dispatchRuntimeCommandInner(o     , moment     )      {
     case 'model-role': return handleModelRoleCommand({ role: o.role, exclude: o.exclude, json: o.json, repoRoot: REPO_ROOT });
     case 'route': return handleRouteCommand({ intent: o.intent, query: o.query, check: o.check, json: o.json, projectRoot: evidenceRoot(o) });
     case 'claim': return handleClaimCommand({ slug: storeSlug, taskId: requireTaskId(o), action: o.action, statement: o.statement, claimId: o.claimId, evidenceId: o.evidenceId, replacedBy: o.replacedBy, relation: o.relation, role: o.role, json: o.json, stateRoot: storeRoot });
-    case 'context-pack': return handleContextPackCommand({ taskId: requireTaskId(o), taskClass: o.taskClass, objective: o.objective, json: o.json, stateRoot: evidenceRoot(o), slug: o.slug });
-    case 'retrieval-plan': return handleRetrievalPlanCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, need: o.need, stage: o.stage, json: o.json, repoRoot: REPO_ROOT, stateRoot: evidenceRoot(o) });
+    case 'context-pack': return handleContextPackCommand({ taskId: requireTaskId(o), taskClass: o.taskClass, objective: o.objective, json: o.json, stateRoot: evidenceRoot(o), slug: o.slug, mandatoryFile: o.mandatoryFile, harness: o.harness, maxBytes: o.maxBytes, bare: o.bare, noRecord: o.noRecord, reason: o.reason, since: o.since, expand: o.expand });
+    case 'retrieval-plan': return handleRetrievalPlanCommand({ slug: storeSlug, taskId: requireTaskId(o), action: o.action, need: o.need, stage: o.stage, provider: o.provider, attemptStatus: o.attemptStatus, reason: o.reason, note: o.note, json: o.json, repoRoot: REPO_ROOT, stateRoot: storeRoot, sourceRoot: evidenceRoot(o) });
     case 'outcome': return handleOutcomeCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, state: o.state, taskClass: o.taskClass, stage: o.stage, readiness: o.readiness, verification: o.verification, json: o.json, repoRoot: REPO_ROOT, stateRoot: evidenceRoot(o) });
     case 'verify': return handleVerifyCommand({ slug: o.slug, taskId: requireTaskId(o), action: o.action, risk: o.risk, planPath: o.planPath, scope: o.scope, verificationInput: o.verificationInput, verificationPhase: o.verificationPhase, baselineRef: o.baselineRef, json: o.json, projectRoot: evidenceRoot(o) });
     case 'leak-scan': return handleLeakScanCommand({ paths: o.paths, exclude: o.exclude, json: o.json, repoRoot: evidenceRoot(o) });
@@ -278,4 +292,29 @@ async function dispatchRuntimeCommand(o     )               {
   return result;
 }
 
+function handleEnforcementCommand(o     )         {
+  const fail = (error        , detail        )         => {
+    if (o.json) console.log(JSON.stringify({ error, detail }));
+    else console.error(`doflow enforcement: ${detail}`);
+    process.exitCode = 2;
+    return 2;
+  };
+  if (typeof o.harness !== 'string' || !o.harness || typeof o.policy !== 'string' || !o.policy || (o.profile !== undefined && typeof o.profile !== 'string')) return fail('usage', 'requires --harness <id> --policy <id> [--profile <id>]');
+  try {
+    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    const answer = enforcementFor(registry.coverage, { harness: o.harness, policy: o.policy, ...(o.profile ? { profile: o.profile } : {}) });
+    if (o.json) console.log(JSON.stringify(answer));
+    else {
+      console.log(`${answer.harness} ${answer.policy}: ${answer.enforced ? 'enforced' : 'not enforced'} (${answer.class}, ${answer.verification})`);
+      for (const item of answer.doesNotCover) console.log(`does not cover: ${item}`);
+      for (const item of answer.prerequisites) console.log(`prerequisite: ${item}`);
+    }
+    process.exitCode = answer.enforced ? 0 : 1;
+    return process.exitCode;
+  } catch (error     ) {
+    if (error instanceof UnknownEnforcementTarget) return fail(error.code, error.message);
+    return fail('usage', error.message);
+  }
+}
+
 module.exports = { dispatchRuntimeCommand };

package/src/lifecycle/coverage.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const CLASS_ORDER = Object.freeze(['unknown', 'unsupported', 'observation', 'advisory', 'blocking']);
+const POLICY_ORDER = Object.freeze(['pre-implementation-gate', 'pre-bash-guard', 'session-context', 'mcp-tool-guard', 'stop-check']);
+const HARNESS_ORDER = Object.freeze(['claude', 'codex', 'gemini', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity']);
+const NEVER_BLOCKING_EVENTS = new Set([
+  'pi\u0000tool_execution_start', 'antigravity\u0000PostToolUse', 'antigravity\u0000PreInvocation',
+  'antigravity\u0000PostInvocation', 'gemini\u0000AfterTool', 'claude\u0000PostToolUse', 'codex\u0000PostToolUse',
+]);
+function stable(value     )         {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+function rowsDigest(rows       )         { return `sha256:${crypto.createHash('sha256').update(stable(rows)).digest('hex')}`; }
+class UnknownEnforcementTarget extends Error {
+  code        ;
+  constructor(code        , detail        ) { super(detail); this.name = 'UnknownEnforcementTarget'; this.code = code; }
+}
+function enforcementFor(coverage     , query                                                       )      {
+  const rows = coverage?.rows || [];
+  const profiles = coverage?.profiles || {};
+  if (query.policy === '*') throw new UnknownEnforcementTarget('unknown-policy', "Unknown policy '*'");
+  if (!rows.some((row     ) => row.harness === query.harness)) throw new UnknownEnforcementTarget('unknown-harness', `Unknown harness '${query.harness}'`);
+  if (!rows.some((row     ) => row.policy === query.policy)) throw new UnknownEnforcementTarget('unknown-policy', `Unknown policy '${query.policy}'`);
+  if (query.profile !== undefined && !Object.hasOwn(profiles, query.profile)) throw new UnknownEnforcementTarget('unknown-profile', `Unknown profile '${query.profile}'`);
+  const pairRows = rows.filter((row     ) => row.harness === query.harness && (row.policy === query.policy || row.policy === '*'));
+  const timing = query.policy === 'stop-check' ? 'stop' : 'pre-tool';
+  const applicable = pairRows.filter((row     ) => row.timing === timing && (query.profile === undefined || row.profile === query.profile || row.profile === 'any'));
+  const enforced = applicable.length > 0 && applicable.every((row     ) => row.wired && row.class === 'blocking' && row.verification === 'verified');
+  const rank = (row     ) => CLASS_ORDER.indexOf(row.class);
+  const weakest = [...applicable].sort((a     , b     ) => rank(a) - rank(b))[0];
+  const intersection = (field        ) => applicable.length ? [...new Set        (applicable[0][field] || [])].filter((item) => applicable.every((row     ) => (row[field] || []).includes(item))) : [];
+  const union = (field        ) => [...new Set(applicable.flatMap((row     ) => row[field] || []))];
+  const parity = enforced && pairRows.length > 0 && pairRows.every((row     ) => row.class === 'blocking');
+  return {
+    harness: query.harness, policy: query.policy, profile: query.profile ?? null, enforced, parity,
+    class: weakest?.class || 'unknown', verification: weakest?.verification || 'unverified',
+    prerequisites: union('prerequisites'), covers: intersection('covers'), doesNotCover: union('doesNotCover'), caveats: union('caveats'),
+    rows: applicable, matrix: { schemaVersion: coverage.schemaVersion, revision: coverage.revision, rowsDigest: coverage.rowsDigest },
+    reason: weakest ? `${weakest.class} at (${weakest.policy}, ${weakest.harness}, ${weakest.event}, ${weakest.profile})` : `unknown at (${query.policy}, ${query.harness}, *, ${query.profile ?? '*'})`,
+  };
+}
+function renderEnforcementMatrix(coverage     )         {
+  const order = (items                   , value        ) => {
+    const index = items.indexOf(value);
+    return index < 0 ? items.length : index;
+  };
+  const rows = [...coverage.rows].sort((a     , b     ) => order(POLICY_ORDER, a.policy) - order(POLICY_ORDER, b.policy)
+    || order(HARNESS_ORDER, a.harness) - order(HARNESS_ORDER, b.harness)
+    || a.event.localeCompare(b.event) || a.profile.localeCompare(b.profile));
+  const lines = [`Schema ${coverage.schemaVersion}; revision ${coverage.revision}; ${coverage.rowsDigest}`, '| Policy | Harness | Native event | Profile | Class | Verification | Prerequisites | Does not cover |', '|---|---|---|---|---|---|---|---|'];
+  for (const row of rows) lines.push(`| ${row.policy} | ${row.harness} | ${row.event} | ${row.profile} | ${row.class} | ${row.verification} | ${(row.prerequisites || []).join(', ')} | ${(row.doesNotCover || []).join(', ')} |`);
+  return lines.join('\n');
+}
+module.exports = { enforcementFor, renderEnforcementMatrix, rowsDigest, UnknownEnforcementTarget, NEVER_BLOCKING_EVENTS };

package/src/lifecycle/hook-step.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// IC-037 (DEC-034): the shared hooks tree and the hook front doors of every harness that reads it
+// move together. An install or update that writes changed bytes into `hooks.shared` also plans the
+// front doors of the other harnesses installed in the same scope, so a harness the run does not
+// name is never left with doors written for an older tree. The doors ride the same plan, backup
+// and ledger write as the run's own targets, and a door edited outside DoFlow refuses the whole plan.
+const { selectAssets } = require('../registry/index.js');
+const { resolveAdapter, projectAdapterInput } = require('../adapters/index.js');
+const { renderPolicies } = require('./policies.js');
+
+const HOOKS_TREE_ASSET = 'hooks.shared';
+const OPERATIONS = ['install', 'update'];
+
+/** Whether any target of the plan creates or updates a file of the shared hooks tree. */
+function hooksTreeChanged(targets       ) {
+  return targets.some((target     ) => !target.skipped
+    && target.changes.some((change     ) => change.assetId === HOOKS_TREE_ASSET && (change.operation === 'create' || change.operation === 'update')));
+}
+
+/** The plan entries for the hook front doors of every harness installed in this scope that the run
+ * does not name. Only the doors that differ from the current source appear, each with one notice;
+ * a door the adapter refuses to overwrite carries the conflict and the command that resolves it.
+ * `harnessScope` is the registry's name for the scope. `targetFromResult` is the lifecycle's own
+ * conversion of an adapter result into a plan entry. */
+function planHookCompanions({ registry, adapters, scope, harnessScope, scopeRoot, ledger, context, targets, targetFromResult }     ) {
+  // DEC-034 is about install and update: every other operation plans exactly the targets it was asked for.
+  if (!OPERATIONS.includes(context.operation) || !hooksTreeChanged(targets)) return [];
+  const named = new Set(targets.map((target     ) => target.harness));
+  const installed = new Set((ledger?.resources ?? []).map((resource     ) => resource.harness));
+  const run = targets.filter((target     ) => !target.skipped).map((target     ) => target.harness).join(',');
+  const companions        = [];
+  for (const harness of registry.harnesses) {
+    if (named.has(harness.id) || !installed.has(harness.id) || !harness.scopes.includes(harnessScope)) continue;
+    if (!harness.capabilities?.hooks || harness.capabilities.hooks.status === 'unavailable') continue;
+    const adapter = resolveAdapter(adapters, harness);
+    if (typeof adapter.planHookDoors !== 'function') continue;
+    const assets = selectAssets(registry, { harness: harness.id });
+    const policies = renderPolicies(registry, { harness: harness.id });
+    const adapterInput = projectAdapterInput({ registry, harness, scope, scopeRoot, assets, mcp: [], mcpAdoptable: [], policies, context });
+    const input = { ...adapterInput, registry, ledger };
+    const discovery = adapter.discover(input);
+    const target = targetFromResult({ harness, assets, mcp: [], mcpSelected: null, policies, adapterInput, discovery,
+      result: adapter.planHookDoors({ ...input, discovery }) });
+    if (!target.changes.length && !target.conflicts.length) continue;
+    companions.push({
+      ...target, hookDoorsOnly: true,
+      // The assets that own the doors this run plans, not the harness's whole set.
+      assets: target.assets.filter((asset     ) => target.changes.some((change     ) => change.assetId === asset.id)),
+      conflicts: target.conflicts.length
+        ? [...target.conflicts, `${harness.id} hook front doors must move with the shared hooks tree; run: doflow update -t ${run},${harness.id} (add -f to overwrite edited doors). Working command: doflow update -t ${run},${harness.id} -f`]
+        : target.conflicts,
+      notices: target.changes.length ? [`refreshed ${harness.id} hook front doors to match the shared hooks tree`, ...target.notices] : target.notices,
+    });
+  }
+  return companions;
+}
+
+module.exports = { planHookCompanions };

package/src/lifecycle/index.js

@@ -16,6 +16,7 @@ const { renderPolicies } = require('./policies.js');
 const { renderMcpIndex } = require('./mcp-index.js');
 const { hasBashCapableShell } = require('./bash-availability.js');
 const { hookTrustFor: geminiHookTrustFor } = require('../adapters/gemini/index.js');
+const { planHookCompanions } = require('./hook-step.js');
 
 const OPERATIONS = new Set(['create', 'merge', 'update', 'remove']);
 /** A harness's MCP selection meaning "the servers it owns now", read through its adapter's
@@ -453,6 +454,18 @@ function pruneRetiredRuntimeFiles(harnessPlans       , ledger     , { scopeRoot,
     : withChanges(target, replaced.get(target.harness) , added.get(target.harness) , notices.get(target.harness) )));
 }
 
+/** One harness's plan entry, from what its adapter returned: the changes checked against the
+ * harness's assets, and the conflicts, prerequisites and notices in the lifecycle's common shape. */
+function targetFromResult({ harness, assets, mcp, mcpSelected, policies, adapterInput, discovery, result }     ) {
+  if (!result || typeof result !== 'object') throw new Error(`Adapter '${harness.id}' returned an invalid plan`);
+  const changes = (result.changes || []).map((change     ) => normalizeChange(change, { harness, assets }));
+  const conflicts = adapterConflicts(result, harness);
+  const prerequisites = [...(result.prerequisites || []), ...changes.map((change     ) => change.prerequisite).filter(Boolean)];
+  const requiredNativeResources = result.requiredNativeResources ?? changes;
+  if (!Array.isArray(requiredNativeResources)) throw new Error(`Adapter '${harness.id}' returned invalid requiredNativeResources`);
+  return { harness: harness.id, adapter: harness.adapter, assets, mcp, mcpSelected, policies, adapterInput, discovery, changes, requiredNativeResources, conflicts, prerequisites, notices: adapterNotices(result), skipped: false };
+}
+
 function planLifecycle({ registry, adapters, scope, scopeRoot, targets, mcpSelections = {}, mcpAdoptable = {}, retainedMcpIds = [], ledger, context = {} }     ) {
   assertScope(scope);
   if (!registry) throw new Error('registry is required');
@@ -478,13 +491,7 @@ function planLifecycle({ registry, adapters, scope, scopeRoot, targets, mcpSelec
     const input = { ...adapterInput, registry, ledger: baseLedger };
     const discovery = adapter.discover(input);
     const result = adapter.plan({ ...input, discovery });
-    if (!result || typeof result !== 'object') throw new Error(`Adapter '${harness.id}' returned an invalid plan`);
-    const changes = (result.changes || []).map((change     ) => normalizeChange(change, { harness, assets }));
-    const conflicts = adapterConflicts(result, harness);
-    const prerequisites = [...(result.prerequisites || []), ...changes.map((change     ) => change.prerequisite).filter(Boolean)];
-    const requiredNativeResources = result.requiredNativeResources ?? changes;
-    if (!Array.isArray(requiredNativeResources)) throw new Error(`Adapter '${harness.id}' returned invalid requiredNativeResources`);
-    return { harness: harness.id, adapter: harness.adapter, assets, mcp, mcpSelected: capable ? mcp.map((server     ) => server.id) : null, policies, adapterInput, discovery, changes, requiredNativeResources, conflicts, prerequisites, notices: adapterNotices(result), skipped: false };
+    return targetFromResult({ harness, assets, mcp, mcpSelected: capable ? mcp.map((server     ) => server.id) : null, policies, adapterInput, discovery, result });
   });
   // The MCP index names every server a harness of this scope uses: the selections planned here and
   // the recorded selections of the harnesses this run does not touch.
@@ -495,12 +502,17 @@ function planLifecycle({ registry, adapters, scope, scopeRoot, targets, mcpSelec
   const retained = markRetainedRemovals(harnessPlans, baseLedger, scope);
   const annotated = context.operation === 'remove' ? retained
     : pruneRetiredRuntimeFiles(retained, baseLedger, { scopeRoot, repoRoot: context.repoRoot });
-  const changes = annotated.flatMap((item     ) => item.changes);
-  const conflicts = annotated.flatMap((item     ) => item.conflicts.map((reason     ) => ({ harness: item.harness, reason })));
-  const prerequisites = annotated.flatMap((item     ) => item.prerequisites.map((prerequisite     ) => ({ harness: item.harness, prerequisite })));
-  const requiredNativeResources = annotated.flatMap((item     ) => item.requiredNativeResources || []);
-  const notices = annotated.flatMap((item     ) => item.notices.map((notice     ) => ({ harness: item.harness, notice })));
-  return Object.freeze({ scope, scopeRoot, mcp: selectedMcp, ledger: baseLedger, targets: annotated, changes, requiredNativeResources, conflicts, prerequisites, notices,
+  // The shared hooks tree may have moved under harnesses this run does not name (IC-037): their
+  // front doors come along, as targets of this same plan.
+  const companions = planHookCompanions({ registry, adapters, scope, harnessScope: registryScope(scope), scopeRoot, ledger: baseLedger, context,
+    targets: annotated, targetFromResult });
+  const planned = [...annotated, ...companions];
+  const changes = planned.flatMap((item     ) => item.changes);
+  const conflicts = planned.flatMap((item     ) => item.conflicts.map((reason     ) => ({ harness: item.harness, reason })));
+  const prerequisites = planned.flatMap((item     ) => item.prerequisites.map((prerequisite     ) => ({ harness: item.harness, prerequisite })));
+  const requiredNativeResources = planned.flatMap((item     ) => item.requiredNativeResources || []);
+  const notices = planned.flatMap((item     ) => item.notices.map((notice     ) => ({ harness: item.harness, notice })));
+  return Object.freeze({ scope, scopeRoot, mcp: selectedMcp, ledger: baseLedger, targets: planned, changes, requiredNativeResources, conflicts, prerequisites, notices,
     retained: retainedChanges(changes), safe: conflicts.length === 0 && prerequisites.length === 0 });
 }
 
@@ -644,7 +656,9 @@ function verifyLifecycle({ plan, adapters, context = {} }     ) {
     const plannedWrites = context.checkPlannedWrites
       ? target.changes.filter((change     ) => !change.retained && (change.operation === 'create' || change.operation === 'update')).map((change     ) => change.target)
       : undefined;
-    let verification = normalizeVerification(adapter.verify({ ...target.adapterInput,
+    // A hook-front-door companion (IC-037) is verified for its doors alone: the rest of that
+    // harness is not part of this run and may legitimately trail the current source.
+    let verification = normalizeVerification(adapter[target.hookDoorsOnly ? 'verifyHookDoors' : 'verify']({ ...target.adapterInput,
       registry: context.registry ?? plan.registry, discovery: target.discovery, ledger: plan.ledger,
       operation, context: { ...target.adapterInput.context, operation, ...(plannedWrites ? { plannedWrites } : {}) } }), harness);
     if (operation === 'remove') verification = normalizeRemovalVerification(verification, target.changes, plan.ledger);