reorganize-logic

Rebuild the design-contract layer of an existing project from the ground up,
with the code as the single source of truth. The old contracts are untrusted
context — compacted, read, then discarded as a source: the new contracts are
re-derived from the code, never copy-pasted from the legacy docs. Output is
three fresh artifacts (architecture diagram · structure diagram · explicit
interface definitions) plus a review-gated deletion manifest for the stale legacy.

The anchor (read first): a contract is only trustworthy once a runnable check
ties it back to the code. So every documented interface is cross-checked against
the code's public surface by scripts/verify_contracts.mjs, and the new contracts
are written before anything legacy is deleted. A contract the gate can't tie to
real code is a hallucination; the gate rejects it. The gate flags everything
ambiguous for you to reconcile — it never rubber-stamps — and it never rules on
design intent: whether an excluded symbol is really internal is judged by a fresh
reader against the code, not by the gate.

When this fires (vs neat — the key boundary)

• reorganize-logic = deliberate, heavyweight, ground-up REBUILD. Old contracts
  are untrusted; deleting legacy is a feature. Use when docs have drifted so far
  that syncing is not worth it.
• neat = incremental sync at session end; keeps what's right, fixes drift,
  non-destructive. Route there for "tidy up / sync the docs / 同步一下".

If the docs are mostly right → neat. If you'd rather throw them out and
re-derive from code → this skill.

Orchestration (the gate stays portable)

The gate is deterministic node (runs anywhere, CI included). The judged work —
derivation, synthesis, faithfulness, exclusion verdicts — runs like this:

• Fan out the derivation. An Explore subagent maps entry points, then one
  derivation subagent per module in parallel returns its surface + responsibilities.
• Derivers and readers are non-fork. Spawn every derivation and fresh-reader
  subagent as a fresh subagent that starts from only the prompt you give it — not a
  fork of your context, which inherits the legacy docs and your draft. If the host
  only offers forking, use a separate claude -p session. The reply says how
  isolation was achieved (a self-report, not an enforcement).
• Raise effort, don't pad. If a contract reads shallow, raise effort for the
  running model rather than padding the prompt; effort names are not equivalent
  across models.
• Survive compaction from disk. After a compaction, re-read the on-disk artifacts
  (_legacy-context.md, the contracts written so far, _exclusion-review.md) AND
  this skill's Controls — a summary may have evicted a standing constraint.
• Walk every entry point. The coverage gate and the readers enumerate the
  surface; they never sample it.

Protocol

Preflight: confirm REBUILD (not sync), resolve scope (whole project | a named
module/dir). Then the 6 steps (detail in references/protocol.md):

1. Compact old contracts → read-only, gitignored docs/contracts/_legacy-context.md
   headed "CONTEXT ONLY — DO NOT COPY".
2. Re-derive from the code — read structure + public surface; build a fresh
   model. Code wins every disagreement. No copying from legacy.
3. Author docs/contracts/architecture.md — Mermaid architecture diagram +
   components/responsibilities/data+control flow/boundaries.
4. Author docs/contracts/structure.md (Mermaid + module map) and
   docs/contracts/interfaces.md in the strict gate-parseable format
   (references/contract-format.md).
5. Gate — node scripts/verify_contracts.mjs <root> [--scope <dir>]. FAIL and
   FLAG block: fix every FAIL, reconcile every FLAG (open the cited code, fix the
   contract, re-run). REVIEW lines don't block, but every STRONG_EXPORT_EXCLUDED
   item goes through the fresh-reader exclusion card before you report. A line
   clearable only by an untrue statement or by editing code/the gate, one surviving
   two fix attempts, or a language with no matcher → escalate (protocol step 5).
6. Emit docs/contracts/deletion-manifest.md — stale legacy to delete/overwrite,
   one reason each. Never delete anything; the human approves and applies.

Verify (eat the dogfood)

Run the gate on the produced interfaces.md before reporting:

node scripts/verify_contracts.mjs <project-root> [--scope <subdir>]

A PASS with exit 0 is PASS (structural): the gate proves doc-vs-code
structure — not prose faithfulness, and not whether an excluded symbol is
really internal. Any FAIL [tag] / FLAG [tag] line means the contract is not yet
tied to the code — fix and re-run. The final word needs the fresh-reader pass
and the exclusion card verdicts (references/protocol.md): non-fork readers
check the diagrams, responsibilities and signatures against the code, and
adjudicate every STRONG_EXPORT_EXCLUDED item.

Controls

• Code is the only source of truth. Old contracts inform context, never content.
  No copy-paste from legacy into the new artifacts.
• Review-gated deletion. Write the new contracts first; emit the manifest; never
  delete/overwrite legacy without explicit human approval. Nothing is auto-deleted;
  git is the safety net.
• Strict gate, judged exclusions. Return contracts only after
  verify_contracts.mjs PASSes: FAIL and FLAG block. REVIEW items are adjudicated
  by a non-fork fresh reader with the exclusion card. The gate proves structure,
  not publicness. The reply names the gate command it ran (the shipped skill path).
• Never edit the checks mid-task. Never edit, patch, copy-modify, or run a
  modified copy of scripts/verify_contracts.mjs or evals/ during a user task.
  An unrecognized export form or unsupported language goes to the owner as a
  proposal (form, example line, file) — and the run escalates.
• No untrue contract for a green gate. Never write a contract statement you
  believe untrue, and never edit product code, to clear a gate line — escalate.
• These controls are a rule layer: no sandbox or hook ships; the host's permission
  mode is the only enforcement, git the recovery net.
• Scopable. Whole project by default; --scope <dir> for cheap re-runs;
  coverage is scoped accordingly.

Modules

Lifecycle

• version: see frontmatter metadata.version.
• Breaking change = any change to the gate's input format or the interfaces.md
  gate-parseable schema (downstream contracts must be re-authored).
• Rollback = git restore docs/contracts/; the deletion-manifest is never
  auto-applied, so a bad run leaves the legacy intact.
• Superseded by neat for the lighter keep-and-sync path.