Spec: M0 — Cut

[Sandstorm831]

Spec for M0: Cut. Cut from the milestone issue and its Starting context; no triage label per docs/agents/milestones.md. /to-tickets cuts tracer bullets from this under the Secant slicing rulebook.

Problem Statement

The repository still ships legacy DevFlow: a provider-agnostic orchestrator built on PTY control and node-pty, hook sockets, JSONL session-log tailing, scoped provider homes, repo-local .devflow/ JSONL state, and a fixed six-stage pipeline. Every one of those mechanisms is now contradicted by a settled target decision, and the target product has a new name, Secant. Nothing depends on the legacy code: there is no user, no published package, and no compatibility obligation.

Keeping legacy alive while Crucible (the target model, shipping as Secant) grows would force throwaway translators between the Provider and Harness models, keep 539 Node 20 tests in a gate that must move to Node 24, and let target code be written under names that are already retired. Meanwhile the maintainer cannot start the first target slice, an AFK agent has no green three-OS gate to code against, the package still identifies as devflow-cli/devflow, and the Secant slicing rulebook that every later /to-spec and /to-tickets session must obey is not yet landed or policed.

Solution

Perform the slice-zero cut in a single, reviewable step so the repository stops being DevFlow and becomes an empty-but-green Secant ready to grow.

From the maintainer's and future agent's point of view, after M0:

• The legacy DevFlow implementation is gone at main, but readable forever at the legacy-devflow tag for any later slice that needs a mechanism as evidence.
• The package, binary, and all guidance identify as Secant, using the canonical identifiers from ADR 0028 (bin secant, npm @secantdev/secant), so no target code is ever written under the DevFlow or Crucible names.
• Running secant answers --help and --version from a stub, so the installed-package smoke passes even though no target behavior exists yet.
• The toolchain runs on Node 24, and the canonical npm run check is green on the three-OS matrix (Windows x64, macOS arm64, Linux x64) — the acceptance path for this and every later slice.
• The Secant slicing rulebook is landed as guidance and policed by the guidance-structure suite, so it is a live, checked contract rather than a comment on a ticket.
• No ADR link breaks: the two legacy cross-links are rewritten to the tag before deletion, and ADR numbering keeps its gap so every pinned link elsewhere stays valid.
• Nothing is published to npm.

User Stories

1. As the migrating maintainer, I want legacy DevFlow deleted in one commit, so that I start the target work from a clean tree instead of strangling code slice by slice.
2. As the migrating maintainer, I want the pre-cut tree tagged legacy-devflow, so that every deleted mechanism stays readable as evidence at a fixed point.
3. As a later slice author, I want deleted legacy code preserved only at the tag, so that I read a similar mechanism there and write fresh code against the target Interface rather than copying a legacy file into a target path.
4. As the migrating maintainer, I want every legacy runtime dependency removed, so that each library is re-earned by the slice that actually needs it under the built-ins-first runtime rule.
5. As the migrating maintainer, I want the legacy adapters, orchestrator, state, ledger, run summary, grill recorder, logger, project-root, and bootstrap deleted, so that no retired transport or Provider-era mechanism lingers in the tree.
6. As the migrating maintainer, I want prompts/, the tracked .agent/Progress.md, the provider integration checklist, and the legacy tests and fixtures deleted, so that no legacy authoring evidence is mistaken for a target input.
7. As a domain reader, I want the five legacy glossary clusters and the legacy section of CONTEXT.md removed, so that the glossary describes only the target Crucible/Secant model.
8. As a decision archivist, I want ADRs 0001 through 0017 deleted while the numbering gap is preserved, so that later ADRs and their commit-pinned links stay valid.
9. As the migrating maintainer, I want the toolchain configuration, gate scripts, CI workflow, architecture suite, and temp-dir test helper kept, so that the working verification machinery survives the cut.
10. As the migrating maintainer, I want the kept toolchain realigned to Node 24 in engines, Node types, the build target, and CI, so that the gate runs on the target runtime.
11. As the migrating maintainer, I want the legacyFiles set and the boundary checker's exemption branch removed rather than left empty, so that no residual legacy exemption remains once legacy is gone.
12. As an npm consumer eventually, I want the package renamed to @secantdev/secant, so that the scoped fallback name the pre-cut name-hold Task recorded is what M0 writes.
13. As a CLI user eventually, I want the binary renamed to secant, so that the command matches the product name.
14. As the migrating maintainer, I want CONTEXT.md, README.md, package.json identifiers, and agent guidance renamed to Secant, so that no target artifact carries the old identity.
15. As a package installer, I want a stub CLI that answers --help and --version, so that the installed-package smoke passes before any target command exists.
16. As a repository visitor, I want the README replaced with an in-development notice, so that nobody mistakes the empty tree for a usable tool.
17. As a release engineer, I want the single-OS check turned into the ADR 0027 three-OS matrix, so that every later slice must stay green on Windows, macOS, and Linux.
18. As a reviewer, I want the milestone green only on the three-OS matrix and never on "verified locally", so that CI is the sole acceptance path.
19. As a /to-spec and /to-tickets author, I want the Secant slicing rulebook landed as guidance, so that every later milestone's slices are cut under one written contract.
20. As the guidance-structure suite, I want the slicing rulebook indexed from the root agent guidance, so that the landed rulebook is mechanically policed like every other focused document.
21. As a decision reader, I want the relative cross-links in ADR 0020 (to ADR 0010) and ADR 0022 (to ADR 0011) rewritten to legacy-devflow-tag URLs before deletion, so that no link breaks once the legacy ADRs are gone.
22. As the migrating maintainer, I want the one wayfinder/guidance merge already on main and its single testing.md conflict already resolved by keeping both sections, so that no further merge work precedes the cut.
23. As the project lead, I want the organization/repository rename and the npm-name hold treated as a human Task performed before the cut, so that M0 only writes the name that Task recorded and does no registry work itself.
24. As an AFK agent starting a later slice, I want M0 to land before any target source, so that I code the first Module against a renamed, Node-24, three-OS-green baseline.
25. As a security-minded maintainer, I want nothing published from the cut commit, so that publishing stays behind the ADR 0027 release gate and ADR 0028's public-use gates.
26. As a reviewer, I want the cut to leave the target Module topology consistent after deletion and stub, so that the reserved paths and policy table still describe an internally coherent (if empty) architecture.
27. As the guidance-structure suite, I want CLAUDE.md to stay a one-line @AGENTS.md import and the root index under its line cap after the rename, so that the renamed guidance tree still passes structure checks.
28. As a later milestone curator, I want M0 closed only when every M0 ticket is closed, legacy is deleted, the rename is complete, the scoped npm name is written, the stub answers --help/--version, the rulebook is policed, and the matrix is green, so that the "Done when" contract is fully met before M1 opens.

Implementation Decisions

Ordering and boundaries

• M0 is the first implementation slice and lands before any target source. The only thing preceding the cut is the wayfinder/guidance merge, which is already on main at the pinned commit; its single docs/agents/testing.md conflict was resolved by keeping both the "Release Evidence" and "Recorded Harness Fixtures" sections, so no merge work remains in this milestone.
• The GitHub organization/repository rename and the npm-name hold are a human Task already performed before the cut (org and repo are secantdev/secant; the @secantdev/secant scope holds a 0.0.0 placeholder). M0 performs no registry work; it only writes the name the Task recorded.
• The cut is authored as one deletion+rename commit, preceded by the tag and the ADR link rewrites. Whether the link rewrites and the tag are separate commits or folded in is a /to-tickets slicing concern under the rulebook, not a spec decision; the invariant is that the tag captures the pre-cut tree and the link rewrites land before the legacy ADRs are removed.

Deletion (authority: ADR 0026 and the #20 legacy disposition table)

• Delete every path in the boundary checker's legacy list, the tests and fixtures that mirror them, prompts/, the tracked .agent/Progress.md, the five legacy glossary clusters plus the legacy section of CONTEXT.md, the provider integration checklist, ADRs 0001–0017, and every runtime dependency. The exhaustive path list is owned by ADR 0026 and the legacyFiles set at the tag; tickets read it there rather than from this spec.
• ADR numbering keeps its gap after 0001–0017 are removed, so later ADRs and pinned links stay valid.
• Disposition rule: legacy code is reused or deleted, never extracted. Reuse applies only to target-neutral baseline files (architecture suite, gate scripts, toolchain config, temp-dir helper). No legacy dependency is grandfathered.
• src/cli.ts is deleted and replaced by a stub entry; prompts/ is deleted and is explicitly not read as evidence for any later Bundle.

Kept and realigned (authority: ADR 0026, #20 disposition)

• Keep the toolchain configuration, gate scripts (run-tests.mjs, package-smoke.mjs), CI workflow, architecture suite (module-policy.ts, check-module-boundaries.ts, check-guidance-structure.ts and their tests), and the temp-dir test helper.
• Realign to Node 24 in the engines range, @types/node, the tsup build target, and the CI Node version. The exact Node 24 minimum minor and the floor-versus-pin shape are a spec/ticket detail to settle, not a new decision.
• Remove the legacyFiles set and the checker's exemption branch from the module policy; the boundary checker keeps its synthetic allowed/forbidden graphs and every other rule.

Rename (authority: ADR 0028, superseded by the 2026-09-07 npm-name amendment)

• Package name → @secantdev/secant; bin → secant; author/repository/homepage/bugs identifiers → the secantdev/secant shape. The npm name is the scoped fallback because the bare secant name, though unregistered, is blocked from publishing as too similar to recast.
• Rename CONTEXT.md, README.md, and agent guidance to Secant so no target artifact carries the DevFlow or Crucible name. The README becomes an in-development notice.
• Existing ADRs and closed tickets keep the historical working name Crucible and are not rewritten; a reader maps Crucible to Secant.
• Stub CLI: a single executable entry answering --help and --version only. It is the smoke target, not target behavior; its owning Module is src/cli/ per the topology, created by this slice because the smoke needs it.

CI gate (authority: ADR 0027)

• The former single-OS check.yml becomes a matrix over Windows x64, macOS arm64, and Linux x64 on one pinned Node 24 version, running npm ci then npm run check. A red job on any OS blocks merge. This is the gate M0 introduces and every later slice keeps green.
• The richer ADR 0027 evidence (real-terminal suite, installed-Harness runs, release environment, support matrix) is not M0 work; M0 introduces only the three-OS check matrix.

ADR link rewrites (authority: #20 amendment; fixed, do not reopen)

• Rewrite ADR 0020's relative link to ADR 0010 and ADR 0022's relative link to ADR 0011 to legacy-devflow-tag URLs before the deletion, so both resolve after the legacy ADRs are removed. ADR 0022's link to ADR 0018 stays relative (0018 is kept).

Guidance (authority: #20 rulebook, #25 guidance resolution)

• Land the Secant slicing rulebook as docs/agents/slicing.md and index it from the root AGENTS.md so the guidance-structure suite polices it. Its content is the eight-rule rulebook fixed in the Sequence vertical slices, refactoring gates, and legacy deletion #20 resolution (both clients; CI is the acceptance path; no scaffolding; the Owner:/Ratchet:/Deletes:/Gate:/Dependencies: packet lines; Bundles exercised not fixtured; no branching on workflow identity; TUI slices copy the Prototype Crucible's launch and Run information architecture #23 deferred items; publish without ready-for-agent).
• The document must satisfy the structure suite: focused-doc line cap (≤120), 175-column prose wrap, resolving links, and a resolving backticked reference from the root index; the root index stays ≤60 lines and CLAUDE.md stays the @AGENTS.md import.

Testing Decisions

• What a good test is here. M0 introduces no target production behavior, so its tests observe only external, durable facts of the cut: the installed package answers --help/--version, the guidance tree obeys its declared structure, the import-boundary checker still works with no legacy exemption, and the whole gate builds and passes on three operating systems. No test asserts an implementation detail of a soon-to-arrive Module, because none exists yet.
• One seam. The single acceptance seam is the canonical npm run check gate run on the ADR 0027 three-OS matrix. "Verified locally" is explicitly not acceptance (rulebook rule 2). No new production Module seam is introduced; target source and its seams arrive in M1+.
• Existing sub-suites observe the deliverables (reused, not new):
  • The package smoke (scripts/package-smoke.mjs) installs the packed archive under a temporary global prefix and runs the installed secant command — this observes the rename of package/bin and the stub's --help/--version. Prior art: it is the current smoke, retained and realigned to Node 24.
  • The guidance-structure suite (tests/architecture/guidance-structure.test.ts over check-guidance-structure.ts) observes that slicing.md is landed and indexed, that testing.md carries both merged sections, that ADR 0020/0022 links resolve, that the root index is ≤60 lines, and that CLAUDE.md is the import. Prior art: the eight existing structure tests.
  • The module-boundaries suite (tests/architecture/module-boundaries.test.ts over check-module-boundaries.ts and module-policy.ts) observes that the legacy list and exemption branch are gone while the synthetic allowed/forbidden graphs still pass. Prior art: the existing boundary suite and its synthetic graphs.
  • Typecheck and build on the Node 24 target observe the toolchain realignment.
• Modules tested. None of the target domain Modules — they do not exist in M0. Only the architecture/guidance suites, the package smoke, and the build are exercised, all pre-existing seams reused across the cut.
• The temp-dir test helper is kept and reused by the structure tests; no new test infrastructure is introduced by M0.

Out of Scope

• Any target production Module or behavior (Renderer Port, presentation subset, Workspace approval, Run Store, execution, step kinds, Harness Adapters, Projection Port). These begin in M1 and later.
• The organization/repository rename and the npm-name hold themselves — a human Task already completed before the cut. M0 only writes the recorded name.
• Publishing anything to npm, and the rest of the ADR 0027 release machinery: the real-terminal suite, installed-Harness runs, the release environment, scripts/release-checks/, the per-release checklist, docs/support-matrix.md, and THIRD-PARTY-NOTICES.md (M1/M4).
• Reopening the two ADR link rewrites (fixed by the Sequence vertical slices, refactoring gates, and legacy deletion #20 amendment) or any settled ADR (0025–0028) or the milestone spine.
• Rewriting the historical working name Crucible in existing ADRs and closed tickets.
• The exact Node 24 minimum minor and floor-versus-pin shape are a ticket-level detail to settle within M0, not re-litigated as a decision here.
• node-pty returning as a devDependency for the real-terminal suite — that is M1, not M0.

Further Notes

• Authority order. Where any source disagrees, an ADR at HEAD supersedes ticket wording; the Sequence vertical slices, refactoring gates, and legacy deletion #20 resolution and its two 2026-09-07 amendments supersede the resolution text where they differ. The npm package name is @secantdev/secant (latest amendment), superseding the earlier hyphenated @secant-dev/secant.
• Starting context is pinned at e02c919 on main. The guidance branch the spine named as an M0 input is already merged and lives at that pin.
• Green ≠ implemented. A green three-OS check after M0 proves the cut, the rename, the stub, and the policed rulebook — it does not claim the target architecture exists. The reserved topology paths are intentionally absent; synthetic graphs prove the boundary checker works before production arrives.
• Reading rule (from the milestone's Starting context): read ADR 0026 for what the cut removes and ADR 0028 for what it renames, then the Sequence vertical slices, refactoring gates, and legacy deletion #20 rename order for the recorded npm name and link-rewrite steps, and the Sequence vertical slices, refactoring gates, and legacy deletion #20 slicing rulebook for what to land as guidance. Everything else the map already settled.
• Next step: a /to-tickets session cuts tracer bullets from this spec under the slicing rulebook, publishes them as sub-issues of M0: Cut #43 with native blocking edges, and leaves them without ready-for-agent until each packet exists.