jwc-global
  • Status: Proposed simplification.
  • Owner: Jon.
  • Scope: E:/hooks/depcruiser-migrations plus the kai-chattr research docs that describe it.
  • Rule: This page does not lock implementation decisions. It records a smaller direction for review before hook code is changed.

Short answer

The depcruiser workflow still needs an authored graph contract, but it does not need the V3 file explosion.

The first clean implementation can be a small hook package with:

  • one hook entrypoint
  • one worker CLI
  • one graph contract file
  • one state store
  • one path-scope helper
  • one closure verifier
  • one focused test file

The graph contract should be data, not a directory of one file per node. The runtime should be a few cohesive modules, not a plugin framework built before the first gate works.

Why this rail exists

The original depcruiser rail contains useful requirements, but the runtime inventory grew into a large architecture that is hard to build safely:

  • V1 listed a broad file inventory before the runtime existed.
  • V2 added browser capture and comparison, which expanded the graph further.
  • V3 removed browser automation but still retained separate nodes/, schemas/, lib/, scripts/, and tests/ inventories.

This simplified rail keeps the required behavior and removes premature decomposition.

Minimum behavior to preserve

The simplified runtime must still do the real work:

  1. The user invokes initialize-depcruiser-migrations.
  2. The worker checks donor and target package managers.
  3. The worker checks for dependency-cruiser in both repos and installs it only when missing.
  4. The worker generates the donor dependency-cruiser JSON trace.
  5. The worker generates a source manifest.
  6. The user approves the adjudicated port, adapter, cut, and target_extras decisions.
  7. The hook allows guarded target edits only after approval.
  8. The verifier runs target dependency-cruiser, tsc --noEmit, and strict reconcile.
  9. The user gives final closure approval.
  10. The runtime disarms the migration.

Browser verification can be a later extension. The first simplified graph is code-closure verified, not browser-parity verified.

Proposed P0 hook files

This implementation proposes to create the following hook-side file inventory:

E:/hooks/depcruiser-migrations/
  README.md
  dependency-cruiser.cjs
  depcruiser-migrations.mjs
  depcruiser-migrations-cli.mjs
  graph.contract.json
  generate-closure-manifest.mjs
  validate-closure-manifest.mjs
  verify-active-closure.mjs

  initialize-depcruiser-migrations/
    SKILL.md

  lib/
    path-scope.mjs
    state-store.mjs

  tests/
    depcruiser-migrations.test.mjs
FilePurpose
README.mdDocuments the hook bundle, operator workflow, local commands, and recovery behavior.
dependency-cruiser.cjsProvides the dependency-cruiser rules used by both donor and target verification.
depcruiser-migrations.mjsRuns the PreToolUse hook gate, reads active state, and permits or blocks guarded edits.
depcruiser-migrations-cli.mjsGives the worker the command surface for initialize, manifest generation, arm, verify, and disarm.
graph.contract.jsonStores the authored migration graph as data instead of scattering node files.
generate-closure-manifest.mjsConverts dependency-cruiser output into the source manifest used for adjudication.
validate-closure-manifest.mjsPerforms strict reconcile checks against approved port, adapter, cut, and target_extras decisions.
verify-active-closure.mjsRuns target dependency-cruiser, typecheck, and manifest closure verification before final approval.
initialize-depcruiser-migrations/SKILL.mdDescribes the worker-first workflow and tells the agent which CLI commands to run first.
lib/path-scope.mjsParses edit paths, including apply_patch, and enforces guarded prefixes and files.
lib/state-store.mjsOwns atomic .state reads, writes, event appends, and active migration validation.
tests/depcruiser-migrations.test.mjsCovers the gate, path extraction, state transitions, and strict reconcile behavior.

This is enough to build the first runtime. Add more files only when behavior becomes too large to maintain in these modules.

State shape

Use .state first:

E:/hooks/.state/depcruiser-migrations/
  active.json
  events.jsonl

active.json is the current migration state. events.jsonl is the audit trail.

Do not add a database for P0 unless .state becomes insufficient. If a DB becomes necessary, use one state DB file:

E:/hooks/.state/depcruiser-migrations/runs.sqlite

Do not overload E:/hooks/_db/hooks.db with depcruiser run state. That DB is already the hook telemetry substrate.

Next page

See V3 Hooks-Aligned Runtime for the proposed P0 runtime, its state model, and its config/schema/quality-gate alignment.