driftseal 0.3.0 → 0.4.0

package/README.md

@@ -75,6 +75,7 @@ The v1 server provides:
 | --- | --- |
 | `driftseal_status`, `driftseal_log` | Read the current intent and intent history. |
 | `driftseal_begin`, `driftseal_end` | Open and honestly close a work round. |
+| `driftseal_reclaim`, `driftseal_unreclaim` | Hide meaningless closed records behind append-only markers, or restore them. |
 | `driftseal_decision_list`, `driftseal_decision_show` | Find and read MADR records. |
 | `driftseal_decision_add`, `driftseal_decision_update` | Add selective decisions and reconcile linked ones. |
 | `driftseal://intent/current` | Read the current intent as a JSON resource. |
@@ -113,7 +114,9 @@ Single-step commands that only build, check, or record work already done — com
 | `driftseal begin "<intent>" [-v "<verify>"] [--decision id] [--force]` | Open a work-round intent and optionally link existing decisions. |
 | `driftseal end [id] [-s status] [-n note] [-r verify-result]` | Close an intent honestly. |
 | `driftseal status` | Show the intent currently in progress. |
-| `driftseal log [-n N]` | Review intent history. |
+| `driftseal log [-n N] [--all]` | Review intent history (`--all` includes reclaimed records). |
+| `driftseal reclaim [id ...] --reason "..." [--older-than days] [--force] [--dry-run]` | Hide meaningless closed records behind append-only markers. |
+| `driftseal unreclaim <id> --reason "..."` | Restore a reclaimed record to the visible log. |
 | `driftseal decision add "<title>" -c "..." -o "..."` | Write a numbered MADR decision. |
 | `driftseal decision update <id> [-s status] -n "..."` | Reconcile a linked decision in the open intent. |
 | `driftseal decision list [-s status] [--last N \| --count]` | List or count decision records, optionally filtered by status. |
@@ -127,6 +130,22 @@ close as `completed` or `partial`. The update changes the current status when
 requested and appends a timestamped history entry tied to the intent. Intents
 without decision links keep the ordinary workflow.
 
+## Reclaiming noise records
+
+Some closed records stop mattering: a harness or sandbox failure is recorded
+honestly as `failed`, but it says nothing about the project. `driftseal
+reclaim` retires such records without rewriting history — it appends a
+`reclaim` marker (with a mandatory `--reason`) to the same append-only log,
+and reclaimed records disappear from `driftseal log` and `driftseal status`
+output while remaining in `events.jsonl` and visible with `log --all`.
+`driftseal unreclaim <id> --reason "..."` restores a record that turned out to
+matter.
+
+Without ids, batch mode reclaims only closed `failed`/`abandoned` records that
+are not linked to decisions and are older than `--older-than` days (default
+7); use `--dry-run` to preview. `completed` and `partial` records, and any
+decision-linked record, can only be reclaimed by explicit id with `--force`.
+
 ## Consistency and recovery
 
 DriftSeal serializes mutating commands with locks on the configured intent and
@@ -157,7 +176,7 @@ index.
 
 ## Storage
 
-- `.intent-log/events.jsonl` is the append-only intent log.
+- `.intent-log/events.jsonl` is the append-only intent log. All access goes through `driftseal` (CLI or MCP) — never read, edit, move, or delete it directly; use `driftseal reclaim` to retire meaningless records instead of deleting log lines.
 - `.decision-log/` contains numbered MADR decision records.
 - Set `DRIFTSEAL_HOME` or `DRIFTSEAL_DECISION_HOME` to store either log outside the current project.
 

package/README.zh-CN.md

@@ -75,6 +75,7 @@ v1 server 提供：
 | --- | --- |
 | `driftseal_status`, `driftseal_log` | 读取当前 intent 和 intent 历史。 |
 | `driftseal_begin`, `driftseal_end` | 开启并诚实关闭一轮工作。 |
+| `driftseal_reclaim`, `driftseal_unreclaim` | 用 append-only 标记隐藏已无意义的已关闭记录，或将其恢复。 |
 | `driftseal_decision_list`, `driftseal_decision_show` | 查找并读取 MADR record。 |
 | `driftseal_decision_add`, `driftseal_decision_update` | 克制地增加 decision，并 reconcile 已关联的 decision。 |
 | `driftseal://intent/current` | 以 JSON resource 读取当前 intent。 |
@@ -113,7 +114,9 @@ driftseal end \
 | `driftseal begin "<intent>" [-v "<verify>"] [--decision id] [--force]` | 开启一轮工作，并可关联已有 decision。 |
 | `driftseal end [id] [-s status] [-n note] [-r verify-result]` | 诚实地关闭 intent。 |
 | `driftseal status` | 查看当前进行中的 intent。 |
-| `driftseal log [-n N]` | 查看 intent 历史。 |
+| `driftseal log [-n N] [--all]` | 查看 intent 历史（`--all` 包含已回收的记录）。 |
+| `driftseal reclaim [id ...] --reason "..." [--older-than days] [--force] [--dry-run]` | 用 append-only 标记隐藏已无意义的已关闭记录。 |
+| `driftseal unreclaim <id> --reason "..."` | 把已回收的记录恢复到可见历史中。 |
 | `driftseal decision add "<title>" -c "..." -o "..."` | 写入编号化的 MADR decision。 |
 | `driftseal decision update <id> [-s status] -n "..."` | 在当前 intent 中 reconcile 已关联的 decision。 |
 | `driftseal decision list [-s status] [--last N \| --count]` | 列出或统计 decision records，也可按 status 筛选。 |
@@ -126,6 +129,19 @@ driftseal end \
 每一条关联 decision。update 可以改变当前 status，并会追加一条包含时间和
 intent ID 的 history。没有关联 decision 的 intent 仍沿用普通流程。
 
+## 回收已无意义的记录
+
+有些已关闭的记录会随着时间失去意义：harness 或 sandbox 导致的失败会被如实记录为
+`failed`，但它与项目本身无关。`driftseal reclaim` 可以在不改写历史的前提下让这类
+记录退场——它只是向同一个 append-only log 追加一条 `reclaim` 标记（必须附带
+`--reason`），被回收的记录会从 `driftseal log` 和 `driftseal status` 的输出中隐藏，
+但仍保留在 `events.jsonl` 中，并可通过 `log --all` 查看。若事后发现某条记录仍然
+重要，用 `driftseal unreclaim <id> --reason "..."` 恢复。
+
+不带 id 的批量模式只回收已关闭、未关联 decision、且早于 `--older-than` 天（默认 7
+天）的 `failed`/`abandoned` 记录；可以先用 `--dry-run` 预览。`completed` 和 `partial`
+记录，以及任何关联了 decision 的记录，只能按显式 id 加 `--force` 回收。
+
 ## 一致性与恢复
 
 DriftSeal 会对配置后的 intent log 与 decision log 根目录加锁，并按固定顺序获取这些
@@ -152,7 +168,7 @@ recovery 只处理当前 intent，因此历史冲突不会阻塞之后的 decisi
 
 ## 数据保存在哪里
 
-- `.intent-log/events.jsonl`：append-only intent log。
+- `.intent-log/events.jsonl`：append-only intent log。所有读写都必须经过 `driftseal`（CLI 或 MCP）——不要直接读取、修改、移动或删除该文件；需要让无意义的记录退场时使用 `driftseal reclaim`，而不是删除日志行。
 - `.decision-log/`：编号化的 MADR decision records。
 - 设置 `DRIFTSEAL_HOME` 或 `DRIFTSEAL_DECISION_HOME`，即可把对应 log 放到当前项目之外。
 

package/bin/driftseal-mcp.js

@@ -77,6 +77,9 @@ function registerTools(server, api, z) {
     verifyResult: z.string().nullable(),
     beganAt: z.string(),
     endedAt: z.string().nullable(),
+    reclaimed: z.boolean(),
+    reclaimReason: z.string().nullable(),
+    reclaimedAt: z.string().nullable(),
   });
   const decisionRecord = z.object({
     id: z.string(),
@@ -163,18 +166,85 @@ function registerTools(server, api, z) {
     {
       title: 'List DriftSeal intent history',
       description:
-        'Review recent or complete DriftSeal intent history to re-anchor work and understand prior outcomes.',
-      inputSchema: { last: z.number().int().positive().max(100).optional() },
+        'Review recent or complete DriftSeal intent history to re-anchor work and understand prior outcomes. Reclaimed records are hidden unless includeReclaimed is set.',
+      inputSchema: {
+        last: z.number().int().positive().max(100).optional(),
+        includeReclaimed: z.boolean().default(false),
+      },
       outputSchema: { root: z.string(), intents: z.array(intentRecord) },
       annotations: readOnly,
     },
     async (input) =>
       guarded(() => {
-        const intents = api.log(input);
+        const intents = api.log({ last: input.last, all: input.includeReclaimed });
         return success({ root: api.root, intents }, `Found ${intents.length} DriftSeal intent records.`);
       })
   );
 
+  server.registerTool(
+    'driftseal_reclaim',
+    {
+      title: 'Reclaim DriftSeal intent records',
+      description:
+        'Hide meaningless closed intent records (for example harness- or sandbox-caused failures) by appending reclaim markers. Never deletes log lines. Without ids, reclaims failed/abandoned, decision-unlinked records older than olderThan days.',
+      inputSchema: {
+        ids: z
+          .array(z.string())
+          .default([])
+          .describe('Intent IDs to reclaim; omit for batch mode by age.'),
+        reason: nonEmpty.describe('Why these records are meaningless (required, kept in the log).'),
+        olderThan: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Batch mode retention window in days (default 7).'),
+        force: z
+          .boolean()
+          .default(false)
+          .describe('Allow reclaiming partial/completed or decision-linked records by explicit id.'),
+        dryRun: z.boolean().default(false),
+      },
+      outputSchema: { root: z.string(), intents: z.array(intentRecord) },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    },
+    async (input) =>
+      guarded(() => {
+        const intents = api.reclaim({
+          ids: input.ids,
+          reason: input.reason,
+          olderThan: input.olderThan,
+          force: input.force,
+          dryRun: input.dryRun,
+        });
+        return success(
+          { root: api.root, intents },
+          input.dryRun
+            ? `${intents.length} DriftSeal intent records match.`
+            : `Reclaimed ${intents.length} DriftSeal intent records.`
+        );
+      })
+  );
+
+  server.registerTool(
+    'driftseal_unreclaim',
+    {
+      title: 'Restore a reclaimed DriftSeal intent record',
+      description: 'Restore one reclaimed intent record to the visible log by appending an unreclaim marker.',
+      inputSchema: {
+        id: z.string(),
+        reason: nonEmpty.describe('Why this record is being restored (required, kept in the log).'),
+      },
+      outputSchema: { root: z.string(), intent: intentRecord },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const intent = api.unreclaim(input);
+        return success({ root: api.root, intent }, `Restored DriftSeal intent ${intent.id}.`);
+      })
+  );
+
   server.registerTool(
     'driftseal_decision_list',
     {

package/bin/driftseal.js

@@ -34,8 +34,8 @@ const DECISION_STATUSES = [
   'deprecated',
   'superseded',
 ];
-const EVENT_SCHEMA_VERSION = 2;
-const PROTOCOL_VERSION = 5;
+const EVENT_SCHEMA_VERSION = 3;
+const PROTOCOL_VERSION = 7;
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const MAX_DECISION_SLUG_LENGTH = 180;
@@ -130,6 +130,13 @@ function normalizeEvent(event, line) {
     return event;
   }
 
+  if (event.type === 'reclaim' || event.type === 'unreclaim') {
+    if (typeof event.reason !== 'string' || event.reason.trim().length === 0) {
+      fail(`invalid ${event.type} event on log line ${line}`);
+    }
+    return event;
+  }
+
   if (
     event.type === 'decision_reconcile' ||
     event.type === 'decision_reconcile_prepare' ||
@@ -566,8 +573,28 @@ function fold(events) {
         tsEnd: null,
         note: null,
         verifyResult: null,
+        reclaimed: false,
+        reclaimReason: null,
+        reclaimedAt: null,
       });
       order.push(ev.id);
+    } else if (ev.type === 'reclaim' || ev.type === 'unreclaim') {
+      const rec = records.get(ev.id);
+      if (!rec) fail(`${ev.type} event references unknown intent id: ${ev.id}`);
+      if (ev.type === 'reclaim') {
+        if (rec.status === 'in_progress') {
+          fail(`cannot reclaim intent ${ev.id} while it is in_progress`);
+        }
+        if (rec.reclaimed) fail(`duplicate reclaim event for intent id: ${ev.id}`);
+        rec.reclaimed = true;
+        rec.reclaimReason = ev.reason;
+        rec.reclaimedAt = ev.ts;
+      } else {
+        if (!rec.reclaimed) fail(`unreclaim event for intent id that is not reclaimed: ${ev.id}`);
+        rec.reclaimed = false;
+        rec.reclaimReason = null;
+        rec.reclaimedAt = null;
+      }
     } else if (ev.type === 'end') {
       const rec = records.get(ev.id);
       if (!rec) fail(`end event references unknown intent id: ${ev.id}`);
@@ -1038,6 +1065,7 @@ function render(rec) {
   if (rec.verifyResult) lines.push(`  verify-result: ${rec.verifyResult}`);
   if (rec.note) lines.push(`  note: ${rec.note}`);
   lines.push(`  began: ${rec.tsBegin}` + (rec.tsEnd ? `  ended: ${rec.tsEnd}` : ''));
+  if (rec.reclaimed) lines.push(`  reclaimed: ${rec.reclaimReason}`);
   return lines.join('\n');
 }
 
@@ -1053,6 +1081,9 @@ function publicIntent(rec) {
     verifyResult: rec.verifyResult,
     beganAt: rec.tsBegin,
     endedAt: rec.tsEnd,
+    reclaimed: rec.reclaimed,
+    reclaimReason: rec.reclaimReason,
+    reclaimedAt: rec.reclaimedAt,
   };
 }
 
@@ -1102,14 +1133,38 @@ This repo uses DriftSeal (\`driftseal\`) to prevent agent drift. Every work roun
    just-closed log finalizes that round without requiring a new intent. Any content
    change made while preparing the commit does require a new intent.
 4. **Re-anchor after context loss**: run \`driftseal status\` and \`driftseal log --last 3\` before
-   doing anything else. The open intent is the source of truth.
+   doing anything else. The open intent is the source of truth: resume it when its
+   objective still matches the current task; otherwise close it (\`partial\` or
+   \`abandoned\`, with a note) and \`begin\` a new one.
+
+**Log access goes only through DriftSeal.** Never read, edit, move, or delete
+\`.intent-log/events.jsonl\` (or anything under \`$DRIFTSEAL_HOME\`) directly; use
+\`driftseal\` commands or the MCP tools. Retire meaningless closed records with
+\`driftseal reclaim [id ...] --reason "<why>"\` — it appends a marker, never
+deletes log lines; \`driftseal unreclaim <id> --reason "<why>"\` restores one.
 
 Log: \`.intent-log/events.jsonl\` (override with \`$DRIFTSEAL_HOME\`); commit it with the code.
 ${INTENT_PROTOCOL_END}`;
 }
 
 function previousIntentProtocolBlock(version) {
-  const v4 = intentProtocolBlock(version).replace(
+  const v6 = intentProtocolBlock(version).replace(
+    'doing anything else. The open intent is the source of truth: resume it when its\n' +
+      '   objective still matches the current task; otherwise close it (`partial` or\n' +
+      '   `abandoned`, with a note) and `begin` a new one.',
+    'doing anything else. The open intent is the source of truth.'
+  );
+  if (version >= 6) return v6;
+  const v5 = v6.replace(
+    '\n**Log access goes only through DriftSeal.** Never read, edit, move, or delete\n' +
+      '`.intent-log/events.jsonl` (or anything under `$DRIFTSEAL_HOME`) directly; use\n' +
+      '`driftseal` commands or the MCP tools. Retire meaningless closed records with\n' +
+      '`driftseal reclaim [id ...] --reason "<why>"` — it appends a marker, never\n' +
+      'deletes log lines; `driftseal unreclaim <id> --reason "<why>"` restores one.\n',
+    ''
+  );
+  if (version >= 5) return v5;
+  const v4 = v5.replace(
     '1. **Write intent first**, before modifying, creating, or deleting files, or\n' +
       '   making any other change that may need a rollback:\n' +
       '   `driftseal begin "<what this round will accomplish>" --verify "<command or check that proves it>"`.\n' +
@@ -1144,7 +1199,7 @@ revisiting, non-obvious rationale behind a long-lived or costly-to-reverse accep
 choice, or a deprecated or superseded decision. Do not record routine, local,
 readily reversible choices.
 
-\`driftseal decision add "<title>" --context "<problem and constraints>" --outcome "<decision and rationale>" --option "<considered option>" --consequence "<result>"\`
+\`driftseal decision add "<title>" --context "<problem and constraints>" --outcome "<decision and rationale>" --driver "<decision driver>" --option "<considered option>" --consequence "<result>"\`
 
 Add one \`--driver\`, \`--option\`, or \`--consequence\` flag per item. Use
 \`--status proposed|accepted|rejected|deferred|deprecated|superseded\` when needed.
@@ -1209,6 +1264,10 @@ When an intent declares an existing decision with \`--decision <id>\`, use
 Commit \`.decision-log/\` with the code.`;
 }
 
+function previousDecisionProtocolBlock(version) {
+  return decisionProtocolBlock(version).replace(' --driver "<decision driver>"', '');
+}
+
 function upgradeManagedBlock({
   content,
   marker,
@@ -1408,9 +1467,10 @@ const commands = {
   },
 
   log(argv) {
-    const { positionals, flags } = parseArgs(argv, { last: '-n' });
-    if (positionals.length > 0) fail('usage: driftseal log [--last N]');
+    const { positionals, flags } = parseArgs(argv, { last: '-n', all: 'boolean' });
+    if (positionals.length > 0) fail('usage: driftseal log [--last N] [--all]');
     let records = fold(readEvents({ repairTail: true }));
+    if (!flags.all) records = records.filter((record) => !record.reclaimed);
     if (flags.last) {
       const n = positiveInteger(flags.last, '--last');
       records = records.slice(-n);
@@ -1423,6 +1483,109 @@ const commands = {
     return records.map(publicIntent);
   },
 
+  reclaim(argv) {
+    const { positionals, flags } = parseArgs(argv, {
+      reason: '-r',
+      'older-than': 'single',
+      force: 'boolean',
+      'dry-run': 'boolean',
+    });
+    const reason = flags.reason && flags.reason.trim();
+    if (!reason) {
+      fail(
+        'usage: driftseal reclaim [id ...] --reason "<why>" [--older-than <days>] [--force] [--dry-run]'
+      );
+    }
+    let olderThanDays = 7;
+    if (flags['older-than'] !== undefined) {
+      olderThanDays = positiveInteger(flags['older-than'], '--older-than');
+    }
+
+    const records = fold(readEvents({ repairTail: true }));
+    let targets;
+    if (positionals.length > 0) {
+      const ids = [...new Set(positionals)];
+      targets = ids.map((id) => {
+        const record = records.find((candidate) => candidate.id === id);
+        if (!record) fail(`unknown intent id: ${id}`);
+        if (record.status === 'in_progress') {
+          fail(`cannot reclaim intent ${id} while it is in_progress`);
+        }
+        if (record.reclaimed) fail(`intent ${id} is already reclaimed`);
+        const routine = ['failed', 'abandoned'].includes(record.status) &&
+          record.decisions.length === 0;
+        if (!routine && !flags.force) {
+          fail(
+            `intent ${id} is ${record.status}` +
+              (record.decisions.length > 0 ? ' and linked to decisions' : '') +
+              '; re-run with --force to reclaim it anyway'
+          );
+        }
+        return record;
+      });
+    } else {
+      if (flags.force) fail('--force requires explicit intent ids');
+      const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+      targets = records.filter(
+        (record) =>
+          record.status !== 'in_progress' &&
+          ['failed', 'abandoned'].includes(record.status) &&
+          record.decisions.length === 0 &&
+          !record.reclaimed &&
+          Date.parse(record.tsEnd) < cutoff
+      );
+      if (targets.length === 0) {
+        printLine('no reclaimable intents');
+        return [];
+      }
+    }
+
+    if (flags['dry-run']) {
+      printLine(targets.map((record) => `${record.id} ${record.status} — ${record.intent}`).join('\n'));
+      return targets.map(publicIntent);
+    }
+
+    let events = readEvents({ repairTail: true });
+    for (const record of targets) {
+      events.push(
+        appendEvent({
+          type: 'reclaim',
+          id: record.id,
+          ts: new Date().toISOString(),
+          reason,
+        })
+      );
+    }
+    const reclaimed = fold(events).filter((record) =>
+      targets.some((target) => target.id === record.id)
+    );
+    printLine(targets.map((record) => `${record.id} reclaimed`).join('\n'));
+    return reclaimed.map(publicIntent);
+  },
+
+  unreclaim(argv) {
+    const { positionals, flags } = parseArgs(argv, { reason: '-r' });
+    const reason = flags.reason && flags.reason.trim();
+    if (positionals.length !== 1 || !reason) {
+      fail('usage: driftseal unreclaim <id> --reason "<why>"');
+    }
+    const events = readEvents({ repairTail: true });
+    const record = fold(events).find((candidate) => candidate.id === positionals[0]);
+    if (!record) fail(`unknown intent id: ${positionals[0]}`);
+    if (!record.reclaimed) fail(`intent ${positionals[0]} is not reclaimed`);
+    events.push(
+      appendEvent({
+        type: 'unreclaim',
+        id: record.id,
+        ts: new Date().toISOString(),
+        reason,
+      })
+    );
+    const restored = fold(events).find((candidate) => candidate.id === record.id);
+    printLine(`${record.id} unreclaimed`);
+    return publicIntent(restored);
+  },
+
   decision(argv) {
     const [subcommand, ...rest] = argv;
     if (subcommand === 'add') {
@@ -1576,6 +1739,8 @@ const commands = {
         protocolEol(previousIntentProtocolBlock(2), eol),
         protocolEol(previousIntentProtocolBlock(3), eol),
         protocolEol(previousIntentProtocolBlock(4), eol),
+        protocolEol(previousIntentProtocolBlock(5), eol),
+        protocolEol(previousIntentProtocolBlock(6), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyIntentProtocolBlock(), eol)],
     });
@@ -1587,9 +1752,11 @@ const commands = {
       versionPattern: /^<!-- driftseal-decisions-version: (\d+) -->\r?$/m,
       replacement: decisionBlock,
       knownManagedBlocks: [
-        protocolEol(decisionProtocolBlock(2), eol),
-        protocolEol(decisionProtocolBlock(3), eol),
-        protocolEol(decisionProtocolBlock(4), eol),
+        protocolEol(previousDecisionProtocolBlock(2), eol),
+        protocolEol(previousDecisionProtocolBlock(3), eol),
+        protocolEol(previousDecisionProtocolBlock(4), eol),
+        protocolEol(previousDecisionProtocolBlock(5), eol),
+        protocolEol(previousDecisionProtocolBlock(6), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyDecisionProtocolBlock(), eol)],
     });
@@ -1627,7 +1794,11 @@ usage:
   driftseal begin "<intent>" [--verify "<how to verify>"] [--decision <id>] [--force]
   driftseal end [id] [--status completed|partial|failed|abandoned] [--note "..."] [--verify-result "..."]
   driftseal status                     show the intent currently in progress (re-anchor after drift)
-  driftseal log [--last N]             show intent history
+  driftseal log [--last N] [--all]     show intent history (--all includes reclaimed records)
+  driftseal reclaim [id ...] --reason "<why>" [--older-than <days>] [--force] [--dry-run]
+                                 hide meaningless closed records without deleting them
+  driftseal unreclaim <id> --reason "<why>"
+                                 restore a reclaimed record to the visible log
   driftseal decision add "<title>" --context "..." --outcome "..." [options]
   driftseal decision update <id> [--status STATUS] --note "..."
                                  reconcile a linked decision in the open intent
@@ -1659,6 +1830,7 @@ function requestedEndStatus(argv) {
 
 function mutationResources(cmd, argv) {
   if (cmd === 'init') return [process.cwd()];
+  if (cmd === 'reclaim' || cmd === 'unreclaim') return [logDir()];
   if (cmd === 'begin' && !argv.some((arg) => arg === '--decision' || arg.startsWith('--decision='))) {
     return [logDir()];
   }
@@ -1676,7 +1848,7 @@ function dispatch(argv) {
   const fn = commands[cmd];
   if (!fn) fail(`unknown command: ${cmd} (run: driftseal help)`);
   const mutates =
-    ['begin', 'end', 'init'].includes(cmd) ||
+    ['begin', 'end', 'init', 'reclaim', 'unreclaim'].includes(cmd) ||
     (cmd === 'decision' && ['add', 'update'].includes(rest[0]));
   const readsIntentLog = ['status', 'log'].includes(cmd);
   if (mutates || readsIntentLog) {
@@ -1768,11 +1940,22 @@ function createApi({ root = process.cwd(), isolateStorage = false } = {}) {
       appendFlag(argv, '--verify-result', verifyResult);
       return call(argv);
     },
-    log({ last } = {}) {
+    log({ last, all = false } = {}) {
       const argv = ['log'];
       appendFlag(argv, '--last', last);
+      if (all) argv.push('--all');
+      return call(argv);
+    },
+    reclaim({ ids = [], reason, olderThan, force = false, dryRun = false }) {
+      const argv = ['reclaim', ...ids.map(String), '--reason', reason];
+      appendFlag(argv, '--older-than', olderThan);
+      if (force) argv.push('--force');
+      if (dryRun) argv.push('--dry-run');
       return call(argv);
     },
+    unreclaim({ id, reason }) {
+      return call(['unreclaim', String(id), '--reason', reason]);
+    },
     decisionAdd({ title, context, outcome, status, drivers = [], options = [], consequences = [] }) {
       const argv = ['decision', 'add', title, '--context', context, '--outcome', outcome];
       appendFlag(argv, '--status', status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",
@@ -12,13 +12,13 @@
     "decision-log",
     "madr"
   ],
-  "homepage": "https://github.com/ruanboyu/driftseal#readme",
+  "homepage": "https://github.com/rowan-hiro/DriftSeal#readme",
   "bugs": {
-    "url": "https://github.com/ruanboyu/driftseal/issues"
+    "url": "https://github.com/rowan-hiro/DriftSeal/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ruanboyu/driftseal.git"
+    "url": "git+https://github.com/rowan-hiro/DriftSeal.git"
   },
   "license": "MIT",
   "author": "Ruan Boyu <boyuruan@gmail.com>",

package/skills/use-driftseal/SKILL.md

@@ -5,162 +5,62 @@ description: Run repository work through the DriftSeal (`driftseal`) intent, ver
 
 # Use DriftSeal
 
-Run repository work as small, closed, auditable rounds. Treat the intent log,
-decision log, and Git history as complementary records rather than duplicate
-activity streams.
+This skill is the usage guide for DriftSeal: how to find it and which command
+or tool to reach for. The binding protocol — when an intent is required, how
+to close one honestly, when a decision record is warranted, how reclamation
+works — lives in the target repository's `AGENTS.md` (injected by
+`driftseal init`). Follow that file; do not substitute this guide or memory
+for it.
 
 ## Locate DriftSeal
 
 - Prefer the `driftseal_*` MCP tools when the DriftSeal MCP server is available
-  for the target repository. Use `driftseal_status`, `driftseal_begin`,
-  `driftseal_end`, and the corresponding decision tools instead of invoking the
-  CLI through a shell.
-- Work from the repository root unless its instructions specify another scope.
-- When MCP is unavailable, prefer `driftseal` from `PATH`. In a DriftSeal source
-  checkout, fall back to `node bin/driftseal.js` when the global command is
-  unavailable.
-- Follow the repository's `AGENTS.md`. Storage overrides such as
-  `DRIFTSEAL_HOME` apply to CLI use; the MCP server deliberately keeps state in
-  its fixed repository root.
-- If DriftSeal is unavailable, limit activity to read-only discovery and report the
-  blocker. Do not mutate the repository without the required log.
-
-Use one interface consistently within a round. The examples below use
-`driftseal`; map them directly to the same-named MCP workflow when MCP is
-available, or substitute the local source command when necessary.
-
-## Re-anchor Before Acting
-
-1. Run `driftseal status` at the start of work.
-2. Run `driftseal log --last 3` after compaction, a resumed session, or uncertainty.
-3. Continue an open intent when it matches the requested work. Treat it as the
-   source of truth; do not open a duplicate intent.
-4. Close a conflicting intent as `partial` or `abandoned` with an honest note,
-   then begin the replacement round.
-
-Do not use `--force` merely for convenience. If another live actor owns the
-open intent, stop mutating and coordinate instead of abandoning its work.
-
-## Begin the Round
-
-Before modifying, creating, or deleting files — or making any other change that
-may need a rollback — declare one objective and its proof:
+  for the target repository: `driftseal_status`, `driftseal_begin`,
+  `driftseal_end`, `driftseal_log`, `driftseal_reclaim`, `driftseal_unreclaim`,
+  and the `driftseal_decision_*` tools. Their input schemas come from the MCP
+  client, not from `driftseal help`. The server keeps state in its fixed
+  repository root and ignores storage-override environment variables.
+- Otherwise prefer `driftseal` from `PATH`, where `DRIFTSEAL_HOME` and
+  `DRIFTSEAL_DECISION_HOME` overrides apply. In a DriftSeal source checkout,
+  fall back to `node bin/driftseal.js`.
+- Use one interface consistently within a round.
+- If DriftSeal is unavailable, limit activity to read-only discovery and report
+  the blocker. Do not mutate the repository without the required log.
+
+## Command Map
+
+Re-anchor after context loss or uncertainty; when `status` reports an open
+intent, the repository protocol defines whether to resume or replace it:
 
 ```sh
-driftseal begin "<small objective for this round>" \
-  --verify "<exact command or outcome check>"
+driftseal status
+driftseal log --last 3        # add --all to include reclaimed records
 ```
 
-Make the intent small enough to finish and verify in one round. Prefer an
-outcome-focused check over a vague activity such as "inspect the result."
-Starting the intent is the first permitted mutation. Single-step commands that
-only build, check, or record work already done — compiling, running tests,
-`git add`/`git commit` — need no intent of their own.
-
-When the round may change or confirm an existing decision, declare each one at
-the boundary with `--decision <id>`. Do not add decision links speculatively.
-
-Read-only inspection needed to choose the objective or verifier may happen
-before `begin`. Do not let that inspection turn into unlogged implementation.
-
-## Execute Without Drift
-
-- Change only what the open intent covers.
-- Preserve unrelated worktree changes and other actors' edits.
-- If the objective expands or changes, close the current intent as `partial`
-  or `abandoned`, then start a new round before continuing.
-- If the declared verifier becomes invalid, record that honestly and start a
-  new round with the correct verifier instead of silently substituting proof.
-- If the user replaces the active request, reconcile the open intent before
-  acting on the replacement.
-
-## Record Decisions Selectively
-
-Before adding a decision record, ask what useful information would disappear
-if only the intent log and final Git commit remained.
-
-Add a MADR record only when it preserves at least one of these:
-
-- a rejected path worth preventing future agents from retrying;
-- an unresolved or deliberately deferred path with a concrete revisit trigger;
-- non-obvious rationale or trade-offs behind an accepted choice that is
-  long-lived, cross-cutting, or costly to reverse;
-- the reason an earlier decision became deprecated or superseded.
-
-Skip routine, local, readily reversible choices. Do not restate an accepted
-change that the intent and commit already explain.
-
-Use `proposed` for unresolved choices still under active consideration. Use
-`deferred` for choices that are deliberately postponed, and state the revisit
-trigger in the outcome or consequences. Use `rejected` for an explicitly
-ruled-out choice. Reserve `accepted` for the exceptional accepted decisions
-whose rationale would otherwise be lost.
-
-Count postponed choices with `driftseal decision list --status deferred --count`,
-then review them with `driftseal decision list --status deferred` so they do not
-disappear into the chronological log.
-
-For every decision explicitly linked by the open intent, reconcile its current
-status and rationale before a successful close:
+Run each work round as the repository's protocol directs (`-v`, `-s`, `-n`,
+and `-r` are the short forms of `--verify`, `--status`, `--note`, and
+`--verify-result`):
 
 ```sh
-driftseal decision update <id> \
-  --status <proposed|accepted|rejected|deferred|deprecated|superseded> \
-  --note "<what changed or was confirmed, and why>"
+driftseal begin "<objective>" --verify "<proof>" [--decision <id>]
+# ... do only what the intent covers ...
+driftseal end --status <status> --note "<what happened>" --verify-result "<proof output>"
 ```
 
-The update appends a decision history entry tied to the open intent. An
-unchanged decision still needs an explicit confirmation note. DriftSeal rejects a
-`completed` or `partial` close if any declared decision remains unreconciled;
-`failed` and `abandoned` remain available as escape paths.
-
-Do not edit a linked decision after reconciling it. Run `decision update` again
-so the final content hash is recorded. If an update is interrupted, rerun it or
-successfully close the linked intent; DriftSeal recovers only that intent's pending
-transaction. Closing as `failed` or `abandoned` cancels its pending recovery so
-historical conflicts cannot block future decision work.
+Record and reconcile decisions as the repository's decision protocol directs:
 
 ```sh
-driftseal decision add "<decision title>" \
-  --status deferred \
-  --context "<problem and constraints>" \
-  --outcome "<current disposition, rationale, and revisit trigger>" \
-  --option "<considered option>" \
-  --consequence "<result of this disposition>"
+driftseal decision add "<title>" --context "..." --outcome "..."
+driftseal decision update <id> [--status <status>] --note "<what changed or was confirmed>"
+driftseal decision list --status deferred
 ```
 
-## Verify and Close
-
-Run the declared verification exactly as written. Then close the intent before
-reporting success:
+Retire meaningless closed records as the repository's protocol directs:
 
 ```sh
-driftseal end \
-  --status completed \
-  --note "<what actually happened>" \
-  --verify-result "<concise, honest result>"
+driftseal reclaim [id ...] --reason "<why>" [--dry-run]
+driftseal unreclaim <id> --reason "<why>"
 ```
 
-Choose the status from evidence:
-
-- `completed`: achieve the objective and pass the declared verification.
-- `partial`: leave useful work but do not achieve the whole objective.
-- `failed`: fail to produce a usable result or fail essential verification.
-- `abandoned`: intentionally stop or replace the round.
-
-Never leave an intent open merely because the work failed. Never report a
-completed result while the log still says `in_progress`.
-
-## Persist the Round in Git
-
-Treat a focused Git commit as the third record: the intent says what was
-planned and how it was checked, the decision log preserves otherwise-lost
-context, and the commit shows what actually landed.
-
-When the user has authorized a commit, stage and commit only the verified
-changes, the closed intent events, and any relevant decision record. This
-bookkeeping finalizes the just-closed round and does not require a new intent.
-
-Keep this exception narrow. Open a new intent before making content changes,
-fixing a hook failure, rewriting history, rebasing, pushing, or including work
-outside the closed round.
+For exact flags, eligibility rules, and recovery behavior, run
+`driftseal help` and read the repository's `AGENTS.md`.