@milehimikey/em 1.6.0 → 1.7.0

package/.claude/skills/event-modeling/reference/implement.md

@@ -0,0 +1,172 @@
+# Implementing a ratified slice
+
+The contract for the implementation half of the workflow: an agent (or engineer) turning **one
+ratified slice** into merged, verified code. The facilitation phases (`discover`/`extract` →
+`model` → `slice`) produce the inputs; this document governs consuming them. It applies to any
+implementing agent, whether or not the session started from `/event-modeling`.
+
+**The contract in one paragraph:** the slice doc is the spec — nothing between it and the code
+is a source of truth. Verify readiness mechanically before writing any code; implement exactly
+what the doc says; put every gap in front of a human instead of deciding it silently; never
+edit the ratified doc except the two lifecycle fields at merge; prove the work with tests
+traceable to the doc's invariants and scenarios.
+
+Why the rules are shaped this way: **agents propose, humans ratify.** Everything in the model
+and its slice docs is there because a human decided it on purpose — that is what makes the
+model authoritative. An implementing agent that silently patches a gap, or edits a ratified
+doc outside a session, converts the model into just another generated artifact and voids the
+whole methodology. (The full human/agent partition is `docs/process.md` in the
+[em repository](https://github.com/milehimikey/em/blob/main/docs/process.md) — not vendored
+with this skill.)
+
+## 1. Gate: verify readiness before starting
+
+```bash
+em validate <model>.em --slice-ready <slice-key>
+```
+
+`<slice-key>` is the slice's export key — the kebab-case slug of its name (`"Place Order"` →
+`place-order`). Exit 0 means: the slice has a doc bound via `note "slices/<key>.md"`, its
+frontmatter is usable, `status: ready-to-implement`, every `## Open Questions` checkbox is
+checked, and no status/version/link incoherence is flagged.
+
+**Non-zero exit means stop.** Report which checks failed and hand the slice back to the humans.
+Never make the gate pass yourself — checking an open-question box, flipping `status`, or
+editing frontmatter are ratification decisions, and ratification happens in a facilitated
+session, not in an implementation branch.
+
+## 2. Read the spec
+
+Read `slices/<slice-key>.md` end to end — every section is load-bearing:
+
+| Section | What it is to the implementer |
+|---|---|
+| frontmatter `pattern:` | Which of the four patterns' implementation shapes to build (State Change / State View / Automation / Translation) |
+| Command / Event field tables | The contracts — names, types, validation rules, immutable-fact markers |
+| `## Invariants / Business Rules` (INV-n IDs) | The non-negotiable rules; every one needs a test citing its ID |
+| `## Scenarios (Given / When / Then)` | The acceptance tests, already written — compile them, don't reinvent them |
+| `## Alternate & Error Flows` | Retries, idempotency, compensations — real requirements, not appendix |
+| `## Non-Functional Requirements` | Authz, PII, performance — implement or consciously surface, never skip |
+| `## Dependencies & Read Models Affected` | The blast radius — what else to check before and after |
+
+For timeline context, read the slice's surroundings in the `.em` (what triggers it, what
+consumes its output) — the slice's own diagram (`slices/<slice-key>.svg`) shows its canonical
+pattern shape. For machine-readable facts, use `em export <model>.em` rather than parsing the
+DSL or the doc's frontmatter yourself: it carries the slice's `pattern`, element refs, fields,
+and the joined doc metadata (`slice.doc.status`, `version`, `driftSignal`).
+
+If the project ships pattern-specific implementation skills (for example an Axon/DCB skill
+set keyed on a slice doc's `pattern:` frontmatter), route by the slice's pattern and follow
+those.
+
+## 3. Two modes: first version vs. ratified delta
+
+Check the doc's `version:` and `## Delta` section (or `em export`'s `slice.doc.driftSignal`):
+
+- **First implementation** (`version: 1`, no `## Delta`, `driftSignal: never-implemented`):
+  green-field slice implementation. Build the whole pattern shape the doc specifies.
+- **Ratified delta** (`version` > 1, `## Delta` present, `status: ready-to-implement` while
+  `implementedIn` still names the prior version's PR — `driftSignal: unpropagated-delta`):
+  this is a **change to existing, owned code**. The `## Delta` section's typed operations
+  (Added/Modified/Removed/Renamed, each with scenarios) scope the work precisely — which
+  invariants, which scenarios, which tests change. Touch what the delta names; leave the rest.
+  **Never regenerate merged code wholesale from the model** — after merge, code is owned by
+  the people who've edited it (generated-then-owned); regeneration is legal only for slices
+  whose code never merged.
+
+## 4. Gaps: propose, never decide
+
+Mid-implementation you will hit things the doc doesn't answer — a field's edge case, an
+undocumented ordering, a contradiction with adjacent code. The discipline:
+
+- **Stop that thread and surface it.** State precisely what's unspecified, the options, and
+  your recommendation. The human resolves it — at the model, where the resolution lands as an
+  answered open question or a small ratified delta alongside your fix, so the decision is
+  recorded instead of buried in an implementation diff.
+- **Never edit the ratified doc to record your own answer**, and never quietly pick a behavior
+  a business person could have an opinion on. Silent divergence is the failure mode the whole
+  conformance loop exists to catch — don't manufacture it.
+- Purely technical choices with no behavioral surface (private naming, idiomatic structure,
+  which assertion library) are yours; anything observable in behavior, data, or contract is not.
+
+## 5. Definition of done
+
+- Every `INV-n` invariant has at least one test that cites its ID.
+- Every scenario in `## Scenarios (Given / When / Then)` exists as a passing test; rejection
+  scenarios assert the doc's named rejection reason.
+- Alternate/error flows (idempotency included) are covered by tests.
+- The build and full test suite are green; the model still validates (`em validate` in CI —
+  you didn't touch the `.em`, so this only fails if something else broke).
+- Nothing between the slice doc and the code was committed as a source of truth (see §7 —
+  work containers are ephemeral; generated or symlinked specs are renderings).
+
+## 6. At merge: the lifecycle flip
+
+When the PR merges, exactly **two** frontmatter fields change on the slice doc:
+
+```yaml
+status: implemented
+implementedIn: <PR or commit URL>
+```
+
+This is supply-loop mechanics, not ratification — it's the one edit an implementing agent makes
+to a slice doc, and it's why `em ledger` deliberately excludes these two fields from what
+counts as content. **Do not bump `version:`** — versions bump only when a delta is ratified;
+a bump here is a ledger defect. In bridge-equipped projects,
+`npx -p em-sdd-bridge em-sdd-mark-implemented <slice-key> <pr-url>` does the flip for you.
+
+Then update the model's `README.md` slice index if the project keeps one, so the one canonical
+slice table reflects the new status and link. The `implementedIn` link is what the `conform`
+phase later uses to anchor drift-checking — leaving it empty blinds the loop.
+
+## 7. Spec-kit projects: the SDD adapter
+
+If the repository uses spec-kit (a `.specify/` directory exists), do not hand-author spec-kit
+artifacts — allocate through **em-sdd-bridge**, redirect mode preferred:
+
+```bash
+npx em-sdd-bridge@<pinned-version> <slice-key> --symlink
+```
+
+That allocates the feature branch and `specs/NNN-slug/` dir, runs the same readiness gates,
+and drops `spec.md` as a **symlink to the slice doc** — the slice doc itself travels through
+plan/tasks as FEATURE_SPEC. The rules that keep redirect mode safe:
+
+- **Never run `/speckit.specify`.** The ratified slice *is* the spec; an interactive specify
+  session against a defined slice creates a second, unratified source of truth.
+- **`/speckit.clarify` must never write into a slice doc.** Open questions resolve at the
+  model (that's what the readiness gate enforced); a ratified slice has nothing to clarify.
+  Projects using em-sdd-preset's overlays carry a mechanical guard for this — respect the
+  rule even where the guard isn't installed.
+- `/speckit.plan` and `/speckit.tasks` may run against the slice doc directly; the preset's
+  redirect preambles map spec-kit's section vocabulary onto the slice doc's sections.
+- **Emission fallback**: where redirect can't work (Windows checkouts without symlink
+  privileges, two-doc pattern-pair bundles, a toolchain that mutates its spec files), run the
+  bridge without `--symlink` to render `spec.md` from the slice doc. The generated file is a
+  rendering — never hand-edit it; regenerate it from the slice doc instead.
+- Everything under `specs/NNN-*/` is an **ephemeral work container** — one per change effort,
+  discardable; the PR is the durable record of the effort, the slice doc the durable
+  definition of the behavior.
+
+No spec-kit (or any SDD tool)? Implement straight from the slice doc — it already contains
+everything a spec holds. Don't introduce an intermediate spec document of your own.
+
+## 8. Never do
+
+| Rule | Because |
+|---|---|
+| Never implement from a slice that fails `--slice-ready` | The gate is the handoff contract; bypassing it hands you unratified decisions |
+| Never edit a ratified slice doc, except the two §6 fields at merge | Doc content is ratified; edits outside a session are unratified decisions |
+| Never edit the `.em` model | Model edits are ratified decisions — propose, don't write |
+| Never bump `version:` | Versions move only with ratified deltas; see `em ledger` |
+| Never silently decide unspecified behavior | Silent divergence is the disease the conformance loop exists to catch |
+| Never regenerate merged code from the model | Generated-then-owned: post-merge code belongs to its owners |
+| Never commit an authored intermediate spec | The slice is the spec; anything between it and the code is a rendering |
+
+## 9. Afterward: the loop closes
+
+Implementation isn't the end of the slice's story. On a cadence — or whenever someone asks —
+the `conform` phase checks implemented slices against the code, using the `implementedIn` link
+you recorded, and reports drift for humans to rule on (see `reference/conform.md`). Your two
+duties to that future loop are already behind you if you followed this doc: an accurate
+lifecycle flip, and zero silent decisions.

package/.claude/skills/event-modeling/reference/methodology.md

@@ -135,6 +135,11 @@ records an event directly.
   The processor band holds no event; the command in the next slice produces it. Keeping the
   triggered command in the same slice as the processor is a validation warning — always split it.
   Forgetting the third slice leaves `E` unread, which is also a warning.
+- **Naming:** name the read model after the pending work — `Payments To Process`,
+  `Orders To Fulfill`, `Pending Approvals` — never after the triggering event. The event is what
+  happened; the view is what's left to do. Reusing the event's name also collides in the shared
+  element namespace: `from` references then resolve by element kind, and `em validate` flags the
+  duplicated name.
 - Socratic prompts: *"What should happen without a human? What condition triggers it? What work
   list does the processor watch? What command does it fire? What if it fails or retries?"*
 

package/.claude/skills/event-modeling/templates/conformance-report.md

@@ -16,11 +16,15 @@ Replace bracketed placeholders; delete guidance comments before finishing.
 
 ## Summary
 
-| Surface | Real drift | Model gap | Internal inconsistency | Accepted divergence | Uncertainty |
-|---|---|---|---|---|---|
-| Structural | {{n}} | {{n}} | — | {{n}} | {{n}} |
-| Spec | {{n}} | {{n}} | — | {{n}} | {{n}} |
-| Internal | — | — | {{n}} | {{n}} | {{n}} |
+| Surface | Real drift | Model gap | Internal inconsistency | Accepted divergence | Unpropagated delta | Uncertainty |
+|---|---|---|---|---|---|---|
+| Structural | {{n}} | {{n}} | — | {{n}} | {{n}} | {{n}} |
+| Spec | {{n}} | {{n}} | — | {{n}} | {{n}} | {{n}} |
+| Internal | — | — | {{n}} | {{n}} | — | {{n}} |
+
+**Unpropagated delta** — a slice re-ratified past its shipped version (`slice.doc.driftSignal:
+"unpropagated-delta"` in `em export --json`): a known state, not a code defect. See
+`reference/conform.md` step 4.
 
 {{One or two sentences: overall read — clean, mostly clean with N items, or notably drifted.}}
 
@@ -32,15 +36,17 @@ Replace bracketed placeholders; delete guidance comments before finishing.
 ### {{n}}. {{Short finding title}}
 
 - **Surface:** {{structural | spec | internal}}
-- **Classification:** {{real drift | model gap | internal inconsistency | accepted divergence}}
+- **Classification:** {{real drift | model gap | internal inconsistency | accepted divergence | unpropagated delta}}
 - **Slice:** {{slice name}}
 - **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name) —
-  for accepted divergence, the `divergence "..."` annotation text itself}}
+  for accepted divergence, the `divergence "..."` annotation text itself; for unpropagated
+  delta, `slice.doc.driftSignal` and `slice.doc.version` from `em export --json`}}
 - **Claim:** {{what the model/doc says vs. what the code/doc shows — the actual disagreement}}
 - **Proposed red note:** `issue "conformance: {{text}}"` on {{element}} (slice "{{slice}}")
   <!-- Omit this line entirely for internal-inconsistency findings with no clear side to flag,
-       for any accepted-divergence finding (already ratified — don't propose re-ratifying it),
-       or when the finding doesn't warrant a red note (say why instead). -->
+       for any accepted-divergence or unpropagated-delta finding (already ratified, or already
+       a known pending-ship state — don't propose re-ratifying either), or when the finding
+       doesn't warrant a red note (say why instead). -->
 
 ## Scenario / invariant coverage
 

package/.claude/skills/event-modeling/templates/model-readme.md

@@ -34,9 +34,9 @@ never connected to one another.
 <!-- The canonical slice index — the ONE place slices are enumerated (the state file
      points here rather than keeping its own copy). Keep it in sync as slice docs are
      written and as statuses move. -->
-| # | Slice | Pattern | Status | Design doc |
-|---|-------|---------|--------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | {{none / draft / reviewed / ready-to-implement / implemented}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
+| # | Slice | Pattern | Status | Implemented in | Design doc |
+|---|-------|---------|--------|----------------|------------|
+| 1 | {{Slice Name}} | {{Pattern}} | {{no doc yet / draft / reviewed / ready-to-implement / implemented}} | {{PR/commit link once implemented, else —}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

package/.claude/skills/event-modeling/templates/slice.md

@@ -4,18 +4,84 @@ linked from the .em model with:  note "slices/<slice-name>.md"  on the slice's d
 Fill every section through Socratic questioning. Leave "Open Questions" rather than guessing.
 Replace the bracketed placeholders; delete guidance comments before finishing.
 
+The frontmatter below is the canonical, machine-read metadata dialect — `em`'s own parser
+(src/catalog/sliceDoc.ts) reads `status:`, `version:`, `pattern:`, and the lineage keys
+(`split-from:`/`merged-from:`/`superseded-by:`) from it. `pattern` is kebab-case
+(state-change/state-view/automation/translation) even though the skill's prose always says
+"State Change"/"State View"/etc. — the frontmatter value is a machine key, not a display label.
+Older docs using a `- **Status:** ...` bullet line instead of frontmatter still parse (legacy/
+accepted input), but new docs should always use this frontmatter form; `version` and lineage
+have no legacy form — frontmatter-only from day one.
+
+`version` is this slice's own ratified-content version — starts at `1`, bumps when a delta is
+ratified — distinct from `schemaVersion`, which versions the frontmatter dialect itself, not
+this slice. When a ratified change lands on an already-`implemented` slice: bump `version`,
+flip `status` back to `ready-to-implement` (it tracks the CURRENT version's implementation
+state — `implementedIn` legitimately keeps naming the PRIOR version's PR until the new version
+ships; that mismatch is an intended drift signal, not a bug), and fill in the `## Delta` section
+below with this hop's change, replacing whatever it held before (it always shows only the latest
+hop — full history lives in git, same-commit-ratification convention). Full grammar — the fixed
+heading, the four operation subsections, why the heading never varies, the replace-not-accumulate
+lifecycle — is documented in docs/slice-doc-schema.md#delta-section-grammar-and-lifecycle; treat
+it the same Socratic way as every other section here, don't generate it mechanically.
+
+The three lineage keys only apply when this doc was produced by a split, merge, or rename —
+delete them otherwise; most slices never carry them. Grammar: `<slice-key>@v<N>`, where
+`<slice-key>` is the referenced slice's kebab-case filename stem.
+
+Full machine schema — required-vs-optional keys per `status`, value types/enums, the
+unknown-key policy — is documented in docs/slice-doc-schema.md.
+
 The diagram below is generated, not hand-drawn: `em render <model>.em --slice "{{Slice Name}}"
 -o slices/{{slice-name}}.svg` (kebab-case the slice name to match this doc's own filename).
 -->
 
+---
+schemaVersion: 1
+pattern: {{state-change | state-view | automation | translation}}
+swimlane: {{Persona/Actor}} → {{Context/Aggregate}}
+status: {{draft | reviewed | ready-to-implement | implemented}}
+version: 1
+implementedIn: {{PR/commit link — fill in once status is `implemented`}}
+# Lineage — only when this doc exists because of a split, merge, or rename (delete these three
+# lines otherwise). Grammar: <slice-key>@v<N>. See
+# docs/slice-doc-schema.md#lineage-grammar-and-cardinality.
+# split-from: <slice-key>@v<N>
+# merged-from: <slice-key>@v<N>, <slice-key>@v<N>
+# superseded-by: <slice-key>@v<N>, <slice-key>@v<N>
+---
 # Slice: {{Slice Name}}
 
 ![Diagram](./{{slice-name}}.svg)
 
-- **Pattern:** {{State Change | State View | Automation | Translation}}
-- **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
-- **Status:** {{draft | reviewed | ready-to-implement | implemented}}
-- **Implemented in:** {{PR/commit link — fill in once status is `implemented`}}
+<!-- Only on re-ratification of an already-`implemented` slice — omit this whole section on a
+     slice's first version (v1 has no delta yet). The heading is always the literal `## Delta`,
+     never `## Delta: vX → vY` — hop metadata is a display line inside the section instead (see
+     docs/slice-doc-schema.md#delta-section-grammar-and-lifecycle for why). Replace this
+     section's content wholesale on the next re-ratification — it shows only the latest hop, not
+     an accumulating log. Omit any of the four subsections below with no entries this hop; keep
+     the remaining ones in this order (Added/Modified/Removed/Renamed). `Renamed` is for a
+     requirement/invariant renamed within this slice, not a substitute for the frontmatter
+     `split-from`/`merged-from`/`superseded-by` lineage keys above, which record the slice-doc
+     itself splitting, merging, or being renamed. -->
+## Delta
+**v{{X}} → v{{Y}}, ratified {{date}}** — {{one-line summary of the ratified change}}
+
+### Added
+#### Requirement: {{title}} ({{stable ID, e.g. an INV-n from Invariants below}})
+{{requirement text — same voice as an Invariants entry}}
+##### Scenario: {{name}}
+- **GIVEN** {{...}} **WHEN** {{...}} **THEN** {{...}}
+
+### Modified
+<!-- Same shape as Added — the stable ID names the requirement that changed. -->
+
+### Removed
+#### Requirement: {{title}} ({{stable ID}})
+{{why it was removed}}
+
+### Renamed
+- {{old title}} ({{old ID}}) → {{new title}} ({{new ID}})
 
 ## Intent
 {{Why this slice exists — the user or business goal it serves, in one or two sentences. Note the

package/.claude/skills/event-modeling/templates/state.md

@@ -7,7 +7,7 @@ Keep it current at the end of every working session.
 # Event Modeling Progress — {{Model Name}}
 
 - **Model file:** `{{model-name}}.em`
-- **Current phase:** {{extract | discover | model | slice}}
+- **Current phase:** {{discover | extract | model | slice | implement | conform | review | validate}}
 - **Current step:** {{1–7, see methodology; or extraction round R1–R7}}
 - **Last updated:** {{YYYY-MM-DD}}
 - **Last conformance:** {{YYYY-MM-DD @ <target-repo revision> — report: conformance/<date>-report.md | never}}
@@ -50,10 +50,11 @@ Keep it current at the end of every working session.
 
 ## Usage log
 <!-- The team's only usage signal today (see docs/usage-data.md) — cheap and coarse on purpose.
-     One line per session: phase(s) touched, and validate diagnostic *categories* hit (the rule
-     name from docs/validation.md's tables, e.g. "read model nothing consumes" — never the full
-     instance message or any domain content). Append, never edit past entries. -->
-- {{YYYY-MM-DD}}: phases: {{discover | extract | model | slice | conform | review | validate | watch, ...}} — validate: {{diagnostic category (docs/usage-data.md#categories), ... | none}}
+     One line per session: phase(s) touched, and validate diagnostic *categories* hit (one of
+     the exact fixed strings in docs/usage-data.md#categories, e.g. "read model has no
+     consumer" — never the full instance message or any domain content). Append, never edit
+     past entries. -->
+- {{YYYY-MM-DD}}: phases: {{discover | extract | model | slice | implement | conform | review | validate | watch, ...}} — validate: {{diagnostic category (docs/usage-data.md#categories), ... | none}}
 
 ## Open questions / parking lot
 <!-- Unresolved items to bring back to the user. Never guess these. Metadata is optional and

package/README.md

@@ -84,6 +84,7 @@ built this way.
 |---|---|
 | [docs/tutorial.md](docs/tutorial.md) | Learn the tool by building a model from scratch |
 | [docs/workflow.md](docs/workflow.md) | The model lifecycle: specify, gate, hand off, track change, detect drift |
+| [docs/process.md](docs/process.md) | Who does what: where humans are required, where agents work with review |
 | [docs/patterns.md](docs/patterns.md) | The four Event Modeling patterns and their DSL shapes |
 | [docs/dsl.md](docs/dsl.md) | Full DSL reference: keywords, `from`, `again`, fields, notes |
 | [docs/cli.md](docs/cli.md) | Every command and flag |

package/dist/catalog/build.d.ts

@@ -1,5 +1,6 @@
 import { NormalizedModel } from "../model/model.js";
 import { Grid } from "../layout/grid.js";
+import { RefsResult } from "../model/refs.js";
 import { Diagnostic } from "../model/validate.js";
 export interface CatalogModelInput {
     /** The .em file as given on the command line — used for the doc-discovery path and display. */
@@ -7,6 +8,10 @@ export interface CatalogModelInput {
     model: NormalizedModel;
     grid: Grid;
     dot: string;
+    /** Already-computed by the same `compile()` call that produced `model`/`grid` (MIL-91) —
+     *  never recomputed here, so its ref-collision diagnostics (already in `compile()`'s own
+     *  `diagnostics`) aren't emitted a second time. */
+    refs: RefsResult;
 }
 export interface CatalogOptions {
     outDir: string;

package/dist/catalog/build.js

@@ -15,7 +15,6 @@ import { copyFile, mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { layoutDot, composeSvg, writeRendered } from "../render/render.js";
 import { buildSliceDiagram } from "../render/sliceDiagram.js";
-import { computeRefs } from "../emit/json.js";
 import { dedupe, kebabSlug } from "../util/slug.js";
 import { classifySlicePattern } from "./classify.js";
 import { parseSliceDoc } from "./sliceDoc.js";
@@ -29,7 +28,7 @@ export async function buildCatalog(inputs, opts) {
     const modelSummaries = [];
     const diagnostics = [];
     let sliceCount = 0;
-    for (const { file, model, grid, dot } of inputs) {
+    for (const { file, model, grid, dot, refs } of inputs) {
         const modelKey = dedupe(kebabSlug(basename(file, extname(file))), usedModelKeys, "~");
         const modelDir = join(outDir, modelKey);
         const slicesDir = join(modelDir, "slices");
@@ -40,7 +39,6 @@ export async function buildCatalog(inputs, opts) {
         const raw = await layoutDot(dot);
         const mainSvg = composeSvg(raw, model, grid, dirname(file), modelDir);
         await writeRendered(mainSvg, join(modelDir, diagramFile), format);
-        const refs = computeRefs(model);
         if (refs.diagnostics.length > 0)
             diagnostics.push({ file, diagnostics: refs.diagnostics });
         const sliceSummaries = [];

package/dist/catalog/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/catalog/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/catalog/build.ts"],"names":[],"mappings":"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"}

package/dist/catalog/docJoin.d.ts

@@ -0,0 +1,39 @@
+import { Slice } from "../model/model.js";
+import { Diagnostic } from "../model/validate.js";
+import { DriftSignalKind } from "./driftSignal.js";
+import { SliceRef } from "./sliceDoc.js";
+export type DocReason = "no-doc-bound" | "binding-missing-file" | "frontmatter-invalid" | null;
+/** A slice's export-facing doc join — always a non-null object (never JSON `null`), matching
+ *  every other optional field in `em export`'s style: explicit-null-on-a-stable-key, never a
+ *  nullable wrapper. `reason` is null exactly when `found` is true and the frontmatter parsed
+ *  cleanly; otherwise it names which of the three broken states applies. */
+export interface SliceDocExport {
+    found: boolean;
+    /** The conventional path (`slices/<sliceKey>.md`), always present regardless of `found` —
+     *  the path a doc would need to exist at, and (when `found`) the path it was read from. */
+    path: string;
+    reason: DocReason;
+    status: string | null;
+    version: number | null;
+    implementedIn: string | null;
+    splitFrom: SliceRef | null;
+    mergedFrom: SliceRef[];
+    supersededBy: SliceRef[];
+    /** Implementation-drift classification (MIL-85), from `status`+`implementedIn` alone — see
+     *  catalog/driftSignal.ts. Null only when `found` is false (nothing to classify); paired with
+     *  `version` above from the same doc parse — a finding built from `driftSignal` should always
+     *  cite `version` alongside it, never cache one without the other. */
+    driftSignal: DriftSignalKind | null;
+}
+export interface SliceDocJoinResult {
+    doc: SliceDocExport;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Resolve one slice's doc join. `baseDir` is the `.em` file's directory (doc paths, like note
+ * paths everywhere else in em, are relative to it). `sliceRef`/`elementRefOf` supply the
+ * export-stable refs (from the same `computeRefs()` result `em export`'s per-element/slice
+ * entries use) so the returned diagnostics point at the same identities every other export
+ * diagnostic does — never a second identifier scheme.
+ */
+export declare function resolveSliceDocJoin(slice: Slice, sliceKey: string, baseDir: string, elementRefOf: (id: string) => string): SliceDocJoinResult;

package/dist/catalog/docJoin.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+// The `em export` slice-doc join (MIL-91): for each slice, resolve whether a design doc was
+// declared, found, and well-formed, and if so pull its canonical frontmatter fields into the
+// export JSON. Used ONLY by `em export` (src/emit/json.ts) — `em catalog`'s own doc lookup
+// (catalog/build.ts) deliberately keeps its simpler existsSync+parseSliceDoc convention: it
+// has a standing tested invariant that catalog's doc discovery ignores `note` entirely
+// (test/catalog.e2e.test.ts), and doesn't need this module's 3-state reason granularity. The
+// underlying read (`readSliceDoc.ts`) is shared with `em diff`'s lineage annotation
+// (model/diff.ts) and `em validate`'s lineage-ref resolution (catalog/lineageValidate.ts,
+// MIL-84) — this module's `note`-binding gate and 3-state `DocReason` stay export-specific.
+//
+// Three states (MIL-91): the `note "slices/<name>.md"` binding on an element is the
+// load-bearing fact — binding a note IS the ratified declaration that a doc should exist. No
+// note binding is a normal, unremarkable state (a slice that hasn't reached specify yet); a
+// binding pointing at a missing file, or a doc whose frontmatter is missing or malformed, are
+// both broken-contract states and warn.
+import { makeDiag } from "../model/rules.js";
+import { classifyImplementationDrift } from "./driftSignal.js";
+import { readSliceDoc } from "./readSliceDoc.js";
+import { hasUsableFrontmatter } from "./sliceDoc.js";
+const EMPTY_CONTENT = {
+    status: null,
+    version: null,
+    implementedIn: null,
+    splitFrom: null,
+    mergedFrom: [],
+    supersededBy: [],
+    driftSignal: null,
+};
+/**
+ * Resolve one slice's doc join. `baseDir` is the `.em` file's directory (doc paths, like note
+ * paths everywhere else in em, are relative to it). `sliceRef`/`elementRefOf` supply the
+ * export-stable refs (from the same `computeRefs()` result `em export`'s per-element/slice
+ * entries use) so the returned diagnostics point at the same identities every other export
+ * diagnostic does — never a second identifier scheme.
+ */
+export function resolveSliceDocJoin(slice, sliceKey, baseDir, elementRefOf) {
+    const path = `slices/${sliceKey}.md`;
+    const boundEls = slice.elements.filter((el) => el.note === path);
+    if (boundEls.length === 0) {
+        return { doc: { found: false, path, reason: "no-doc-bound", ...EMPTY_CONTENT }, diagnostics: [] };
+    }
+    const parsed = readSliceDoc(baseDir, sliceKey);
+    if (!parsed) {
+        return {
+            doc: { found: false, path, reason: "binding-missing-file", ...EMPTY_CONTENT },
+            diagnostics: [
+                makeDiag("binding-missing-file", {
+                    message: `slice "${slice.name}" notes "${path}" but no such file exists`,
+                    line: boundEls[0].line,
+                    refs: [sliceKey, ...boundEls.map((el) => elementRefOf(el.id))],
+                }),
+            ],
+        };
+    }
+    if (!hasUsableFrontmatter(parsed)) {
+        return {
+            doc: { found: true, path, reason: "frontmatter-invalid", ...EMPTY_CONTENT },
+            diagnostics: [
+                makeDiag("frontmatter-invalid", {
+                    message: parsed.frontmatterPresent
+                        ? `slice doc "${path}" is missing required frontmatter keys: ${parsed.missingRequiredFields.join(", ")}`
+                        : `slice doc "${path}" has no frontmatter block`,
+                    line: slice.line,
+                    refs: [sliceKey],
+                }),
+            ],
+        };
+    }
+    return {
+        doc: {
+            found: true,
+            path,
+            reason: null,
+            status: parsed.status,
+            version: parsed.version,
+            implementedIn: parsed.implementedIn,
+            splitFrom: parsed.splitFrom,
+            mergedFrom: parsed.mergedFrom,
+            supersededBy: parsed.supersededBy,
+            driftSignal: classifyImplementationDrift(parsed),
+        },
+        diagnostics: [],
+    };
+}
+//# sourceMappingURL=docJoin.js.map

package/dist/catalog/docJoin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docJoin.js","sourceRoot":"","sources":["../../src/catalog/docJoin.ts"],"names":[],"mappings":"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"}

package/dist/catalog/driftSignal.d.ts

@@ -0,0 +1,16 @@
+import { SliceDoc } from "./sliceDoc.js";
+export type DriftSignalKind = 
+/** status: implemented, implementedIn set — normal shipped state. */
+"in-sync"
+/** status not implemented, implementedIn absent — normal pre-ship state. */
+ | "never-implemented"
+/** status not implemented, implementedIn still set — a ratified delta hasn't shipped yet.
+ *  Expected, not a defect: never surface this as fresh drift or a validate diagnostic. */
+ | "unpropagated-delta"
+/** status: implemented, implementedIn absent — genuine incoherence (em validate warns). */
+ | "implemented-without-link";
+/**
+ * Classify a doc's status/implementedIn pair. Takes a `Pick` rather than the full `SliceDoc` so
+ * callers building a partial/synthetic doc (tests, future callers) don't need every field.
+ */
+export declare function classifyImplementationDrift(doc: Pick<SliceDoc, "status" | "implementedIn">): DriftSignalKind;

package/dist/catalog/driftSignal.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// Classifies a slice doc's implementation-drift state from `status` + `implementedIn` alone
+// (MIL-85). Pure — same spirit as sliceDoc.ts itself: no fs, no model, no baseDir — so
+// `em export`'s doc join (catalog/docJoin.ts), `em validate`'s frontmatter-coherence check
+// (catalog/frontmatterCoherenceValidate.ts), and the conform skill (reading `em export --json`'s
+// `slice.doc.driftSignal`) all consume the exact same answer instead of re-deriving this
+// predicate three different ways.
+//
+// The load-bearing distinction (docs/slice-doc-schema.md, "`status` under re-ratification"):
+// re-ratifying a shipped slice flips `status` back off `implemented` while `implementedIn` keeps
+// naming the prior version's PR. That combination — `unpropagated-delta` — is the EXPECTED drift
+// signal, not staleness, and must never be flagged as incoherence. Only `implemented-without-link`
+// (status: implemented, no link at all) is a genuine coherence problem worth a diagnostic.
+/**
+ * Classify a doc's status/implementedIn pair. Takes a `Pick` rather than the full `SliceDoc` so
+ * callers building a partial/synthetic doc (tests, future callers) don't need every field.
+ */
+export function classifyImplementationDrift(doc) {
+    const hasLink = typeof doc.implementedIn === "string" && doc.implementedIn.trim().length > 0;
+    if (doc.status === "implemented")
+        return hasLink ? "in-sync" : "implemented-without-link";
+    return hasLink ? "unpropagated-delta" : "never-implemented";
+}
+//# sourceMappingURL=driftSignal.js.map

package/dist/catalog/driftSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driftSignal.js","sourceRoot":"","sources":["../../src/catalog/driftSignal.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,4FAA4F;AAC5F,uFAAuF;AACvF,2FAA2F;AAC3F,iGAAiG;AACjG,yFAAyF;AACzF,kCAAkC;AAClC,EAAE;AACF,6FAA6F;AAC7F,iGAAiG;AACjG,iGAAiG;AACjG,mGAAmG;AACnG,2FAA2F;AAe3F;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAA+C;IACzF,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7F,IAAI,GAAG,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC;IAC1F,OAAO,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,mBAAmB,CAAC;AAC9D,CAAC"}

package/dist/catalog/frontmatterCoherenceValidate.d.ts

@@ -0,0 +1,8 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { Diagnostic } from "../model/validate.js";
+/**
+ * Resolve every slice's doc and flag genuine status/implementedIn incoherence. `baseDir` is the
+ * `.em` file's directory (doc paths, like every other doc/note path in em, are relative to it).
+ */
+export declare function validateFrontmatterCoherence(model: NormalizedModel, refs: RefsResult, baseDir: string): Diagnostic[];