@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/COMPARISON.md

@@ -4,7 +4,8 @@ loam is not a replacement for an architecture renderer, a software catalog, a co
 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.
+the problem each one should own. One section is different in kind and carries a date: the
+spec-driven change tools overlap loam's own job, and they change every week.
 
 ## Architecture as code: LikeC4 and Structurizr
 
@@ -48,8 +49,11 @@ replace consumer-driven contract tests.
 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.
+changed — `loam diff` names them for a removal, a deprecation, and a modification of the operation
+or anything its `$ref`s reach — and never whether the change breaks them. Authored means drawn or
+written in the docs repo: a caller the map does not draw is invisible to it, and one drawn without
+an operation on its edge is reported as a consumer nobody could check. 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
 
@@ -71,6 +75,90 @@ question loam intentionally does not: whether the code actually has the structur
 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.
 
+## Spec-driven change tools, as of October 2026
+
+These are the tools a team evaluating loam usually holds it against, and unlike the neighbours
+above they overlap its job: each turns an intended change into specs an agent implements. They
+release about weekly, so this section is dated — checked 2026-10-09 against each project's
+releases, documentation and issue tracker — and each claim links its source. It records what each
+offers for a change that crosses repositories or services, what is still open upstream, and where
+loam differs. It does not rank them.
+
+**OpenSpec** (1.14.1, published 2026-10-05)
+
+- [Stores](https://openspec.dev/docs/stores), in beta since 1.5.0, keep specs in a repository of
+  their own that several code repositories plan against; worksets, also beta, group them. The guide
+  says OpenSpec does not route tasks to repositories: for a change spanning components, its pattern
+  is a shared contract in the store plus a separate local change in each component repository,
+  linked by hand. Since 1.14.0, a store-backed apply may also edit the code repository that
+  declares the store.
+- `openspec show <change> --diff` (1.11.0) renders each requirement of a change as a unified diff
+  against its base, with `--json --diff` for pipelines
+  ([releases](https://github.com/Fission-AI/OpenSpec/releases)).
+- The [Cloud Agent](https://openspec.dev/blog/openspec-cloud-agents), in early access since
+  2026-08-28 with new sign-ups paused on 2026-09-11, is hosted. It checks pull requests against
+  spec requirements, shows requirements across repositories as in sync, drifted or needing a
+  decision, scans daily and opens corrective pull requests. The page does not say how it detects
+  drift.
+- Open: [#725](https://github.com/Fission-AI/OpenSpec/issues/725), multi-repository and
+  microservice spec management, open since 2026-02-18. On 2026-09-07 the maintainers' bot confirmed
+  that shared changes with repository slices and explicit apply targets do not exist yet.
+
+**Spec Kit** (1.1.2, 2026-10-07)
+
+- The [contract-driven development
+  guide](https://github.github.com/spec-kit/guides/contract-driven-development.html) (September
+  2026) covers interfaces between repositories or components by convention: the owner publishes a
+  versioned contract, consumers pin it, and provider and consumer contract tests go into the tasks.
+  It excludes contract sync, cross-repository dependency resolution and release orchestration, and
+  describes no automated check between consumer and provider.
+- [`/speckit.converge`](https://raw.githubusercontent.com/github/spec-kit/main/templates/commands/converge.md)
+  (June 2026) runs after implementation: the agent compares the code with one feature's spec, plan
+  and tasks, classes each gap as missing, partial, contradicting or unrequested, and appends tasks
+  for them.
+- 1.1.1 added an experimental MCP server, and 1.1.2 MCP tools that list a project's artifacts
+  ([releases](https://github.com/github/spec-kit/releases)).
+- Open: [#4583](https://github.com/github/spec-kit/issues/4583), multi-repository microservices,
+  open since 2026-09-14 and labelled triage-can-wait. The maintainer linked the contract-driven
+  guide and asked whether it is enough to close it.
+
+**Kiro** (IDE 1.2, CLI 2.28)
+
+- [Feature specs](https://kiro.dev/docs/specs/) are Requirements-First or, since IDE 0.10
+  (February 2026), Design-First — requirements derived from an existing architecture or sketch —
+  and live per feature under `.kiro/specs`. Analyze Requirements (0.12, May 2026) checks a
+  requirements document for ambiguity, conflicts and gaps before design.
+- [Kiro Web](https://kiro.dev/changelog/web/introducing-kiro-web-preview/) (preview from
+  2026-05-18) clones several repositories into one cloud session, coordinates a change across them
+  and opens a pull or merge request in each repository it changed; since June, GitHub and GitLab
+  repositories can share a session.
+- For specs that span repositories, the [best-practices
+  page](https://kiro.dev/docs/specs/best-practices/) suggests a central specs repository linked by
+  submodules, packages or symlinks. The docs describe no merge of a finished spec into a living
+  baseline and no drift detection; [#9435](https://github.com/kirodotdev/Kiro/issues/9435), open,
+  asks for a git ref stamped into spec metadata and a warning when referenced code changed.
+
+**Where loam differs**
+
+- A cross-service change is one feature with a requirement delta for each service it touches, and
+  each service's part is computed: `loam delta <FEAT> --service <id>` is that service's slice, and
+  `loam tasks` lists the work per service, providers before consumers. That is the routing #725
+  asks for, held as data rather than executed. loam clones nothing and opens no pull request;
+  running an agent in each repository is the host's job — Kiro Web's, or a cloud agent's.
+- The joins between services are exact tokens that `loam validate` grades: a call edge's `op`
+  against the provider's OpenAPI `operationId`, a requirement's `Operations:` line against its own
+  contract. Spec Kit's guide leaves that agreement to people, and converge and the Cloud Agent ask
+  a model. loam asks no model and judges no meaning, so a requirement that is wrong but correctly
+  joined passes.
+- Drift is detected by digests kept in the files: `sources.stale` when vouched code moves,
+  `content.stale` when vouched words move, and a digest on every generated scenario. The checks run
+  in each repository's CI and store nothing elsewhere. There is no dashboard, and nothing opens a
+  corrective pull request.
+- Two gaps against these tools are open. loam has no per-requirement diff of a change against the
+  living spec like `openspec show --diff`: `loam delta` prints whole requirements, and
+  `loam archive --dry-run` says only which contract slots the merge quotes unchanged and which it
+  overwrites. And it has no analysis pass before code like Kiro's Analyze Requirements.
+
 ## The boundary
 
 Every individual mechanism loam uses has neighbours with more depth in that mechanism. loam's

package/CONTRIBUTING.md

@@ -71,6 +71,43 @@ workflow. When adding a new suite that touches LikeC4, extend the workflow's sui
 change. GitHub disables scheduled workflows after sixty days without repository activity, so after a
 quiet stretch check that the canary is still enabled.
 
+## The OpenSpec canary
+
+[openspec-canary.yml](https://github.com/ybotok/loam/blob/main/.github/workflows/openspec-canary.yml)
+is the same kind of early-warning smoke for the OpenSpec migration, weekly on Thursday with manual
+dispatch. It resolves the newest `vX.Y.Z` OpenSpec tag with `git ls-remote`, shallow-clones it, and
+runs `npm run test:openspec-corpus -- --baseline latest` against it. Like the LikeC4 canary it has no
+push or pull-request trigger and blocks nothing. The certified claim is the exact-commit corpus job
+in `ci.yml`, whose `release` pin is `OPENSPEC_BASELINES.release` in
+`src/core/openspec/model/model.ts`. When the newest tag is that pin, the sweep re-checks it exactly
+and the summary says there is nothing newer.
+
+What a red run means, by failing step. A red sweep means a file in the newest upstream corpus no
+longer survives the migration's read/serialize/read round trip; the log names the file. A red audit
+means `audit-openspec` could not complete on OpenSpec's own workspace — a YAML, root or I/O refusal,
+not a blocker, since blockers are only listed. A red resolve or clone step is infrastructure: GitHub,
+or a tag scheme upstream changed. The parser-source diff never fails. It warns when upstream's
+readers (`src/core/parsers/`), archive merge (`src/core/specs-apply.ts`) or validation rules
+(`src/core/validation/`) moved since the pin, and it is the step to read first. The 1.13 grammar
+changes appeared in no upstream spec file, so a green sweep says nothing about them.
+
+Reproduce locally:
+
+```sh
+git clone --depth 1 --branch <tag> https://github.com/Fission-AI/OpenSpec.git /tmp/OpenSpec
+npm run test:openspec-corpus -- --baseline latest /tmp/OpenSpec
+npm run dev -- audit-openspec /tmp/OpenSpec
+```
+
+Moving the pin is an ordinary pull request. Run the sweep and the documented audit, mapping and
+staged-apply path against the new release. Read the parser diff and give loam's OpenSpec reader
+(`src/core/openspec/scan/shape.ts`) whatever grammar it shows, each with a test. Then update
+`OPENSPEC_BASELINES.release` and the `release` totals in `scripts/openspec-corpus.ts`, the `ci.yml`
+matrix, and the pin tables in MIGRATING-from-OpenSpec.md and `test/fixtures/openspec/README.md`.
+The outgoing release becomes the `previous` pin, and the pin it displaces either gets a name of its
+own or a recorded reason to go. The banner and `baselines.release` under `--json` change, so the
+move needs a CHANGELOG entry.
+
 ## Releases
 
 Only maintainers create release tags. A release is driven by an exact `v<package.version>` tag and

package/MIGRATING-from-OpenSpec.md

@@ -6,30 +6,47 @@ is measured, not inferred from a successful directory walk.
 
 ## Version matrix
 
-> **Compatibility boundary:** the v1.9 exact-commit corpus is certified for the parser and one-way
-> migration boundary documented here. That boundary is the Markdown and the staged migration, not
-> OpenSpec's behavior: `audit-openspec` inventories v1.8/v1.9 workspace shapes, and loam does not
-> reimplement v1.9 validation, archive recovery, capability retirement, Store or agent-delivery
-> semantics.
+> **Compatibility boundary:** the v1.14.1 exact-commit corpus is certified for the parser and
+> one-way migration boundary documented here. That boundary is the Markdown and the staged
+> migration, not OpenSpec's behavior: `audit-openspec` inventories the workspace shapes v1.8
+> introduced and v1.14.1 still uses, and loam does not reimplement OpenSpec validation, archive
+> recovery, capability retirement, Store or agent-delivery semantics.
 
 | OpenSpec source | Exact pin | loam coverage | Status |
 |---|---|---|---|
-| [v1.9.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.9.0) | `2826b8889e5223a9a8095d4428b60b56597e1020`, released 2026-08-13 | Full living + active + archived Markdown corpus sweep, seven verbatim regression fixtures re-vendored at this commit, and the documented audit/mapping/staged-apply path. | **Certified for this documented parser/migration boundary.** It is not bidirectional OpenSpec compatibility. |
-| [v1.8.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.8.0) | `d57889664cab4f2f061d236ec3ff82a5578701bb`, released 2026-08-05 | Audit inventories or preserves modern planning roots, Stores, nested capability paths, config context/rules/references, custom schemas/templates, per-change metadata, `skip_specs`, `RENAMED`, and authored artifacts. | **Inventoried, and superseded by the certified v1.9.0 pin.** No v1.8 exact-release sweep of its own runs; the shapes v1.8 introduced are carried by the v1.9 corpus. |
-| [v1.7.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.7.0) | `4e16790d90d8f54d4773ad9a5e71a57cd9f1e86b` | The previously certified corpus, still swept file by file. | **Regression pin.** A parser change may not fix the current corpus by breaking the one somebody already migrated from. |
-| Historical post-v1.7 `main` canary | `45cca5db6137ed209117cc70510eb3e057fb981b` | A third exact living + active + archived parser corpus. | **Regression pin only.** It is not a release and not a moving claim. |
-
-The seven verbatim fixtures come from the v1.9.0 commit and run in routine CI. A scheduled/manual
-matrix separately sweeps all three pinned commits across living, active, and archived spec trees:
-v1.9.0 211 files / 746 requirements / 2317 scenarios; v1.7.0 207 / 739 / 2273; canary 209 / 742 /
-2284. These test requirement/scenario parsing, not every v1.8/v1.9 workspace feature. The
+| [v1.14.1 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.14.1) | `87c3595ace6a2e22957f39ebe5b74c2f2316e0cb`, released 2026-10-05 | Full living + active + archived Markdown corpus sweep through the migration's own reader, the 1.13 requirement grammar described below, and the documented audit/mapping/staged-apply path, run against OpenSpec's own v1.14.1 workspace. | **Certified for this documented parser/migration boundary.** It is not bidirectional OpenSpec compatibility. |
+| v1.10.0 – v1.14.0 releases | — | Carried by the v1.14.1 corpus and grammar; no exact sweep of their own runs. | **Superseded by the certified v1.14.1 pin.** |
+| [v1.9.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.9.0) | `2826b8889e5223a9a8095d4428b60b56597e1020`, released 2026-08-13 | The previously certified corpus, still swept file by file; the seven verbatim regression fixtures are vendored from this commit. | **Regression pin.** A parser change may not fix the current corpus by breaking the one somebody already migrated from. |
+| [v1.8.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.8.0) | `d57889664cab4f2f061d236ec3ff82a5578701bb`, released 2026-08-05 | Audit inventories or preserves modern planning roots, Stores, nested capability paths, config context/rules/references, custom schemas/templates, per-change metadata, `skip_specs`, `RENAMED`, and authored artifacts. | **Inventoried, and superseded.** No v1.8 exact-release sweep of its own runs; the shapes v1.8 introduced are carried by the v1.9.0 and v1.14.1 corpora. |
+| [v1.7.0 release](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.7.0) | `4e16790d90d8f54d4773ad9a5e71a57cd9f1e86b` | An older certified corpus, still swept file by file. | **Regression pin**, for the same reason. |
+| Historical post-v1.7 `main` canary | `45cca5db6137ed209117cc70510eb3e057fb981b` | A further exact living + active + archived parser corpus. | **Regression pin only.** It is not a release and not a moving claim. |
+| Newest upstream release | None: the newest `vX.Y.Z` tag, resolved each week | The same sweep without a pin (`--baseline latest`), an audit of OpenSpec's own workspace, and a diff of upstream's parser sources against the certified pin, in [openspec-canary.yml](https://github.com/ybotok/loam/blob/main/.github/workflows/openspec-canary.yml). | **Early warning, never a certification.** A red canary means upstream moved; it blocks no pull request and no release. |
+
+The seven verbatim fixtures come from the v1.9.0 commit and run in routine CI. At v1.14.1 five are
+byte-identical and the other two gained only prose and scenarios of shapes the set already holds, so
+the set was not re-vendored. A scheduled/manual matrix separately sweeps all four pinned commits
+across living, active, and archived spec trees: v1.14.1 223 files / 765 requirements / 2475
+scenarios; v1.9.0 211 / 746 / 2317; v1.7.0 207 / 739 / 2273; canary 209 / 742 / 2284. These test
+requirement/scenario parsing, not every workspace feature. The
 [fixture provenance, immutable upstream paths, and checksums](https://github.com/ybotok/loam/blob/main/test/fixtures/openspec/README.md)
 and the [compatibility tests](https://github.com/ybotok/loam/blob/main/test/openspec-compat.test.ts)
 use absolute GitHub URLs because this guide is also shipped in the npm tarball while `test/` is not.
 
-OpenSpec v1.10.0 (released 2026-08-19) changed no requirement-Markdown format, so the certified
-v1.9.0 boundary also covers documents it writes; its workspace-level additions are inventoried like
-the v1.8/v1.9 shapes above.
+**What moved between v1.9.0 and v1.14.1.** OpenSpec 1.13.0 and 1.13.1 changed the requirement
+grammar: a `*` or `+` bullet lists a `REMOVED` requirement or a `RENAMED` pair exactly as `-`
+always did, a heading's closing `#` run (`### Requirement: Late fees ###`) is not part of the
+requirement's name, and a delta file may repeat a section header with every copy applied.
+`audit-openspec` and `migrate-openspec` read all four the way OpenSpec does. 1.13.1 also stopped
+counting a bare `#### Scenario:` header with no body as a scenario; loam keeps it, and
+`loam validate` names it stepless in the staged target. The rest of v1.10–v1.14 — `show --diff`,
+`status --all`, `validate --archived`, Store-backed apply, new agent targets — is OpenSpec behavior,
+outside the boundary above.
+
+The certification run read OpenSpec's own v1.14.1 workspace: 36 capabilities, 30 active and 85
+archived changes. With the one change still at the proposal stage set aside (the
+`openspec.change-no-specs` case below), apply staged all 251 living requirements and 747 scenarios
+across 36 services, and 145 requirements across 29 features. Its planning roots, artifact kinds and
+change-metadata fields were the ones the v1.9.0 run met.
 
 An audit result of `ready: true` means that the particular files the installed loam inspected
 satisfy loam's documented migration checks. It is not a statement that every behavior of the
@@ -251,11 +268,12 @@ 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. The certified corpus is
-the OpenSpec v1.9.0 release `2826b888`: 211 Markdown files, 746 requirements, and 2317 scenarios.
-The v1.7.0 release `4e16790` (207, 739, 2273) and the post-v1.7 main canary `45cca5d` (209, 742,
-2284) remain as regression sweeps. All three 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.
+the OpenSpec v1.14.1 release `87c3595`: 223 Markdown files, 765 requirements, and 2475 scenarios.
+The v1.9.0 release `2826b88` (211, 746, 2317), the v1.7.0 release `4e16790` (207, 739, 2273) and
+the post-v1.7 main canary `45cca5d` (209, 742, 2284) remain as regression sweeps. All four read
+each file as the migration does and check read/serialize/read 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.

package/QUICKSTART.md

@@ -1,8 +1,11 @@
 # loam quick start
 
-From installation to the first agent-driven change, with the smallest useful setup. This guide
-uses one application and a local docs directory. A real fleet normally keeps that directory in a
-separate repository; the commands and chat flow stay the same.
+From installation to the first agent-driven change, with the smallest useful setup. Section 2 is
+ten minutes with the CLI alone — no agent, no service checkout, no adoption — and shows the check
+only a fleet-wide map can make: a call between two services that names an operation the provider
+does not have. From section 3 on, the guide uses one application and a local docs directory. A real
+fleet normally keeps that directory in a separate repository; the commands and chat flow stay the
+same.
 
 ## 1. Install
 
@@ -16,7 +19,167 @@ loam --version
 A project-local install works too: `npm install --save-dev @ybotok/loam`, then replace `loam` below
 with `npx loam`.
 
-## 2. Wire one project
+## 2. Ten minutes, CLI only: the fleet spine
+
+Nothing here needs requirement Markdown, `loam adopt` or `loam vouch` — only the map and a contract
+you already have. In an empty directory, write `fleet.yaml`: the services, and who calls whom.
+
+```yaml
+services:
+  - order-service
+  - payment-service
+
+calls:
+  - order-service -> payment-service
+```
+
+Make the docs repo there, and let `seed` draw the map from that file:
+
+```bash
+loam init --docs . --create
+loam seed --from fleet.yaml
+```
+
+```text
+architecture/landscape.likec4 written (replaced the scaffold's untouched stub) — 2 service(s), 1 call(s), from fleet.yaml
+  + architecture/landscape.likec4
+  + services/order-service/.gitkeep
+  + services/payment-service/.gitkeep
+  + architecture/services.likec4
+
+Next:
+  loam validate --all
+  loam list --needs-work
+  loam adopt --service order-service
+```
+
+Now the two things only you can do. First, put the provider's existing contract at
+`services/payment-service/openapi.yaml` — copy the one its build produces; loam never generates it
+and never reads the code. For this walk-through, one operation is enough:
+
+```yaml
+openapi: 3.1.0
+info:
+  title: payment-service
+  version: 1.0.0
+paths:
+  /payments:
+    post:
+      operationId: authorizePayment
+      responses:
+        "201":
+          description: Authorized
+          content:
+            application/json:
+              schema: { type: object }
+```
+
+Second, name the operation on the call edge in `architecture/landscape.likec4`. `seed` drew the
+edge bare; replace that line with this one, spelled the British way on purpose:
+
+```likec4
+  svc_order_service -> svc_payment_service 'Authorises the order' {
+    metadata { op 'authorisePayment' }
+  }
+```
+
+```bash
+loam validate --all --errors-only
+```
+
+```text
+No C4 model at <docs>/services/order-service/model.likec4. Run `loam adopt` for 'order-service' first.  (service.no-model)
+No C4 model at <docs>/services/payment-service/model.likec4. Run `loam adopt` for 'payment-service' first.  (service.no-model)
+⚠ payment-service: 1 operation(s) not governed by any requirement — authorizePayment  (api.ungoverned)
+✗ payment-service: landscape edge order-service → payment-service calls 'authorisePayment', not defined in payment-service's OpenAPI  (spine.op-undefined)
+
+2 services, 0 features — 3 errors, 3 warnings
+⚠ requirements axis not started fleet-wide (0 of 2 services), expected during staged adoption — 2 warning(s) grouped: service.no-spec×2; every finding is unchanged in --json
+
+→ `loam explain <code>` says what a code means and how to fix it
+```
+
+(`<docs>` is the absolute path of the directory; a fleet scorecard follows, cut here.) The last
+`✗` line is the one you came for: one letter between the map and the provider's contract, an
+**error**, and no other check a team normally runs would see it. `loam explain spine.op-undefined`
+says what it means and what to do. The two `service.no-model` errors are not misconfiguration:
+they are a truthful reading of a fleet where adoption has not started, and they stay until each
+service has a model. Spell the operation `authorizePayment` and the `✗` line is gone — the edge now
+reads `spine.resolved` in `--json`. Committed, this directory is a docs repo, and README's
+[PR recipe](README.md#guard-the-fleets-edges-on-every-pr) guards these edges on every pull request
+from here on — `loam diff --base` names who still calls an operation a branch removes.
+
+A change can start before any adoption, too. A feature that only states requirements needs no C4
+delta and no contract change:
+
+```bash
+loam new FEAT-1 --title "Idempotent payment authorization" --touches order-service --touches payment-service
+```
+
+```text
+FEAT-1 scaffolded at features/FEAT-1-idempotent-payment-authorization
+  + features/FEAT-1-idempotent-payment-authorization/intent.md
+  + features/FEAT-1-idempotent-payment-authorization/delta.likec4
+  + features/FEAT-1-idempotent-payment-authorization/specs/order-service/spec.md
+  + features/FEAT-1-idempotent-payment-authorization/specs/payment-service/spec.md
+
+Next: fill in the delta, then `loam validate --feature FEAT-1`.
+If this feature changes no architecture, delete delta.likec4 — a requirements-only
+feature is complete without it, and an empty `model {}` validates clean too.
+```
+
+Delete `delta.likec4`, write the intent's Why and Scope and its `owner`, and replace each
+`specs/<service>/spec.md` with the requirement that service takes on — the file's comment carries
+the template. payment-service's, for example:
+
+```markdown
+# payment-service — requirement delta for FEAT-1
+
+## ADDED Requirements
+
+### Requirement: Authorize a payment once per idempotency key
+Requirement-ID: PAY-AUTHORIZE-IDEMPOTENT
+Operations: authorizePayment
+
+The service SHALL return the original authorization, and charge nothing, when a request repeats an
+idempotency key it has already authorized.
+
+#### Scenario: A retried authorization is not charged twice
+- **Given** a payment authorized under idempotency key K
+- **When** an authorization request arrives again with key K
+- **Then** the response carries the original authorization and no second charge is made
+```
+
+```bash
+loam validate --feature FEAT-1
+loam archive FEAT-1 --dry-run
+```
+
+```text
+FEAT-1
+✓ order-service: requirements covered (1 requirement, all with scenarios)
+✓ payment-service: requirements covered (1 requirement, all with scenarios)
+  coherence: ✓ C4 · requirements · OpenAPI agree
+archive FEAT-1  (dry run)
+
+  requirements: order-service — created living spec.md (1 requirement(s))
+  requirements: payment-service — created living spec.md (1 requirement(s))
+
+  plan — 2 file(s):
+    create  services/order-service/spec.md
+    create  services/payment-service/spec.md
+    move    features/FEAT-1-idempotent-payment-authorization → features/archive/FEAT-1-idempotent-payment-authorization
+
+  dry run — nothing was written.
+```
+
+The archive would write each service's first living `spec.md` from the change itself, and the
+`Operations:` line already joins payment-service's requirement to the contract above. That is the
+small-change loop WORKFLOW.md calls
+[the honestly-small change](WORKFLOW.md#the-honestly-small-change), used as a first entry. The adoption below is still how a service's existing behaviour gets written down; this is
+how a change that cannot wait for it starts.
+
+## 3. Wire one project
 
 Run this in the code repository you want to govern:
 
@@ -30,14 +193,21 @@ boundary `commerce-app`, and installs command and Agent Skill pointers for the A
 Commit the generated `loam.json`, agent files and docs directory. Use your real stable service or
 application id instead of `commerce-app`.
 
-`--create` is only for a new docs repo. To join an existing shared docs repo, use:
+`--create` is only for a new docs repo. To join an existing shared docs repo from one service's
+checkout, use:
 
 ```bash
-loam init --docs ../architecture-docs --service commerce-app
+loam init --docs ../architecture-docs --service commerce-app --agent-profile service
 loam doctor
 ```
 
-## 3. Adopt what already exists
+`--agent-profile service` installs the entry points that run beside the code — adopt, implement,
+check, verify and report — and leaves feature authoring and shipping to the shared docs repo,
+which takes `--agent-profile docs` when its own `loam init` runs. Without the flag every checkout
+gets all seven. The one-project setup above keeps all seven on purpose: there, the code repo is
+also where features are written and shipped.
+
+## 4. Adopt what already exists
 
 In chat, use the explicit entry point:
 
@@ -57,7 +227,7 @@ Most hosts use `/loam-adopt`; Gemini uses `/loam:adopt`, Amazon Q uses `@loam-ad
 skills-only host can use `$loam-adopt`. A natural-language request such as “adopt commerce-app into
 loam” may load the same skill automatically, but the explicit spelling is the predictable path.
 
-## 4. Make the first change
+## 5. Make the first change
 
 For this one-project setup, stay in the wired code repo: its `loam.json` resolves `loam-docs/`, and
 its generated agent entries are already present. In a separately cloned team docs repo, run
@@ -90,7 +260,7 @@ loam status --json
 Its ordered `next[]` is the work queue. The agent runs an entry only when `next[].execution.runnable`
 is true; edits, work in another checkout and human review stay visibly different.
 
-## 5. When something behaves badly
+## 6. When something behaves badly
 
 Use the support entry point; it is not another lifecycle step:
 
@@ -124,6 +294,8 @@ only pointers whose recorded digest still matches; a file your team edited remai
 - [WORKFLOW.md](WORKFLOW.md) explains the complete lifecycle and human/agent boundary.
 - [SCHEMA.md](SCHEMA.md) defines every docs-repo artifact and join.
 - [COMPARISON.md](COMPARISON.md) explains where loam fits beside neighboring tools.
+- [docs/SERVICE-TEAMS.md](https://github.com/ybotok/loam/blob/main/docs/SERVICE-TEAMS.md) is the
+  one screen for a team whose repository is one service in a fleet.
 - [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) covers an OpenSpec migration.
 
 Three rules prevent most surprises: use `--create` only once, let a human vouch, and branch on JSON