@khoavu882/doflow 2.0.0-beta.3 → 2.0.0-beta.5

package/core/shared/skills/do-execute-plan/references/readiness_gate.md

@@ -153,3 +153,5 @@ checklist it is. Do not halt indefinitely on a persistent `NEEDS_EVIDENCE` — r
 actually established, state which requirements it covers, and say what remains. And do not write
 `READY` yourself. The gate did not say it, and saying it on the gate's behalf is precisely the
 failure this page exists to prevent.
+
+Record an absence with `--absence --need <intent>`; a positive item never states `--absence`.

package/core/shared/skills/do-execute-plan/references/scaffold.md

@@ -56,7 +56,7 @@ Two rules deserve their reasoning, because both are easy to "improve" into a def
 | | Part 1 — in-scope | Part 2 — external dependency |
 |---|---|---|
 | Input | `requirement.md`, `design.md`, `plan.md` | a `depends-on:` value with no owning task |
-| Produced by | `src/runtime/scaffold/generate.ts`, deterministically | this file's algorithm, executed by you |
+| Produced by | `src/runtime/scaffold/generate.js`, deterministically | this file's algorithm, executed by you |
 | Lands in | `scaffold/src/`, `scaffold/test/`, `scaffold/MANIFEST.md` | `scaffold/contracts/<service>/` |
 | Answers | what shape does my own plan imply | what shape must I code against at the boundary |
 
@@ -391,7 +391,7 @@ this Part; `scaffold/contracts/<service>/` is the only place any of it may write
 ## Constraints (carried from the design — do not relax these)
 
 The first applies to both Parts. Every other constraint here is Part 2's, and its bare step numbers
-are Part 2's steps — Part 1's equivalents are enforced by `src/runtime/scaffold/generate.ts` and its guard
+are Part 2's steps — Part 1's equivalents are enforced by `src/runtime/scaffold/generate.js` and its guard
 rather than restated as prose.
 
 - Never write outside `agent-docs/doflow/<slug>/scaffold/` — not into the source tree, and not

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

@@ -111,8 +111,9 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      "$DOFLOW" context-pack --task-id "<task id>" --json
      ```
      This verb exits 1 on an empty pack by design — nothing recorded is not the same as nothing
-     needed — and that non-zero exit is never read as success. Because this call only runs after the
-     evidence check above already found something recorded for this task id, an exit 1 here means
+     needed — and that non-zero exit is never read as success; exit 3 means overflow: the pack is
+     complete, act on `overflowAction.message` and report the gap. Because this call only runs after
+     the evidence check above already found something recorded for this task id, an exit 1 here means
      the compiled pack still held nothing usable (evidence with no linked claims, most likely):
      treat that as a mismatch worth naming in step 6's report, not as license to proceed as though
      there were no prior context to look for. On a normal, non-empty pack, carry its evidence and

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

@@ -67,14 +67,13 @@ not have.
    ```bash
    "$DOFLOW" context-pack --task-id "<task id>" --json
    ```
-   **Exit 1 means the pack came back empty.** By this point `do-design` should already have batched
-   its own stage-boundary evidence and claims (its step 8), so an empty pack here carries more
-   weight than it does at design time: either that batch never ran, or this task id doesn't match
-   the one design used. Treat it as advisory rather than blocking — plan's hard gate is artifact
-   existence only — but say so plainly in this stage's report, and in `plan.md`'s own §3 "Research &
-   Decisions": a decision written straight from `requirement.md`/`design.md` prose, with no compiled
-   pack behind it, must not be recorded as if it traced to prior evidence it doesn't have. When the
-   pack is non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
+   **Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on
+   `overflowAction.message` and report the gap.** By this point `do-design` should have batched
+   evidence and claims (step 8), so an empty pack carries weight: either the batch never ran or the
+   task id mismatched. Treat it as advisory rather than blocking — plan's hard gate is artifact
+   existence only — but note it in this stage's report and `plan.md` §3 "Research & Decisions": a
+   decision written straight from prose without a compiled pack must not claim prior evidence. When
+   non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
    **Also read `specs.md` when step 1's `has_specs` is true** — use that flag, never a filesystem
    check of your own, and read the `specs` path the resolver returned. `/do-design` moves the
    interface and data-model contracts out of `design.md` into `specs.md` §1 as numbered `IC-###`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "description": "DoFlow config installer — npx CLI for the registry-driven multi-harness install/update/remove lifecycle",
   "keywords": [
     "claude-code",
@@ -31,9 +31,11 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
     "typecheck": "npx -y -p typescript@5.7.2 tsc -p tsconfig.json",
+    "build:package": "node src/release/build-package.js .pack",
     "bench": "node bench/runner.js",
     "drift": "node scripts/check-format-drift.js",
-    "version": "node src/release/sync-plugin-versions.ts && git add core/.codex-plugin/plugin.json core/.claude-plugin/plugin.json core/.plugin/plugin.json"
+    "release-notes": "node src/release/changelog-section.js",
+    "version": "node src/release/sync-plugin-versions.js && git add core/.codex-plugin/plugin.json core/.claude-plugin/plugin.json core/.plugin/plugin.json"
   },
   "files": [
     "bin/",

package/src/adapters/antigravity/{index.ts → index.js}

@@ -20,10 +20,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.ts');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor } = require('../copy-tree.ts');
-const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.ts');
-const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.ts');
+const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, readJson, sourceDirFor } = require('../copy-tree.js');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { readMcpFiles, planMcpEntries, verifyMcpEntries, ownedMcpIds, writeMcpEntries } = require('../mcp-entries.js');
 
 const HARNESS = 'antigravity';
 const MCP_CONTAINER = 'mcpServers';
@@ -31,7 +31,7 @@ const MCP_RENDERER = 'antigravity-mcp';
 
 /** copy-tree's readJson distinguishes absent/unparseable via an {exists,value,error} envelope;
  * every caller here wants the plain object or {}. */
-function readJsonObject(file: any, { fsImpl = fs }: any = {}) {
+function readJsonObject(file     , { fsImpl = fs }      = {}) {
   const result = readJson(file, { fsImpl });
   if (!result || !result.exists || result.error) return {};
   return result.value ?? {};
@@ -54,20 +54,20 @@ const GATE_MATCHER = 'write_to_file|replace_file_content|multi_replace_file_cont
 /** Build DoFlow's hooks.json groups from the projected scripts' on-disk locations. Absolute command
  * path: the docs' own examples use relative ./scripts paths whose resolution base is not stated,
  * and an absolute path is unambiguous for a per-workspace install. */
-function hookGroups({ gateCommand, stopCommand }: any) {
+function hookGroups({ gateCommand, stopCommand }     ) {
   return {
     [HOOKS_GROUP]: { PreToolUse: [{ matcher: GATE_MATCHER, hooks: [{ type: 'command', command: gateCommand }] }] },
     [STOP_HOOKS_GROUP]: { Stop: [{ type: 'command', command: stopCommand }] },
   };
 }
 
-function hookScriptTarget(identity: any, paths: any) {
+function hookScriptTarget(identity     , paths     ) {
   return identity === 'pre-implementation-gate.sh' ? paths.hookScript : paths.stopHookScript;
 }
 
-function planHooks({ paths, scope, neutralResources, removing, repoRoot, fsImpl = fs }: any) {
-  const changes: any[] = [];
-  const conflicts: any[] = [];
+function planHooks({ paths, scope, neutralResources, removing, repoRoot, fsImpl = fs }     ) {
+  const changes        = [];
+  const conflicts        = [];
   if (scope !== 'project') {
     // The shims resolve the workspace via git/transcriptPath; a user-scope hooks.json would fire
     // against every project including non-git ones. Project-only until a documented user story exists.
@@ -76,9 +76,9 @@ function planHooks({ paths, scope, neutralResources, removing, repoRoot, fsImpl
   const target = paths.hooksJson;
   const scriptSource = sourceDirFor({ source: 'core/harnesses/antigravity/hooks' }, { repoRoot }, fsImpl, HARNESS);
 
-  const previousHookRows = (neutralResources || []).filter((r: any) => r.harness === HARNESS && r.assetId === HOOKS_ASSET_ID && r.kind === 'hooks-json');
-  const previousScriptRows = (neutralResources || []).filter((r: any) => r.harness === HARNESS && r.assetId === HOOKS_ASSET_ID && r.kind === 'copy-tree-file');
-  const docRow = previousHookRows.find((r: any) => r.target === target);
+  const previousHookRows = (neutralResources || []).filter((r     ) => r.harness === HARNESS && r.assetId === HOOKS_ASSET_ID && r.kind === 'hooks-json');
+  const previousScriptRows = (neutralResources || []).filter((r     ) => r.harness === HARNESS && r.assetId === HOOKS_ASSET_ID && r.kind === 'copy-tree-file');
+  const docRow = previousHookRows.find((r     ) => r.target === target);
 
   if (removing) {
     if (docRow || fsImpl.existsSync(target)) {
@@ -89,7 +89,7 @@ function planHooks({ paths, scope, neutralResources, removing, repoRoot, fsImpl
     }
     for (const identity of HOOK_SCRIPTS) {
       const scriptTarget = hookScriptTarget(identity, paths);
-      const scriptRow = previousScriptRows.find((r: any) => r.identity === identity);
+      const scriptRow = previousScriptRows.find((r     ) => r.identity === identity);
       if (scriptRow && fsImpl.existsSync(scriptTarget)) {
         const current = sha256File(fsImpl, scriptTarget);
         if (current === scriptRow.fingerprint) {
@@ -130,7 +130,7 @@ function planHooks({ paths, scope, neutralResources, removing, repoRoot, fsImpl
   return { changes, conflicts };
 }
 
-function sha256File(fsImpl: any, file: any) {
+function sha256File(fsImpl     , file     ) {
   return require('node:crypto').createHash('sha256').update(fsImpl.readFileSync(file)).digest('hex');
 }
 
@@ -138,7 +138,7 @@ function sha256File(fsImpl: any, file: any) {
  * ("paths"): project customization lives at <root>/.agents, global config at ~/.gemini/config
  * (the shared-customization root); instructions and skills are project-only surfaces, so no user
  * rule is declared for them and they resolve to null there. */
-function resolveNativePaths(declaredPaths: any, { scope, scopeRoot, homeDir }: any = {}) {
+function resolveNativePaths(declaredPaths     , { scope, scopeRoot, homeDir }      = {}) {
   if (scope !== 'project' && scope !== 'global') throw new Error(`Unsupported Antigravity scope '${scope}'`);
   const resolved = resolveHarnessPaths(declaredPaths, { scope, scopeRoot, homeDir });
   return {
@@ -168,33 +168,35 @@ function nativePaths(options = {}) {
  * keeps its planners module-level (they already thread resolved `paths` explicitly), so injection
  * flows through an optional `impl.nativePaths` seam instead of a full closure rewrite.
  */
-function createAntigravityAdapter({ declaredPaths = DEFAULT_DECLARED_PATHS }: any = {}) {
-  const nativePathsFor = (options: any) => resolveNativePaths(declaredPaths, options);
+function createAntigravityAdapter({ declaredPaths = DEFAULT_DECLARED_PATHS }      = {}) {
+  const nativePathsFor = (options     ) => resolveNativePaths(declaredPaths, options);
   return {
     nativePaths: nativePathsFor,
-    discover: (options: any, impl = {}) => discover(options, { ...impl, nativePaths: nativePathsFor }),
+    discover: (options     , impl = {}) => discover(options, { ...impl, nativePaths: nativePathsFor }),
     render,
-    plan: (options: any, impl = {}) => plan(options, { ...impl, nativePaths: nativePathsFor }),
+    plan: (options     , impl = {}) => plan(options, { ...impl, nativePaths: nativePathsFor }),
     apply,
     remove,
-    verify: (options: any, impl = {}) => verify(options, { ...impl, nativePaths: nativePathsFor }),
+    verify: (options     , impl = {}) => verify(options, { ...impl, nativePaths: nativePathsFor }),
+    planHookDoors: (options     , impl = {}) => planHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
+    verifyHookDoors: (options     , impl = {}) => verifyHookDoors(options, { ...impl, nativePaths: nativePathsFor }),
   };
 }
 
 const singleton = createAntigravityAdapter();
 
 /** The scope's paths exactly as plan() and verify() resolve them, so discovery reads the same files. */
-function scopePaths(options: any, resolvePaths = singleton.nativePaths) {
+function scopePaths(options     , resolvePaths = singleton.nativePaths) {
   return resolvePaths({ ...options, scope: options.scope ?? 'project', homeDir: options.context?.homeDir });
 }
 
-function ledgerResources(options: any) {
+function ledgerResources(options     ) {
   return options.ledger?.resources ?? options.managedResources ?? [];
 }
 
 /** Discovery keeps the MCP files as plan read them (`mcpSnapshot`), which verify compares against,
  * and reports the servers DoFlow owns in mcp_config.json now (`mcpOwned`). */
-function discover(options: any, { fsImpl = fs, nativePaths: resolvePaths = singleton.nativePaths }: any = {}) {
+function discover(options     , { fsImpl = fs, nativePaths: resolvePaths = singleton.nativePaths }      = {}) {
   const paths = scopePaths(options, resolvePaths);
   const instruction = paths.instruction && fsImpl.existsSync(paths.instruction)
     ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
@@ -206,11 +208,11 @@ function discover(options: any, { fsImpl = fs, nativePaths: resolvePaths = singl
   return { paths, instruction, mcpSnapshot, mcpOwned: ownedMcpIds({ ...entries, files: mcpSnapshot }), mcpConfigured };
 }
 
-function render({ content = '' }: any = {}) {
+function render({ content = '' }      = {}) {
   return `${MARKER_START}\n${String(content).trimEnd()}\n${MARKER_END}\n`;
 }
 
-function managedInstruction(existing: any, rendered: any) {
+function managedInstruction(existing     , rendered     ) {
   if (existing === null) return { ok: true, operation: 'create', content: rendered };
   const start = existing.indexOf(MARKER_START);
   const end = existing.indexOf(MARKER_END);
@@ -224,7 +226,7 @@ function managedInstruction(existing: any, rendered: any) {
   return { ok: true, operation: content === existing ? 'none' : 'merge', content };
 }
 
-function strippedInstruction(existing: any) {
+function strippedInstruction(existing     ) {
   if (typeof existing !== 'string') return null;
   const start = existing.indexOf(MARKER_START);
   const end = existing.indexOf(MARKER_END);
@@ -239,7 +241,7 @@ function strippedInstruction(existing: any) {
 /** Scope policy mirrors the registry notes, resolved from each asset's own flat nativeDir:
  *   ../x or .agents/x or .doflow/x  → rooted at the install root (project scope)
  *   plain names (bin, agents)       → inside the scope's config dir (.agents | ~/.gemini/config) */
-function treeDestFor(asset: any, paths: any, scope: any) {
+function treeDestFor(asset     , paths     , scope     ) {
   const nativeDir = asset.nativeDir;
   if (!nativeDir) return null;
   if (asset.id === 'skills.doflow') {
@@ -263,7 +265,7 @@ function treeDestFor(asset: any, paths: any, scope: any) {
   return path.join(paths.configDir, nativeDir);
 }
 
-function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot, force = false, fsImpl = fs }: any) {
+function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot, force = false, fsImpl = fs }     ) {
   const changes = [];
   const conflicts = [];
   const treeResults = [];
@@ -285,10 +287,10 @@ function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot,
       // planTrees as well, since its signature did not carry the context the others already had.
       force: !removing && force === true });
     treeResults.push(result);
-    conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+    conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
     // A hand-edited file at a path DoFlow no longer writes is the user's: it stays, only its
     // ownership row is released.
-    notices.push(...result.kept.map((item: any) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+    notices.push(...result.kept.map((item     ) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
     for (const change of result.changes) {
       changes.push({
         assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
@@ -303,15 +305,15 @@ function planTrees({ assets, paths, scope, neutralResources, removing, repoRoot,
   return { changes, conflicts, targets, notices: [...siblingReplacedNotices(treeResults), ...notices] };
 }
 
-function runTreeChanges(changes: any, mode: any) {
+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
   // everything through one engine call silently deleted nothing (verification then correctly
   // refused to journal the no-op). Writes go to applyTree, removals to removeTree, always.
   void mode;
   const treeChanges = changes
-    .filter((c: any) => c.projection?.renderer === 'copy-tree' || c.kind === 'copy-tree-file')
-    .map((c: any) => ({ relPath: c.identity ?? c.relPath, target: c.target,
+    .filter((c     ) => c.projection?.renderer === 'copy-tree' || c.kind === 'copy-tree-file')
+    .map((c     ) => ({ relPath: c.identity ?? c.relPath, target: c.target,
       source: c._text ? undefined : c.source, operation: c.operation,
       fingerprint: c.fingerprint, pruneGuard: c.pruneGuard, ...(c._text ? { _text: c._text } : {}) }));
   // Content-managed tree files (hook scripts): write rendered text with +x, not a byte copy.
@@ -324,17 +326,17 @@ function runTreeChanges(changes: any, mode: any) {
   }
   return {
     applied: 0, removed: 0,
-    ...(function (): any {
-      const plain = treeChanges.filter((t: any) => t._text === undefined);
-      const writes = plain.filter((c: any) => c.operation !== 'remove');
-      const removals = plain.filter((c: any) => c.operation === 'remove');
+    ...(function ()      {
+      const plain = treeChanges.filter((t     ) => t._text === undefined);
+      const writes = plain.filter((c     ) => c.operation !== 'remove');
+      const removals = plain.filter((c     ) => c.operation === 'remove');
       const applied = writes.length ? applyTree({ changes: writes }).applied : 0;
       const removed = removals.length ? removeTree({ changes: removals }).removed : 0;
       return { applied, removed };
     })(),
   };
-  const writes = treeChanges.filter((c: any) => c.operation !== 'remove');
-  const removals = treeChanges.filter((c: any) => c.operation === 'remove');
+  const writes = treeChanges.filter((c     ) => c.operation !== 'remove');
+  const removals = treeChanges.filter((c     ) => c.operation === 'remove');
   const applied = writes.length ? applyTree({ changes: writes }).applied : 0;
   const removed = removals.length ? removeTree({ changes: removals }).removed : 0;
   return { applied, removed };
@@ -342,7 +344,7 @@ function runTreeChanges(changes: any, mode: any) {
 
 // ---- instructions component ----
 
-function planInstructions({ paths, assets, removing, repoRoot, fsImpl = fs }: any) {
+function planInstructions({ paths, assets, removing, repoRoot, fsImpl = fs }     ) {
   if (scopeOf(paths) !== 'project') return { changes: [], conflicts: [] };
   void repoRoot;
   if (removing) {
@@ -380,7 +382,7 @@ function planInstructions({ paths, assets, removing, repoRoot, fsImpl = fs }: an
   };
 }
 
-function pointerBody(fsImpl: any) {
+function pointerBody(fsImpl     ) {
   // The shared pointer prose ships once; read it through the same repo-relative anchor the other
   // AGENTS-style adapters use.
   try {
@@ -388,11 +390,11 @@ function pointerBody(fsImpl: any) {
   } catch { return null; }
 }
 
-function scopeOf(paths: any) { return paths.scope; }
+function scopeOf(paths     ) { return paths.scope; }
 
 // ---- MCP component ----
 
-function mcpDefinitionFor(server: any) {
+function mcpDefinitionFor(server     ) {
   // Remote transports project url/httpUrl -> serverUrl per the current Antigravity schema.
   if (server.transport === 'stdio') {
     return { command: server.command, ...(server.args?.length ? { args: server.args } : {}) };
@@ -400,27 +402,27 @@ function mcpDefinitionFor(server: any) {
   return { serverUrl: server.url ?? server.httpUrl };
 }
 
-function ownershipIdentity(id: any) { return `doflow:${HARNESS}:mcp-server:${id}`; }
+function ownershipIdentity(id     ) { return `doflow:${HARNESS}:mcp-server:${id}`; }
 
 /** Everything the shared entry-ownership rules (../mcp-entries.ts) need from this adapter. Rows
  * recorded before entries were fingerprinted carry `fingerprint: null`; such a row owns its entry
  * only while the entry still equals DoFlow's rendering. */
-function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], resources = [] }: any) {
-  const rendered = (servers: any) => servers.map((server: any) => ({ id: server.id, entry: mcpDefinitionFor(server) }));
-  const rows = resources.filter((row: any) => row.kind === 'mcp-server');
+function mcpEntriesInput({ paths, mcp = [], mcpAdoptable = [], resources = [] }     ) {
+  const rendered = (servers     ) => servers.map((server     ) => ({ id: server.id, entry: mcpDefinitionFor(server) }));
+  const rows = resources.filter((row     ) => row.kind === 'mcp-server');
   return {
     file: paths.mcpFile, selected: rendered(mcp), adoptable: rendered(mcpAdoptable),
-    ownRows: rows.filter((row: any) => row.harness === HARNESS).map((row: any) => ({
+    ownRows: rows.filter((row     ) => row.harness === HARNESS).map((row     ) => ({
       identity: row.identity, target: row.target, fingerprint: row.fingerprint ?? null, ownershipIdentity: row.ownershipIdentity, legacy: false,
     })),
-    foreignRows: rows.filter((row: any) => row.harness !== HARNESS).map((row: any) => ({ harness: row.harness, identity: row.identity, target: row.target })),
+    foreignRows: rows.filter((row     ) => row.harness !== HARNESS).map((row     ) => ({ harness: row.harness, identity: row.identity, target: row.target })),
     identityFor: ownershipIdentity, assetId: POINTER_ASSET_ID, renderer: MCP_RENDERER, label: 'Antigravity MCP',
   };
 }
 
 // ---- required six-function surface ----
 
-function plan(options: any = {}, impl: any = {}) {
+function plan(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   const context = options.context ?? {};
   const scope = options.scope ?? 'project';
@@ -449,7 +451,30 @@ function plan(options: any = {}, impl: any = {}) {
   };
 }
 
-function apply(options: any = {}, impl: any = {}) {
+/** The hook front doors (IC-037): the shims and the hooks.json groups that run them, planned and
+ * verified alone. Project scope only, and only when the harness selected the hooks asset. */
+function planHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (!(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { changes: [], conflicts: [], prerequisites: [], notices: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = planHooks({ paths, scope, neutralResources: ledgerResources(options), removing: false, repoRoot: context.repoRoot, fsImpl });
+  return { changes: doors.changes, conflicts: doors.conflicts, prerequisites: [], notices: [] };
+}
+
+function verifyHookDoors(options      = {}, impl      = {}) {
+  const fsImpl = impl.fsImpl || fs;
+  const context = options.context ?? {};
+  const scope = options.scope ?? 'project';
+  if (scope !== 'project' || !(options.assets ?? []).some((asset     ) => asset.id === HOOKS_ASSET_ID)) return { ok: true, statuses: [], resources: [], conflicts: [] };
+  const paths = (impl.nativePaths ?? singleton.nativePaths)({ ...options, scope, homeDir: context.homeDir });
+  const doors = verifyHooks({ options, paths, context, fsImpl });
+  const conflicts = doors.statuses.filter((status     ) => status.status === 'conflict').map((status     ) => status.reason ?? status.identity);
+  return { ok: conflicts.length === 0, ...doors, conflicts };
+}
+
+function apply(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   // apply()/verify() are reached through the lifecycle with the same scope inputs plan() saw, so
   // they re-derive paths instead of trusting plan-private state. `paths` itself is unused here —
@@ -458,7 +483,7 @@ function apply(options: any = {}, impl: any = {}) {
   (impl.nativePaths ?? singleton.nativePaths)(options);
   const changes = options.changes ?? [];
 
-  for (const change of changes.filter((c: any) => c.projection?.renderer === 'antigravity-instructions')) {
+  for (const change of changes.filter((c     ) => c.projection?.renderer === 'antigravity-instructions')) {
     if (change.operation === 'remove') {
       // pi precedent: strip only the managed span; the file survives even when nothing remains.
       if (!fsImpl.existsSync(change.target)) continue;
@@ -469,7 +494,7 @@ function apply(options: any = {}, impl: any = {}) {
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     fsImpl.writeFileSync(change.target, change._content ?? render({ content: '' }), 'utf8');
   }
-  for (const change of changes.filter((c: any) => c.projection?.renderer === 'antigravity-hooks')) {
+  for (const change of changes.filter((c     ) => c.projection?.renderer === 'antigravity-hooks')) {
     if (change.kind === 'copy-tree-file') continue;          // handled by runTreeChanges below
     if (change.operation === 'remove') {
       // Unmerge only DoFlow's groups (one per policy); a user's own hook groups survive.
@@ -502,11 +527,65 @@ function apply(options: any = {}, impl: any = {}) {
 // Removal flows through apply(): plan(context.operation='remove') emits operation:'remove'
 // changes, and the branches above already know how to execute each kind. The six-function
 // contract still requires the verb itself.
-function remove(options: any = {}, impl: any = {}) {
+function remove(options      = {}, impl      = {}) {
   return apply(options, impl);
 }
 
-function verify(options: any = {}, impl: any = {}) {
+/** The hook shims' bytes and the registered groups (project scope), as statuses and resources. */
+function verifyHooks({ options, paths, context, fsImpl }     ) {
+  const statuses        = [];
+  const resources        = [];
+  const hooksTarget = paths.hooksJson;
+  const scriptTargets                      = {
+    'pre-implementation-gate.sh': paths.hookScript,
+    'stop-check.sh': paths.stopHookScript,
+  };
+  // Source-side residue: reads the shims from THIS checkout (the authored source of the
+  // projection, not an install destination — the destination is declared as the paths above).
+  const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
+  const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
+  const fingerprints                      = {};
+  let scriptsOk = true;
+  let anyPresent = false;
+  for (const identity of HOOK_SCRIPTS) {
+    let sourceFp = null;
+    try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
+    fingerprints[identity] = sourceFp;
+    const target = scriptTargets[identity];
+    const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
+    if (current !== null) anyPresent = true;
+    if (current === null || current !== sourceFp) scriptsOk = false;
+  }
+  const doc = readJsonObject(hooksTarget, { fsImpl });
+  const gate = doc?.[HOOKS_GROUP];
+  const stop = doc?.[STOP_HOOKS_GROUP];
+  const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
+    && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
+    && gate.PreToolUse[0].matcher === GATE_MATCHER;
+  // Stop registration is matcher-free: handlers sit directly under the event key.
+  const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
+    && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
+  const groupsOk = gateOk && stopOk;
+  statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
+    removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
+      : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
+    ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
+  if (!removingOp && scriptsOk && groupsOk) {
+    resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
+      ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
+      fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
+      projection: { renderer: 'antigravity-hooks' } });
+    for (const identity of HOOK_SCRIPTS) {
+      resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
+        ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
+        kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
+        sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
+    }
+  }
+  return { statuses, resources };
+}
+
+function verify(options      = {}, impl      = {}) {
   const fsImpl = impl.fsImpl || fs;
   const context = options.context ?? {};
   const scope = options.scope ?? 'project';
@@ -564,68 +643,25 @@ function verify(options: any = {}, impl: any = {}) {
 
   // Hooks projection (project scope): the shims' bytes and the registered groups.
   if (scope === 'project') {
-    const hooksTarget = paths.hooksJson;
-    const scriptTargets: Record<string, any> = {
-      'pre-implementation-gate.sh': paths.hookScript,
-      'stop-check.sh': paths.stopHookScript,
-    };
-    // Source-side residue: reads the shims from THIS checkout (the authored source of the
-    // projection, not an install destination — the destination is declared as the paths above).
-    const scriptSourceDir = path.join(path.resolve(registryRepoRoot(options)), 'core', 'harnesses', 'antigravity', 'hooks');
-    const removingOp = (context.operation ?? options.operation ?? '') === 'remove';
-    const fingerprints: Record<string, any> = {};
-    let scriptsOk = true;
-    let anyPresent = false;
-    for (const identity of HOOK_SCRIPTS) {
-      let sourceFp = null;
-      try { sourceFp = sha256File(fsImpl, path.join(scriptSourceDir, identity)); } catch { /* checkout without that shim */ }
-      fingerprints[identity] = sourceFp;
-      const target = scriptTargets[identity];
-      const current = fsImpl.existsSync(target) ? sha256File(fsImpl, target) : null;
-      if (current !== null) anyPresent = true;
-      if (current === null || current !== sourceFp) scriptsOk = false;
-    }
-    const doc = readJsonObject(hooksTarget, { fsImpl });
-    const gate = doc?.[HOOKS_GROUP];
-    const stop = doc?.[STOP_HOOKS_GROUP];
-    const gateOk = Boolean(gate?.PreToolUse?.[0]?.hooks?.[0]?.command)
-      && gate.PreToolUse[0].hooks[0].command === scriptTargets['pre-implementation-gate.sh']
-      && gate.PreToolUse[0].matcher === GATE_MATCHER;
-    // Stop registration is matcher-free: handlers sit directly under the event key.
-    const stopOk = Array.isArray(stop?.Stop) && stop.Stop.length > 0
-      && stop.Stop[0]?.command === scriptTargets['stop-check.sh'];
-    const groupsOk = gateOk && stopOk;
-    statuses.push({ assetId: HOOKS_ASSET_ID, capability: 'hooks', status:
-      removingOp ? (!anyPresent && !groupsOk ? 'absent' : 'retained')
-        : (scriptsOk && groupsOk ? 'managed' : (!anyPresent && !groupsOk ? 'absent' : 'missing')),
-      ownershipIdentity: `${HARNESS}:hooks:registration`, target: hooksTarget });
-    if (!removingOp && scriptsOk && groupsOk) {
-      resources.push({ assetId: HOOKS_ASSET_ID, target: hooksTarget,
-        ownershipIdentity: `${HARNESS}:hooks:registration`, kind: 'hooks-json',
-        fingerprint: fingerprint(JSON.stringify(doc)), sourceVersion: 'registry-v1',
-        projection: { renderer: 'antigravity-hooks' } });
-      for (const identity of HOOK_SCRIPTS) {
-        resources.push({ assetId: HOOKS_ASSET_ID, target: scriptTargets[identity],
-          ownershipIdentity: `${HARNESS}:copy-tree:${HOOKS_ASSET_ID}:${identity}`,
-          kind: 'copy-tree-file', identity, fingerprint: fingerprints[identity],
-          sourceVersion: 'registry-v1', projection: { renderer: 'antigravity-hooks' } });
-      }
-    }
+    const hooks = verifyHooks({ options, paths, context, fsImpl });
+    statuses.push(...hooks.statuses);
+    resources.push(...hooks.resources);
   }
 
   const conflicts = [...statuses.filter((s) => s.status === 'conflict').map((s) => s.reason ?? s.identity), ...mcp.conflicts];
   return { ok: conflicts.length === 0, statuses, resources, conflicts };
 }
 
-function registryRepoRoot(options: any) {
+function registryRepoRoot(options     ) {
   return options.registry?.repoRoot ?? process.cwd();
 }
 
-function conflictsToStatuses(conflicts: any, assetId: any, statuses: any) {
+function conflictsToStatuses(conflicts     , assetId     , statuses     ) {
   for (const reason of conflicts) statuses.push({ assetId, capability: 'scripts', status: 'conflict', reason });
 }
 
 module.exports = {
   HARNESS, nativePaths: singleton.nativePaths, discover, render, plan, apply, remove, verify,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
   createAntigravityAdapter,
 };