@khoavu882/doflow 2.0.0 → 2.0.2

package/core/shared/skills/do-implement/SKILL.md

@@ -53,6 +53,8 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 
 **Stop when** every work-list finding the contract names has an answer or a stated gap, **and** the last round produced no new work-list finding. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
 
+Once per stage, after `feature_slug` resolves, run `"$DOFLOW" attendance --task-id "<feature_slug>"`; `unattended` → `references/WORKFLOW_HANDOFF.md` § Unattended stage.
+
 2. **Resolve the task id, then evaluate readiness — skip only when standalone**:
    - `<task id>` is the same unit every recording stage keys on: the plan task id when one exists,
      otherwise the feature slug that step 1's `"$DOFLOW" paths --json` resolved, or the issue id you
@@ -73,9 +75,9 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      of `bug`, `refactor`, `dependency-change` or `trivial-edit` the recorded work already fits.
      `do-implement` never serves `feature`; that class's implementation stage is `/do-execute-plan`.
      ```bash
-     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-implement --json
+     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-implement --view brief --json
      ```
-     Branch on the returned `outcome`, not the exit code. `ACCEPTED` — the returned `workflow` names
+     Branch on `outcome`, not the exit code. `ACCEPTED` — the returned `workflow` names
      the validated class to evaluate readiness against. `REJECTED` — stop, print `message` verbatim
      (it names `validClasses`), ask the user to choose from that set, then re-validate; never
      substitute `feature` for the class that was rejected.
@@ -118,8 +120,8 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      established.
    - The repository's `pre-implement-gate` hook checks file existence (`requirement.md` /
      `design.md` / `plan.md`) on every `Edit`/`Write` call regardless of which skill is editing. On
-     a harness with an edit hook it also denies the edit of a task held to a readiness record that
-     is not `READY`; this step writes that record, and is not a way around the hook.
+     a harness with an edit hook it also advises when a held task's readiness record is not
+     `READY`; the hook never denies. This step writes that record, and is not a way around it.
 
 3. **Understand before writing**:
    - Read the files the change touches and their immediate neighbors — naming conventions, error
@@ -146,8 +148,8 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      unimplemented mock functions, or `throw new Error('Not implemented')` placeholders in the
      produced change. Every changed component must be fully wired and functional.
    - Before the first source edit, a run for this task needs step 2's recorded readiness to be
-     `READY`: the hook denies the edit otherwise where there is one, and elsewhere step 7's handoff
-     is refused after the edits are made. A standalone `NEEDS_EVIDENCE` does not pass it.
+     `READY`: the edit hook only advises, and the runtime refuses step 7's handoff after the edits are
+     made. A standalone `NEEDS_EVIDENCE` does not pass it.
    - Keep it scoped to what was asked — no bonus refactors, no speculative abstractions (the same
      scope-discipline rule the chain's own artifacts would otherwise remind you of; here, hold
      yourself to it directly).
@@ -215,6 +217,6 @@ advance past the mutating stage only this skill may complete.
 multi-task checklist through specialist subagents — that is `/do-execute-plan`'s job once a real
 plan exists; silently override the repository's own `pre-implement-gate` hook. That hook triggers
 on any `Edit`/`Write` call, not on which skill made it — a branch mid-chain with a started feature
-but no `design.md` still gets blocked here exactly as it would anywhere else, and that is by
+but no `design.md` still gets the same advisory here as it would anywhere else, and that is by
 design, not a gap this skill works around. Resolve a workflow gate, or start a workflow run for a
 standalone implementation.

package/core/shared/skills/do-plan/SKILL.md

@@ -37,13 +37,15 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 
 `feature_slug` `null` with a non-empty `candidate_slugs` is an unresolved choice, not "no active feature": ask one option per entry, re-resolve with `"$DOFLOW" paths --json --slug="<chosen>"`, and use that slug for the rest of this flow. `/do-flow` passing `--slug` already resolves it — no prompt then.
 
+Once per stage, after `feature_slug` resolves, run `"$DOFLOW" attendance --task-id "<feature_slug>"`; `unattended` → `references/WORKFLOW_HANDOFF.md` § Unattended stage.
+
 2. **Propose one task class; the runtime validates it** — name exactly one class id for the work
    being planned. `/do-flow` passes one when it invoked this skill; a user who named one settles it;
    otherwise derive it from `requirement.md` and `design.md`, not from their mere existence.
    ```bash
-   "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --json
+   "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --view brief --json
    ```
-Branch on the returned `outcome` field, not the exit code.
+Branch on `outcome`, not the exit code.
 - **`ACCEPTED`** — the returned `workflow` is this run's plan of record; read `stages`, `gates` and `handoff` off it rather than from memory.
 - **`REJECTED`** — **stop.** Print `message` verbatim (it already names `validClasses` and any `suggestions`), ask the user to choose from `validClasses`, then re-validate. Never substitute `feature`.
   A rejection may be about **you** rather than the class (`reason: caller-not-a-stage`). Then the fix is to propose one of the classes in `fit.hostingClasses`, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
@@ -59,8 +61,8 @@ stages to implementation, and writing them a `plan.md` adds a gate their workflo
 not have.
 
 3. **Precondition (advisory)** — if `has_requirement` or `has_design` is false, warn and offer to
-   run `/do-brainstorm` / `/do-design` first. This gate is **advisory** (skippable), not the hard
-   hook gate.
+   run `/do-brainstorm` / `/do-design` first. This gate is **advisory** (skippable), like the edit
+   hook.
 4. **Read inputs** — compile the recorded prior context first, using the same task id rule step 10
    uses below (the plan task id for anything already scoped to a single `- [ ]` task, otherwise the
    feature slug):
@@ -124,7 +126,7 @@ Filling §8's task dependency graph, read the guidance tree's `references/DIAGRA
    SHOULD`) and PASS/FAIL; a base MUST that tier-2 makes SHOULD names that overlay version in its
    row. On a violation, revise the approach first. A MUST marked FAIL or left
    without a row refuses step 11's handoff; a SHOULD FAIL is a note. That refusal is the runtime's,
-   beside the hard hook that covers artifact existence (`references/DOFLOW_CHAIN.md` scopes both).
+   beside the advisory hook on artifact existence (`references/DOFLOW_CHAIN.md` scopes both).
    There is no waiver: revise the plan, or a person amends the constitution with `/do-constitution`.
 7. **Decompose into Tasks (section 8)** — dependency-ordered, `[US#]`-traced to the requirement's
    user stories, owner+files named per task, with checkpoints and completion criteria.
@@ -197,7 +199,8 @@ Item schema, provenance rules, and the refused-field list: the guidance tree's `
    ```bash
    "$DOFLOW" render-audit --slug="<task id>" --json
    ```
-   Leave any returned approval gate for `/do-flow` or `/do-execute-plan` to present.
+   Leave any returned approval gate for `/do-flow` or `/do-execute-plan` to present (unattended: the loop
+   decides it by policy).
 
 12. **Stop** — report the plan path, Constitution Check result, the task count (`[P]`/sequential),
    and the derived branch name/repo count when the Repo Branch Plan is populated.

package/core/shared/templates/doflow/data-model-template.md

@@ -2,166 +2,200 @@
 
 **Feature:** [NNN-slug] · **Design:** ./design.md · **Maturity:** Draft · **Created:** [DATE]
 
-> Entity/data model and data-flow diagrams a design decided, split out of design.md's own narrative
-> (Data Model and Sequence / Data Flow) and specs.md's interface-contract detail (§1). Reads ./design.md; distinct from ./specs.md
-> the way a persisted shape and the flows that move through it are distinct from the contracts that
-> expose them.
+> Entity/data model, lifecycles and data-flow diagrams a design decided, split out of design.md's own
+> narrative (Data Model and Sequence / Data Flow) and specs.md's interface-contract detail (§1). Reads
+> ./design.md; distinct from ./specs.md the way a persisted shape and the flows that move through it
+> are distinct from the contracts that expose them.
 >
 > Structure follows `references/ARTIFACT_FORMAT.md`: the document-level `Maturity` is `Draft`,
-> `In review` or `Approved`. Neither §1 nor §2 below carries an `ID`-bearing index — a diagram is not
-> a normative, citable statement — so both stay free-form; §3 History is index-then-detail like
-> every other chain artifact's final section, and its item-level `Status` is only `Live` or
-> `Superseded → <ref>`.
+> `In review` or `Approved`. The file has nine sections. Only §9 History carries an `ID`-bearing
+> index (index-then-detail, item-level `Status` is `Live` or `Superseded → <ref>`); §1 to §8 are
+> free-form, because a diagram or a table row is not a normative, citable statement.
+
+<!-- Rules for every section below.
+     Source: each row of the §1 dictionary and of every table in §3 to §8 ends with a Source cell
+     holding exactly one of: FR-###, NFR-###, IC-###, code:<path>:<line>, proposed, UNKNOWN -> Open Point.
+     A `proposed` or `UNKNOWN -> Open Point` row is copied to design.md Open Points for Review.
+     Placeholders are bracketed and bare; fill them, never leave a row of placeholders in place.
+     A conditional section accepts "N/A: [why]" in place of its content.
+     Worked example, read only while filling this file: do-design/references/data_model_example.md -->
 
 ## 1. Data Model
 
-<!-- Free-form, NOT part of the indexed convention above — diagrams and schema tables are not
-     ID-bearing normative statements, so this section stays exactly as specs-template.md's former
-     §2 already was.
+<!-- Free-form. Order: domain inventory, domain map, ER views, data dictionary, schemas, UX.
+     The domain map carries no attributes, so the shape of the domain is legible before any field
+     name. One ER view per bounded subdomain carries that subdomain's attributes, keys and
+     cardinalities alone; splitting must not drop an entity, a key or a constraint. -->
 
-     The model is presented in two tiers. The conceptual domain map comes first and carries no
-     attributes, so the shape of the domain is legible before any field name. One ER view per
-     bounded subdomain follows, each carrying the attributes, keys and cardinalities of that
-     subdomain alone. Splitting one diagram into views must not drop an entity, a key or a
-     constraint the single diagram carried. -->
+### Domain inventory
+
+| Domain | Entities | Stateful | Owner | Source |
+|---|---|---|---|---|
+| [domain] | [entity, entity] | [yes or no] | [owning component] | [Source] |
 
 ### Conceptual domain map
 
-<!-- The entities and the relationships between them, with no attributes. Skip with "N/A: [why]" if
-     the feature persists no entity. -->
+<!-- A flowchart of entities and relationships, no attributes. "N/A: [why]" if the feature stores no entity (persisted captures count as entities). -->
 
 ```mermaid
 flowchart LR
-    USER["User"]
-    POST["Post"]
-    COMMENT["Comment"]
-
-    USER -->|"creates"| POST
-    POST -->|"contains"| COMMENT
+    A["[Entity]"] -->|"[relationship]"| B["[Entity]"]
 ```
 
 #### ER view: [subdomain]
 
-<!-- One heading of this form per bounded subdomain, each an erDiagram carrying the attributes,
-     keys and cardinalities of that subdomain alone. Skip with "N/A: [why]" if the feature persists
-     no entity. -->
+<!-- One heading of this form per bounded subdomain, each an erDiagram. Every entity named here
+     needs a dictionary block below and a lifecycle block in §3. -->
 
 ```mermaid
 erDiagram
-    USER ||--o{ POST : "creates"
-    USER {
-        uuid id PK
-        string email UK
-        string name
-        timestamp created_at
-    }
-    POST ||--o{ COMMENT : "contains"
-    POST {
-        uuid id PK
-        uuid user_id FK
-        string title
-        text content
-        timestamp created_at
+    [ENTITY_A] ||--o{ [ENTITY_B] : "[relationship]"
+    [ENTITY_A] {
+        [type] [field] PK
     }
-    COMMENT {
-        uuid id PK
-        uuid post_id FK
-        uuid author_id FK
-        text body
-        timestamp created_at
+    [ENTITY_B] {
+        [type] [field] FK
     }
 ```
 
+### Data dictionary
+
+#### Dictionary: [entity]
+
+<!-- One block per ER entity, one row per field. -->
+
+| Field | Type | Null | Rule | PII class | Source |
+|---|---|---|---|---|---|
+| [field] | [type] | [yes or no] | [constraint or format] | [none, direct, indirect] | [Source] |
+
 ### Database Schemas (ORM / DDL)
 
 <!-- The catalog of every table the views above draw, with its keys, indexes and ORM file. -->
 
 | Table | Purpose | Primary Key | Foreign Keys & Relations | Key Indexes | Schema / ORM File |
 |---|---|---|---|---|---|
-| `[table_name]` | [one-line table responsibility] | `id` (UUID) | `[user_id]` → `users(id)` | `idx_[table]_[col]` | `src/db/schema/[table].ts` |
+| `[table_name]` | [one-line responsibility] | [key] | [fk → table(key)] | [index] | [path] |
 
 ### UX / UI Specifications
-- **Design Tokens & Cues:** [color tokens (e.g. Indigo for Work, Emerald for Personal), badge variants, typography]
-- **Component States:** [loading, empty, populated, error states]
+- **Design Tokens & Cues:** [tokens, badge variants, typography]
+- **Component States:** [loading, empty, populated, error]
 
 ## 2. Sequence / Data Flow
 
-<!-- Free-form, NOT part of the indexed convention — a diagram is not an ID-bearing normative
-     statement, so this section stays free-form exactly as §1 does.
-
-     One `sequenceDiagram` per non-trivial interaction the feature introduces. Scaffolding matches
-     §1's depth deliberately: this is the chain's most-used diagram type, not an afterthought.
-
-     `references/DIAGRAM_GUIDE.md` governs the lifeline ceiling. There is no message ceiling,
-     because a sequence diagram lays out columnwise and cannot tangle however many messages it
-     carries — so show the whole interaction rather than trimming it to look tidy.
-
-     Conventions:
-       - Declare every participant up front, in the order they first act, so the columns read
-         left-to-right in causal order.
-       - Use `actor` for a human or an external caller and `participant` for a component.
-       - `->>` is a call, `-->>` is a return. Keep returns only where the returned value matters.
-       - Put the failure path in an `alt` block. An interaction drawn only on its happy path hides
-         the branch a reader most needs.
-       - `Note over X,Y:` carries a constraint or an invariant, never narration of the line above.
-       - Prefer `rect` over `par` to mark a region: `par` claims the steps happen simultaneously,
-         which most groupings cannot support. Reserve `par` for genuine parallelism, `alt` for a
-         branch.
+<!-- Free-form. `references/DIAGRAM_GUIDE.md` governs lifeline ceilings; there is no message ceiling.
+     Declare participants in the order they first act. `->>` is a call, `-->>` a return. Put the
+     failure path in an `alt` block. Prefer `rect` over `par` unless steps are truly parallel.
+     "N/A: [why]" if the feature has no non-trivial interaction. -->
 
-     Skip with "N/A: [why]" if the feature introduces no non-trivial interaction. -->
-
-### [Interaction name]
+### Interaction: [name]
 
 [One sentence: what triggers this flow and what it ends with.]
 
 ```mermaid
 sequenceDiagram
     actor User
-    participant API as [entry point]
-    participant SVC as [service]
+    participant SVC as [component]
     participant DB as [data store]
 
-    User->>API: [request]
-    API->>SVC: [call]
-
+    User->>SVC: [request]
     alt [failure condition]
-        SVC-->>API: [error shape]
-        API-->>User: [status code and message]
+        SVC-->>User: [error]
     else [success]
         SVC->>DB: [read or write]
         DB-->>SVC: [result]
-        SVC-->>API: [payload]
-        API-->>User: [status code]
+        SVC-->>User: [response]
     end
+```
+
+### Swimlane flows
+
+<!-- One "#### Flow: <name>" per end-to-end flow, each embedding its committed render from
+     design/c4/flow-<name>.png. The name matches the source file's stem; nothing keeps a manifest.
+     No inline text diagram here: Mermaid has no lane primitive. `references/DIAGRAM_GUIDE.md` §6
+     governs lanes. "N/A: [why]" when the flow has a single actor. -->
+
+#### Flow: [name]
+
+![End-to-end flow: [name]](design/c4/flow-[name].png)
+
+[One sentence: what triggers this flow and what it ends with.]
 
-    Note over SVC,DB: [invariant that must hold across this step]
+## 3. Lifecycles
+
+> **Authoritative:** this section governs [the state, rule or outcome].
+
+<!-- Every entity state lives here and nowhere else. Other sections link to the entity by name and
+     restate no state (ARTIFACT_FORMAT.md §11). One block per ER entity.
+     Stateful entity: a stateDiagram-v2 of at most 10 states, a Transitions table, Illegal
+     transitions and terminal states. Every diagram state (except [*]) appears in the From or To
+     column. Above 10 states, split the entity or group states into a composite state.
+     Stateless entity: the single line "N/A: stateless, [why]". -->
+
+#### Lifecycle: [entity]
+
+```mermaid
+stateDiagram-v2
+    [*] --> [State]
+    [State] --> [State]: [event]
 ```
 
-[If the failure branch has consequences the diagram cannot carry — a retry policy, a compensating
-action, an idempotency requirement — state them in a sentence beneath the diagram rather than
-crowding the fence.]
+**Transitions**
 
-### Flow: [name]
+| From | Event | Guard | Actor | Side effect | To | Emitted event | Source |
+|---|---|---|---|---|---|---|---|
+| [state] | [event] | [condition] | [who triggers] | [effect] | [state] | [event or none] | [Source] |
 
-<!-- One "#### Flow: <name>" heading per end-to-end flow, each embedding its committed render from
-     design/c4/flow-<name>.png. The heading name matches its source file's stem, which is the only
-     index -- nothing maintains a manifest, because a manifest could disagree with the directory.
+**Illegal transitions**
 
-     This slot carries NO inline text diagram, and that asymmetry is forced by grammar rather than
-     chosen: Mermaid has no lane primitive, and approximating lanes with subgraph grouping would
-     carry no lane semantics and so would misrepresent the diagram it stood in for. The authored
-     .puml remains readable text under review, so the flow's logic is still diffable.
+- [From] → [To]: [why it is refused]
 
-     `references/DIAGRAM_GUIDE.md` §6 governs the lane conventions. Skip with "N/A: [why]" when the
-     feature's flow involves a single actor. -->
+**Terminal states:** [state, state]
 
-![End-to-end flow: [name]](design/c4/flow-[name].png)
+#### Lifecycle: [entity]
+
+N/A: stateless, [why]
+
+## 4. Cross-entity coupling
+
+<!-- Conditional: two or more actors; otherwise "N/A: [why]". Link to the §2 flow by name; restate
+     no picture and no state. -->
+
+| Trigger entity and transition | Effect on entity | Via event | Source |
+|---|---|---|---|
+| [entity: From → To] | [entity: effect] | [event] | [Source] |
+
+## 5. Invariants
+
+<!-- Mandatory. A statement that must hold at all times, and where it is enforced. -->
+
+| Invariant | Holds over | Enforced by | Source |
+|---|---|---|---|
+| [statement] | [entities or fields] | [constraint, code path, or check] | [Source] |
+
+## 6. Ownership / CRUD matrix
+
+| Entity | Owner | Create | Read | Update | Delete | Source |
+|---|---|---|---|---|---|---|
+| [entity] | [component] | [who] | [who] | [who] | [who] | [Source] |
+
+## 7. Event catalogue
+
+<!-- Domain events this feature emits; external stream events it only consumes are not listed here.
+     "N/A: [why]" when no domain event is emitted. -->
+
+| Event | Emitted by | Payload | Consumers | Source |
+|---|---|---|---|---|
+| [event] | [component] | [fields] | [components] | [Source] |
+
+## 8. Retention, PII and migration
+
+<!-- Conditional: "N/A: [why]" when nothing is retained, personal or migrated. -->
 
-[One sentence: what triggers this flow and what it ends with. Any consequence the lanes cannot
-carry — a retry policy, a compensating action, an idempotency requirement — belongs here rather
-than crowded into the diagram.]
+| Entity | Retention | PII class | Migration | Source |
+|---|---|---|---|---|
+| [entity] | [period or rule] | [none, direct, indirect] | [step or none] | [Source] |
 
-## 3. History
+## 9. History
 
 <!-- Superseded data-model entries move here; the index row above stays as a tombstone with
      `Superseded → <ref>`. -->

package/core/shared/workflows/do-flow-chain.md

@@ -13,5 +13,7 @@ delivery sequence, pausing where human judgment matters:
 5. Execute `/do-execute-plan --scope next` repeatedly until the plan's checklist is complete.
 6. Run `/do-test`, then `/do-code-review`, and report both results before proposing any commit.
 
+Unattended (no person watching), stop at each pause above and report; silence is never approval.
+
 If the user comments directly inside any specification file, re-read it, apply the requested
 changes, and ask for approval again before moving on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "DoFlow config installer — npx CLI for the registry-driven multi-harness install/update/remove lifecycle",
   "keywords": [
     "claude-code",

package/src/adapters/antigravity/index.js

@@ -26,6 +26,7 @@ const { MARKER_START, MARKER_END, removeMarkedSection } = require('../../helper/
 const { planTree, applyTree, removeTree, verifyTree, resolveTransform, copyTreeAssets, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor } = require('../copy-tree.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 const { renderGuidancePointer } = require('../guidance-pointer.js');
+const { replacementManagesFile } = require('../../lifecycle/retired-harnesses.js');
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 
 const HARNESS = 'antigravity';
@@ -229,8 +230,9 @@ function managedInstruction(existing     , rendered     , { name = 'AGENTS.md',
   if (start === -1 && predecessor) start = existing.indexOf(PREDECESSOR_MARKER_START);
   const end = existing.indexOf(MARKER_END);
   if (start === -1 && end === -1) {
-    const separator = existing === '' || existing.endsWith('\n') ? '\n' : '\n\n';
-    const content = `${existing}${separator}${rendered}`;
+    // Always exactly one '\n' before the span, so strippedInstruction can take back exactly that one
+    // byte whatever the file ended with (a file with no final newline just gets the span on the next line).
+    const content = `${existing}\n${rendered}`;
     return { ok: true, operation: 'merge', content };
   }
   if (start === -1 || end === -1 || end < start) return { ok: false, conflict: `${name} has malformed DoFlow managed-section markers` };
@@ -245,7 +247,11 @@ function strippedInstruction(existing     ) {
   if (start === -1 || end === -1 || end < start) return null;
   let after = end + MARKER_END.length;
   if (existing[after] === '\n') after += 1;
-  return `${existing.slice(0, start)}${existing.slice(after)}`;
+  const before = existing.slice(0, start);
+  const rest = existing.slice(after);
+  // Exact inverse of managedInstruction's append: a span at the end of the file goes with the one '\n'
+  // put before it. A span with the person's text after it was placed, not appended; it keeps its before.
+  return `${rest === '' && before.endsWith('\n') ? before.slice(0, -1) : before}${rest}`;
 }
 
 // ---- copy-tree components (skills, agents, locator) ----
@@ -318,6 +324,45 @@ function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot,
   return { changes, conflicts, targets, notices: [...siblingReplacedNotices(treeResults), ...notices] };
 }
 
+// ---- legacy Gemini shim ----
+
+/** sha256 of every `doflow-run` locator the retired Gemini adapter wrote to ~/.gemini/bin, which
+ * moved to ~/.gemini/config/bin in f7928c48. Each is a blob of core/harnesses/shared/locator/doflow-run
+ * that was current while the adapter still projected to ~/.gemini/bin (blob: commit that introduced
+ * it): 22340592: e575b259, 34bb6c6c: 1fbab132, 344ebd52: a3c15cdb. Hashes only; the bodies stay in git. */
+const LEGACY_GEMINI_SHIM_SHA256 = Object.freeze([
+  'bee62b0a97b9365fba95541a2d2979b1dd57f63a13e0d7bcc6077147664008a4',
+  '66530de094c6ec22bda9219b19f9c02e6a076068aa671b5eb6dff463d06f966a',
+  '9b5cae2a84d7486deff8ecabe477c06af5802d77af6efa72476897f08b8864d6',
+]);
+
+/** The one change that retires a stale ~/.gemini/bin/doflow-run: global scope only, and only a
+ * regular file (never a link) whose bytes equal a shipped legacy shim. Anything else at that path
+ * is the person's and is left alone. No ledger row owns the file, so the change carries
+ * `legacyRetirement` and the lifecycle journals it as a swept tombstone (src/lifecycle/index.js). */
+function planLegacyGeminiShim({ assets, paths, scope, fsImpl = fs }     ) {
+  const none = { changes: [], notices: [] };
+  const locator = scope === 'global' ? (assets ?? []).find((asset     ) => asset.id === 'locator.doflow') : null;
+  const currentDir = locator && treeDestFor(locator, paths, scope);
+  if (!currentDir) return none;
+  const target = path.join(paths.root, '.gemini', 'bin', 'doflow-run');
+  let digest;
+  try {
+    if (!fsImpl.lstatSync(target).isFile()) return none;
+    digest = sha256File(fsImpl, target);
+  } catch { return none; }
+  if (!LEGACY_GEMINI_SHIM_SHA256.includes(digest)) return none;
+  return {
+    changes: [{
+      assetId: locator.id, target, operation: 'remove', kind: 'copy-tree-file', identity: 'bin/doflow-run',
+      ownershipIdentity: `doflow:${HARNESS}:legacy:locator.doflow:bin/doflow-run`,
+      fingerprint: digest, projection: { renderer: 'copy-tree' },
+      legacyRetirement: { toTarget: path.join(currentDir, 'doflow-run') },
+    }],
+    notices: ['removed ~/.gemini/bin/doflow-run: an unmodified older DoFlow shim, replaced by ~/.gemini/config/bin/doflow-run'],
+  };
+}
+
 function runTreeChanges(changes     , mode     ) {
   // Route by what each change IS, not by which verb invoked us: remove() delegates here with a
   // plan full of operation:'remove' changes, and applyTree deliberately skips those — so routing
@@ -367,17 +412,13 @@ function instructionTarget({ paths, assets, registry }     ) {
   if (!paths.instruction) return null;
   if (scopeOf(paths) === 'project') return paths.instruction;
   if (!(assets ?? []).some((asset     ) => asset.id === POINTER_ASSET_ID)) return null;
-  const declaredBy = (harness     ) => {
-    if (harness?.id === HARNESS || !harness?.paths?.instruction) return false;
-    try { return resolveHarnessPaths({ instruction: harness.paths.instruction }, { scope: 'global', scopeRoot: paths.root, homeDir: paths.root }).instruction === paths.instruction; } catch { return false; }
-  };
-  return (registry?.harnesses ?? []).some(declaredBy) ? null : paths.instruction;
+  return replacementManagesFile({ registry, harnessId: HARNESS, surface: 'instruction', target: paths.instruction, scope: 'global', scopeRoot: paths.root }) ? paths.instruction : null;
 }
 
 /** How this run stands to a section it took over (IC-007): the lifecycle's handover verdict for the
  * file, this harness's own row on it, and whether a person-edited file stays as it is (`retained`:
  * edited before the handover, or kept since, and no --force). `predecessor` lets the retired
- * harness's span count as the section to replace; `keptRow` is a row recorded as kept. A handover
+ * harness's span count as the section to replace; `keptRow` is any own row on the file. A handover
  * file whose DoFlow span already is this harness's render was written by DoFlow itself (a run that
  * threw after that write and before its ledger write), so it does not count as edited. */
 function instructionState({ target, context, resources, paths, fsImpl = fs }     ) {
@@ -391,7 +432,7 @@ function instructionState({ target, context, resources, paths, fsImpl = fs }
   };
   const edited = (handover?.edited === true && !ownWrite()) || ownRow?.retainedEdit === true;
   return { predecessor: Boolean(handover) || ownRow?.retainedEdit === true, retained: edited && context.force !== true,
-    keptRow: ownRow?.retainedEdit === true };
+    keptRow: ownRow !== null };
 }
 
 function instructionsChange(target     , fields     ) {
@@ -492,6 +533,7 @@ function plan(options      = {}, impl      = {}) {
   const instructions = planInstructions({ paths, target: instructionFile, removing, fsImpl,
     state: instructionState({ target: instructionFile, context, resources: neutralResources, paths, fsImpl }) });
   const trees = planTrees({ assets: options.assets, paths, scope, neutralResources, removing, repoRoot: context.repoRoot, force: context.force === true, fsImpl });
+  const legacyShim = removing ? { changes: [], notices: [] } : planLegacyGeminiShim({ assets: options.assets, paths, scope, fsImpl });
   const mcp = planMcpEntries({
     ...mcpEntriesInput({ paths, mcp: selectedServers, mcpAdoptable: options.mcpAdoptable, resources: neutralResources }),
     files: discovery.mcpSnapshot, removing,
@@ -501,14 +543,14 @@ function plan(options      = {}, impl      = {}) {
   const hooksPlan = context.hooksOff === true && !removing ? { changes: [], conflicts: [] }
     : planHooks({ paths, scope, neutralResources, removing, repoRoot: context.repoRoot, fsImpl });
 
-  const changes = [...instructions.changes, ...trees.changes, ...mcp.changes, ...hooksPlan.changes];
+  const changes = [...instructions.changes, ...trees.changes, ...legacyShim.changes, ...mcp.changes, ...hooksPlan.changes];
   const conflicts = [...instructions.conflicts, ...trees.conflicts, ...mcp.conflicts, ...hooksPlan.conflicts];
   return {
     changes,
     conflicts,
     prerequisites: [],
     requiredNativeResources: changes,
-    notices: [...instructions.notices, ...trees.notices, ...mcp.notices],
+    notices: [...instructions.notices, ...trees.notices, ...legacyShim.notices, ...mcp.notices],
   };
 }
 

package/src/adapters/claude/index.js

@@ -29,6 +29,12 @@ const SETTINGS_RENDERER = 'claude-settings';
  *    its install destination is declared (paths.statuslineScript).
  */
 const SETTINGS_FILES = ['settings.json', 'keybindings.json'];
+/** Hook entries an earlier DoFlow wrote into settings.json and no longer ships. The update prunes their
+ * scripts, so a merge strips these entries from the live file (and a remove does too) instead of leaving a
+ * hook that points at a missing script. Written in the global form; `retiredHooks` rewrites the prefix for project scope. */
+const RETIRED_SETTINGS_HOOKS = {
+  PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: `${GLOBAL_HOOK_PREFIX}pre-bash-guard.sh` }] }],
+};
 
 function sha256(value     ) {
   return crypto.createHash('sha256').update(value).digest('hex');
@@ -194,6 +200,18 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
     const { hooks, ...rest } = parsed;
     return { raw: serializeSettings(rest), droppedHooks: hooks };
   }
+  function retiredHooks(scope     ) {
+    const raw = JSON.stringify(RETIRED_SETTINGS_HOOKS);
+    return JSON.parse(scope === 'global' ? raw : raw.split(GLOBAL_HOOK_PREFIX).join(PROJECT_HOOK_PREFIX));
+  }
+  /** The managed settings text with the retired hook entries added, so a remove strips them as well. */
+  function withRetiredHooks(raw     , scope     ) {
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { return raw; }
+    const hooks = { ...(parsed.hooks || {}) };
+    for (const [event, entries] of Object.entries     (retiredHooks(scope))) hooks[event] = [...(hooks[event] || []), ...entries];
+    return JSON.stringify({ ...parsed, hooks });
+  }
   /** The live settings without DoFlow's own entries of `hooks`; every other key is left alone. */
   function withoutManagedHooks(current     , hooks     ) {
     if (!hooks || !current || typeof current !== 'object' || current.hooks === undefined) return current;
@@ -246,7 +264,9 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         // entries, so a drifted file is safe to process rather than a reason to refuse.
         changes.push({ assetId: asset.id, target, operation: 'remove', ownershipIdentity: `doflow:claude:settings:${fileName}`,
           ...settingsChangeExtras(fileName), fingerprint: prev.fingerprint,
-          managed: settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope),
+          managed: fileName === 'settings.json'
+            ? withRetiredHooks(settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope), scope)
+            : settingsContent(fileName, fs.readFileSync(sourceAbs, 'utf8'), scope),
           projection: { renderer: SETTINGS_RENDERER } });
       }
       if (previous.get(statuslineScriptName)) {
@@ -286,7 +306,8 @@ function createClaudeAdapter({ declaredPaths = declaredHarnessPaths().claude } =
         const currentRaw = fs.readFileSync(target, 'utf8');
         let merged;
         try {
-          merged = mergeSettings(withoutManagedHooks(JSON.parse(currentRaw), tiered.droppedHooks), JSON.parse(managedRaw));
+          const live = fileName === 'settings.json' ? withoutManagedHooks(JSON.parse(currentRaw), retiredHooks(scope)) : JSON.parse(currentRaw);
+          merged = mergeSettings(withoutManagedHooks(live, tiered.droppedHooks), JSON.parse(managedRaw));
         } catch {
           conflicts.push(`${fileName} is not valid JSON and cannot be merged`);
           continue;

package/src/adapters/codex/agents.js

@@ -194,6 +194,17 @@ function planCodexAgents({ scope, codexDir, projectRoot, sourceDir, sourceVersio
     else if (current === null || current !== agent.source) changes.push({ type: current === null ? 'create' : 'update', identity, file, content: agent.source });
     nextManagedResources.push(resourceFor(agent, scope, sourceVersion));
   }
+  // An owned agent the source no longer ships (removed, or downgraded out of the selection): the ledger
+  // row is dropped above, so the file has to be dealt with here or it stays in ~/.codex/agents for good.
+  // An unmodified file is removed; one the user changed is released (ownership dropped, file kept).
+  const shipped = new Set(agents.map((agent     ) => `agent:${agent.name}`));
+  for (const [identity, record] of owned) {
+    if (shipped.has(identity) || !/^agent:[a-z][a-z0-9-]*$/.test(identity)) continue;
+    const file = destinationFor(directory, identity.slice('agent:'.length));
+    if (!fsImpl.existsSync(file)) continue;
+    if (fingerprint(fsImpl.readFileSync(file, 'utf8')) === record.fingerprint) changes.push({ type: 'remove', identity, file });
+    else changes.push({ type: 'remove', identity, file, release: true });
+  }
   if (conflicts.length) return { ok: false, status: 'conflict', directory, agents, changes: [], conflicts, managedResources };
   return {
     ok: true, status: changes.length ? 'change' : 'unchanged', directory, agents, changes, conflicts: [],
@@ -203,7 +214,10 @@ function planCodexAgents({ scope, codexDir, projectRoot, sourceDir, sourceVersio
 
 function applyCodexAgents(plan     , { dryRun = false, fsImpl = fs }                                     = {})      {
   if (!plan.ok || dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
-  for (const change of plan.changes) atomicWrite(change.file, change.content, fsImpl);
+  for (const change of plan.changes) {
+    if (change.type !== 'remove') atomicWrite(change.file, change.content, fsImpl);
+    else if (!change.release) fsImpl.rmSync(change.file, { force: true });
+  }
   return { ...plan, applied: true };
 }