@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/adapters/kiro/index.js

@@ -7,11 +7,13 @@
 // Kiro's native root is symmetric across scopes — `.kiro/` (project) / `~/.kiro/` (global) is the
 // one directory that holds everything Kiro reads: steering, agents, hooks, and settings/mcp.json
 // (see src/targets.js's toolDirs() for the same convention this adapter's own nativePaths()
-// mirrors). Unlike every other harness in this codebase, Kiro receives DoFlow's *full* guidance
-// tree as steering files rather than a single marker-wrapped pointer file plus a separately-copied
-// tree (design.md §4's "research decision D3"): there is no single-file instruction surface here
-// at all, so — unlike src/adapters/gemini or src/adapters/opencode — this adapter never renders a
-// marker-wrapped instruction file.
+// mirrors). Unlike every other harness in this codebase, Kiro receives DoFlow's guidance as
+// steering files rather than a single marker-wrapped pointer file plus a separately-copied tree
+// (design.md §4's "research decision D3"): there is no single-file instruction surface here at all,
+// so — unlike src/adapters/opencode — this adapter never renders a
+// marker-wrapped instruction file. Steering holds the core set only (DOFLOW_CORE.md and the files it
+// imports, selected by the `guidance-manifest` select); the full guidance tree remains under
+// `.doflow/guidance` through kiro.guidance-tree, where `retrieve` and the runtime read it.
 //
 // Evidence: https://kiro.dev/docs/steering/, https://kiro.dev/docs/mcp/configuration/,
 // https://kiro.dev/docs/hooks/
@@ -37,6 +39,15 @@ const LEGACY_MCP_REGISTRATION = `${HARNESS}:mcp:registration`;
  * module-level exports delegate to a default-configured instance so direct callers keep their
  * historical shape.
  */
+/** Hook tiers (maint-hooks): with Kiro outside `hooks.harnesses` (`context.hooksOff`) its agents carry no
+ * `hooks`, so they never name a hook script DoFlow did not install. */
+const CONTENT_ONLY_TRANSFORMS                                   = Object.freeze({ 'kiro-agents': 'kiro-agents-content' });
+function transformFor(asset     , context     )                {
+  if (context?.hooksOff !== true) return asset.transform || null;
+  if (asset.id === 'kiro.doflow-agent') return 'kiro-agent-content';
+  return CONTENT_ONLY_TRANSFORMS[asset.transform] ?? (asset.transform || null);
+}
+
 function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } = {}) {
   // Parity note: Kiro's historical nativePaths() derived even its user-scope root from scopeRoot
   // (the CLI passes $HOME there for -g installs), never from a separate homeDir argument — so the
@@ -59,8 +70,8 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
 
   /**
    * Kiro has no single-file, marker-managed instruction surface for this adapter to render into —
-   * the guidance tree is projected file-for-file by the copy-tree engine below, once as steering
-   * (guidance.context-layer) and once into the shared `.doflow/guidance` (kiro.guidance-tree). Every
+   * guidance is projected file-for-file by the copy-tree engine below, the core set as steering
+   * (guidance.context-layer) and the whole tree into the shared `.doflow/guidance` (kiro.guidance-tree). Every
    * asset routed to 'kiro' in core/registry/assets.json uses `renderer: copy-tree` or
    * `kiro-agents`, so nothing reaches this function. It is kept as a pure passthrough only to
    * satisfy the six-function adapter contract every harness must implement identically.
@@ -98,7 +109,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
       const destDir = copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
       const previousResources = ledgerFileResources(ledger?.resources, HARNESS, asset.id);
-      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: asset.transform, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: transformFor(asset, context), select: asset.select, keepModified: !removing,
         // Forwarded so the CLI's --force reaches planTree's conflict check; omitting it let
         // planTree's own `force = false` default stand in silently. Gated on `!removing` for the
         // reason codex/index.ts states in full: force heals drift on apply, but a hand-edited file
@@ -115,7 +126,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
           ownershipIdentity: `doflow:${HARNESS}:copy-tree:${asset.id}:${change.relPath}`,
           kind: 'copy-tree-file', identity: change.relPath,
           afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
-          transformName: asset.transform || null,
+          transformName: transformFor(asset, context),
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
           projection: { renderer: asset.renderer },
         });
@@ -153,7 +164,7 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
     for (const asset of kiroTreeAssets(assets)) {
       const destDir = copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Kiro');
-      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: transformFor(asset, context), select: asset.select, plannedWrites: context?.plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -209,8 +220,8 @@ function createKiroAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS] } =
 
   /** Kiro has no hooks or mcp asset of its own in core/registry/assets.json (mcp servers come from
    * core/registry/mcp.json, not an asset), so an MCP entry change piggybacks on an asset id
-   * this harness actually receives — the same "pseudo-component" technique
-   * src/adapters/gemini/index.js#hooksAssetId already uses for its own settings-only component. */
+   * this harness actually receives — the same "pseudo-component" technique the opencode and
+   * copilot adapters use for their settings-only changes. */
   function pseudoAssetId(assets     ) {
     return assets.find((asset     ) => asset.id === 'guidance.context-layer')?.id ?? assets[0]?.id;
   }

package/src/adapters/opencode/index.js

@@ -4,7 +4,7 @@
 
 // OpenCode adapter.
 //
-// OpenCode gets its own copy of DoFlow's skills tree, the same as Claude, Codex, and Gemini: it
+// OpenCode gets its own copy of DoFlow's skills tree, the same as Claude and Codex: it
 // natively discovers skills under `.opencode/skills/` (project) and `~/.config/opencode/skills/`
 // (global) without any settings entry, so the shared copy-tree engine in ../copy-tree.ts
 // materialises `skills.doflow` there directly. What remains registration, rather than
@@ -20,11 +20,11 @@ const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDes
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 
 // Only the marker constants: marker-merge.js reads and writes files itself, which cannot be used
-// from plan(), whose contract is to compute changes without touching disk. The gemini adapter
-// solves this the same way, with a pure managedInstruction() over strings.
+// from plan(), whose contract is to compute changes without touching disk.
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { destructiveCommandGlobs } = require('../../helper/guardrails.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 
 const HARNESS = 'opencode';
 /**
@@ -107,9 +107,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   }
 
   /** Replace only the span between DoFlow's markers, leaving everything else byte-identical.
-   * An AGENTS.md that exists without a DoFlow section is refused rather than appended to — the same
-   * policy the gemini adapter applies to GEMINI.md, and for the same reason: AGENTS.md is a shared,
-   * cross-tool file, so where DoFlow's content belongs inside it is a decision for its owner, not a
+   * An AGENTS.md that exists without a DoFlow section is refused rather than appended to:
+   * AGENTS.md is a shared, cross-tool file, so where DoFlow's content belongs inside it is a decision for its owner, not a
    * guess for the installer. Add an empty marker pair to opt in. */
   /** Opt-in (--permissions) guardrail projection: DoFlow's destructive-command blocklist lands as
    * deny rules under permission.bash. Only keys this feature owns (each carries a matching
@@ -259,7 +258,7 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
   /** OpenCode's settings-merge change has no asset of its own in core/registry/assets.json (it's a
    * registration side-effect of the instructions/mcp assets, not a projected asset), so it piggybacks
    * on a real asset id already routed to this harness — the same "pseudo-component" technique
-   * src/adapters/gemini/index.js#hooksAssetId and src/adapters/kiro/index.js#pseudoAssetId use. The
+   * src/adapters/kiro/index.js#pseudoAssetId uses. The
    * lifecycle layer validates every change's assetId against the harness's actual asset list, so an
    * invented id like the literal string 'opencode.config' is rejected as unknown. */
   function pseudoAssetId(assets     ) {
@@ -308,7 +307,8 @@ function createOpenCodeAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS]
 
     const guidance = assets.find((asset     ) => asset.capability === 'instructions');
     if (guidance) {
-      const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
+      const pointer = renderGuidancePointer(fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8'), { scope, scopeRoot });
+      const rendered = render({ content: pointer });
       const outcome = removing
         ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
         : managedInstruction(found.instruction, rendered);

package/src/adapters/pi/hooks.js

@@ -93,7 +93,8 @@ function verifyPiHooks({ scope, scopeRoot, assets = [], ledger, context = {}, ad
   const plannedWrite = (context?.plannedWrites || []).includes(target);
   const bridgeMatches = !!content && content.includes(JSON.stringify(path.relative(path.dirname(target), bridgePath).split(path.sep).join('/')));
   const commandOnPath = (command        ) => String(pathEnv || '').split(path.delimiter)
-    .some((dir) => fsImpl.existsSync(path.join(dir, command)));
+    .some((dir) => [command, ...(process.platform === 'win32' ? ['.exe', '.cmd', '.bat'].map((ext) => command + ext) : [])]
+      .some((name) => fsImpl.existsSync(path.join(dir, name))));
   const status = present && !owned && !plannedWrite && !adopt ? 'conflict'
     : (present && (fingerprintMatches || plannedWrite) && bridgeMatches && commandOnPath('bash') && commandOnPath('jq') ? 'managed' : 'absent');
   const resources = status === 'managed' ? [{ assetId: ASSET_ID, target, ownershipIdentity: OWNERSHIP,

package/src/adapters/pi/index.js

@@ -3,7 +3,7 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
 // Pi adapter — a marker-merged instruction file plus copy-tree materialisation, the same shape
-// Claude/Codex/Gemini already use for their own skills trees.
+// Claude/Codex already use for their own skills trees.
 //
 // Skills materialise into Pi's own directories (`~/.pi/agent/skills` global, `.pi/skills` project)
 // via the shared copy-tree engine, rather than pointing Pi's settings.json at DoFlow's already
@@ -22,10 +22,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor } = require('../copy-tree.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor, resolveTransform } = require('../copy-tree.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 const { mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp } = require('./mcp.js');
 const { planPiHooks, verifyPiHooks, removePiHooks } = require('./hooks.js');
+const { renderGuidancePointer } = require('../guidance-pointer.js');
 
 const HARNESS = 'pi';
 const AGENT_DIR_MCP_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, but DoFlow moves only mcp.json there; skills and AGENTS.md stay in ~/.pi/agent.';
@@ -105,7 +106,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
       const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
       const previousResources = ledgerFileResources(ledger?.resources, HARNESS, asset.id);
-      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, keepModified: !removing,
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, transform: asset.transform, keepModified: !removing,
         // Forwarded so the CLI's --force reaches planTree's conflict check; omitting it let
         // planTree's own `force = false` default stand in silently. Gated on `!removing` for the
         // reason codex/index.ts states in full: force heals drift on apply, but a hand-edited file
@@ -123,6 +124,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
           kind: 'copy-tree-file', identity: change.relPath,
           afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
           ...(change.kept ? { retained: true, retainedFor: [] } : {}),
+          transformName: asset.transform || null,
           projection: { renderer: 'copy-tree' },
         });
       }
@@ -132,8 +134,12 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
   function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
     const treeChanges = changes.filter((change     ) => change.projection?.renderer === 'copy-tree' && change.operation !== 'remove')
-      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint }));
-    return applyTree({ changes: treeChanges, fsImpl }).applied;
+      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint, transformName: change.transformName || null }));
+    const grouped = new Map                      ();
+    for (const change of treeChanges) grouped.set(change.transformName, [...(grouped.get(change.transformName) || []), change]);
+    let applied = 0;
+    for (const [transformName, group] of grouped) applied += applyTree({ changes: group, fsImpl, transform: resolveTransform(transformName) }).applied;
+    return applied;
   }
 
   function removeCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
@@ -150,7 +156,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     for (const asset of copyTreeAssets(assets)) {
       const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
       const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
-      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, plannedWrites: context?.plannedWrites });
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, transform: asset.transform, plannedWrites: context?.plannedWrites });
       conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
       for (const resource of result.resources) {
         resources.push({
@@ -175,7 +181,8 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
     const guidance = assets.find((asset     ) => asset.capability === 'instructions');
     if (guidance) {
-      const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
+      const pointer = renderGuidancePointer(fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8'), { scope, scopeRoot });
+      const rendered = render({ content: pointer });
       const outcome = removing
         ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
         : managedInstruction(found.instruction, rendered);

package/src/adapters/resolve-source.js

@@ -2,12 +2,36 @@
 
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
+const fs = require('node:fs');
 const path = require('node:path');
 
 /** Resolve a registry-declared source path against the repo root, refusing escapes. Shared by the
  * common projection module and by per-adapter native-projection normalizers, which is why it lives
- * in its own module rather than in index.js — a normalizer importing index.js would be a cycle. */
-function resolveRegistrySource(registry     , source     , label        )         {
+ * in its own module rather than in index.js — a normalizer importing index.js would be a cycle.
+ * `sourceRoot` checks containment against that root using real paths, as required by IC-017.
+ * When omitted, the existing lexical repository-root check is preserved. */
+function resolveRegistrySource(registry     , source     , label        , sourceRoot         )         {
+  if (sourceRoot !== undefined) {
+    if (typeof sourceRoot !== 'string' || !sourceRoot) {
+      throw new Error(`Registry ${label} sourceRoot must be a non-empty string`);
+    }
+    if (typeof source !== 'string' || !source) throw new Error(`Registry ${label} source is required`);
+    let realRoot        ;
+    let realSource        ;
+    try {
+      realRoot = fs.realpathSync(path.resolve(sourceRoot));
+      realSource = fs.realpathSync(path.resolve(sourceRoot, source));
+    } catch (error     ) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+        throw new Error(`Registry ${label} source is missing under source root: ${source}`);
+      }
+      throw error;
+    }
+    if (!realSource.startsWith(`${realRoot}${path.sep}`)) {
+      throw new Error(`Registry ${label} source escapes source root: ${source}`);
+    }
+    return realSource;
+  }
   if (typeof registry.repoRoot !== 'string' || !registry.repoRoot) throw new Error(`Registry repoRoot is required for ${label}`);
   if (typeof source !== 'string' || !source) throw new Error(`Registry ${label} source is required`);
   const root = path.resolve(registry.repoRoot);

package/src/cli/commands/install.js

@@ -20,7 +20,7 @@ const { loadRegistry } = require('../../registry/index.js');
 const { storageAfterInstall } = require('../../runtime/storage/upkeep.js');
 const { applyLifecycle, applyMcpIndex, recordMcpOwnership } = require('../../lifecycle/index.js');
 const {
-  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, assertSafeRegistryPlan,
+  codexScope, registryLifecycleView, printRegistryLifecycle, printRetiredPlans, printPlanNotices, assertSafeRegistryPlan,
   lockDocument, recordLock,
 } = require('../../lifecycle/view.js');
 const {
@@ -120,6 +120,7 @@ function cmdInstall(o     )       {
         const owned = result.ledger.resources.filter((resource     ) => resource.harness === target.harness).length;
         console.log(`[INFO] ${target.harness}: lifecycle verified (${owned} owned resource(s))`);
       }
+      printRetiredPlans(lifecycleView);
       ledgerAfter = result.ledger;
     } else {
       // MCP_INDEX.md is generated, not a tracked resource, so it never appears in plan.changes and

package/src/cli/commands/reconcile.js

@@ -2,13 +2,19 @@
 // `doflow reconcile` — converge observed state onto the doflow.lock pin: report drift, then heal
 // it on confirmation. Never re-prompts for MCP; selections ride exactly as pinned.
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const path = require('node:path');
 const { toolDirs } = require('../../install/targets.js');
 const { resolveContext, printContext } = require('../../install/context.js');
 const { writeManifest } = require('../../install/manifest.js');
+const { DEFAULT_BACKUP_RETENTION, createFileBackup } = require('../../install/backup.js');
+const { backupSetFromPlan, backupSetFromPaths } = require('../../install/backup-set.js');
+const { ledgerPath } = require('../../state/index.js');
+const { backupStep, reportBackup, applyBackupRetention } = require('./install.js');
 const { confirm } = require('../../helper/prompt.js');
 const { sourceCommit } = require('../../helper/git.js');
-const { loadRegistry } = require('../../registry/index.js');
+const { loadRegistry, retiredFor } = require('../../registry/index.js');
 const { applyLifecycle, recordMcpOwnership } = require('../../lifecycle/index.js');
+const { formatRetiredPlans, retiredReleaseKeys } = require('../../lifecycle/retired-harnesses.js');
 const {
   registryLifecycleView, assertSafeRegistryPlan,
 } = require('../../lifecycle/view.js');
@@ -33,6 +39,10 @@ function reconcileReport(view     )      {
     }
     perHarness.set(target.harness, entry);
   }
+  // A retired harness's rows (row 127 IC-003) are drift too: converging means releasing them.
+  for (const change of (view.plan.retiredHarnesses ?? []).flatMap((item     ) => item.changes)) {
+    drifts.push({ harness: change.harness, operation: change.operation, assetId: change.assetId, target: change.target, retired: true });
+  }
   return {
     drifts,
     conflicts: view.plan.conflicts,
@@ -42,17 +52,29 @@ function reconcileReport(view     )      {
   };
 }
 
-function printReconcileReport(report     , lock     )       {
+function printReconcileReport(report     , lock     , retiredLines           = [])       {
   console.log(`[INFO] Reconciling against doflow.lock (sourceVersion ${lock.sourceVersion ?? 'unknown'})`);
   for (const [harness, counts] of Object.entries     (report.perHarness)) {
     const total = counts.create + counts.update + counts.remove;
     console.log(`[INFO] ${harness}: ${total === 0 ? 'clean' : `${total} drift(s) (${counts.create} create, ${counts.update} update, ${counts.remove} remove)`}`);
   }
+  for (const line of retiredLines) console.log(line);
   for (const conflict of report.conflicts) console.log(`[CONFLICT] ${conflict.harness}: ${conflict.reason}`);
   for (const prerequisite of report.prerequisites) console.log(`[PENDING-TRUST] ${prerequisite.harness}: ${prerequisite.prerequisite}`);
   if (report.clean) console.log('[OK] Observed state matches doflow.lock.');
 }
 
+/** The backup a retirement sweep takes (row 127 FR-4): the set install and update take, files and
+ * ledger. A sweep that only gives up rows (release, drop, keep) touches no file, so that set is empty;
+ * the ledger alone is then what a rollback needs to bring the rows and the target entry back. */
+function retirementBackupSet(view     , paths     , scope     )      {
+  const ledger = ledgerPath(view.stateRoot);
+  const args = { scope: scope.global ? 'global' : 'project', scopeRoot: paths.scopeRoot, records: [ledger],
+    exclude: [paths.backupRoot, view.stateRoot, paths.manifestPath, path.join(paths.doflowRoot, 'doflow.lock')] };
+  const set = backupSetFromPlan({ plan: view.plan, ...args });
+  return set.count ? set : backupSetFromPaths({ items: [{ path: ledger, harnesses: [] }], ...args });
+}
+
 function cmdReconcile(o     )       {
   refuseHomeRootedProject(o, 'reconcile');
   const scope = scopeOf(o);
@@ -61,23 +83,33 @@ function cmdReconcile(o     )       {
     const dirs = toolDirs(scope);
     const lifecyclePaths = installPaths(scope);
     const { lock, ledger, manifestServers } = scopeSelectionState(scope);
+    // Read only when there is a pin or a row to classify, as before this check existed.
+    const registry = lock?.targets?.length || ledger?.resources?.length ? loadRegistry({ repoRoot: REPO_ROOT }) : null;
+    const retired = (harness        ) => (registry ? retiredFor(registry, harness) : null);
+    // A retired pin (row 127 IC-004) names a harness with no adapter: dropped, said, and the rest
+    // converge. Its ledger rows are released by this run's plan, like install's and update's.
+    for (const entry of lock?.targets ?? []) {
+      const record = retired(entry.harness);
+      if (record) console.log(`[WARN] ${entry.harness}: retired (use ${record.replacement}); dropped from the pinned targets`);
+    }
+    const livePins = (lock?.targets ?? []).filter((entry     ) => !retired(entry.harness));
     // A harness the ledger holds but the lock does not pin is installed and outside reconcile's reach.
     // Said, not converged: the lock records choices, and reconcile has no choice to record for it.
-    const pinned = new Set((lock?.targets ?? []).map((entry     ) => entry.harness));
-    const unpinned = [...new Set((ledger?.resources ?? []).map((resource     ) => resource.harness))].filter((harness) => !pinned.has(harness)).sort();
+    const pinned = new Set(livePins.map((entry     ) => entry.harness));
+    const unpinned = [...new Set((ledger?.resources ?? []).map((resource     ) => resource.harness))]
+      .filter((harness     ) => !pinned.has(harness) && !retired(harness)).sort();
     for (const harness of unpinned) {
       const count = ledger.resources.filter((resource     ) => resource.harness === harness).length;
       console.log(`[WARN] ${harness}: installed (ledger holds ${count} resource(s)) but absent from doflow.lock; reconcile does not converge it.`);
     }
-    if (!lock || !lock.targets.length) {
+    if (!lock || !livePins.length) {
       // Reconcile converges onto what install pinned; with no pin there is no desired state to
       // converge to, and guessing one from the registry would silently adopt targets the user
       // never chose.
       console.log('[INFO] No doflow.lock in this scope — nothing pinned to reconcile against. Run `doflow install` first.');
       return;
     }
-    const targets = lock.targets.map((entry     ) => entry.harness);
-    const registry = loadRegistry({ repoRoot: REPO_ROOT });
+    const targets = livePins.map((entry     ) => entry.harness);
     printContext(resolveContext({ repoRoot: REPO_ROOT, targets, dirs, sourceCommit: sourceCommit(SCRIPT_DIR), ...scope }));
     // Each harness converges onto its own pinned selection — reconcile never re-prompts and never
     // lends one harness's servers to another.
@@ -87,7 +119,7 @@ function cmdReconcile(o     )       {
     if (!lifecycleView.plan.safe) { assertSafeRegistryPlan(lifecycleView); return; }
 
     const report = reconcileReport(lifecycleView);
-    printReconcileReport(report, lock);
+    printReconcileReport(report, lock, formatRetiredPlans(lifecycleView.plan.retiredHarnesses ?? []));
     if (o.json) console.log(JSON.stringify({ scope: lock.scope, sourceVersion: lock.sourceVersion, targets, unpinned, ...report }, null, 2));
     if (o.dryRun) {
       console.log('[DRY] Reconcile plan complete — no changes written');
@@ -107,10 +139,22 @@ function cmdReconcile(o     )       {
       process.exit(1);
     }
     checkpointRunLock(hold);
+    // A run that changes a retired harness's rows backs the retirement up first, as install and
+    // update do, so `doflow rollback` restores it (row 127 FR-4). Any other reconcile takes none.
+    let bid = '';
+    const retiring = retiredReleaseKeys(lifecycleView.plan.retiredHarnesses ?? []).size > 0;
+    if (retiring && o.noBackup) {
+      console.error('[WARN]  Skipping backup (--no-backup)');
+    } else if (retiring) {
+      const commit = sourceCommit(SCRIPT_DIR);
+      bid = reportBackup(backupStep(() => createFileBackup({ operation: 'reconcile', set: retirementBackupSet(lifecycleView, lifecyclePaths, scope),
+        backupRoot: lifecyclePaths.backupRoot, repoRoot: SCRIPT_DIR, sourceCommit: commit, version: pkg.version, date: new Date() })));
+    }
     applyLifecycle({ plan: lifecycleView.plan, registry: lifecycleView.registry,
       adapters: buildAdapterRegistry(),
       stateRoot: lifecycleView.stateRoot, ledger: lifecycleView.ledger });
-    writeManifest({ scopeRoot: lifecyclePaths.scopeRoot, scriptVersion: pkg.version, operation: 'update', repoRoot: SCRIPT_DIR, sourceCommit: sourceCommit(SCRIPT_DIR), backupId: '', tools: targets, date: new Date() });
+    writeManifest({ scopeRoot: lifecyclePaths.scopeRoot, scriptVersion: pkg.version, operation: 'update', repoRoot: SCRIPT_DIR, sourceCommit: sourceCommit(SCRIPT_DIR), backupId: bid, tools: targets, date: new Date() });
+    if (bid) applyBackupRetention({ backupRoot: lifecyclePaths.backupRoot, prune: o.prune, keep: o.prune ?? DEFAULT_BACKUP_RETENTION, bid });
     console.log('[OK] Reconciliation complete — state converged onto doflow.lock.');
   } finally {
     hold?.release();

package/src/cli/commands/remove.js

@@ -59,8 +59,8 @@ function cmdRemove(o     )       {
       scope: codexScope(scope), scopeRoot: scope.global ? os.homedir() : path.resolve(scope.projectRoot),
       targets: lifecycleTargets, mcpAdoptable, retainedMcpIds, stateRoot: view.stateRoot, ledger: view.ledger,
       context: view.plan.targets[0].adapterInput.context });
-    // Shared destinations (one .doflow/scripts tree for claude/codex/gemini, one .agents for
-    // gemini/copilot) mean a removal can legitimately leave files standing. Saying only "removed"
+    // Shared destinations (one .doflow/scripts tree for claude/codex, one .agents for
+    // antigravity/copilot) mean a removal can legitimately leave files standing. Saying only "removed"
     // would be half the truth, so what was kept and who still claims it is printed, not implied.
     for (const line of retentionSummary(result.retained)) console.log(`[INFO] ${line}`);
     console.log(`[OK] Removed ${result.ledger.resources.length === 0 ? 'all' : 'eligible'} native resource(s) for ${lifecycleTargets.join(', ')}; ${result.ledger.resources.length} owned record(s) remain.`);

package/src/cli/commands/rollback.js

@@ -6,7 +6,7 @@
 // restores per tool, as it always did.
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 const path = require('node:path');
-const { resolveTargets, toolDirs } = require('../../install/targets.js');
+const { VALID, resolveTargets, toolDirs } = require('../../install/targets.js');
 const { resolveContext, printContext } = require('../../install/context.js');
 const {
   BackupError, createFileBackup, planRestore, executeRestore, listBackups, formatBytes,
@@ -59,9 +59,12 @@ function cmdRollback(o     )       {
       fail(error);
     }
     // A per-file backup restores the harnesses it holds (only those in --target when given), so the
-    // banner and the install manifest name those, not the default target.
+    // banner and the install manifest name those, not the default target. A backup taken by a run
+    // that swept a retired harness (127 IC-003) holds that harness's files and rows too: they are
+    // restored like any other, but a retired id is no target, so the banner and manifest skip it.
     const restoredTools = plan.format === 2
-      ? [...new Set(plan.restore.flatMap((item     ) => item.harnesses))].filter((h) => !explicitTargets || targets.includes(h)).sort()
+      ? [...new Set(plan.restore.flatMap((item     ) => item.harnesses))]
+        .filter((h     ) => VALID.includes(h) && (!explicitTargets || targets.includes(h))).sort()
       : targets;
     printContext(resolveContext({ repoRoot: REPO_ROOT, targets: restoredTools, dirs, sourceCommit: commit, global: o.global, projectRoot: '.' }));
 

package/src/cli/commands/self-update.js

@@ -2,32 +2,41 @@
 // `doflow self-update` — git fetch/pull the checkout, then re-run the install path so the
 // installed trees match the freshly pulled source.
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const fs = require('node:fs');
+const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { REPO_ROOT } = require('../shared.js');
 const cmdInstall = require('./install.js');
 
-function cmdSelfUpdate(o     )       {
+/** The second argument is for tests: the checkout to update and the install it re-runs. */
+function cmdSelfUpdate(o     , { repoRoot = REPO_ROOT, install = cmdInstall }                                                    = {})       {
   console.log('[INFO] Self-update: checking for upstream changes...');
   let pulled = false;
   let fetchOk = false;
-  try {
-    execFileSync('git', ['-C', REPO_ROOT, 'fetch', '--depth=1', 'origin'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
-    fetchOk = true;
-  } catch {
-    console.error('[WARN]  git fetch failed (offline or no remote configured) — installing from current HEAD');
+  // An npm install is not a git checkout: `git -C` there would act on whatever repository holds
+  // node_modules (or fail), never on DoFlow's source.
+  const isCheckout = fs.existsSync(path.join(repoRoot, '.git'));
+  if (!isCheckout) console.log('[INFO] This install is not a git checkout; to upgrade DoFlow run: npm install -g @khoavu882/doflow');
+  if (isCheckout) {
+    try {
+      execFileSync('git', ['-C', repoRoot, 'fetch', '--depth=1', 'origin'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
+      fetchOk = true;
+    } catch {
+      console.error('[WARN]  git fetch failed (offline or no remote configured) — installing from current HEAD');
+    }
   }
   if (fetchOk) {
     try {
-      execFileSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
+      execFileSync('git', ['-C', repoRoot, 'pull', '--ff-only'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10000 });
       pulled = true;
-      const commit = execFileSync('git', ['-C', REPO_ROOT, 'rev-parse', '--short', 'HEAD']).toString().trim();
+      const commit = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD']).toString().trim();
       console.log(`[INFO] Updated to commit: ${commit}`);
     } catch {
       console.error('[WARN]  Fast-forward not possible — using current local state');
     }
   }
   console.log(`[INFO] Running install (after ${pulled ? 'a git pull' : 'checking for updates'})...`);
-  cmdInstall(o);
+  install(o);
 }
 
 module.exports = cmdSelfUpdate;

package/src/cli/commands/status.js

@@ -42,6 +42,10 @@ function cmdStatus(o     )       {
       ledgerPresent: Boolean(readLedger(registryView.stateRoot)),
       plan: { changes: registryView.plan.changes.length, conflicts: registryView.plan.conflicts, prerequisites: registryView.plan.prerequisites },
     };
+    // Row 127: a retired harness the ledger still holds rows of, which the next install or update
+    // releases. Absent when there is none, so the report is unchanged for every other ledger.
+    const retired = (registryView.plan.retiredHarnesses ?? []).map((item     ) => ({ harness: item.harness, replacement: item.replacement, rows: item.changes.length }));
+    if (retired.length) ctx.registry.retired = retired;
     // Per-harness status must derive from that harness's own plan target, not the flattened
     // registryView.plan.changes/conflicts across every target — otherwise, e.g., Codex having
     // pending changes when it isn't installed yet would make Claude's line falsely report
@@ -50,7 +54,7 @@ function cmdStatus(o     )       {
     // Hook-wiring status needs the same general per-harness verification every install/update run
     // already flows through (src/lifecycle's verifyLifecycle) rather than a Codex-only hardcode:
     // it is the one place that can tell 'installed and active' apart from 'installed but pending a
-    // prerequisite' (Codex's unreviewed trust, Gemini's live hook-trust check) from 'absent'.
+    // prerequisite' (Codex's unreviewed trust) from 'absent'.
     const verification = verifyLifecycle({ plan: registryView.plan, adapters: registryView.adapters, context: { registry } });
     const hooksFor = (harness        ) => verification.verifications.find((item     ) => item.harness === harness)?.hookWiring ?? null;
     const harnessStatus = (harness        ) => {
@@ -80,8 +84,19 @@ function cmdStatus(o     )       {
     ctx.registry = { status: 'invalid', error: error.message };
   }
 
+  // The primary is read on use only (row 120 A.4): a fault in resolving it never breaks status.
+  let primary      = null;
+  let primaryText        ;
+  try {
+    const { primarySummary, resolveForReport } = require('../../runtime/context/primary-command.js');
+    primary = resolveForReport({ env: process.env, projectRoot: path.resolve(scope.projectRoot) }).primary;
+    primaryText = primarySummary(primary);
+  } catch (error     ) {
+    primaryText = `unavailable (${error?.message || String(error)})`;
+  }
+
   if (o.json) {
-    console.log(JSON.stringify({ context: ctx, manifest, codex: ctx.codex ?? null, mcpSelections }, null, 2));
+    console.log(JSON.stringify({ context: ctx, manifest, codex: ctx.codex ?? null, mcpSelections, primary }, null, 2));
     return;
   }
 
@@ -92,6 +107,7 @@ function cmdStatus(o     )       {
   };
 
   printContext(ctx);
+  console.log(`primary: ${primaryText}`);
   if (!manifest) {
     console.log("[WARN] No install manifest found — run 'doflow install' to get started");
     return;
@@ -126,6 +142,9 @@ function cmdStatus(o     )       {
   if (ctx.registry) {
     console.log(`  Registry lifecycle:   ${ctx.registry.status === 'invalid' ? ctx.registry.error : `${ctx.registry.plan.changes} pending, ${ctx.registry.plan.conflicts.length} conflict(s)`}`);
     if (ctx.registry.status !== 'invalid') console.log(`  Neutral state:         ${ctx.registry.stateRoot}${ctx.registry.ledgerPresent ? ' (ledger present)' : ' (not yet created)'}`);
+    for (const item of ctx.registry.retired ?? []) {
+      console.log(`  Retired harness:      ${item.harness} (use ${item.replacement}): ${item.rows} ledger row(s); the next 'doflow install' or 'doflow update' in this scope releases them`);
+    }
   }
   console.log('\n  TOOL         STATUS         LAST UPDATED');
   for (const tool of LIFECYCLE_HARNESSES) {