@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/COMPARISON.md

@@ -1,63 +1,80 @@
-# 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.
+# Where loam fits
+
+loam is not a replacement for an architecture renderer, a software catalog, a contract-testing
+broker, an API-diff engine, or a code-level architecture test. It is the layer that keeps an
+authored C4 model, requirements, contracts and verification evidence semantically connected while
+the system changes. Most of the tools below can sit beside it; the useful question is which part of
+the problem each one should own.
+
+## Architecture as code: LikeC4 and Structurizr
+
+[LikeC4](https://likec4.dev/) and the [Structurizr
+DSL](https://docs.structurizr.com/dsl) describe architecture as code and turn it into navigable C4
+views. They own modeling and visualization; loam deliberately uses LikeC4 for that job instead of
+building another renderer. loam adds checked joins from the model to requirements, contracts and
+evidence, plus the feature transaction that changes those artifacts together. Structurizr is an
+alternative modeling environment, not a format loam currently reads.
+
+## Software catalogs: Backstage
+
+The [Backstage Software Catalog](https://backstage.io/docs/features/software-catalog/) makes
+software components, APIs, ownership and dependencies discoverable across an organization. It is
+the stronger home for inventory, search, team ownership and a portal assembled from many systems.
+loam keeps a smaller Git-native authority for architecture change: it checks what a feature means
+across authored artifacts, but it does not provide a catalog server, discovery pipeline or portal.
+
+## Architecture and event catalogs: EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) gives domains, systems, services, APIs, events,
+schemas and owners a connected, versioned and searchable documentation experience, with generation
+from contract sources. It is closer to loam's subject matter than a general software catalog and is
+the better presentation and discovery surface for event-driven architecture. loam's distinct job is
+the local change protocol: exact requirement/model/contract joins, a deterministic validation gate
+and a rollback-capable merge into living documents. There is no built-in connector between the two
+today.
+
+## Contract verification and deployability: Pact Broker
+
+The [Pact Broker](https://docs.pact.io/pact_broker/overview) stores consumer contracts and provider
+verification results; its [`can-i-deploy`](https://docs.pact.io/pact_broker/can_i_deploy) decision
+uses tested application versions and deployment environments. That is stronger runtime-facing
+evidence than loam's documentation and attestation record. loam sees a wider design transaction —
+C4, requirements, OpenAPI, AsyncAPI and feature intent — but has no environment matrix and does not
+replace consumer-driven contract tests.
+
+## Contract change detection: oasdiff and buf
+
+[oasdiff](https://github.com/oasdiff/oasdiff) and [Buf breaking-change
+detection](https://buf.build/docs/breaking/overview/) inspect contract revisions in much greater
+depth than loam. They answer whether an OpenAPI or Protobuf change is structurally breaking; loam
+answers which authored consumers and requirements are joined to the operation or message being
+changed. Use the specialist diff in CI beside loam rather than expecting either tool to infer the
+other half.
+
+## Requirements traceability: OpenFastTrace, Doorstop, StrictDoc and Sphinx-Needs
+
+[OpenFastTrace](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md),
+[Doorstop](https://doorstop.readthedocs.io/en/latest/),
+[StrictDoc](https://strictdoc.readthedocs.io/) and
+[Sphinx-Needs](https://sphinx-needs.readthedocs.io/) provide mature ways to identify requirements,
+link them to other artifacts and report traceability. They are broader choices when requirements
+engineering, compliance matrices or configurable document relations are the primary problem. loam
+uses a deliberately fixed vocabulary of joins because those links also drive C4 projection,
+contract coherence and one transactional feature lifecycle.
+
+## Architecture conformance in code: ArchUnit and dependency-cruiser
+
+[ArchUnit](https://www.archunit.org/userguide/html/000_Index.html) and
+[dependency-cruiser](https://github.com/sverweij/dependency-cruiser) inspect implementation
+dependencies and enforce rules such as layers, allowed imports and cycle freedom. They answer a
+question loam intentionally does not: whether the code actually has the structure the architecture
+claims. Use them to turn selected architecture rules into executable code checks; use loam to keep
+the authored system model and the rest of its semantic record coherent.
+
+## The boundary
+
+Every individual mechanism loam uses has neighbours with more depth in that mechanism. loam's
+boundary is their intersection: an authored C4 change and requirement deltas, joined to contracts
+and distinguishable evidence, validated and merged as one reviewable filesystem transaction. If
+only one of those axes matters, choose the specialist. loam starts paying when a change crosses
+several of them and “all the files are valid” is weaker than “all the claims still agree.”

package/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Loam
+
+Loam requires Node.js 22.22.3 or newer. Install from the lockfile with `npm ci`. Before submitting a
+change, run the complete gate in this order:
+
+```sh
+npm run lint
+npm run typecheck
+npm run arch:check
+npm test
+npm run test:coverage
+npm run test:package
+```
+
+The one-shot `npm run setup` command performs installation, build, and a CLI smoke check. Keep
+changes scoped, add tests for behavior changes, and do not commit generated `dist/`, coverage, local
+`loam.json`, fleet data, or command outputs containing internal paths.
+
+Read [AGENTS.md](https://github.com/ybotok/loam/blob/main/AGENTS.md) before changing Loam itself.
+[docs/DESIGN.md](https://github.com/ybotok/loam/blob/main/docs/DESIGN.md) explains the module
+boundaries and dependency direction, while
+[docs/CODE-STYLE.md](https://github.com/ybotok/loam/blob/main/docs/CODE-STYLE.md) records the
+conventions the compiler and linter cannot enforce and the defect behind each one. Read the
+code-style guide before a first change to `src/`.
+
+Three of those conventions are hard limits, counted by `test/code-limits.test.ts` inside `npm test`:
+at most 400 lines per source file, at most 4 parameters per function or constructor, and at most 5
+files per package directory. A fourth — a branded type on every validated identifier or path — is
+held by the compiler instead. `test/code-limits-baseline.json` is currently empty and must remain
+empty: any entry is a regression, not accepted backlog. Do not add an entry to land a change.
+
+Pull requests should explain the user-visible contract being changed, the failure mode being
+prevented, and the verification performed. Machine-facing CLI changes must preserve the documented
+JSON envelope and stable error codes or explicitly describe a versioned contract change.
+
+## The LikeC4 canary
+
+[likec4-canary.yml](https://github.com/ybotok/loam/blob/main/.github/workflows/likec4-canary.yml) is
+a weekly scheduled workflow (manual dispatch included) that installs `likec4@latest` over the exact
+lockfile pin and runs the LikeC4-touching suites against it, then the committed 120-service
+benchmark as informational evidence in the run's step summary. It is an early-warning smoke,
+explicitly not the gate: the gate and every release run against the exact 1.59.2 lockfile pin, the
+canary has no push or pull-request trigger — so it can never post a status on a pull request or
+become a required check — and a red canary blocks nothing. When the npm latest equals the pin, every
+step after the version comparison is skipped and the summary says nothing new was tested.
+
+What a red run means, by failing step. A red typecheck means likec4's type surface moved. A red
+`likec4-batch-parity.test.ts` means the undocumented multi-project workspace behaviour the batch
+loader leans on — per-folder configs, per-project model parsing, error attribution by source path —
+moved upstream; that suite was designed as this exact tripwire. A red `scale.test.ts` is the
+superlinear blow-up alarm. A failure in the version-comparison or install steps is infrastructure
+(usually the npm registry), not upstream drift. The benchmark step never fails on timing —
+wall-clock thresholds on shared runners measure the host, not the code — only on a run that is
+itself unsound.
+
+Reproduce a red locally:
+
+```sh
+npm ci
+npm install --no-save likec4@latest
+npx vitest run test/likec4-batch-parity.test.ts   # or the workflow's full suite list
+```
+
+then `npm ci` again to restore the pinned tree — the overlay install mutates `node_modules` without
+touching the lockfile.
+
+A red has three honest outcomes: fix the adapter and bump the pin in an ordinary pull request (a pin
+bump is a user-visible dependency change and needs a CHANGELOG entry); stay pinned and record the
+blocked version in ROADMAP.md or an issue; or, when only the canary's own plumbing broke, fix the
+workflow. When adding a new suite that touches LikeC4, extend the workflow's suite list in the same
+change. GitHub disables scheduled workflows after sixty days without repository activity, so after a
+quiet stretch check that the canary is still enabled.
+
+## Releases
+
+Only maintainers create release tags. A release is driven by an exact `v<package.version>` tag and
+the workflow in `.github/workflows/release.yml`; do not run `npm publish` from a workstation and do
+not add an `NPM_TOKEN` fallback. The canonical GitHub repository, protected `npm-production`
+environment, npm trusted publisher, changelog date, private security channel, and all
+release-readiness checks must be in place first.
+
+See the
+[fail-closed release checklist](https://github.com/ybotok/loam/blob/main/docs/RELEASE-READINESS.md).
+Creating a tag or publishing a package is never part of an ordinary contribution.