@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/helper/semver.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// SemVer 2.0.0 parsing and precedence, and the package host-range grammar (IC-016).
+// No dependency: DoFlow ships `2.0.0-beta.N`, so prerelease precedence is part of the contract.
+                                                                                    
+                                                            
+                                                                             
+                                                                                                
+
+const HOST_RANGE_GRAMMAR = 'one or more comparators separated by single spaces, all of which must hold: '
+  + '>=V, <V, =V or a bare V (exact), where V is a full semver 2.0.0 version; '
+  + 'an upper bound (<V, =V or a bare V) is required; no ^, ~, ||, x or *';
+
+function parseSemVer(value        )                {
+  const match = value.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+  if (!match) return null;
+  const prerelease = match[4] ? match[4].split('.') : [];
+  if (prerelease.some((identifier) => /^\d+$/.test(identifier)
+    && identifier.length > 1 && identifier.startsWith('0'))) return null;
+  return { major: match[1], minor: match[2], patch: match[3], prerelease };
+}
+
+function compareNumeric(left        , right        )         {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function compareSemVer(leftValue        , rightValue        )                {
+  const left = parseSemVer(leftValue);
+  const right = parseSemVer(rightValue);
+  if (!left || !right) return null;
+
+  for (const key of ['major', 'minor', 'patch']         ) {
+    const order = compareNumeric(left[key], right[key]);
+    if (order !== 0) return order;
+  }
+
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+  if (left.prerelease.length === 0) return 1;
+  if (right.prerelease.length === 0) return -1;
+
+  const length = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const leftId = left.prerelease[index];
+    const rightId = right.prerelease[index];
+    const leftNumeric = /^\d+$/.test(leftId);
+    const rightNumeric = /^\d+$/.test(rightId);
+    if (leftNumeric && rightNumeric) {
+      const order = compareNumeric(leftId, rightId);
+      if (order !== 0) return order;
+    } else if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    } else if (leftId !== rightId) {
+      return leftId < rightId ? -1 : 1;
+    }
+  }
+  if (left.prerelease.length === right.prerelease.length) return 0;
+  return left.prerelease.length < right.prerelease.length ? -1 : 1;
+}
+
+function refused(message        )            {
+  return { ok: false, error: { code: 'bad-type', message, allowed: HOST_RANGE_GRAMMAR } };
+}
+
+// Never throws: a refused range comes back as { ok: false, error } for the caller to turn into a finding.
+function parseHostRange(text         )            {
+  if (typeof text !== 'string') return refused('the host range must be a string');
+  const comparators               = [];
+  for (const token of text.split(' ')) {
+    const match = token.match(/^(>=|<|=)?(.+)$/);
+    if (!match || parseSemVer(match[2]) === null) {
+      return refused(`"${token}" is not a comparator of the host range grammar`);
+    }
+    comparators.push({ op: (match[1] || '=')                    , version: match[2] });
+  }
+  if (!comparators.some((comparator) => comparator.op !== '>=')) {
+    return refused('the host range has no upper bound');
+  }
+  return { ok: true, comparators };
+}
+
+// `range` is the range text or a parseHostRange result; a refused range or an invalid version satisfies nothing.
+function satisfiesHostRange(version        , range                    )          {
+  const parsed = typeof range === 'string' ? parseHostRange(range) : range;
+  if (!parsed.ok) return false;
+  return parsed.comparators.every(({ op, version: bound }) => {
+    const order = compareSemVer(version, bound);
+    if (order === null) return false;
+    return op === '>=' ? order >= 0 : op === '<' ? order < 0 : order === 0;
+  });
+}
+
+module.exports = { parseSemVer, compareSemVer, parseHostRange, satisfiesHostRange, HOST_RANGE_GRAMMAR };

package/src/install/backup.js

@@ -24,7 +24,7 @@ const { sourceCommit: gitSourceCommit } = require('../helper/git.js');
 const {
   legacyBackupReadRoot, isLegacyBackupReadRoot, scopeRootFromCanonicalBackupRoot,
 } = require('./paths.js');
-const { validateLedger } = require('../state/index.js');
+const { validateLedger, ownershipKey } = require('../state/index.js');
 
 /** Where a listed/restorable backup was found. 'current' = the canonical `.doflow/backups` root the
  * installer writes to; 'legacy' = the pre-7de6d5f `.claude/backups` root, readable only. Callers
@@ -69,6 +69,8 @@ function backupId(op        , date      )         {
 const MANIFEST_FILE = '.manifest.json';
 const OWNER_FILE = '.owner.json';
 const TEMP_PREFIX = '.tmp-';
+/** A backup retention is removing: renamed here first so a half-removed backup is never listed or counted. */
+const REMOVING_PREFIX = '.tmp-del-';
 const STALE_TEMP_MS = 24 * 60 * 60 * 1000;
 const MAX_ID_ATTEMPTS = 1000;
 const RENAME_COLLISION_CODES = new Set(['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES']);
@@ -129,7 +131,9 @@ function createFileBackup({
       fsImpl.mkdirSync(backupRoot, { recursive: true });
       fsImpl.mkdirSync(tmpDir);
       tmpCreated = true;
-      const owner = { pid: process.pid, hostname: os.hostname(), startedAt: date.toISOString() };
+      // When this run started, not `date`: that is the time the backup is named for, and a caller may pass any
+      // date. isStaleTemp measures a temp's age from this field.
+      const owner = { pid: process.pid, hostname: os.hostname(), startedAt: new Date().toISOString() };
       fsImpl.writeFileSync(path.join(tmpDir, OWNER_FILE), `${JSON.stringify(owner)}\n`, { flag: 'wx' });
     } catch (err) { throw writeFailure(err); }
 
@@ -234,6 +238,35 @@ function defaultIsAlive(pid        )          {
   }
 }
 
+/**
+ * The id of this process's pid namespace where the platform exposes one (Linux: the target of
+ * `/proc/self/ns/pid`, such as `pid:[4026531836]`), else the empty string. A pid means something only
+ * inside the namespace that issued it; two containers can share a hostname and not a pid space.
+ */
+function pidNamespaceId()         {
+  try { return fs.readlinkSync('/proc/self/ns/pid'); } catch { return ''; }
+}
+
+/**
+ * Eight hex digits that identify the host and pid namespace in a rename-aside name. A pid means
+ * something only in the namespace it was issued in, so an aside is judged by pid only by a process
+ * in the same namespace on the same host. Where no namespace id exists the tag is the hostname alone.
+ */
+function hostTag(hostname         = os.hostname(), pidNamespace         = pidNamespaceId())         {
+  return crypto.createHash('sha1').update(`${hostname}\0${pidNamespace}`).digest('hex').slice(0, 8);
+}
+
+/**
+ * The owner a rename-aside folder (`.tmp-del-<id>-<host tag>-<pid>-<8 hex>`) names, or null when the
+ * name does not carry one. Ids contain `-`, so the fields are read from the end. Names without a host
+ * tag (an earlier layout that never shipped: it existed only on unreleased commits, so no migration)
+ * are unparseable and are kept.
+ */
+function removingOwner(name        )                                       {
+  const m = /-([0-9a-f]{8})-([0-9]+)-[0-9a-f]{8}$/.exec(name);
+  return m ? { host: m[1], pid: Number(m[2]) } : null;
+}
+
 function isStaleTemp(dir        , { now, fsImpl, isAlive, hostname }     )          {
   let owner = null;
   try { owner = JSON.parse(fsImpl.readFileSync(path.join(dir, OWNER_FILE), 'utf8')); } catch { /* no owner */ }
@@ -247,15 +280,25 @@ function isStaleTemp(dir        , { now, fsImpl, isAlive, hostname }     )
 /**
  * Remove `.tmp-*` directories left in `backupRoot` by runs that died: the owner process is gone on
  * this host, or the temp is older than 24 hours. Returns how many were removed.
+ *
+ * A `.tmp-del-*` rename-aside is a backup a retention pass is deleting, so age says nothing about it
+ * (it keeps the backup's own, possibly old, mtime and may be rolled back if the delete fails). It is
+ * removed only by the host and pid namespace named in it, and only when the pid in its name is not
+ * alive; any other host's or namespace's aside, and one whose name carries no owner, is left alone.
  */
-function sweepStaleTemps(backupRoot        , { now = Date.now(), fsImpl = fs, isAlive = defaultIsAlive, hostname = os.hostname() }      = {})         {
+function sweepStaleTemps(backupRoot        , { now = Date.now(), fsImpl = fs, isAlive = defaultIsAlive, hostname = os.hostname(), pidNamespace = pidNamespaceId() }      = {})         {
   assertMutableBackupRoot(backupRoot, 'clean up backups');
   if (!fsImpl.existsSync(backupRoot)) return 0;
   let removed = 0;
   for (const e of fsImpl.readdirSync(backupRoot, { withFileTypes: true })) {
     if (!e.isDirectory() || !e.name.startsWith(TEMP_PREFIX)) continue;
     const dir = path.join(backupRoot, e.name);
-    if (!isStaleTemp(dir, { now, fsImpl, isAlive, hostname })) continue;
+    if (e.name.startsWith(REMOVING_PREFIX)) {
+      // Removed only by the host that made it, and only once its pid is gone there. Another host's
+      // (or an unparseable) aside is kept: its pass may be live where this one cannot see it.
+      const owner = removingOwner(e.name);
+      if (owner === null || owner.host !== hostTag(hostname, pidNamespace) || isAlive(owner.pid)) continue;
+    } else if (!isStaleTemp(dir, { now, fsImpl, isAlive, hostname })) continue;
     try {
       fsImpl.rmSync(dir, { recursive: true, force: true });
       removed += 1;
@@ -347,7 +390,7 @@ function formatBytes(n                           )         {
 
 /** Security guard: a backup id is a directory *name*, never a path — reject traversal/absolute ids. */
 function assertSafeBackupId(bid        )       {
-  if (!bid || bid.includes('/') || bid.includes('\\') || bid === '..' || bid.includes('..')) {
+  if (!bid || bid === '.' || bid.includes('/') || bid.includes('\\') || bid === '..' || bid.includes('..')) {
     throw new Error(`Invalid backup id: '${bid}'`);
   }
 }
@@ -441,6 +484,9 @@ function refusalOf(entry     , target        , { scope, scopeRoot, bkDir, fsImpl
   } catch {
     return 'content missing from backup';
   }
+  // A restore chmods the file it writes to this mode, so a manifest that lacks one (or holds anything
+  // but a permission mask) is refused here, with a name, rather than failing inside the write.
+  if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777) return 'invalid mode';
   return null;
 }
 
@@ -473,6 +519,8 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
     untargeted: 0,
     snapshot: [],
     v1: null,
+    // --target narrows the ledger with the files: the retired-harness rule of mergeRestoredLedger is off.
+    narrowed: Boolean(explicitTargets),
   };
   const wanted = new Set(targets);
 
@@ -535,13 +583,25 @@ function planRestore({ bid, backupRoot, scope, scopeRoot, targets, explicitTarge
  * the backup does not hold and rows of MCP entries (a file holding only MCP entries is never backed
  * up) stay as they are; restoring the whole old ledger would make DoFlow forget files and entries it
  * still has on disk. With no current ledger the backup's is taken whole.
+ *
+ * A harness in `retired` (retired in the registry now, row 127) is the exception: every row of it
+ * and its `targets` entry come back as the backup holds them. A sweep that retired it released some
+ * rows with no file effect (a file a live harness still claims), so no file of theirs is in the backup,
+ * yet the run dropped them. Only the sweep ever changes a retired row, so the backup's copy is never
+ * staler than the current one; a current row of it the backup lacks stays. A restored row whose file
+ * a live harness now claims is released by the next sweep (claim rule 2), file untouched.
  */
-function mergeRestoredLedger(backup     , current     , restored             )      {
+function mergeRestoredLedger(backup     , current     , restored             , retired              = new Set())      {
   if (!current) return backup;
   const at = (target     ) => typeof target === 'string' && restored.has(path.resolve(target));
+  const whole = (row     ) => retired.has(row?.harness);
+  const back = backup.resources.filter((r     ) => at(r.target) || whole(r));
+  const backKeys = new Set(back.filter(whole).map(ownershipKey));
+  const targets = Object.entries(backup.targets ?? {}).filter(([id]) => retired.has(id));
   return {
     ...current,
-    resources: [...current.resources.filter((r     ) => !at(r.target)), ...backup.resources.filter((r     ) => at(r.target))],
+    ...(targets.length ? { targets: { ...current.targets, ...Object.fromEntries(targets) } } : {}),
+    resources: [...current.resources.filter((r     ) => !at(r.target) && !(whole(r) && backKeys.has(ownershipKey(r)))), ...back],
     tombstones: [
       ...(current.tombstones ?? []).filter((t     ) => !at(t.fromTarget)),
       ...(backup.tombstones ?? []).filter((t     ) => at(t.fromTarget)),
@@ -549,21 +609,32 @@ function mergeRestoredLedger(backup     , current     , restored             )
   };
 }
 
+/** Ids the registry retires (row 127 IC-001): `registry` when a caller passes one, else the shipped
+ * registry. One that cannot be read retires nothing, which leaves the merge per restored file. */
+function retiredIds(registry     )              {
+  if (registry === undefined) {
+    const { REPO_ROOT } = require('../helper/repo-root.js');
+    try { registry = require('../registry/index.js').loadRegistry({ repoRoot: REPO_ROOT }); } catch { registry = null; }
+  }
+  return new Set((Array.isArray(registry?.retired) ? registry.retired : []).map((entry     ) => entry?.id).filter((id     ) => typeof id === 'string'));
+}
+
 /** The bytes a ledger restore item writes: the backup's ledger merged onto the current one. */
-function restoredLedgerBytes(item     , restored             , fsImpl     )         {
+function restoredLedgerBytes(item     , restored             , retired             , fsImpl     )         {
   const backup = validateLedger(JSON.parse(fsImpl.readFileSync(item.stored, 'utf8')));
   const current = fsImpl.existsSync(item.path) ? validateLedger(JSON.parse(fsImpl.readFileSync(item.path, 'utf8'))) : null;
-  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored)), null, 2)}\n`);
+  return Buffer.from(`${JSON.stringify(validateLedger(mergeRestoredLedger(backup, current, restored, retired)), null, 2)}\n`);
 }
 
 /**
  * Carry out a plan from planRestore. Format 2 writes each restore item through a temp file renamed
  * over the target (or straight through a symlinked target, which stays a link); a failed item is
  * reported and the rest continue. The ownership ledger goes last and restores only the rows of the
- * files written back before it (mergeRestoredLedger). It never deletes a file and never writes
+ * files written back before it, plus every row of a retired harness unless --target narrowed the
+ * restore (mergeRestoredLedger); `registry` is for tests, omitted the shipped one is read. It never deletes a file and never writes
  * outside `plan.restore`. A 1.19 plan goes through restoreBackup unchanged.
  */
-function executeRestore(plan     , { backupRoot, dryRun = false, fsImpl = fs }     )      {
+function executeRestore(plan     , { backupRoot, dryRun = false, registry, fsImpl = fs }     )      {
   if (plan.format !== 2) {
     const toolDirs = Object.fromEntries(plan.v1.tools.map((t     ) => [t.tool, t.dstDir]));
     restoreBackup({ bid: plan.bid, backupRoot, dirs: toolDirs, dryRun });
@@ -583,7 +654,7 @@ function executeRestore(plan     , { backupRoot, dryRun = false, fsImpl = fs }
     try {
       const dir = path.dirname(item.path);
       fsImpl.mkdirSync(dir, { recursive: true });
-      const bytes = item.ledger ? restoredLedgerBytes(item, files, fsImpl) : fsImpl.readFileSync(item.stored);
+      const bytes = item.ledger ? restoredLedgerBytes(item, files, plan.narrowed ? new Set() : retiredIds(registry), fsImpl) : fsImpl.readFileSync(item.stored);
       let isLink = false;
       try {
         isLink = fsImpl.lstatSync(item.path).isSymbolicLink();
@@ -685,7 +756,12 @@ function applyRetention({ backupRoot, keep, protect = [], reserve = 0, dryRun =
   const protectedCandidates = candidates.filter((c) => protectedIds.has(c.id));
   const ordered = [...protectedCandidates, ...candidates.filter((c) => !protectedIds.has(c.id))];
   const keepCount = keep === 0 ? ordered.length : Math.max(keep - reserve, protectedCandidates.length);
-  const removal = ordered.slice(keepCount).map((c) => c.id);
+  // The protected backup is the run's own, so one newer than it was made by another run that finished
+  // after it; this pass only reaps history older than its own backup.
+  const newestProtected = protectedCandidates[0];
+  const removal = ordered.slice(keepCount)
+    .filter((c) => !newestProtected || compareSortKeys(c, newestProtected) >= 0)
+    .map((c) => c.id);
 
   if (dryRun || keep === 0) {
     if (dryRun) result.wouldRemove = removal;
@@ -693,16 +769,30 @@ function applyRetention({ backupRoot, keep, protect = [], reserve = 0, dryRun =
     return result;
   }
 
+  // Also deletes what an earlier pass renamed aside and died before deleting (a `.tmp-del-*` whose pid
+  // is dead): already out of every listing, so it goes at once. One whose pid is alive belongs to a
+  // pass that may still roll it back, so it is never touched here, whatever its age.
   result.sweptTemps = sweepStaleTemps(backupRoot, { now, fsImpl });
   for (const id of removal) {
     const dir = path.join(backupRoot, id);
     // Another run's retention pass may have removed it already.
     if (!fsImpl.existsSync(dir)) continue;
+    // One rename takes the backup out of the listing whole; the deletion then happens out of sight.
+    const aside = path.join(backupRoot, `${REMOVING_PREFIX}${id}-${hostTag()}-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
     try {
-      fsImpl.rmSync(dir, { recursive: true, force: true });
+      fsImpl.renameSync(dir, aside);
+    } catch (err     ) {
+      if (err.code !== 'ENOENT') result.failed.push({ id, error: err.message });
+      continue;
+    }
+    try {
+      fsImpl.rmSync(aside, { recursive: true, force: true });
       result.removed.push(id);
     } catch (err     ) {
+      // Not removed: put it back under its id so it is still counted and listed, as when it was
+      // removed in place. If that fails too the aside folder is not listed and the next pass deletes it.
       result.failed.push({ id, error: err.message });
+      try { fsImpl.renameSync(aside, dir); } catch { /* the next pass cleans the aside folder */ }
     }
   }
   result.kept = ordered.filter((c) => fsImpl.existsSync(path.join(backupRoot, c.id))).length;
@@ -718,7 +808,7 @@ function retentionNote(prune                           , keep        )         {
 
 module.exports = {
   backupId, restoreBackup, listBackups, assertSafeBackupId, scopeRelative, retentionNote,
-  backupReadRoots, BACKUP_ORIGIN_CURRENT, BACKUP_ORIGIN_LEGACY,
+  backupReadRoots, hostTag, BACKUP_ORIGIN_CURRENT, BACKUP_ORIGIN_LEGACY,
   BackupError, DEFAULT_BACKUP_RETENTION, createFileBackup, sweepStaleTemps, classifyBackupDir,
   sortKey, backupSize, formatBytes, planRestore, executeRestore, mergeRestoredLedger, applyRetention,
 };

package/src/install/context.js

@@ -46,7 +46,7 @@ function printContext(ctx     )       {
     '[CONTEXT] Resolved install context',
     `  scope         : ${ctx.scope}  (root: ${ctx.scopeRoot})`,
     `  targets       : ${ctx.targets.join(', ')}`,
-    ...ctx.targets.map((t        ) => `    ${t.padEnd(7)}-> ${ctx.dirs[t]}`),
+    ...ctx.targets.map((t        ) => `    ${t.padEnd(7)}-> ${ctx.dirs[t] ?? '(resolved by adapter)'}`),
     `  repo root     : ${ctx.repoRoot}`,
     `  source commit : ${ctx.sourceCommit}`,
     `  node          : ${ctx.nodeVersion}`,

package/src/install/targets.js

@@ -1,6 +1,6 @@
 'use strict';
 // targets.js — target validation + install-dir resolution.
-// PARITY: sync.sh is global-only — $HOME/.{claude,codex,gemini}, hardcoded, NOT CLAUDE_CONFIG_DIR.
+// PARITY: sync.sh is global-only — $HOME/.{claude,codex}, hardcoded, NOT CLAUDE_CONFIG_DIR.
 // doflow extends this with a second, DoFlow-only scope: project-local install (this repo's own
 // .claude/ is a real precedent — Claude Code, Codex, and Copilot all support project-scoped config
 // alongside global, see agent-docs/research/context-setup-claude-codex-copilot.md).
@@ -15,25 +15,43 @@
 const os = require('node:os');
 const path = require('node:path');
 
-const VALID = ['claude', 'codex', 'gemini', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
+const VALID = ['claude', 'codex', 'copilot', 'kiro', 'opencode', 'pi', 'antigravity'];
 
 /** The target used when `--target` is omitted. Deliberately one harness, not all of VALID: an
  * install with no flag should touch the one tool the user almost certainly has, not write
  * configuration into every harness DoFlow knows about — several of which may not be installed at
  * all. That mattered less when VALID was three entries and matters more as it grows. Ask for the
- * rest explicitly with `--target claude,codex,gemini`. */
+ * rest explicitly with `--target claude,codex,antigravity`. */
 const DEFAULT_TARGETS = ['claude'];
 
 const TARGET_ALIASES                         = {
   agy: 'antigravity',
 };
 
-/** Default to DEFAULT_TARGETS; validate any explicitly requested. */
-function resolveTargets(requested                      )           {
+/** The registry's retired record for `id`, or null. The registry is read only for an id outside
+ * VALID, and a registry that cannot be read leaves the id unknown rather than failing differently. */
+function retiredTarget(id        , registry     )      {
+  const { loadRegistry, retiredFor } = require('../registry/index.js');
+  if (!registry) {
+    const { REPO_ROOT } = require('../helper/repo-root.js');
+    try { registry = loadRegistry({ repoRoot: REPO_ROOT }); } catch { return null; }
+  }
+  return retiredFor(registry, id);
+}
+
+/** Default to DEFAULT_TARGETS; validate any explicitly requested. A retired id (row 127 IC-002) is
+ * refused like an unknown one, naming its replacement. `registry` is for tests; omitted, the
+ * shipped registry is read. */
+function resolveTargets(requested                      , { registry }                     = {})           {
   const rawTargets = requested && requested.length ? requested : [...DEFAULT_TARGETS];
   const targets = rawTargets.map((t) => TARGET_ALIASES[t] || t);
   for (const t of targets) {
     if (!VALID.includes(t)) {
+      const retired = retiredTarget(t, registry);
+      if (retired) {
+        const alias = Object.keys(TARGET_ALIASES).find((key) => TARGET_ALIASES[key] === retired.replacement);
+        throw new Error(`Target '${t}' was retired on ${retired.retiredOn}; use '${retired.replacement}'${alias ? ` (alias ${alias})` : ''}. Its DoFlow files are released by the next 'doflow install' or 'doflow update' in that scope.`);
+      }
       throw new Error(`Unknown target: '${t}' (valid: ${VALID.join(', ')})`);
     }
   }
@@ -47,16 +65,14 @@ function resolveTargets(requested                      )           {
 
 /**
  * Map tool -> install root.
- *   global=true         -> $HOME/.{claude,codex,gemini,copilot,kiro,pi}, $HOME/.config/opencode
- *                          (sync.sh parity for claude/codex/gemini; the four new harnesses follow
- *                          each one's own documented global root — see below)
- *   global=false (dflt) -> <resolved projectRoot>/.{claude,codex,kiro,opencode,pi}, but .agents for
- *     gemini and .github for copilot — both deliberately asymmetric with their own global-scope
- *     directory, for reasons native to each harness (see per-key notes below).
+ *   global=true         -> $HOME/.{claude,codex,copilot,kiro,pi}, $HOME/.config/opencode
+ *                          (sync.sh parity for claude/codex; the other harnesses follow each one's
+ *                          own documented global root — see below)
+ *   global=false (dflt) -> <resolved projectRoot>/.{claude,codex,kiro,opencode,pi}, but .github for
+ *     copilot — deliberately asymmetric with its own global-scope directory, for reasons native to
+ *     the harness (see per-key notes below). antigravity has no entry: its adapter resolves its
+ *     own paths from core/registry/harnesses.json.
  *
- *   gemini   -> project-scoped Gemini config follows the Antigravity customization convention, not
- *               `.gemini/`, so it is asymmetric with its own global directory and with the other
- *               targets.
  *   copilot  -> Copilot has no single native root the way Claude's `.claude` is one: instructions,
  *               skills, agents, and MCP each live under a different path (see design.md §4's
  *               native-surfaces table). `.github` is the project root DoFlow treats as Copilot's
@@ -67,7 +83,7 @@ function resolveTargets(requested                      )           {
  *               the clean, symmetric case.
  *   opencode -> Global config is `~/.config/opencode`, NOT `~/.opencode/` — a path DoFlow's own
  *               docs asserted incorrectly for several releases (see src/adapters/opencode/index.js).
- *               Project scope is `.opencode`, asymmetric with the global path the same way gemini's
+ *               Project scope is `.opencode`, asymmetric with the global path the same way copilot's
  *               is.
  *   pi       -> Global config is `~/.pi/agent` — note the `agent/` segment; `~/.pi/settings.json`
  *               is not a location Pi reads. Project scope is `.pi` (see
@@ -79,7 +95,6 @@ function toolDirs(opts                  = {})                         {
   return {
     claude: path.join(root, '.claude'),
     codex: path.join(root, '.codex'),
-    gemini: global ? path.join(root, '.gemini') : path.join(root, '.agents'),
     copilot: global ? path.join(root, '.copilot') : path.join(root, '.github'),
     kiro: path.join(root, '.kiro'),
     opencode: global ? path.join(root, '.config', 'opencode') : path.join(root, '.opencode'),

package/src/lifecycle/coverage.js

@@ -0,0 +1,74 @@
+'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', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity']);
+const BEHAVIOUR_ORDER = Object.freeze(['context-authority', 'default-silence', 'summary-scope', 'summary-grant', 'identity', 'check-freshness']);
+const NEVER_BLOCKING_EVENTS = new Set([
+  'pi\u0000tool_execution_start', 'antigravity\u0000PostToolUse', 'antigravity\u0000PreInvocation',
+  'antigravity\u0000PostInvocation', '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');
+}
+// IC-019: one row per behaviour x harness, ordered by IC-018's behaviour list, then HARNESS_ORDER.
+function renderBehaviourMatrix(coverage     )         {
+  const order = (items                   , value        ) => {
+    const index = items.indexOf(value);
+    return index < 0 ? items.length : index;
+  };
+  const entries = [...(coverage.behaviours || [])].sort((a     , b     ) => order(BEHAVIOUR_ORDER, a.behaviour) - order(BEHAVIOUR_ORDER, b.behaviour)
+    || order(HARNESS_ORDER, a.harness) - order(HARNESS_ORDER, b.harness)
+    || a.behaviour.localeCompare(b.behaviour) || a.harness.localeCompare(b.harness));
+  const lines = [`Schema ${coverage.schemaVersion}; revision ${coverage.revision}`, '| Behaviour | Harness | Status | Limitation or tests |', '|---|---|---|---|'];
+  for (const entry of entries) {
+    const detail = entry.status === 'enforced' ? (entry.tests || []).join(', ') : (entry.limitation || '');
+    lines.push(`| ${entry.behaviour} | ${entry.harness} | ${entry.status} | ${detail} |`);
+  }
+  return lines.join('\n');
+}
+module.exports = { enforcementFor, renderEnforcementMatrix, renderBehaviourMatrix, BEHAVIOUR_ORDER, HARNESS_ORDER, 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 };