@khoavu882/doflow 2.0.1 → 2.0.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "2.0.1",
+  "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/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 };
 }
 

package/src/adapters/codex/config.js

@@ -202,8 +202,11 @@ function planCodexConfig({ file, scope, managedResources = [], desiredResources
     if (nextLines.length && nextLines.at(-1) !== '') nextLines.push('');
     nextLines.push(`[${table}]`, ...lines);
   }
-  let content = nextLines.join('\n');
-  if (content && !content.endsWith('\n')) content += '\n';
+  // The file keeps its own line ending (the first one it uses) and its own final-newline state; only a file
+  // that was empty or ended in a newline gets one, so a remove can hand back the user's exact bytes.
+  const eol = /\r?\n/.exec(original)?.[0] ?? '\n';
+  let content = nextLines.join(eol);
+  if (content && !content.endsWith('\n') && (original === '' || original.endsWith('\n'))) content += eol;
   const invalid = newViolation({ file, original, content, identities: changes.map((change     ) => change.identity) });
   if (invalid) return { ok: false, status: 'conflict', file, original, changes: [], conflicts: [invalid], managedResources };
   const nextManagedResources = managedResources.filter((resource     ) => !isOwnedRecord(resource, scope) || desired.has(resource.identity));

package/src/adapters/copilot/index.js

@@ -36,6 +36,7 @@ const path = require('node:path');
 const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
 const { planTree, applyTree, removeTree, verifyTree, copyTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor, resolveTransform } = require('../copy-tree.js');
 const { renderGuidancePointer } = require('../guidance-pointer.js');
+const { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile } = require('../created-file.js');
 const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
 
@@ -108,7 +109,8 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
    * file it doesn't fully own is a decision for the file's owner, not a guess for the installer. Add
    * an empty marker pair to opt in. */
   function managedInstruction(existing     , rendered     ) {
-    if (existing === null) return { ok: true, operation: 'create', content: rendered };
+    // A file holding only whitespace has nothing to protect and counts as absent.
+    if (existing === null || isBlank(existing)) return { ok: true, operation: 'create', content: rendered };
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
     if (start === -1 && end === -1) return { ok: false, conflict: `${INSTRUCTION_FILE} exists without a DoFlow managed section` };
@@ -132,7 +134,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
   /** Plan the single instructions change (or none). Global scope always yields no change and no
    * conflict — the user-level ~/.copilot/copilot-instructions.md is not projected, so there is no
    * global target, the same way other adapters skip a capability they do not project at a scope. */
-  function planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl }     ) {
+  function planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, ledger, fsImpl }     ) {
     if (!found.paths.instruction) return { changes: [], conflicts: [] };
     // The marker-managed instruction file is one specific asset: exclude tree-projected rule
     // assets (copilot-rule-instructions), whose `source` is a directory, not a file.
@@ -148,6 +150,8 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
         assetId: guidance.id, target: found.paths.instruction, operation: outcome.operation,
         content: outcome.content, ownershipIdentity: `${HARNESS}:instructions:managed-section`,
         fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'copilot-instructions' },
+        // A file DoFlow created and a removal that leaves only whitespace: the file goes (remove()).
+        ...(removing && createdByDoFlow(ledger, HARNESS, `${HARNESS}:instructions:managed-section`, found.paths.instruction) ? { deleteWhenBlank: true } : {}),
       }],
       conflicts: [],
     };
@@ -305,7 +309,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
     const conflicts = [];
     const removing = context.operation === 'remove';
 
-    const instructions = planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, fsImpl });
+    const instructions = planInstructionsChange({ assets, found, scope, scopeRoot, context, removing, ledger, fsImpl });
     changes.push(...instructions.changes);
     conflicts.push(...instructions.conflicts);
 
@@ -365,6 +369,7 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
       if (change.operation !== 'remove') continue;
       if (change.projection?.renderer === 'copy-tree' || change.kind === 'mcp-server') continue;
       if (typeof change.content !== 'string') continue;
+      if (change.deleteWhenBlank && isBlank(change.content) && removeCreatedFile(change.target, fsImpl)) { removed += 1; continue; }
       writeChange(change, fsImpl);
       removed += 1;
     }
@@ -389,9 +394,11 @@ function createCopilotAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS],
         status: hasSection ? 'managed' : 'absent', target: found.paths.instruction,
         ownershipIdentity: `${HARNESS}:instructions:managed-section` });
       if (hasSection) {
+        const origin = creationOrigin({ ledger, harness: HARNESS, ownershipIdentity: `${HARNESS}:instructions:managed-section`, target: found.paths.instruction, before: discovery?.instruction });
         resources.push({ assetId, target: found.paths.instruction,
           ownershipIdentity: `${HARNESS}:instructions:managed-section`, fingerprint: fingerprint(found.instruction),
-          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'copilot-instructions' } });
+          sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'copilot-instructions' },
+          ...(origin ? { origin } : {}) });
       }
     }
 

package/src/adapters/copy-tree.js

@@ -661,6 +661,13 @@ function applyTree({ changes = [], fsImpl = fs, transform }     )
     if (change.operation === 'remove') continue;
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     const sourceStat = fsImpl.statSync(change.source);
+    // A destination symlink (`install -f` plans over one) is replaced by the regular file, never written through:
+    // its target, which may be a file outside the install, keeps its bytes and mode.
+    try {
+      if (fsImpl.lstatSync(change.target).isSymbolicLink()) fsImpl.unlinkSync(change.target);
+    } catch (error     ) {
+      if (error.code !== 'ENOENT') throw error;
+    }
     if (mapContent) {
       // Re-derive the bytes from the source at write time instead of copying it: the transform,
       // not the source file, is what the recorded fingerprint describes. Keeps recovery retries

package/src/adapters/created-file.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// Shared by the adapters whose instruction file (and opencode.json) is a file DoFlow may have
+// created: the ledger row records `origin: { created: 'file' }` when the file was absent before the
+// install, so a removal that leaves nothing but whitespace can delete exactly the files DoFlow made
+// and keep every file that existed beforehand. Same record Pi's mcp.json rows carry (pi/mcp.ts).
+const fs = require('node:fs');
+
+/** Whitespace is not content: a file holding only whitespace carries none of the user's text. */
+function isBlank(text     )          { return typeof text === 'string' && text.trim() === ''; }
+
+function ownedRow(ledger     , harness        , ownershipIdentity        , target        )      {
+  return (ledger?.resources || []).find((row     ) => row.harness === harness
+    && row.ownershipIdentity === ownershipIdentity && row.target === target);
+}
+
+/** Whether the ledger row for `ownershipIdentity` at `target` says DoFlow created that file. */
+function createdByDoFlow(ledger     , harness        , ownershipIdentity        , target        )          {
+  return ownedRow(ledger, harness, ownershipIdentity, target)?.origin?.created === 'file';
+}
+
+/** The origin to record on the row verify emits. A row already in the ledger passes its origin on
+ * (absent for rows an older version wrote, which are never guessed at). With no row, `before` is
+ * the file as plan read it: `null` means absent, so this install creates it. `undefined` means the
+ * caller has no pre-apply read (a status verify), and nothing is recorded. */
+function creationOrigin({ ledger, harness, ownershipIdentity, target, before }     )                                  {
+  const row = ownedRow(ledger, harness, ownershipIdentity, target);
+  if (row) return row.origin;
+  return before === null ? { created: 'file' } : undefined;
+}
+
+/** Delete `target` unless it is a symlink (the link is the user's, not DoFlow's). */
+function removeCreatedFile(target        , fsImpl      = fs)          {
+  try {
+    if (fsImpl.lstatSync(target).isSymbolicLink()) return false;
+    fsImpl.rmSync(target);
+    return true;
+  } catch { return false; }
+}
+
+module.exports = { isBlank, createdByDoFlow, creationOrigin, removeCreatedFile };

package/src/adapters/mcp-entries.js

@@ -281,15 +281,25 @@ function writePath(file        , fsImpl     )         {
   try { return fsImpl.realpathSync(file); } catch { return path.resolve(path.dirname(file), fsImpl.readlinkSync(file)); }
 }
 
+/** The indent the file already uses (its first indented line, tabs included), else two spaces. */
+function indentOf(file        , fsImpl     )         {
+  try {
+    const found = /^\s*[{[][ \t]*\r?\n([ \t]+)\S/.exec(fsImpl.readFileSync(file, 'utf8'));
+    if (found) return found[1].slice(0, 10);
+  } catch { /* absent or unreadable: the default */ }
+  return '  ';
+}
+
 /** Write a JSON document atomically, keeping the existing file's permission bits: an MCP file kept
  * private for its tokens stays so. Creates missing directories; never deletes a file. */
 function writeMcpJson(file        , doc     , { fsImpl = fs }                   = {})         {
   const dest = writePath(file, fsImpl);
   fsImpl.mkdirSync(path.dirname(dest), { recursive: true });
   const mode = fsImpl.existsSync(dest) ? fsImpl.statSync(dest).mode & 0o7777 : null;
+  const indent = indentOf(dest, fsImpl);
   const temp = path.join(path.dirname(dest), `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
   try {
-    fsImpl.writeFileSync(temp, `${JSON.stringify(doc, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', ...(mode === null ? {} : { mode }) });
+    fsImpl.writeFileSync(temp, `${JSON.stringify(doc, null, indent)}\n`, { encoding: 'utf8', flag: 'wx', ...(mode === null ? {} : { mode }) });
     if (mode !== null) fsImpl.chmodSync(temp, mode);
     fsImpl.renameSync(temp, dest);
   } finally {