@ybotok/loam 0.0.0 → 0.1.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable project changes are recorded here. The format follows Keep a Changelog, and release versions follow Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0-beta.2] - 2026-08-07
+
+Still a prerelease, still under the `beta` dist-tag: the 5–10 service pilot has not run yet, and this release changes what `loam init` leaves in a repository, which is exactly the kind of thing a pilot is for. Two new commands, that change to the generated files, and a code-quality pass over `src/` with the defects it turned up. The refactoring half is invisible by construction; what follows is only the part a user can observe.
+
+### Added
+
+- **`loam explore [<service>...]`** — read the fleet around a change nobody has written down yet, and write nothing. It answers the one question `loam new` takes as an argument: which services a feature touches. For each seed it reports the ring one hop out in the fleet map, each service's maturity rung and living operations, who already calls whom, the active features already covering the same services, and the literal `loam new` line the seeds imply. `--op <operationId>` seeds from an operation when you know the call but not who owns it; `--as <FEAT>` names the feature in the suggested line. A seed naming no `services/<id>/` is reported with its near-misses rather than refused — a feature may be introducing that service, and a typo looks identical until you read the list. The neighbours are deliberately **not** folded into the suggested command: loam knows those services are connected, not whether you change them.
+- **`loam instructions [<workflow>] [args...]`** — print one of the six workflow protocols (`loam-adopt`, `loam-feature`, `loam-implement`, `loam-check`, `loam-verify`, `loam-ship`) with `$1`, `$2` filled in from the arguments given. With no argument it lists them. It is the only command that reads no `loam.json` and no docs repo, deliberately: `loam-adopt`'s own first step is to run `loam init` when there is no config, so it cannot be the step that requires one.
+- **[WORKFLOW.md](WORKFLOW.md)** — the working protocol as a document: the artifact graph and its five derived states, what actually gates and what only advises, the six workflows, how an agent drives the cycle from `--json`, and why there is no task-list artifact.
+
+### Changed — what `loam init` writes into a command or skill file
+
+- **A generated file is now a pointer at `loam instructions`, not a copy of the protocol.** It carries the workflow's purpose and its spine — the verbs, in order — and defers this release's flags, finding codes and fix tables to the binary; a fresh `.claude/commands/` drops from about 53 KB to about 11 KB, and the finding-code tables move with it. The protocol itself is unchanged and complete; only its delivery moved. The reason is that the two go stale in opposite directions and only one is fixable: loam never regenerates a generated file (your edits outrank the template, and that is not changing), so a protocol copied into a repository will eventually describe a different loam with total confidence, while a pointer cannot. `doctor.agent-files-stale` still reports a file whose version stamp has fallen behind, and now has almost nothing to be wrong about.
+- **Nothing rewrites an existing file.** A repository scaffolded by an earlier loam keeps exactly the files it was given, full protocol text and all — re-running `loam init` over it leaves them byte-unchanged. The version stamp is how you tell, and `loam doctor` raises `doctor.agent-files-stale` against them only once this binary's stamp is ahead of theirs. To take the new form, delete the files and re-run `loam init`.
+- Both new commands reuse the existing refusal codes (`invalid-option`, `unknown-target`). No stable code was added, changed or removed.
+- **The feature-id grammar has one home.** It was spelled privately in `loam new` and again in the OpenSpec migration; `core/ids.ts` owns it now, so an id one command accepts cannot be an id the other refuses. The only user-visible edge is wording: `migrate-openspec`'s `mapping.feature-id-invalid` message now ends with the same "e.g. FEAT-101 or BUG-42" example every other refusal gives. The code is unchanged.
+
+### Fixed — commands that wrote or attested on evidence they had not checked
+
+- **`archive` no longer installs an unreadable feature contract as the living one.** A feature `openapi.yaml` that does not parse as an OpenAPI document was planned verbatim into `services/<svc>/openapi.yaml` and reported `ok: true`; every other command reads `readOpenapi`'s `unreadable` flag, and the one that writes was the one that did not. It now refuses with `merge-failed`, naming the file. The same code now answers when the contract is being created rather than merged — that case used to escape as `internal`.
+- **`verify --record` no longer attests when it could not check the report.** The committed-report binding check tested for git's exit code 1 and nothing else, so a `git diff` killed by a signal — a CI timeout, the OOM killer, a fork failure — skipped the check and wrote the attestation anyway. A run that cannot reach an exit status is now a refusal that says git could not be run to completion.
+- **An interrupted `archive` can be retried on a docs repo composed of symlinks.** Checking whether the snapshot was stale resolved the manifest's paths through a symlink test meant for writes, so a `services/<svc>/` mounted from a sibling checkout — a layout every walk of the repo follows on purpose — turned every retry into a permanent refusal. That check only reads a file and compares a digest; containment is now judged without resolving the mount. `unarchive`, which writes the pre-image back, deliberately keeps the stricter test.
+- **A malformed `.loam-before/manifest.json` or `.loam-lock` is answered, not assumed.** Both were read through a cast: well-formed JSON that was not an object slipped past as "a different loam", and a bare `null` threw a `TypeError` out of the refusal itself. They now answer `commit-interrupted` and `docs-busy` respectively — the codes that case always deserved.
+- **A `spec.md` whose bytes are UTF-16LE is refused on the write path.** The write path's UTF-8 guard was a weaker copy of the read path's and missed exactly the file the read path had been hardened against: such a document parsed as zero requirements, so a merge computed over an empty baseline and wrote that back.
+
+### Fixed — user errors reported as `internal`
+
+- **`list`, `show` and `validate` report `repository-unavailable`** where a filesystem failure carries no path — a directory where `spec.md` belongs reports EISDIR with no `path`, which defeated the guard. `status` had this fix; the other three copies of the same catch block did not.
+- **`loam.json` that cannot be read reports `config-invalid`.** The read sat one line above its own `try`, so a config file that was a directory, or carried a restrictive permission bit, crashed every command in the CLI.
+- **`loam new` refuses instead of scaffolding into a directory that is not a docs repo**, and **`loam adopt` refuses (`docs-missing`)** instead of briefing an agent to write a baseline into a docs repo that does not exist. Both previously exited 0.
+
+### Fixed — checks that answered differently depending on where they were asked
+
+- **A relocated operation grades the same under `validate`, `status` and `archive`.** `FleetContext` carried a second implementation of `serviceOperationIds` that interleaved removals with upserts, so an operation removed at one path and defined at another answered "undefined" or "defined" depending on which the author spelled first — and `spec-api.op-undefined` is a gating error.
+- **`c4.op-ungoverned` joins per service.** Operation ids are unique only within a contract, so an operation governed on one service suppressed the warning for an unrelated service that shared its name.
+- **`api.covered` no longer counts a REMOVED requirement as governing.** An operation whose only governing requirement was removed now reports `api.ungoverned` (a warning; nothing about gating or exit codes changes).
+- **`loam status` (fleet form) reports `blocked` for a repo holding an interrupted commit journal**, agreeing with the per-feature form, which already did. It previously said `done` and "ship it" over a tree the other form called blocked.
+- **`loam delta` exits 1 when the feature's `openapi.yaml` does not parse**, matching the rule the architecture axis already had, and its `--json` payload carries an `openapi` key saying so. An unparseable contract used to project as "no operations".
+
+### Fixed — deletion that reached outside the repository
+
+- **`loam gherkin` orphan cleanup no longer follows a symlinked directory out of the repo.** Enumeration follows symlinks by design, so a planted `<gherkinDir>/loam/sub -> /outside` produced orphan paths that `unlink` resolved and deleted elsewhere. A symlinked `.feature` sitting directly in `loam/` is still removed — the link goes, its target survives — which is the distinction the guard now draws.
+
+### Changed — internal structure
+
+No behaviour depends on this, and it is recorded because the next contributor will notice it: the eight runtime import cycles in `src/core/` are gone, five helper modules were extracted from the modules that happened to hold them (`document-bytes`, `records`, `steps`, `concurrency`, and the docs-repo gate), and the duplicated spellings of six shared rules now have one home each. `docs/CODE-STYLE.md` records the conventions and the defect behind each one.
+
+## [0.1.0-beta.1] - 2026-08-06
+
+The first published release, and a prerelease on purpose: it ships under the `beta` dist-tag, not `latest`. This entry covers the pre-publication hardening pass. Most of it is not new capability — it is the difference between a command that reports a problem and one that was quietly blind to it, and in four places it is the difference between an undo that works and one that certifies text nobody wrote. Grouped by what a user would notice.
+
+### Fixed — data loss and silent failure
+
+- **A file whose bytes are not UTF-8 is no longer rewritten.** The whole write path moves bytes rather than strings; text is produced only where a parser needs it. Undecodable content refuses the merge (`merge-failed`, naming the file) instead of replacing every such byte with U+FFFD — in the living document *and* in the snapshot meant to undo it, which left nothing to restore from. A non-UTF-8 `openapi.yaml` now grades `openapi.invalid` instead of being handed to the YAML parser with the damage already done.
+- **`unarchive` no longer restores an edited snapshot and certifies it.** The snapshot manifest is version 2: every entry records `before`, a sha256 of the pre-image it will restore, alongside the existing `after`. `unarchive` hashes each pre-image before staging anything and refuses on a mismatch (`snapshot-corrupt`) — and `--force` deliberately does not override it, because `--force` discards later changes to the living docs while the damage here is to the undo itself. A version-1 snapshot is refused as `snapshot-missing`.
+- **A commit killed halfway can now be repaired.** `archive` and `unarchive` fsync an intent journal (`.loam-commit`) before the first swap and recover from it on the next run, under the lock: an archive is undone, an unarchive is finished (the merged text it was replacing is recorded nowhere else). Where the files no longer permit a safe repair the answer is `commit-interrupted`, a refusal. Previously a SIGKILL between two renames left a half-merged repo that `doctor` called healthy, `validate` blamed on the author's delta, and nothing could roll back.
+- **A removal marker can no longer be published into a living contract.** `x-loam-remove` written at path level, beside the methods, names no operation and retires nothing; `archive` gates it (`openapi.remove-marker-path-level`) and the marker is stripped from every merge branch, so it never reaches the fleet's living OpenAPI under any flag.
+- **Symlinked service and feature directories are enumerated.** A `services/<svc>` or `features/<FEAT>` reached through a symlink used to vanish from every listing, which also produced a false `landscape.binding-unknown` for the service that was right there. Dangling links are skipped exactly as an absent directory is.
+
+### Fixed — checks that were blind
+
+- **Nested landscape elements are graded.** The landscape cross-check kept only top-level elements, so ordinary grouped C4 — services under an `enterprise`, `group` or `boundary` — reported *every* service as unmodelled. The tree is walked instead: an element is at service level when no ancestor already stands for a service, an element that contains a service is a grouping, and `landscape.binding-unknown` is now graded at any depth.
+- **A missing `openapi.yaml` no longer silences the API axis.** It is an **error** when a living non-`REMOVED` `Operations:` line or an op-linked landscape edge already points into the absent file, with the stranded operationIds in `details`; a warning when nothing does and the landscape cannot prove nobody calls the service; silent when it can. Correspondingly, one absent contract is one finding rather than one `spine.op-undefined` per inbound consumer — a file that is not there proves nothing about an edge.
+- **A feature delta addressed to a nonexistent service is refused** (`delta.service-unknown`, naming close ids). A typo in `--touches` used to validate green and materialise a phantom service directory on archive.
+- **`openapi.duplicate-operationid` fires in service scope**, not only through an unrelated feature's delta — so `validate --all` sees it on a fleet with no feature in flight.
+- **`c4.uncovered` no longer fires on a re-declared edge.** A delta that restates a living edge to hang a requirement on it was told to write a decorative architecture requirement.
+- **`loam doctor` reports what it could not see before**: a held or stale `.loam-lock`, an interrupted commit, orphaned staging temp files, and generated command/skill files that have fallen behind (below).
+
+### Changed — verification says which answers came from a test run
+
+`--record` may still confirm a `scenario.tested` claim on an agent's word; a service with no runnable suite yet has to be able to record its answers. What changed is that the record now says so, everywhere:
+
+- a three-valued **`verdict`** — `verified`, `attested`, `unverified` — recomputed from `claims[]` on every read and never taken from the record's own `summary:` block. `verified` in `--json` is exactly `verdict === "verified"`, so a record with zero claims no longer reads as verified by arithmetic;
+- `verify.scenario-attested` (warning, gating nothing) naming each claim, on the read view, the recording view and the frozen post-archive view alike; `loam status` re-reports it and offers `next.verify-attested`, and such a feature reaches `stage: ready`, never `done`;
+- a `summary:` block contradicting its own `claims[]` makes the whole record `record-unreadable` (`verify.record-miscounted`) — neither half can be believed, so neither is reported as fact;
+- `--results` writes down **which report it read** (path, sha256, mtime, tagged-scenario count), must resolve inside the attesting repository in federated mode, and refuses a committed report that differs from the attested commit. That says which file was consumed; it does not say the file came from executing that commit, and no digest can;
+- two services wording a scenario identically share one digest, so a single report cannot say whose suite ran it: those claims are left unconfirmed under `verify.digest-contested` rather than confirming both.
+
+### Changed — `loam status` is a projection over the gates
+
+`status` used to say "ship it" on trees `archive` refused. It now takes `stage` and `next[]` from the union of what `validate --feature` errors on and what `archive` refuses to merge, so it may be more pessimistic than either and is never greener than both — an invariant with a test behind it. Also: `checks.coherent` runs the same functions `validate` does (coherence, provenance, missing scenarios); `owesContract` keys on the contract *file* rather than the service directory; `next[]` names `loam delta`, `loam gherkin` and `loam rebase`; the fleet form is capped at ten steps plus a `next.elided` notice and always ends on `next.fleet-gate`; and a filesystem failure that carries no path (a directory where a file belongs) is reported rather than crashing the command.
+
+### Changed — generated agent files carry a version stamp
+
+Every generated command and skill body now opens with `<!-- generated by loam vX.Y.Z -->`, and `loam doctor` raises `doctor.agent-files-stale` for a file with no stamp or an older one. loam still never rewrites a generated file — the fix is a human's — but drift is now detectable, which it previously was not: a command file mangled to one line left `doctor: healthy: true`. Doctor also stops reporting a repo initialized `--no-skills` as missing its skills.
+
+`loam rebase` and `loam status` were added to the shipped workflow bodies, which is where the mechanism that prevents two in-flight features from overwriting each other actually gets run. `doctor`'s fix line now spells `loam adopt --service <id>`; the positional form it used to print is refused by the CLI, and a new test parses every command loam prints against the real CLI so that class of defect cannot return silently.
+
+### Changed — `loam init` keeps the pointer it was given
+
+`--docs` wins only when it is actually passed. A re-run in a wired repository keeps the `docsDir` its committed `loam.json` already names, `--create` included, and spreads the rest of the config forward; `--json` reports `docsDirSource` as `flag`, `config` or `default`. Following `doctor`'s advice to re-run `init` used to repoint the repo at an empty decoy over which `validate --all` went green.
+
+### Fixed — the OpenSpec on-ramp
+
+- **A Store checkout is audited by its planning shape, not by its marker.** A `.openspec-store/store.yaml` beside real `specs/` used to make audit look for `<checkout>/openspec`, find nothing, and report `ready: true, capabilities: 0` — then apply a target holding no requirements at all. The shape picks the root; the marker picks only the kind; a checkout with planning content in neither place is refused by name.
+- **A workspace nobody could read is never `ready`** (`openspec.workspace-empty`).
+- New blockers for shapes that silently migrated nothing: `openspec.change-quoted-requirements` (requirements under `## Requirements` inside an active delta — the shape OpenSpec's own living template mandates, which stages nothing in a change), `openspec.nonstandard-living-spec` (markdown under `specs/` named neither `spec.md` nor `design.md`), `openspec.hidden-change-directory` (a dot-prefixed directory under `changes/`, which enumeration skips).
+- **The source digest no longer covers archived changes.** Frozen history never gates, so it must not be able to invalidate a completed mapping either; a living or active edit still does.
+- **The staged target is a real docs repo** — its own `loam.json`, `AGENTS.md` and an empty `architecture/landscape.likec4` — so `FOLLOW-UP.md`'s instructions run where they are written, and `FOLLOW-UP.md` now ends with the cutover procedure: `services/` and `features/` move, everything else is review residue.
+- **A target inside a live loam fleet is refused**, instead of producing phantom features in every `loam list`.
+- The living capability tree is copied verbatim under `legacy/openspec/specs/`, so `## Purpose` prose, section prose and capability `design.md` are preserved rather than dropped; an ISO-8601 `created` timestamp is a valid date; fenced FROM/TO examples inside a `## RENAMED Requirements` block are no longer parsed as renames; and a rename's TO name no longer demands a service allocation the router never asks for.
+
+### Performance
+
+`loam list` and `loam validate --service` are now flat in landscape edge count: loam reads LikeC4's parsed model and never computes a view, which it had no use for. On a generated 120-service fleet the same commands previously did not finish above roughly 200 edges. Measured at 120 services and 400/800 edges on an 8-core laptop: `list --json` 1.1–1.5 s, `validate --service <id> --json` 1.4–1.6 s. `loam init` no longer scaffolds a `views { view index { include * } }` block it never reads.
+
+`loam validate --all` remains ~30 s on that fleet — it parses a fresh LikeC4 workspace per service — and no speedup is claimed for it. Its target loop is now a bounded pool rather than a serial `await`, which is byte-for-byte output-identical and deterministic in ordering, but measured as a wash on the hardware available; the lever that moved this command was the parsed model, not the loop shape.
+
+### Fixed — release engineering
+
+- The CI `package` job could never pass: `release-check.mjs` refused `--fixture-ready` whenever `GITHUB_ACTIONS` was set. The guard now keys on a tag ref, which is what it was actually protecting against. Any claim that CI had validated release readiness was false before this.
+- `npm run test:package` failed against the current tarball — the smoke test called `loam init --docs docs` without `--create`.
+- Five release scripts spawned `npm.cmd`/`loam.cmd` without a shell, which Node ≥ 20.12 rejects on Windows; they now resolve npm's CLI and run it through `process.execPath`. Windows itself is unexercised here — there is no Windows host — so this is verified structurally and by the first real CI run.
+- `pack-release` and `verify-release-artifact` compared an unpeeled `GITHUB_SHA` against `HEAD`, so an annotated or signed tag — the `npm version` and `git tag -a/-s` default — could never pass. Both peel now; `git tag -s v<version>` works.
+- Release artifact retention raised 1 → 14 days, so a candidate awaiting human approval outlives a weekend; CI narrowed to pushes on `main` with a concurrency group, so tags no longer run both workflows in parallel.
+
+### Documentation
+
+README, COMPARISON, SCHEMA and MIGRATING were re-checked claim by claim against the code and against upstream OpenSpec live on 2026-08-05. Corrected: the documented migration entry point (`migrate-openspec <root>` returns `invalid-option`; `audit-openspec` is the real first step and appeared nowhere in the README), the corpus and test counts, the `--baseline` flag the reproduction recipe needs, the Executability and agent-surface comparison rows, and the claim that OpenSpec has no multi-repo story — Stores shipped in v1.5.0, and the honest argument is their documented "No sync, ever — by design" plus the absence of any lockfile or commit pin. Removed: the argument that upstream's generated instructions are broken, which upstream fixed inside 48 hours and which loam had in its own surface.
+
+### Added
+
+- A tag-driven npm release gate using GitHub OIDC trusted publishing and provenance.
+- A reproducible two-fleet pilot harness and scorecard contract.
+
+### Changed
+
+- The supported runtime now matches the direct LikeC4 dependency: Node.js 22.22.3 or newer.
+
+## Upgrading to this release
+
+Nothing to upgrade from — this is the first published version. One note for a repository initialized from a pre-release build: the first `loam doctor` after installing this one reports `doctor.agent-files-stale` for **every** generated command and skill file. Earlier builds wrote no version stamp, so "no stamp" and "an old stamp" are indistinguishable, and loam refuses to assume the instructions on disk describe this binary. Read each file, then bump its stamp by hand, or delete it and re-run `loam init` — the drift is reported and never repaired for you.

package/COMPARISON.md

@@ -0,0 +1,63 @@
+# loam vs OpenSpec
+
+loam reimplements part of [OpenSpec](https://github.com/Fission-AI/OpenSpec)'s requirement format from the outside and deliberately makes different workflow choices — [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) covers the mechanics of moving a repo. Released behavior below is pinned to **OpenSpec v1.7.0**, exact commit `4e16790d90d8f54d4773ad9a5e71a57cd9f1e86b` — still the latest release and the latest tag as of 2026-08-05. The separate **main canary** is pinned to `45cca5db6137ed209117cc70510eb3e057fb981b`; it is not mislabeled as the release, and it is deliberately a *historical* pin rather than a moving target — upstream merged 21 commits to `main` in the five days after that SHA was taken, so a pin that chased `main` would be stale before anyone read it. What the canary buys is a second reproducible corpus, and its totals have not moved since. Routine CI runs [`test/openspec-compat.test.ts`](test/openspec-compat.test.ts) over seven representative, verbatim fixtures. A scheduled/manual matrix clones both exact commits and checks the full living + active + archived spec corpus: release 207 files / 739 requirements / 2273 scenarios, canary 209 / 742 / 2284. Reproduce either with `npm run test:openspec-corpus -- --baseline release|canary /path/to/OpenSpec` — the flag is not optional in practice, because it defaults to `canary` and the sweep refuses a checkout at any other HEAD.
+
+**Every upstream statement below was re-checked against the live repository and the GitHub API on 2026-08-05.** Where a comparison loam used to make no longer holds, it has been removed rather than softened; those are noted where they mattered.
+
+Primary upstream references: [v1.7.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.7.0), [workflow](https://github.com/Fission-AI/OpenSpec/blob/v1.7.0/docs/workflows.md), [concepts](https://github.com/Fission-AI/OpenSpec/blob/v1.7.0/docs/concepts.md), [default schema](https://github.com/Fission-AI/OpenSpec/blob/v1.7.0/schemas/spec-driven/schema.yaml), [Stores](https://github.com/Fission-AI/OpenSpec/blob/v1.7.0/docs/stores-beta/user-guide.md), and the [derived artifact-state implementation](https://github.com/Fission-AI/OpenSpec/blob/45cca5db6137ed209117cc70510eb3e057fb981b/src/core/artifact-graph/state.ts).
+
+## The one-paragraph verdict
+
+OpenSpec v1.7.0 is the lower-friction choice for planning and evolving behavior in a repository. Its action-oriented workflow includes explore, propose, apply, update, early spec sync, verify and archive; nested capability folders and `skip_specs: true` cover domain hierarchies and changes with no behavior delta. It also has beta Stores for Git-owned planning roots and read-only references, configurable artifact graphs, broad agent-tool integrations, and `RENAMED` requirements. loam targets a narrower fleet problem: it persists a **trust chain** (`sources` → content digests → human `vouch`), puts a **C4 service topology at the center**, joins behavior, architecture, and OpenAPI through one ID spine, and can accept scenario evidence from a real Cucumber run. That additional structure costs setup and concepts, and loam's ecosystem and release history are much younger.
+
+## Seven axes
+
+| Axis | OpenSpec | loam |
+|---|---|---|
+| **System model** | Capability-oriented specs. Beta Stores place shared planning in a separate Git repo, but do not define service elements, relationships, or deployment views. | C4 landscape ([LikeC4](https://likec4.dev)) at the center; behavior spec, architecture spec, and OpenAPI joined by `FEAT-*`, service id, C4 element id, and `operationId`. |
+| **Change workflow** | Fluid actions rather than fixed phases: explore/propose/apply/update/sync/verify/archive. Artifact status is derived from generated-file existence in a configurable dependency graph. Archive prepares and validates all target specs before sequential writes and supports already-synced no-ops, `RENAMED`, nested specs and spec-less changes. | Three-axis merge across requirements, OpenAPI, and landscape. The plan is computed first, gated for cross-axis coherence, staged, snapshotted, and rolled back if a write fails; `unarchive` restores recorded bytes. |
+| **Implementation evidence** | `/opsx:verify` instructs the active coding agent to search code and tests for completeness, correctness, and coherence. It is useful but advisory and its conclusions depend on that run. The direction of travel is deeper *deliberative* verification: open PR [#1373](https://github.com/Fission-AI/OpenSpec/pull/1373) adds a fourth verify dimension whose own description says it reports evidence-backed warnings for human review, and does not block. | `loam verify` derives stable claims. Agent answers carry `file:line` evidence. A scenario claim is confirmed **mechanically** by a digest-matched green Cucumber run, and an agent may confirm one too — but the record then reads `verdict: "attested"`, not `verified`, and says so on every surface (`verify.scenario-attested`). The distinction is the point: loam does not claim agent answers are impossible, it claims they are *distinguishable*. |
+| **Drift control** | CLI validation checks planning structure. Agent-led verify can find implementation drift on demand. There is no persisted attestation of any kind: `git grep -lE 'createHash\|sha256\|checksum' -- src` returns nothing at either baseline, so nothing written today can be compared mechanically against anything tomorrow. | `sources` name the code a doc was written from; `vouch` stamps source and content digests; later validation reports code movement (`sources.stale`) and doc movement (`content.stale`). **Scope, plainly:** `content.stale` is checkable from anywhere, but `sources.stale` resolves only inside the service's own repo — the docs-repo run counts what it could not check (`sources.unverifiable-from-here`). Both are warnings, so `validate --all` exits 0 on a fully stale fleet unless CI passes `--strict`. |
+| **Multi-repo & topology** | Stores are real and shipped (v1.5.0, beta): standalone Git planning roots with root selection and read-only references. What they do not do is reconcile: the guide states it as a limitation — *"No sync, ever — by design. OpenSpec never clones, pulls, or pushes. A stale checkout shows stale specs until you pull"*, plus one checkout per store id per machine — and there is no lockfile or commit pin ([#1273](https://github.com/Fission-AI/OpenSpec/issues/1273), open since June). Two engineers can therefore read contradicting requirements for one spec id with no signal that they differ. Service topology and contract edges are outside the requirement model entirely. | One docs repo is one checkout, so "which version" is a git question with one answer; cross-service calls are checked against provider operationIds, and the fleet map is a first-class artifact rather than an inference. |
+| **AI integration & entry curve** | Broader tool coverage, and growing: 34 tools at v1.7.0, selected interactively from a scan, with profiles, delivery modes and schemas. Plain Markdown makes the first change quick. | Narrower coverage: 20 tools, written for whichever ones the repo scan finds, plus `--json` on every command and `loam status` for what-to-do-next. LikeC4, frontmatter, and the operationId spine are still to learn before the fleet checks pay off. The question worth asking is not the count but whether your tool is on the list — and if it is not, `AGENTS.md` plus a binary on `PATH` is the whole integration. |
+| **Who owns a generated file** | The tool does. `openspec update` rewrites its generated instructions; a file you edited is replaced, and the version stamp is what lets it skip the ones already current. | You do. loam stamps the same way — `<!-- generated by loam vX.Y.Z -->` in every command and skill body — but the stamp only makes drift *reportable* (`doctor.agent-files-stale`, `agents.stale`). loam never rewrites the file; the fix is a human reading it. That is a trade, not a win: upstream's upgrade path is one command, loam's is a review per repo. |
+
+## When OpenSpec is enough
+
+Honesty cuts both ways. If you have **a single repository**, a small team, and **no cross-service API contracts**, most of what loam adds is weight you do not need: the C4 axis, two kinds of digest, an architecture requirement file. OpenSpec's "markdown spec and go" is simpler and, for that shape of project, sufficient. Use it.
+
+## When loam
+
+- A **fleet** of services where a business-simple feature routinely spans several of them, and the interesting failures live on the edges — a consumer calling an operation the provider's contract no longer defines.
+- A **legacy adoption campaign**: docs written largely by agents, where an unverified corpus invites exactly the quiet fictions the trust chain exists to catch.
+- A team that wants the **done-check auditable**: a derived checklist where every answer carries a `file:line` and names who gave it, and where the answers a test runner produced are separated from the answers an agent asserted — mechanically, on every surface, rather than by convention. loam does not forbid the assertion; it refuses to let it read as a run.
+
+## What loam takes from OpenSpec
+
+The core requirement shape: `### Requirement:` headings, `#### Scenario:` blocks, and the `## ADDED | MODIFIED | REMOVED Requirements` delta algebra. Seven upstream files are vendored as representative regression fixtures. Separate exact-commit sweeps cover living, active, and archived spec trees at both baselines: release 207 files / 739 requirements / 2273 scenarios and canary 209 / 742 / 2284, including parse/serialize/parse stability of requirement content. This is a Markdown-compatibility corpus, not a claim of full modern workspace compatibility. The multi-tool delivery pattern — one content source plus thin per-tool adapters, emitted both as a slash command and as an Agent Skill — is also borrowed from OpenSpec's integration design, including the per-tool paths its adapters document and the `<tool-dir>/skills/<name>/SKILL.md` skills convention **as it stood at v1.7.0**. That convention is no longer uniform upstream and loam should not claim it is: [#1511](https://github.com/Fission-AI/OpenSpec/pull/1511) (merged 2026-08-05) moved Codex's skills to a shared `.agents/` directory with `.codex/` kept as a legacy location, and the staged v1.8.0 adds a vendor-neutral `agents` target installing to `.agents/skills/`. loam's own layout stays per-tool-dir; the shape was borrowed once, not tracked. What is not borrowed at all is regeneration: `openspec update` rewrites its generated files, loam only reports that they have fallen behind.
+
+## What loam does not adopt wholesale
+
+Each of these exists upstream and was considered, not overlooked. The long-form reasoning lives in [SCHEMA.md](SCHEMA.md) under "Considered and rejected".
+
+- **Workflow/DAG engine** (artifact-graph, `schema.yaml`): OpenSpec derives artifact completion from generated-file existence; it is not a second mutable state database. loam still avoids a configurable graph because fleet-wide validation benefits from one versioned lifecycle and one meaning of green. The risk is project-to-project schema drift, not “one workflow per service”.
+- **Stores as a second planning root**: OpenSpec's beta Stores solve a real cross-repo ownership problem with standalone Git planning repos, root selection and read-only references. loam currently keeps one shared docs repo because that repo also owns the service topology. A reference index may become useful if several independent fleet-doc roots appear; it is not dismissed as a cache.
+- **`RENAMED` sections**: OpenSpec represents rename as heading FROM/TO. loam's preferred conversion assigns a stable `Requirement-ID` and carries it through a `MODIFIED` requirement, so the heading can change without losing identity. `REMOVED` + `ADDED` is only the legacy fallback when identity cannot be established.
+- **Writing OpenSpec back** (bidirectional compatibility): serializing through loam drops `## Purpose` and the `## Requirements` wrapper, both of which OpenSpec's parser requires. Pretending otherwise would corrupt someone's repo politely. Migration is one-way: migrate, then retire the old tooling.
+- **TUI and OpenSpec profiles/worksets**: profiles select installed workflow commands; worksets are personal folder/editor sets, not validator semantics or curated agent evidence bundles. loam keeps a smaller fixed command surface and derives its model-scoped views. Authored `tasks.md` is not authoritative in loam, but migration preserves it as a legacy checklist until a human explicitly disposes of it.
+
+## Architecture decisions: upstream considered them and chose otherwise
+
+This is not a gap in OpenSpec's knowledge, and it should not be presented as one. [PR #566](https://github.com/Fission-AI/OpenSpec/pull/566) proposed ADRs as first-class documents — 1656 added lines across 13 files — and was closed **unmerged** on 2026-08-03. The stated reason is worth reading whole, because every item in it is a question loam had to answer too: the PR proposed a new default-core data model and CLI surface *while ADR ownership, lifecycle, concurrency, retrieval, and mutable-versus-immutable semantics remain unresolved*. The recommendation was to prove the workflow through configurable community schemas first, and that alternative is now documented upstream.
+
+loam's answers are narrower and therefore cheaper: `adrs/` is presence-tracked only, ownership follows the directory it sits in (`services/<svc>/adrs/` belongs to that service's team via CODEOWNERS), there is no lifecycle beyond MADR's own and no mutable state, and retrieval is a filesystem walk. That is a *smaller* answer than the one #566 proposed, not a better one — it works because loam already forced a service topology to hang decisions on, and OpenSpec deliberately has no such unit. If your ADRs need a lifecycle, neither tool has one.
+
+## The asymmetry that does not go away
+
+OpenSpec at the time of writing: 63,900 stars, 4,407 forks, a release every two to four weeks (v1.4.0 through v1.7.0 all landed inside ten weeks), and 21 commits merged to `main` in the five days before this paragraph was written. loam is one repository with no published package. Nothing in this document changes that, and a comparison that reports feature counts against a project moving that fast is a comparison loam loses on principle — which is why the axes above are about *what is checkable*, not about what exists.
+
+Two consequences follow honestly. First, a class of defect upstream fixes inside 48 hours: [#1493](https://github.com/Fission-AI/OpenSpec/issues/1493), a report that generated workflows referenced flags that had moved, was closed completed on 2026-08-04 with its whole fix wave merged the same day. loam has had the same class of defect in its own generated instructions, so this is not an axis loam may cite. Second, anything upstream stages will stale a count here: v1.8.0 is already assembled in `main` and adds a vendor-neutral `agents` target and further tools.
+
+## Migrating
+
+[MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) — what carries over mechanically, how active changes and `RENAMED` become explicitly mapped loam features/stable-id `MODIFIED` deltas, what remains only in preserved legacy source (`## Purpose`, custom artifacts, complete-state prose), what must be added (`Operations:`/`Covers:`, OpenAPI, C4), and the disposition contract for every file in a real OpenSpec repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loam contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATING-from-OpenSpec.md

@@ -0,0 +1,202 @@
+# Migrating from OpenSpec
+
+loam reads OpenSpec requirement Markdown from the outside: `### Requirement:` headings, `#### Scenario:` blocks, and `## ADDED|MODIFIED|REMOVED Requirements` delta sections. Compatibility is measured, not assumed.
+
+Two upstream baselines are named separately:
+
+- released behavior: **OpenSpec v1.7.0**, exact commit `4e16790d90d8f54d4773ad9a5e71a57cd9f1e86b`;
+- compatibility canary: post-release `main` commit `45cca5db6137ed209117cc70510eb3e057fb981b` — a fixed historical pin, not a moving one. Upstream `main` advances daily; the canary exists to give the sweep a second reproducible corpus, and its totals are unchanged since it was taken.
+
+The seven verbatim fixtures come from the main canary and run in routine CI. A scheduled/manual matrix separately checks the exact release and canary commits across living, active, and archived spec trees: release 207 files / 739 requirements / 2273 scenarios; canary 209 / 742 / 2284. These test requirement/scenario parsing, not every modern workspace feature. Provenance and checksums are in [`test/fixtures/openspec/README.md`](test/fixtures/openspec/README.md).
+
+## Start with a read-only audit
+
+```bash
+loam audit-openspec /path/to/repo
+loam audit-openspec /path/to/repo --json
+```
+
+The input may be a repository containing `openspec/`, the `openspec/` directory itself, or a Store checkout. Modern `config.yaml`, Store metadata, nested capability folders, per-change `.openspec.yaml`, `skip_specs: true`, and project custom schemas are inventoried.
+
+For a **Store checkout** the planning shape decides the root and the store marker decides only the kind: the planning content may sit at the checkout root or under `<checkout>/openspec`, and a checkout with a `.openspec-store/store.yaml` but planning content in neither place is refused by name rather than audited as an empty, compatible workspace. Planning content in *both* places is the pre-existing `Ambiguous OpenSpec root` refusal, unchanged. A root that holds no living spec and no active change at all is never `ready` (`openspec.workspace-empty`): a verdict over a corpus nobody read is the one answer this command must not be able to give.
+
+Audit separates four different facts:
+
+- `readiness.living` — living specs are mechanically readable;
+- `readiness.active` — active deltas will not silently strand content;
+- capability/service mappings, active change/feature mappings, rename identities, and authored artifact dispositions — human decisions still required (`readiness.mappingsResolved`, `changesResolved`, `renamesResolved`, and `dispositionsResolved` stay separate);
+- `archiveDiagnostics` — anomalies in frozen history, reported but never allowed to block migration of living/active truth.
+
+An audit that completed exits successfully even when it found blockers. Root, YAML and I/O failures still fail. This makes “the audit ran” distinct from `ready`/`mechanicallyCompatible`.
+
+## Generate and complete the mapping
+
+Audit is read-only by default. An explicit output path outside the OpenSpec source writes a non-overwriting skeleton:
+
+```bash
+loam audit-openspec /path/to/repo --write-mapping /tmp/openspec-map.yaml
+```
+
+The mapping is versioned and bound to both the canonical planning root and a SHA-256 inventory digest. That digest covers the **living tree and the active changes only** — not `changes/archive/**`. Frozen history is reported as diagnostics that never gate, so letting a colleague's typo fix inside an archived change invalidate a 900-line mapping somebody spent a day completing was a cost with no safety behind it. An edit to a living spec or an active delta still invalidates it, which is the case the binding exists for.
+
+Digest and artifact paths are planning-root relative regardless of whether audit receives the repository container or its `openspec/` directory (`@workspace/` is reserved for Store metadata outside that root):
+
+```yaml
+version: 1
+source:
+  root: /path/to/repo/openspec
+  inventoryDigest: sha256:...
+
+capabilities:
+  payments/refunds:
+    services:
+      - payment-service
+    suggestedServices:
+      - refunds
+    requirementServices:
+      Authorize: []
+
+changes:
+  add-refund:
+    feature: FEAT-12
+    suggestedFeature: FEAT-1
+    title: Add refund
+
+renames:
+  "changes/rename/specs/payments/spec.md:1:1":
+    from: Old name
+    to: New name
+    existingRequirementId: null
+    requirementId: payments.authorize
+
+artifacts:
+  changes/add-refund/proposal.md:
+    kind: proposal
+    disposition: convert-to-intent
+    suggestedDisposition: convert-to-intent
+  changes/add-refund/tasks.md:
+    kind: tasks
+    disposition: preserve-as-legacy-checklist
+    suggestedDisposition: preserve-as-legacy-checklist
+```
+
+`suggestedServices`, `suggestedFeature`, and `suggestedDisposition` are hints, not decisions. The fields that count are `services`, an explicit `changes.<OpenSpec-id>.feature` plus `title`, `requirementId` where needed, and `disposition`. Feature ids use loam's `<word>-<number>` grammar and must be unique across active changes.
+
+### Capability → service is a human decision
+
+OpenSpec's unit is a capability; loam's unit is a service bound to the C4 landscape. A nested capability id stays nested (`payments/refunds`) rather than collapsing to `payments`. Mapping scope is the union of living capabilities and capabilities found only in active deltas, so a brand-new nested capability cannot disappear merely because it has not reached `specs/` yet.
+
+- With one selected service, every requirement in the capability goes there.
+- With several selected services, `requirementServices` must allocate every living **and active** requirement to one or more of them. Apply refuses an omitted allocation or a service outside the declared list.
+- If two mapped capabilities would create the same heading/`Requirement-ID` in one service, apply refuses instead of guessing which requirement wins.
+
+### Change → feature is explicit
+
+Every active OpenSpec change gets one `changes.<id>` entry. Fill both the loam feature id and the human title. The skeleton deliberately leaves `feature: null` next to a deterministic suggestion; suggestions never make a migration ready. Unknown OpenSpec change ids, malformed feature ids, blank titles, and duplicate feature ids block apply.
+
+### RENAMED keeps identity
+
+Audit parses every OpenSpec FROM/TO pair and gives it a stable mapping key. FROM must select exactly one living requirement in that delta's capability. If that requirement already has a `Requirement-ID`, the skeleton reuses it and refuses a replacement; otherwise assign a valid id. Apply places that id on the staged living source and emits a `MODIFIED` requirement with the TO heading, the same body/scenarios, and an `OpenSpec-Living-Source` annotation. Conflicting targets, duplicate sources/targets, identity collisions, and multi-change rename chains block instead of being flattened to `REMOVED` + `ADDED`.
+
+### Authored artifacts require explicit disposition
+
+Every active `proposal.md`, `design.md`, and `tasks.md` appears in the mapping with `disposition: null` until a human chooses. A suggestion does not make migration ready.
+
+Typical choices are:
+
+- proposal → `convert-to-intent`;
+- design → `review-as-feature-adr` (proposed decision material, not automatically an accepted ADR);
+- tasks → `preserve-as-legacy-checklist` until progress/order information has been reviewed;
+- `retain-read-only` or `manual-review` when conversion would overstate what is known.
+
+## Dry-run and explicit apply
+
+Validate the completed mapping without writing anything:
+
+```bash
+loam migrate-openspec /path/to/repo --map /tmp/openspec-map.yaml
+loam migrate-openspec /path/to/repo --map /tmp/openspec-map.yaml --json
+```
+
+`--mapping` remains a deprecated spelling of `--map`. Dry-run is always the default and never creates the target.
+
+Writing requires both flags:
+
+```bash
+loam migrate-openspec /path/to/repo \
+  --map /tmp/openspec-map.yaml \
+  --apply \
+  --target /tmp/loam-migration-review
+```
+
+Before apply, loam repeats the audit and compares the fresh source root/digest with the mapping. Any living or active source edit since review invalidates the mapping. The target must be absent or empty, must not overlap the OpenSpec source, and **must not sit inside a live loam fleet**: a target under the `docsDir` of a governing `loam.json` — or under any directory holding `architecture/landscape.likec4` — is refused, because every staged feature would otherwise be enumerated by `loam list` and `loam validate --all` as a phantom feature of the real fleet. A sibling of `docsDir` is fine. Writes are staged and swapped with rollback; source files and live loam docs are never modified, and every refusal above leaves the target directory absent rather than half-written.
+
+The target contains:
+
+- `services/<service>/spec.md` with mapped living requirements and `status: draft`;
+- `features/<FEAT>-<slug>/intent.md` for every active change;
+- `features/<FEAT>-<slug>/specs/<service>/spec.md` with routed ADDED/MODIFIED/REMOVED sections for every non-`skip_specs` change;
+- feature ADR/legacy files according to the explicit proposal/design/tasks dispositions, plus an exact read-only copy of the complete source change tree under `legacy/openspec/`, **and the living capability tree verbatim under `legacy/openspec/specs/`** — `## Purpose` prose, section prose between a heading and its first requirement, and capability `design.md` have no loam equivalent, so they are copied rather than converted and nothing is silently lost;
+- `migration-plan.json` with active changes, mappings, archive diagnostics and every artifact disposition;
+- normalized `mapping.yaml`;
+- `FOLLOW-UP.md` naming the work that still blocks a trustworthy fleet;
+- and the target's own `loam.json` (`{"docsDir": "."}`), `AGENTS.md`, and an **empty** `architecture/landscape.likec4`. The target is therefore a standalone docs repo, which is what makes `FOLLOW-UP.md`'s instructions runnable where they are written: `loam validate --all`, `loam status`, `loam rebase <FEAT>` and `loam doctor` all work inside it. The landscape is laid down empty on purpose — OpenSpec carries no topology, and a generated one would be a guess presented as the map — so every staged service surfaces as exactly one `landscape.service-unmodelled`, which is follow-up item one.
+
+This is deliberately called **staged migration docs**, not a finished or green loam repository. Apply uses the reviewed feature ids and materializes active changes, but it does not invent C4 topology/deltas, OpenAPI contracts, source provenance, or vouch evidence. `skip_specs: true` changes still receive intent and legacy artifacts but no feature spec delta. Every feature therefore remains review material until the follow-up checklist is complete.
+
+## What carries over mechanically
+
+The exact-commit corpus gate checks living, active, and archived spec trees. OpenSpec v1.7.0 release `4e16790` contributes 207 Markdown files, 739 requirements, and 2273 scenarios; main canary `45cca5d` contributes 209, 742, and 2284. Both sweeps check parse/serialize/parse stability of requirement content. Nested bullets, fenced markup, removal prose, CRLF, BOM and non-ASCII names survive. `REMOVED` requirements with no scenarios remain legal.
+
+Modern ADDED/MODIFIED/REMOVED deltas are readable, but “readable” is not “ready”: routing to services, loam frontmatter, Operations/Covers links and feature identity still require decisions.
+
+## Shapes that need repair or review
+
+- **Mixed legacy complete-state deltas.** Any BASE requirement stranded under `## Behavior`, `## Error Handling` or another prose heading is reported even if the same file also contains a valid ADDED/MODIFIED section. Re-home it before conversion.
+- **`## Requirements` inside an active change delta** is a **blocker** (`openspec.change-quoted-requirements`), which needs saying plainly because it is the shape OpenSpec's own living-spec template mandates and it looks correct. In a *living* spec that heading is the requirements section; in a *change delta* it is the one explicitly non-merging quote section, so requirements sitting under it stage nothing. loam refuses rather than counting requirements it cannot route — which is also what guarantees the per-change requirement counts in `migration-plan.json` equal what apply actually stages. Re-home them under `ADDED`, `MODIFIED` or `REMOVED`.
+- **Markdown under `specs/` named neither `spec.md` nor `design.md`** (`openspec.nonstandard-living-spec`) — a `Spec.md` on a case-sensitive filesystem, a `spec.markdown`, a hand-split `part-2.md`. No capability reads it, so migrating would leave its requirements behind. This is the living twin of the same check on change specs.
+- **Dot-prefixed directories under `changes/`** (`openspec.hidden-change-directory`) — a `.wip-refunds/` convention. They are not enumerated as changes, so nothing under them migrates. loam blocks rather than walking them: rename or move the directory before migrating, and its content is never silently dropped. Under `changes/archive/` the same finding is an archive diagnostic and does not gate, because frozen history never blocks.
+- **An ISO-8601 `created` timestamp** in `.openspec.yaml` is a valid date. It used to fail the whole workspace; a calendar date with an optional time and offset is now accepted.
+- **Spec-less changes.** They are valid only when a present, valid `.openspec.yaml` explicitly sets `skip_specs: true` and its named built-in or project custom schema resolves. A custom artifact graph never implies this opt-out by itself. Otherwise an active zero-delta change is a blocker. Explicit `skip_specs` suppresses generated feature specs while preserving intent, metadata, and authored legacy material.
+- **Malformed RENAMED.** A rename-only delta is not “empty”, but every section must supply a FROM/TO pair and every active pair needs an identity decision.
+- **External Store pointer.** A config-only code repo with `store: <id>` identifies external planning. Audit the registered Store checkout itself; loam does not guess a machine-local registry path.
+- **Frozen archive history.** Legacy shapes are diagnostics only. Keep `changes/archive/` read-only where it is; do not reconstruct it as loam `features/archive/`, whose entries imply loam computed and snapshotted the merge.
+
+## What must be added after staged apply
+
+- Truthful `sources:` paths from each service repository, followed by human `loam vouch`; staged specs intentionally remain `status: draft`.
+- `Operations:` links to provider OpenAPI `operationId`s, and `Covers:` links where architecture requirements are created.
+- `architecture/landscape.likec4`, service `model.likec4`, and explicit fleet relationships.
+- Service OpenAPI contracts and provider-before-consumer adoption where inbound edges already name operations.
+- LikeC4 and OpenAPI deltas for the already mapped active feature ids (`FEAT-12`, `BUG-42`, and so on); OpenSpec's prose change id/title remains visible in the staged slug, annotations, plan, and preserved source tree.
+- Human disposition of `config.yaml.context`, per-artifact rules, custom schemas/templates, Stores/references, Purpose prose and generated tool instructions.
+
+## Modern artifact disposition guide
+
+| OpenSpec artifact | Migration treatment |
+|---|---|
+| `config.yaml` (`schema`, `context`, `rules`, optional `store`) | Inventory and review. Move durable operating context into the docs contract; do not silently convert workflow rules into different validator semantics. |
+| `specs/<nested/capability>/spec.md` | Map requirements to one or more services. Apply stages combined `services/<svc>/spec.md` files. |
+| `specs/<capability>/design.md` | Review as a service ADR; do not mark accepted merely because the file existed. |
+| `changes/<id>/.openspec.yaml` | Preserve schema/`skip_specs`/created metadata in the plan and exact feature-local legacy tree. |
+| `changes/<id>/proposal.md` | Explicit `convert-to-intent`, or retain/manual-review in feature legacy material; the original is also preserved. |
+| `changes/<id>/specs/**/spec.md` | Validate and route ADDED/MODIFIED/REMOVED requirements into the mapped feature/service delta, preserving delta kinds; keep the original beneath `legacy/openspec/`. |
+| `changes/<id>/tasks.md` | Preserve as a non-authoritative feature-local legacy checklist with its explicit disposition until reviewed. |
+| `changes/<id>/design.md` | Stage as proposed feature ADR material for `review-as-feature-adr`, otherwise retain as legacy; never imply acceptance merely because it existed. |
+| `changes/archive/**` | Keep read-only as OpenSpec history; diagnostics do not gate living/active readiness. |
+| `schemas/<name>/schema.yaml` and templates | Review custom workflow semantics. The schema name must resolve as a direct portable member of `schemas/`; even a workflow with no specs artifact still needs explicit valid `skip_specs: true` for a zero-spec change. |
+| `.openspec-store/store.yaml`, `references`, Worksets | Record planning ownership/references for humans. They do not become a second loam fleet topology automatically. |
+| OpenSpec-generated skills/commands/instruction blocks | Remove after cutover so agents do not receive two live process contracts. |
+
+## Cutting over
+
+The staged target has two halves, and only one of them moves.
+
+1. Work `FOLLOW-UP.md` until `loam validate --all` **inside the target** is green. That is the gate; nothing before it means anything, because a staged target is deliberately red on arrival.
+2. Move `services/` and `features/` into the live fleet.
+3. Leave the rest behind: `legacy/`, `mapping.yaml`, `migration-plan.json`, `FOLLOW-UP.md`, and the target's own `loam.json` and `AGENTS.md` are review residue. They exist so a human can check the conversion, and the live fleet has its own copies of the last two.
+4. Remove OpenSpec's generated skills, commands and instruction blocks from every repo, so agents stop receiving two live process contracts.
+
+## Migration is one-way
+
+loam reads OpenSpec; it never writes back into the OpenSpec workspace. Loam serialization does not preserve OpenSpec's required `## Purpose` and `## Requirements` framing as an OpenSpec round-trip contract — but the source framing is not lost either: the verbatim living tree under `legacy/openspec/specs/` is what makes "no authored artifact is silently lost" cover living capabilities and not only change trees. Migrate into a separate target, review it, cut over once, and retire the old tooling only after the staged follow-up is complete.