@warpgogol/forge 2.8.0 → 2.8.2

package/skills/_shared/fo-session-summary.md

@@ -22,34 +22,122 @@ The closing block MUST use `aiLanguage` (from `PREFERENCES.md`), same as all oth
 
 **All labels and headings in the closing block must be translated to `aiLanguage`.** The structural format below uses placeholder labels — replace them with the equivalent in the operator's language. Only slash commands and document identifiers (RFC-XXXX, ADR-XXXX, file paths) stay in their original form.
 
-## Closing block format
+## Engineering Checkpoint protocol (RFC-0884)
+
+The closing block has two modes. The agent selects the mode based on what the session changed:
+
+- **Lightweight mode** — for sessions that do not change system structure (typo fixes, small refactors, document edits, read-only exploration). Uses a 3-section format.
+- **Full mode** — for sessions that change architecture, runtime flow, state machines, persistence models, or public contracts. Uses a 6-section format with an optional Mermaid diagram.
+
+### Mode selection
+
+The agent analyzes the session's changes to determine which mode to use. The decision is based on **what changed in the system**, not on the session's chronology:
+
+- If the session changed any of: architecture, component relationships, runtime flow, state machines, persistence models, public contracts, schemas, invariants, pipeline topology → **full mode**.
+- Otherwise → **lightweight mode**.
+
+When in doubt, use lightweight mode. A full checkpoint for a session that made no structural changes adds noise without value.
+
+### Diagram selection rules
+
+When using **full mode**, the agent MUST analyze the session's changes to determine if a Mermaid diagram is warranted.
+
+| Change type | Diagram type | When to use |
+| --- | --- | --- |
+| Architecture / component relationships | `flowchart` | Components, modules, packages, and their dependencies changed |
+| Runtime interaction / request flow | `sequenceDiagram` | New or changed runtime interaction between components, services, or external systems |
+| Lifecycle / state machine | `stateDiagram-v2` | State transitions, mission lifecycle, release states, or protocol states changed |
+| Entities / persistence model | `erDiagram` | Data models, entity relationships, schema changes, storage contracts |
+| Pipeline / dependency chain | `flowchart` | Build pipeline, validation pipeline, deployment pipeline changed |
+| Quantitative results (performance, coverage, benchmarks) | markdown table | Measurable data exists that is clearer as a table than prose |
+| No structural change | _(none)_ | Session did not change system structure, runtime flow, state, or persistence |
+
+**Diagram rules:**
+
+1. **Do not draw a diagram merely to satisfy the requirement.** If no meaningful visualization is warranted, explicitly state: "No diagram: this session did not change system structure, runtime flow, state transitions, persistence relationships, or other relationships that would be clearer visually."
+2. **Diagram shows resulting state, not work chronology.** The diagram depicts the system AFTER changes, not the sequence of edits the agent made.
+3. **At most one diagram per closing block.** If multiple structural changes occurred, pick the one that most reduces cognitive load. Additional diagrams may appear in the session file or handoff document.
+4. **CURRENT vs SESSION DELTA.** For large systems where the full architecture is too complex, the agent may draw a session-delta diagram (only the changed subgraph) instead of the full current-system diagram. If a delta diagram is used, label it as "session delta" and reference the full system context.
+5. **Mermaid syntax only.** Diagrams use Mermaid text syntax (`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`) so they are Git-versionable and diffable.
+6. **Quantitative charts are markdown tables.** No image rendering infrastructure is added. If measurable data exists (test counts, coverage %, performance ms), present it as a markdown table with a caption.
+
+### Quality test self-check
+
+After composing the Engineering Checkpoint (either mode), the agent performs a self-check:
+
+> "Can another engineer understand the resulting system state from this checkpoint alone, without reading the full session transcript?"
+
+If the answer is no, the agent improves the checkpoint before presenting it. This is a semantic check performed by the agent, not an automated validation.
+
+## Closing block format — Full mode
+
+Use when the session changed architecture, runtime flow, state machines, persistence models, or public contracts.
 
 ```
 ---
 
-**<Summary label in aiLanguage>**
+**<Completed label in aiLanguage>**
+
+<1–3 sentences: what was implemented — concretely, with document ids, commit count, review verdict. No filler.>
+
+**<System Delta label in aiLanguage>**
+
+<Changed public contracts, schemas, APIs, state machines, invariants, persistence models, file surfaces. Grouped by category. Each item links to the source file or commit.>
+
+**<Resulting Architecture label in aiLanguage>**
+
+<Mermaid diagram of the system state AFTER changes — only when it reduces cognitive load vs text. See diagram selection rules. If no diagram is warranted, state: "No diagram: this session did not change system structure, runtime flow, state transitions, persistence relationships, or other relationships that would be clearer visually.">
+
+**<Verification label in aiLanguage>**
+
+<Tests executed, type checking, build status, relevant deterministic/recovery/integration checks, important observed results. Each claim links to evidence: test file:line, command output, or commit.>
+
+**<Remaining Issues label in aiLanguage>**
 
-<1–3 sentences in aiLanguage: what was done in this session — concretely, with document ids, commit count, review verdict. No filler.>
+<Known limitations, unverified assumptions, open questions, technical debt introduced. Be honest — this is the uncertainty map.>
 
-**<Next steps label in aiLanguage>**
+**<Next Step label in aiLanguage>**
 
 - `/fo-idea-audit RFC-XXXX` — <one line in aiLanguage: why>
 - `/fo-idea-enhance RFC-XXXX` — <one line in aiLanguage: why>
-- `/fo-idea-implement RFC-XXXX` — <one line in aiLanguage: why>
+```
+
+## Closing block format — Lightweight mode
+
+Use for sessions that do not change system structure (typo fixes, small refactors, document edits, read-only exploration).
+
+```
+---
+
+**<Completed label in aiLanguage>**
+
+<1–3 sentences: what was done.>
+
+**<Verification label in aiLanguage>**
+
+<Tests/typecheck/build status — one line.>
+
+**<Next Step label in aiLanguage>**
+
+- `/fo-idea-status` — <one line in aiLanguage: why>
 ```
 
 ### Rules
 
-1. **Summary** — 1–3 concise sentences in `aiLanguage`. State what was done: document ids, commit count, review verdict, key outcomes. No filler, no repetition of the batch summary — the summary is the _essence_.
-2. **Next steps** — a bulleted list of 1–3 items. Each item is a copy-pasteable slash-command invocation followed by a short `aiLanguage` explanation of why the operator might want to run it.
-3. **Only relevant commands** — list only skills that are genuinely applicable as the next step given the current state. Do not list commands that were already completed or that do not apply. If the skill is terminal (e.g. `fo-idea-status` is read-only), list 0–1 relevant follow-up commands.
-4. **Copy-pasteable** — the slash command must be the exact invocation string the operator can paste into chat. Include the document id if known.
-5. **No more than 3 items** — the operator should not be overwhelmed. Pick the most relevant next steps.
-6. **Translate labels** — the section headings ("Summary", "Next steps") must be in `aiLanguage`, not English. Only slash commands and identifiers stay untranslated.
+1. **Completed** — 1–3 concise sentences in `aiLanguage`. State what was done: document ids, commit count, review verdict, key outcomes. No filler, no repetition of the batch summary — the summary is the _essence_.
+2. **System Delta** (full mode only) — changed public contracts, schemas, APIs, state machines, invariants, persistence models, file surfaces. Grouped by category. Each item links to the source file or commit.
+3. **Resulting Architecture** (full mode only) — optional Mermaid diagram of the system state AFTER changes. Follow the diagram selection rules. If no diagram is warranted, state explicitly.
+4. **Verification** — tests executed, type checking, build status, relevant checks. Each claim links to evidence. In lightweight mode, this is one line.
+5. **Remaining Issues** (full mode only) — known limitations, unverified assumptions, open questions, technical debt introduced.
+6. **Next Step** — a bulleted list of 1–3 items. Each item is a copy-pasteable slash-command invocation followed by a short `aiLanguage` explanation of why the operator might want to run it.
+7. **Only relevant commands** — list only skills that are genuinely applicable as the next step given the current state. Do not list commands that were already completed or that do not apply.
+8. **Copy-pasteable** — the slash command must be the exact invocation string the operator can paste into chat. Include the document id if known.
+9. **No more than 3 items** — the operator should not be overwhelmed. Pick the most relevant next steps.
+10. **Translate labels** — the section headings must be in `aiLanguage`, not English. Only slash commands and identifiers stay untranslated.
 
 ### Examples
 
-**After `fo-idea-create-rfc` completes (aiLanguage = ru):**
+**After `fo-idea-create-rfc` completes (lightweight mode, aiLanguage = ru):**
 
 ```
 ---
@@ -58,34 +146,62 @@ The closing block MUST use `aiLanguage` (from `PREFERENCES.md`), same as all oth
 
 Создан драфт RFC-0380 «Standardize kernel execution reports» (status: draft, 1 коммит). `rfc.validate` проходит без нарушений. Документ ожидает архитектурного ревью.
 
+**Проверка**
+
+`rfc.validate` — 0 нарушений.
+
 **Дальнейшие шаги**
 
 - `/fo-idea-audit RFC-0380` — семантический аудит RFC перед энхансментом
 - `/fo-idea-i-just-want-to-see-the-result RFC-0380` — полный пайплайн до реализации
 ```
 
-**After `fo-idea-implement` completes (aiLanguage = en):**
+**After `fo-idea-implement` completes (full mode, aiLanguage = en):**
 
 ```
 ---
 
-**Summary**
+**Completed**
 
 RFC-0377 implemented: 4 plan steps, 3 commits, scoped build — pass. Review: approved (0 findings). Status: implemented (2026-07-13).
 
+**System Delta**
+
+- **Schemas**: `SessionFrontmatter` extended with `systemDelta`, `diagrams`, `evidence`, `remainingIssues`, `checkpoint` optional fields (`packages/forge/os/session/types.ts:100-117`)
+- **Validation**: SES-06 warning rule added to `session.validate` (`packages/forge/os/session/handlers/validate.ts:166-186`)
+- **Skills**: `fo-session-summary.md` restructured with lightweight and full checkpoint modes
+
+**Resulting Architecture**
+
+No diagram: this session changed types and skill markdown only, not system structure, runtime flow, state transitions, or persistence relationships.
+
+**Verification**
+
+- `pnpm --filter @warpgogol/forge run build:check` — pass
+- `rfc.validate --id RFC-0377` — 0 violations
+- `forge.skill.validate` — 0 violations
+
+**Remaining Issues**
+
+None. All acceptance criteria met.
+
 **Next steps**
 
 - `/fo-idea-status` — overview of current RFC/ADR statuses
 ```
 
-**After `fo-review` completes (aiLanguage = ru):**
+**After `fo-review` completes (lightweight mode, aiLanguage = ru):**
 
 ```
 ---
 
 **Сводка**
 
-Ревью кода завершено: вердикт needs-revision, 3 замечания (Axis B: DNA-23 нарушение, Axis D: legacy путь, Axis E: нет Compass-разметки). Отчёт сохранён в docs/reviews/code/packages-os-site-kernel-checks/.
+Ревью кода завершено: вердикт needs-revision, 3 замечания (Axis B: DNA-23 нарушение, Axis D: legacy путь, Axis E: нет Compass-разметки). Отчёт сохранён в docs/reviews/code/packages-werkstatt-site/.
+
+**Проверка**
+
+Ревью завершено, замечания задокументированы.
 
 **Дальнейшие шаги**
 

package/skills/fo/fo-add-tests/pbt-guide.md

@@ -178,16 +178,16 @@ test("compareSemver is antisymmetric: compare(a, b) == -compare(b, a)", () => {
 
 | Function | Package | Property | Pattern |
 | --- | --- | --- | --- |
-| `normalizeText` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
-| `normalizeHtml` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
-| `normalizeMarkdown` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
-| `normalizeJson` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
-| `compareSemver` | `@warpgogol/site-kernel-handoff` | `a < b and b < c implies a < c` | Transitivity |
-| `compareSemver` | `@warpgogol/site-kernel-handoff` | `compare(a, b) == -compare(b, a)` | Antisymmetry |
-| `parseSemver` / `formatSemver` | `@warpgogol/site-kernel-handoff` | `parse(format(parsed)) == parsed` | Round-trip |
-| `substituteRefsDeep` | `@warpgogol/share` | Input is not mutated after call | Immutability |
-| `markdownTwinRelPath` | `@warpgogol/share` | `twinUrlPath(twinRelPath(x))` is consistent for valid paths | Round-trip |
-| `deepMergeEntryData` | `@warpgogol/share` | Merge is associative for nested objects (not arrays) | Associativity |
-| `citySlug` | `@warpgogol/geo` | Output only contains lowercase alphanumeric and hyphens | Invariance |
-| `redactUrl` | `@warpgogol/observability` | Output never contains a query string | Invariance |
-| `validateAgainstCapabilitySchema` | `@warpgogol/agent-gate` | Non-object input always fails validation | Invariance |
+| `normalizeText` | `@warpgogol/werkstatt-shared` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeHtml` | `@warpgogol/werkstatt-shared` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeMarkdown` | `@warpgogol/werkstatt-shared` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeJson` | `@warpgogol/werkstatt-shared` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `compareSemver` | `@warpgogol/werkstatt` | `a < b and b < c implies a < c` | Transitivity |
+| `compareSemver` | `@warpgogol/werkstatt` | `compare(a, b) == -compare(b, a)` | Antisymmetry |
+| `parseSemver` / `formatSemver` | `@warpgogol/werkstatt` | `parse(format(parsed)) == parsed` | Round-trip |
+| `substituteRefsDeep` | `@warpgogol/werkstatt-shared` | Input is not mutated after call | Immutability |
+| `markdownTwinRelPath` | `@warpgogol/werkstatt-shared` | `twinUrlPath(twinRelPath(x))` is consistent for valid paths | Round-trip |
+| `deepMergeEntryData` | `@warpgogol/werkstatt-shared` | Merge is associative for nested objects (not arrays) | Associativity |
+| `citySlug` | `@warpgogol/werkstatt-site` | Output only contains lowercase alphanumeric and hyphens | Invariance |
+| `redactUrl` | `@warpgogol/werkstatt-shared` | Output never contains a query string | Invariance |
+| `validateAgainstCapabilitySchema` | `@warpgogol/werkstatt` | Non-object input always fails validation | Invariance |

package/skills/fo/fo-doc-audit/SKILL.md

@@ -33,7 +33,7 @@ The ecosystem has seven documentation surfaces. Each has a different audience an
 | **README** | root, `packages/*/README.md`, `services/*/README.md` | Humans (developers, operators) | Public API, CLI surface, usage pattern, or installation flow change |
 | **Compass XML** | `docs/requirements.xml`, `docs/technology.xml`, `docs/development-plan.xml`, `docs/knowledge-graph.xml`, `docs/verification-plan.xml`, `docs/source-markup.xml` | AI agents (machine-readable semantic layer) | Repository-wide requirements, shared package contracts, app-package relationships, verification policy |
 | **architecture-dna.md** | `ref(forge.yaml bindings.paths.invariantsFile)` | AI agents + humans | New DNA invariant, invariant amendment, or invariant retirement |
-| **Templates** | `packages/os/site-kernel-onboarding/src/templates/`, `packages/os/site-kernel-codegen/src/templates/` | Future apps/packages (scaffold time) | Change to what a new app or package should look like at creation time |
+| **Templates** | `packages/werkstatt-site/src/onboarding/templates/`, `packages/werkstatt-site/src/codegen/templates/` | Future apps/packages (scaffold time) | Change to what a new app or package should look like at creation time |
 | **Generated artifacts** | `docs/ecosystem.generated.json`, `docs/command-manifest.generated.yaml`, `fleet/*.generated.yaml`, `*.generated.css` | AI agents (read-only projection) | **Never edit directly** — update the generator or registry, then regenerate |
 | **COMMANDS / PACKAGE_GRAPH** | `docs/COMMANDS.md`, `docs/PACKAGE_GRAPH.md` | Humans + AI agents | New command, removed command, package graph change |
 
@@ -52,7 +52,7 @@ Capture the full list of changed files and categorize them:
 - **Code** — `.ts`, `.js`, `.mjs`, `.astro`, `.css`, `.json`, `.yaml`, etc.
 - **Content** — `src/content/**/*.md`, `src/content/**/*.yaml`.
 - **Docs** — `docs/**/*.md`, `docs/**/*.xml`, `AGENTS.md`, `README.md`.
-- **Templates** — files under `packages/os/site-kernel-*/src/templates/`.
+- **Templates** — files under `packages/werkstatt-site/src/onboarding/templates/` and `packages/werkstatt-site/src/codegen/templates/`.
 - **Generated** — `*.generated.*`, `fleet/*.generated.*`.
 
 ### 2. Run impact analysis
@@ -115,7 +115,7 @@ If yes, update `ref(forge.yaml bindings.paths.invariantsFile)`. If a new invaria
 - Did a **boilerplate file, script, or config** pattern change that onboarding/codegen templates should reflect?
 - Did a **new convention** get introduced that future apps/packages must follow from creation?
 
-If yes, update the **template** files in `packages/os/site-kernel-onboarding/src/templates/` and `packages/os/site-kernel-codegen/src/templates/`. **Never edit generated output in existing apps** — fix the template, then regenerate if needed.
+If yes, update the **template** files in `packages/werkstatt-site/src/onboarding/templates/` and `packages/werkstatt-site/src/codegen/templates/`. **Never edit generated output in existing apps** — fix the template, then regenerate if needed.
 
 #### 2f. Generated artifacts
 
@@ -150,8 +150,8 @@ Present the impact analysis as a concise table before applying any changes. This
 | Surface | Needs update? | Reason |
 | --- | --- | --- |
 | AGENTS.md (root) | Yes | New command lifecycle rule |
-| AGENTS.md (packages/os/site-kernel) | Yes | New cache module registered |
-| README (packages/os/site-kernel) | No | No public API change |
+| AGENTS.md (packages/werkstatt-site) | Yes | New cache module registered |
+| README (packages/werkstatt-site) | No | No public API change |
 | Compass XML (docs/verification-plan.xml) | Yes | New check pipeline stage |
 | architecture-dna.md | No | No DNA invariant change |
 | Templates | No | No scaffold-time change |
@@ -215,7 +215,7 @@ docs: sync documentation for <feature/RFC>
 - AGENTS.md (root): <what changed>
 - docs/verification-plan.xml: <what changed>
 - docs/COMMANDS.md: <what changed>
-- packages/os/site-kernel/README.md: <what changed>
+- packages/werkstatt-site/README.md: <what changed>
 ```
 
 Stage only the documentation files touched by this step. Do not stage unrelated changes — another agent may be working in a different session; `git add -A` or `git add .` is forbidden.

package/skills/fo/fo-handoff/SKILL.md

@@ -33,6 +33,11 @@ Include:
 - **Suggested skills** — which skills the next agent should invoke and why.
 - **References to existing artifacts** — specs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead of duplicating content.
 - **Current state** — what the codebase looks like now, what's uncommitted, what's in progress.
+- **System State Transition (RFC-0884)** — three prose subsections:
+  - **Before** — state N before the session (what the system looked like before changes)
+  - **Change** — what was done (the key changes made during the session)
+  - **After** — state N+1 after the session (what the system looks like now)
+- **Resulting Architecture (RFC-0884)** — optional Mermaid diagram of the system state AFTER changes, following the diagram selection rules from `_shared/fo-session-summary.md`. If no diagram is warranted, state: "No diagram: this session did not change system structure."
 - **Next steps** — concrete, actionable items the next agent should pick up.
 - **Memory layer pointer** — tell the next agent to read `.agents/memory/MEMORY.md` and recent `.agents/memory/daily/` files for project context.
 

package/skills/fo/fo-idea/SKILL.md

@@ -117,7 +117,7 @@ Use the following decision table:
 These patterns **look like RFCs but are ADRs**:
 
 - **"Applied to all apps" ≠ "cross-workspace contract"** — a convention like "use Fontsource for fonts" or "self-host all web fonts" applies everywhere but does not create a package boundary, inter-package type contract, or new command. It is an ADR with `scope: workspace`.
-- **"Changes a shared package" ≠ "establishes a package boundary"** — extending `packages/os/site-kernel-checks/src/fonts.ts` with a new font family modifies shared code, but the decision is about which fonts to use, not about the package's interface or contract. ADR.
+- **"Changes a shared package" ≠ "establishes a package boundary"** — extending `packages/werkstatt-site/src/domain/ui/fonts.ts` with a new font family modifies shared code, but the decision is about which fonts to use, not about the package's interface or contract. ADR.
 - **"Might be mentioned in AGENTS.md" ≠ "modifies a DNA invariant"** — a decision might be documented in AGENTS.md for visibility, but unless it changes a DNA-NN invariant or a governance rule, it is an ADR.
 - **"Has cross-app impact" ≠ "cross-workspace contract"** — adding a font to the shared registry affects all apps' builds, but the decision itself is a tooling/standard choice, not a contract between packages.
 

package/skills/fo/fo-review/SKILL.md

@@ -233,7 +233,7 @@ Present the findings in this structure in `aiLanguage`. **Translate all labels,
 
 ### 7. Persist the review
 
-Derive the `<module-folder>` from the reviewed files: take the package path with the most changed files and convert it to lowercase kebab-case (for example, `packages/growth` → `packages-growth`, `packages/os/site-kernel-checks` → `packages-os-site-kernel-checks`). For cross-workspace diffs, use the package with the largest number of changed files; list all reviewed files in the `filesReviewed` frontmatter field.
+Derive the `<module-folder>` from the reviewed files: take the package path with the most changed files and convert it to lowercase kebab-case (for example, `packages/growth` → `packages-growth`, `packages/werkstatt-site` → `packages-werkstatt-site`). For cross-workspace diffs, use the package with the largest number of changed files; list all reviewed files in the `filesReviewed` frontmatter field.
 
 Write the report to:
 

package/skills/fo/fo-session-retro/SKILL.md

@@ -435,6 +435,12 @@ If any operator insights were routed to `.agents/operator-profile.md`, offer the
 
 Present a concise summary in `aiLanguage`. **ALL labels, headings, column names, and prose MUST be translated to `aiLanguage`** — the template below is structural only. Only identifiers (file paths, skill names, RFC/ADR ids, commit hashes) stay untranslated. This is non-negotiable: an English summary when `aiLanguage` is `ru` is a violation of this skill's language contract.
 
+**Engineering Checkpoint (RFC-0884):** The closing block follows the Engineering Checkpoint protocol defined in `_shared/fo-session-summary.md`. The agent MUST:
+
+1. **Select mode** — analyze the session's changes. If the session changed architecture, runtime flow, state machines, persistence models, or public contracts, use **full mode** (6 sections). Otherwise, use **lightweight mode** (3 sections).
+2. **Diagram selection** (full mode only) — apply the diagram selection rules table from `_shared/fo-session-summary.md` to determine if a Mermaid diagram is warranted. If no structural change warrants a diagram, explicitly state "No diagram: this session did not change system structure..."
+3. **Quality test self-check** — after composing the checkpoint, ask: "Can another engineer understand the resulting system state from this checkpoint alone, without reading the full session transcript?" If no, improve the checkpoint before presenting it.
+
 ```
 ## <Session Retro Summary in aiLanguage>
 
@@ -455,6 +461,8 @@ Present a concise summary in `aiLanguage`. **ALL labels, headings, column names,
 ### <Commit>: <hash | none — no direct edits>
 ```
 
+After the summary table, emit the **Engineering Checkpoint closing block** following the format in `_shared/fo-session-summary.md` (full or lightweight mode). This closing block IS the session-end output — it replaces any ad-hoc summary.
+
 ## Relationship to other session-end skills
 
 | Skill | Question | Overlap |

package/skills/fo/fo-session-save/SKILL.md

@@ -46,6 +46,14 @@ Enhance saved session transcripts with semantic annotations, summaries, and qual
 
 6. **Update the session file:**
    - Update frontmatter: `summary`, `decisions`, refined `types`, corrected metadata.
+   - **Checkpoint fields (RFC-0884):** When the session produced substantial engineering work, populate the optional checkpoint frontmatter fields:
+     - `checkpoint` — object with `before`, `change`, `after` (each 1-2 sentences describing state N, what was done, state N+1)
+     - `systemDelta` — object with arrays: `changedContracts`, `changedSchemas`, `changedStateMachines`, `changedInvariants`, `changedPersistence`
+     - `diagrams` — array of objects: `type` (flowchart/sequenceDiagram/stateDiagram-v2/erDiagram/none), `scope` (current-system/session-delta), `caption`, `mermaid` (Mermaid syntax or empty string)
+     - `evidence` — array of objects: `claim`, `source` (file:line), `test` (test file:line), `command` (command + result)
+     - `remainingIssues` — array of strings: known limitations, unverified assumptions, open questions
+   - These fields are **optional** — only populate when the session produced substantial engineering work. For lightweight sessions (typo fixes, small refactors), skip them.
+   - The `session.save` deterministic command does NOT populate these — they are agent-populated via this skill or manual editing.
    - Append a `## Session notes` section with structured annotations.
 
 7. **Update knowledge files** with any new insights:

package/src/cli-output.ts

@@ -0,0 +1,59 @@
+/*
+<MODULE_CONTRACT>
+<purpose>CLI output rendering helpers (RFC-0542) — renderNextSteps,
+renderIdeRecommendation, generateHelp. Pure functions, no I/O, no process.exit.
+Importable by bin/cli.ts and unit tests.</purpose>
+<non-goals>
+  <item>Do not call console.log or process.exit — callers handle output.</item>
+  <item>Do not import from bin/ — this is the portable layer.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0542: initial CLI output rendering helpers — renderNextSteps, renderIdeRecommendation, generateHelp.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeNextStep, CommandRegistry } from "./types.ts";
+
+export function renderNextSteps(steps?: ForgeNextStep[]): string {
+  if (!steps || steps.length === 0) return "";
+  const lines = ["\nNext steps:"];
+  for (const step of steps) {
+    const label = step.kind === "required" ? "[must do]" : "[can do]";
+    lines.push(`  • ${step.action}        ${label}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderIdeRecommendation(): string {
+  return "\nRecommended IDE: Windsurf (tested with forge). Other IDEs (VS Code, Cursor)\nwork but are not tested.";
+}
+
+export function generateHelp(registry: CommandRegistry): string {
+  const commands = registry.listCommands().filter((cmd) => !cmd.hidden);
+  const header = `forge — autonomous project tooling
+
+Usage:
+  forge <command> [args...] [--flags...]
+  forge --help <command>    Show per-command flags and description
+
+Flags:
+  --json              Output results as JSON
+  --dry-run           Show what would happen without making changes
+  --site <name>       Target a specific site/app
+  --version           Show forge version
+  --help              Show this help (or per-command help with --help <command>)
+
+Registered commands (${commands.length}):`;
+
+  const commandLines = commands
+    .map((cmd) => {
+      const desc =
+        cmd.description.length > 80 ? cmd.description.slice(0, 77) + "..." : cmd.description;
+      const displayName = cmd.name.replace(/^forge\./, "");
+      return `  ${displayName.padEnd(40)} ${desc}`;
+    })
+    .join("\n");
+
+  return `${header}\n${commandLines}\n`;
+}

package/src/config/__tests__/resolve-terminology.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { resolveTerminology, defaultForgeConfig, type ForgeConfig } from "../forge-config.ts";
+import { TERMINOLOGY_DEFAULTS } from "../../profiles/profile-schema.ts";
+
+describe("resolveTerminology", () => {
+  function makeConfig(terminology?: Record<string, string>): ForgeConfig {
+    const config = defaultForgeConfig("test");
+    if (terminology && config.bindings) {
+      config.bindings.terminology = terminology;
+    }
+    return config;
+  }
+
+  it("returns universal default when no overrides exist", () => {
+    const config = makeConfig();
+    expect(resolveTerminology(config, undefined, "artifact")).toBe(TERMINOLOGY_DEFAULTS.artifact);
+    expect(resolveTerminology(config, undefined, "operator")).toBe(TERMINOLOGY_DEFAULTS.operator);
+  });
+
+  it("returns the key itself when not found in any tier", () => {
+    const config = makeConfig();
+    expect(resolveTerminology(config, undefined, "nonexistent")).toBe("nonexistent");
+  });
+
+  it("tier 1: per-project bindings.terminology overrides everything", () => {
+    const config = makeConfig({ artifact: "widget" });
+    expect(resolveTerminology(config, { artifact: "module" }, "artifact")).toBe("widget");
+  });
+
+  it("tier 2: caller-provided terminology overrides universal default", () => {
+    const config = makeConfig();
+    expect(resolveTerminology(config, { artifact: "custom" }, "artifact")).toBe("custom");
+  });
+
+  it("tier 3: universal default used when tiers 1 and 2 are absent", () => {
+    const config = makeConfig();
+    expect(resolveTerminology(config, undefined, "module")).toBe(TERMINOLOGY_DEFAULTS.module);
+  });
+
+  it("handles undefined bindings entirely", () => {
+    const config = defaultForgeConfig("test");
+    delete config.bindings;
+    expect(resolveTerminology(config, { artifact: "thing" }, "artifact")).toBe("thing");
+  });
+});