sdd-mcp-server 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [5.5.0] - 2026-10-20
+
+### Added
+- Add opt-in, advisory JEV checks that call the TypeSafe Jev decision API. They judge requirements testability, design-to-requirement fidelity, planned test cases, RED validity, security finding triage, and coding-principle adherence. JEV is off by default. It needs `SDD_JEV_ENABLED` (or `.spec/sdd-config.json`) and `SDD_JEV_API_KEY`. Code excerpts need the separate `SDD_JEV_ALLOW_CODE`.
+- Add the `sdd-jev-check` MCP tool, the 17th tool. It never changes `spec.json`, approval, validation, or the next action. Results are saved as sidecar files bound to the artifact revision and SHA-256.
+- Add a local RED classifier. It flags setup failures such as `Cannot find module` and `TS2304` without any request.
+- Redact secrets from every JEV request, bound excerpts to 15 lines around a finding and 8 KB per request, and never send `.env*` files, keys, lockfiles, or generated output.
+- Add an optional `baseRef` input to the `security` and `principles` checks of `sdd-jev-check`. A PR or branch review can now judge already-committed changes: the change set is everything that differs between the merge base of `baseRef` and `HEAD`, and the working tree. `baseRef` is validated before any Git command runs and resolved with read-only Git (`--end-of-options`, Git 2.30 or later). A bad ref gives a `skipped` result with the reason `invalid-base-ref`. Without `baseRef`, behavior is unchanged.
+- Committed-range results are saved as `jev-review-<kind>-range-<hash>.json`, bound to the merge-base commit, the `HEAD` commit, and the diff hash. `sdd-commit` still matches staged diffs only.
+
+### Changed
+- The tool contract grows from 16 to 17 tools. The 16 existing tools keep their inputs and outputs.
+- Seven Skills (`sdd-requirements`, `sdd-design`, `sdd-tasks`, `sdd-implement`, `sdd-review`, `sdd-security-check`, `sdd-commit`) show at most one JEV line. `sdd-commit` only reads a saved sidecar.
+- `sdd-security-check` and the `security-auditor` agent now forbid contact with the audited target or its systems. The agent still has no network access. Only the parent may make the opt-in JEV triage call.
+- The installer git-ignores code-review sidecars (`.spec/reviews/` and `jev-review-*`).
+- `.claude-plugin/plugin.json` now lists `sdd-review-test-cases` and `sdd-jev-check`.
+- JEV score answers are zero-based only: an integer from 0 to the index of the last level. Any other value is `invalid-response`. Sidecars no longer record a score base. The question-set version is now 3, so JEV ignores sidecars saved by earlier versions.
+- `sdd-review` and `sdd-security-check` pass the PR or branch base as `baseRef` when they run the JEV code checks.
+
+### Fixed
+- `sdd-status`, `sdd-context-load`, and other reads of a missing feature no longer create an empty `.spec/specs/<feature>/` folder. They report `Feature metadata not found` as before.
+- `sdd-init` now accepts an empty feature folder left behind by earlier versions. It still rejects a folder that contains files with `Feature already exists`.
+
+- `sdd-jev-check` no longer reports `unavailable (invalid-response)` against the real TypeSafe Jev API (model `jev-1.13.0`). The response validator now accepts the real answer shape: `type`, `confidence`, `legend`, `probabilities`, and unknown extra fields. A `type` that differs from the question type, a `legend` with a different number of levels, a `choice` outside the question labels, and a `noul` outside 0 to 1 are still `invalid-response`.
+- A score level is now the highest-probability entry of `probabilities` (ties go to the lowest index) when that object is valid, and `round(score)` otherwise. The level must stay within 0 to the last level index. The raw fractional score is kept, and sidecars accept it. The question-set version stays 3 and the sidecar schema stays 1, because the questions and the stored fields do not change.
+
+### Documentation
+- Add the Optional JEV advisory section to `docs/WORKFLOW.md`. Update the tool count in the README and `ARCHITECTURE.md`.
+
+## [5.4.0] - 2026-10-04
+
+### Added
+- Add the `output-clarity-ladder` skill. It applies to explanation, summary, and teaching replies. It writes about 80% of the way to ASD-STE100. It moves to a diagram, HTML page, or explainer video only when that format makes the same facts easier to understand.
+- Ship Japanese (`references/ja.md`) and Traditional Chinese (`references/zh-TW.md`) guidance with the skill. Other languages use the English rules.
+
+### Changed
+- `output-clarity-ladder` is the only model-invocable skill. Claude Code and OMP render it without `disable-model-invocation`. Codex renders `allow_implicit_invocation: true`. All workflow skills stay manual-only.
+- Root guidance and the `CLAUDE.md` and `AGENTS.md` templates name the skill in one sentence.
+- Validation blockers and recoverable runtime errors state the fact, then the next action. Each message has at most 2 sentences and at most 25 words per sentence. Error codes, blocker references, and numeric limits do not change.
+
+### Build
+- Add GitHub Actions CI for pull requests and pushes to `develop`.
+- Automate releases. A `develop` to `master` pull request commits the next version, chosen from Conventional Commits or a `release:*` label. The merge publishes to npm with trusted publishing and creates the tag and GitHub Release. See `docs/RELEASING.md`.
+
+### Documentation
+- Rewrite the README, `AGENTS.md`, `ARCHITECTURE.md`, `DEPLOYMENT.md`, and the guides in `docs/` to follow the skill's writing rules. Headings, commands, links, and numbers stay the same.
+
 ## [5.3.0] - 2026-10-02
 
 ### Changed

package/README.md

@@ -5,16 +5,74 @@
 
 A Model Context Protocol server and target-native installer for governed Spec-Driven Development (SDD) in Claude Code, Codex, and Oh My Pi (OMP).
 
-> **v5.3.0** — Review, security, and multi-slice implementation skills ask once per session whether to run inline or use project agents, and every skill reports agents, parallelism, configured model/effort, and fallbacks. Installed guidance forbids commit/PR attribution lines. Claude Code requires 2.1.284+ for the pinned 5.5 defaults.
+> **v5.4.0** — The new `output-clarity-ladder` skill makes explanation, summary, and teaching replies easier to check. It is the only skill the model applies without a command, and it ships English, Japanese, and Traditional Chinese guidance. Runtime blockers and errors now state the next action. Releases are automated: a merge to `master` publishes to npm with provenance. Claude Code requires 2.1.284+ for the pinned 5.5 defaults.
 
 ## Why sdd-mcp?
 
-Skills own the requirements, design, task-planning, and TDD method plus the user conversation. The MCP runtime stays behind the Skill boundary and owns feature identity, canonical artifact writes, deterministic validation, revision-bound approvals, optional test review, implementation progress, and restart-safe context.
+Skills own the requirements, design, task-planning, and TDD method. Skills also own the user conversation. The MCP runtime stays behind the Skill boundary. The runtime owns feature identity, canonical artifact writes, deterministic validation, revision-bound approvals, optional test review, implementation progress, and restart-safe context.
 
 ```text
 User -> Skill -> MCP -> .spec
 ```
 
+## Is sdd-mcp the right fit?
+
+No workflow tool is best for every team. Each one makes a different trade-off between control, speed, and reach. Pick the option that matches your situation.
+
+### Which option fits
+
+Answer these questions in order. Each path ends at one option.
+
+```mermaid
+flowchart TD
+    A[New piece of work] --> B{Small, clear change?}
+    B -->|Yes| S[sdd-mcp simple-task<br/>or any light tool]
+    B -->|No| C{Host is Claude Code,<br/>Codex, or OMP?}
+    C -->|No| D{Want the agent to apply<br/>a method automatically?}
+    D -->|Yes| SP[Superpowers]
+    D -->|No| OS[OpenSpec]
+    C -->|Yes| E{Does a missed approval<br/>cost more than extra steps?}
+    E -->|Yes| SDD[sdd-mcp formal workflow]
+    E -->|No| F{Want free iteration on<br/>any artifact at any time?}
+    F -->|Yes| OS
+    F -->|No| SP
+```
+
+On the sdd-mcp path, you also get these properties:
+
+- The runtime binds each approval to an exact revision and artifact hash.
+- A later phase Skill stops when the earlier phase is not approved.
+- Durable state in `.spec/specs/<feature>/spec.json` lets any session or person resume the same feature.
+- Validation checks that EARS requirements, design decisions, and tasks trace to each other.
+
+sdd-mcp does not support other hosts, for example Cursor or GitHub Copilot. Superpowers and OpenSpec support many more hosts.
+
+### Comparison with Superpowers and OpenSpec
+
+This table uses each project's own README as of October 2026. Check the linked projects for current details.
+
+| | sdd-mcp | [Superpowers](https://github.com/obra/superpowers) | [OpenSpec](https://github.com/Fission-AI/OpenSpec) |
+|---|---|---|---|
+| Core idea | Governed phases with a state runtime | A development method built from composable skills | Lightweight specs organized as changes |
+| Hosts | Claude Code, Codex, OMP | 18+ coding agents | 30+ AI tools |
+| How it starts | You invoke a phase Skill | Skills activate automatically before a task | You run slash commands such as `/opsx:propose` |
+| Phase gates | Enforced by the MCP runtime | Approval asked in the conversation | None by design ("no rigid phase gates") |
+| Approval record | Revision and hash in `spec.json` | Not described as a stored record | No approval record in the core workflow |
+| Artifacts | `requirements.md`, `design.md`, `tasks.md` per feature | Design document and implementation plan | `proposal.md`, delta specs, `design.md`, `tasks.md` per change, then archive |
+| Implementation method | Test-first tasks with recorded RED and GREEN evidence | TDD, git worktrees, subagent per task with review | `/opsx:apply` works through tasks |
+| Extra moving parts | MCP server plus installed Skills | Plugin or skill install | CLI plus generated commands |
+| License | MIT | MIT | MIT |
+
+### Trade-offs
+
+| Choice | What you gain | What you pay |
+|---|---|---|
+| sdd-mcp | Enforced gates, an auditable approval record, and resumable state | More ceremony, an MCP runtime to install, and only three hosts |
+| Superpowers | A strong default method that the agent applies without commands, on many hosts | Gates live in the conversation, so nothing outside the agent enforces them |
+| OpenSpec | Low ceremony, free iteration, change history through archive, and many hosts | Alignment depends on team discipline, because no tool blocks a skipped step |
+
+A short rule: choose sdd-mcp when a missed approval costs more than the extra steps. Choose a lighter tool when speed of iteration matters more than proof of approval.
+
 ## One-time personal setup
 
 Install the runtime and manual Skills for Claude Code, Codex, and OMP once per local user/profile, from any directory:
@@ -67,12 +125,12 @@ Use this path when the repository has never had sdd-mcp-generated guidance. The
 
 ```bash
 # Recommended explicit lean installation
-npx sdd-mcp-server@5.3.0 install --profile lean --target claude-code
-npx sdd-mcp-server@5.3.0 install --profile lean --target codex
-npx sdd-mcp-server@5.3.0 install --profile lean --target omp
+npx sdd-mcp-server@5.5.0 install --profile lean --target claude-code
+npx sdd-mcp-server@5.5.0 install --profile lean --target codex
+npx sdd-mcp-server@5.5.0 install --profile lean --target omp
 
 # Interactive full installation: choose Claude Code, Codex, or OMP
-npx sdd-mcp-server@5.3.0 install --profile full
+npx sdd-mcp-server@5.5.0 install --profile full
 ```
 
 Use the local entrypoint only when this checkout itself is the intended project install. It does not repair personal runtime connection. Build once, then install explicitly:
@@ -113,16 +171,19 @@ npx sdd-mcp-server install --profile full --target codex --model-roles models.ya
 npx sdd-mcp-server install --target omp --model-roles models.yaml
 ```
 
-The six SDD roles are `planner`, `architect`, `reviewer`, `security-auditor`, `implementer`, and `tdd-guide`; omitted roles retain package defaults. Claude Code routes installed skills and subagents by model and effort. Codex routes generated custom agents by model and reasoning effort, but this cannot change the inline parent's model. OMP routes its generated agents, not host-level `default`/`smol`/`slow`/`plan`/`task`/`advisor` roles. `--model-roles` reads project YAML; it does not change host configuration or validate model availability. See [Model Routing](docs/MODEL-ROUTING.md) for selector syntax and host-specific limits.
+The six SDD roles are `planner`, `architect`, `reviewer`, `security-auditor`, `implementer`, and `tdd-guide`. Omitted roles keep the package defaults. Claude Code routes installed skills and subagents by model and effort. Codex routes generated custom agents by model and reasoning effort. This cannot change the model of the inline parent. OMP routes its generated agents, not host-level `default`/`smol`/`slow`/`plan`/`task`/`advisor` roles. `--model-roles` reads project YAML. It does not change host configuration, and it does not validate model availability. See [Model Routing](docs/MODEL-ROUTING.md) for selector syntax and host-specific limits.
 
 ## Manual workflow invocation
 
-SDD skills are explicit commands and do not activate implicitly from ordinary prose.
+SDD workflow skills are explicit commands and do not activate implicitly from ordinary prose. The one exception is `output-clarity-ladder`, which the model applies on its own (see the last row).
 
 | Path | Claude Code | Codex | Oh My Pi |
 |---|---|---|---|
 | Small task | `/simple-task` | `$simple-task` | `/skill:simple-task` |
 | Formal SDD | `/sdd-requirements` → `/sdd-design` → `/sdd-tasks` → `/sdd-implement` | `$sdd-requirements` → `$sdd-design` → `$sdd-tasks` → `$sdd-implement` | `/skill:sdd-requirements` → `/skill:sdd-design` → `/skill:sdd-tasks` → `/skill:sdd-implement` |
+| Clearer replies (automatic) | `/output-clarity-ladder` | `$output-clarity-ladder` | `/skill:output-clarity-ladder` |
+
+`output-clarity-ladder` makes explanation, summary, and teaching replies easier to check. It writes about 80% of the way to ASD-STE100 and uses a diagram, HTML page, or video only when that format is easier to understand. It ships English rules plus Japanese (`ja`) and Traditional Chinese (`zh-TW`) guidance. It does not check an approved-word list, and it does not make output ASD-STE100 conformant.
 
 Approvals and optional test-case review are explicit questions inside the relevant Skill flow. Status, context, validation, persistence, and progress recording happen internally.
 
@@ -139,7 +200,7 @@ Approvals and optional test-case review are explicit questions inside the releva
 
 Claude Code and Codex lean profiles install skills, steering, and their supported hook guidance. OMP lean installs skills, steering, and agents. Full profiles add rules, contexts, and agents as supported by each host. OMP does not install Markdown as an executable hook; `--target omp --hooks` fails with an explanation.
 
-**Project agents and execution mode.** Whether a skill can use project agents depends on the profile. With no agents installed (Claude Code/Codex `lean`) every skill runs inline and does not ask. With agents installed (`full`; OMP always), `sdd-review`, `sdd-security-check`, and any run with at least two independent implementation slices ask once per session: inline or project agent. Planning skills (requirements, design, tasks, steering) never ask. Every skill reports the mode, agents started, parallelism, configured model/effort, and fallbacks; see [Model Routing](docs/MODEL-ROUTING.md#execution-mode-and-reporting) to verify on each host. SDD agents are subagents, not the Claude Code `/advisor` tool.
+**Project agents and execution mode.** Whether a skill can use project agents depends on the profile. With no agents installed (Claude Code/Codex `lean`), every skill runs inline and does not ask. With agents installed (`full`; OMP always), these skills ask once per session, inline or project agent: `sdd-review`, `sdd-security-check`, and any run with at least two independent implementation slices. Planning skills (requirements, design, tasks, steering) never ask. Every skill reports the mode, agents started, parallelism, configured model/effort, and fallbacks. To verify on each host, see [Model Routing](docs/MODEL-ROUTING.md#execution-mode-and-reporting). SDD agents are subagents, not the Claude Code `/advisor` tool.
 
 See [Installation Guide](docs/INSTALL-GUIDE.md) and [Model Routing](docs/MODEL-ROUTING.md).
 
@@ -153,7 +214,7 @@ Use this path when the project already contains generated sdd-mcp files from an
 
 ```bash
 # Replace <target> with claude-code, codex, or omp
-npx sdd-mcp-server@5.3.0 install \
+npx sdd-mcp-server@5.5.0 install \
   --profile full \
   --target <target> \
   --refresh-generated
@@ -166,7 +227,7 @@ For an OMP migration, Codex TOML agents remain preserved but are not executable
 After this one-time migration, use a normal install without `--refresh-generated` for subsequent v5 updates. Review conflicts, then reload/restart the host and accept project trust before invoking a native phase Skill.
 
 ## Integrator/runtime reference: canonical v5 inventory
-Every packaged entrypoint exposes the same 16 tools:
+Every packaged entrypoint exposes the same 17 tools:
 
 1. `sdd-init`
 2. `sdd-requirements`
@@ -184,12 +245,15 @@ Every packaged entrypoint exposes the same 16 tools:
 14. `sdd-validate-design`
 15. `sdd-validate-gap`
 16. `sdd-spec-impl`
+17. `sdd-jev-check`
+
+`sdd-jev-check` is opt-in and advisory. It is off by default and never changes workflow state. For a PR or branch review, its code checks accept an optional `baseRef` to judge committed changes. See [Optional JEV advisory](docs/WORKFLOW.md#optional-jev-advisory).
 
 Feature-scoped tools use `featureName`; v5 payloads bind phase mutations and approvals to exact revisions and artifact hashes. This inventory is for MCP integrators and runtime maintainers—not end-user workflow instructions. Hosts discover installed Skills, and the installer supports `--list`.
 
 ## Integrator/runtime reference: compact continuation
 
-The runtime's context API defaults to bounded approved context and supports exact-response ETags. Phase Skills manage fingerprints and draft opt-in internally. Integrators that call the protocol directly must preserve the returned fingerprint for `ifNoneMatch`, request unapproved source only explicitly in full mode, and treat `.spec/specs/<feature>/spec.json` as workflow authority. Compact, standard, and full default bounds are 2,048, 4,096, and 16,384 `estimatedTokens`; full mode never silently truncates raw documents.
+The runtime's context API defaults to bounded approved context and supports exact-response ETags. Phase Skills manage fingerprints and draft opt-in internally. Integrators that call the protocol directly must follow three rules. Preserve the returned fingerprint for `ifNoneMatch`. Request unapproved source only explicitly in full mode. Treat `.spec/specs/<feature>/spec.json` as workflow authority. Compact, standard, and full default bounds are 2,048, 4,096, and 16,384 `estimatedTokens`. Full mode never silently truncates raw documents.
 
 ## Context and usage measurement
 
@@ -209,7 +273,13 @@ Three-run fresh-session A/B comparisons used comparable provider-reported median
 
 ## Routing summary
 
-Claude executes a skill in the current turn with its configured model and effort (default Claude Opus 5.5/high for high-level work and Claude Sonnet 5.5/medium for implementation/TDD); installed Claude subagents have matching metadata. Codex runs inline by default and may use one configured GPT-6 Sol/xhigh custom agent for review and security after the user chooses it once per session; its agent metadata does not change the parent turn. OMP executes invoked SDD skills inline, with the installed `.omp/extensions/sdd-skill-routing.js` switching the parent to the configured model/thinking level (GPT-6 Sol/xhigh for high-level work, GPT-6 Luna/medium for implementation/TDD) for the turn and restoring it afterward. OMP’s `.omp/agents` advisors remain explicit opt-in only, allow one child, and cannot nest or retry. Implementation, TDD, and simple tasks remain inline unless genuinely independent parallel slices justify delegation.
+Claude executes a skill in the current turn with its configured model and effort. The defaults are Claude Opus 5.5/high for high-level work and Claude Sonnet 5.5/medium for implementation/TDD. Installed Claude subagents have matching metadata.
+
+Codex runs inline by default. It may use one configured GPT-6 Sol/xhigh custom agent for review and security, after the user chooses it once per session. Its agent metadata does not change the parent turn.
+
+OMP executes invoked SDD skills inline. The installed `.omp/extensions/sdd-skill-routing.js` switches the parent to the configured model/thinking level for the turn, then restores it afterward. The defaults are GPT-6 Sol/xhigh for high-level work and GPT-6 Luna/medium for implementation/TDD. OMP’s `.omp/agents` advisors remain explicit opt-in only. They allow one child, and they cannot nest or retry.
+
+Implementation, TDD, and simple tasks remain inline unless genuinely independent parallel slices justify delegation.
 
 See [docs/MODEL-ROUTING.md](docs/MODEL-ROUTING.md) for enforcement and fallback boundaries.
 
@@ -231,4 +301,6 @@ npm run build
 npm test
 ```
 
+Releases are automated. A merge from `develop` to `master` bumps the version, tags it, and publishes it to npm. See [docs/RELEASING.md](docs/RELEASING.md).
+
 MIT licensed. See [CHANGELOG.md](CHANGELOG.md) for release history.

package/agents/security-auditor.md

@@ -14,10 +14,10 @@ Audit only the handed-off scope. Treat security as a source-to-sink and trust-bo
 - Identify actors, assets, entry points, privileges, data sensitivity, and trust transitions.
 - Trace untrusted values through validation, authorization, queries, commands, templates, URLs, serialization, storage, errors, and logs.
 - Check applicable access-control, cryptography, injection, authentication, integrity, dependency, configuration, SSRF, abuse, and resource-exhaustion risks.
-- Redact any secret; identify only its type and location. Perform no destructive probe or external contact.
+- Redact any secret; identify only its type and location. Perform no destructive probe, no contact with the audited target or its systems, and no network access of any kind.
 - Report a finding only with preconditions, exploit path, impact, severity rationale, remediation, and regression test. Separate confirmed flaws from hardening.
 
-This is a depth-one read-only assignment. Do not spawn or delegate. Unknown controls remain unresolved, not assumed absent.
+This is a depth-one read-only assignment. Do not spawn or delegate. Unknown controls remain unresolved, not assumed absent. Only the parent may make the opt-in JEV triage call after this assignment returns.
 
 ## Result Contract
 

package/dist/__tests__/helpers/message-clarity.d.ts

@@ -0,0 +1,15 @@
+export interface ClarityBounds {
+    maxSentences: number;
+    maxWords: number;
+}
+export interface ClarityResult {
+    ok: boolean;
+    reason?: string;
+    sentence?: string;
+    wordCount?: number;
+}
+/** Split on . ? ! followed by whitespace or end of text; dotted identifiers stay whole. */
+export declare function splitSentences(text: string): string[];
+/** Words are whitespace-separated tokens; a placeholder such as X is one word. */
+export declare function countWords(sentence: string): number;
+export declare function checkClarity(text: string, bounds: ClarityBounds): ClarityResult;

package/dist/__tests__/helpers/message-clarity.js

@@ -0,0 +1,26 @@
+/** Split on . ? ! followed by whitespace or end of text; dotted identifiers stay whole. */
+export function splitSentences(text) {
+    const parts = text.trim().match(/[\s\S]*?[.?!](?=\s|$)|[\s\S]+$/g) ?? [];
+    return parts.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+/** Words are whitespace-separated tokens; a placeholder such as X is one word. */
+export function countWords(sentence) {
+    const trimmed = sentence.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+export function checkClarity(text, bounds) {
+    if (text.trim() === '')
+        return { ok: false, reason: 'Message is empty or whitespace-only' };
+    const sentences = splitSentences(text);
+    if (sentences.length > bounds.maxSentences) {
+        return { ok: false, reason: `Message has ${sentences.length} sentences; maximum is ${bounds.maxSentences}`, sentence: text };
+    }
+    for (const sentence of sentences) {
+        const wordCount = countWords(sentence);
+        if (wordCount > bounds.maxWords) {
+            return { ok: false, reason: `Sentence has ${wordCount} words; maximum is ${bounds.maxWords}`, sentence, wordCount };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=message-clarity.js.map

package/dist/__tests__/helpers/message-clarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-clarity.js","sourceRoot":"","sources":["../../../src/__tests__/helpers/message-clarity.ts"],"names":[],"mappings":"AAYA,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,iCAAiC,CAAC,IAAI,EAAE,CAAC;IACzE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChC,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAqB;IAC9D,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,EAAE,CAAC;IAC5F,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,SAAS,CAAC,MAAM,0BAA0B,MAAM,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/H,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,SAAS,sBAAsB,MAAM,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QACtH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/__tests__/helpers/message-extractor.d.ts

@@ -0,0 +1,22 @@
+export declare const MESSAGE_FILES: readonly ["src/application/services/WorkflowValidationService.ts", "src/application/services/WorkflowEngineService.ts", "src/adapters/cli/SDDToolAdapter.ts", "src/infrastructure/mcp/ToolRegistry.ts"];
+export declare const DYNAMIC_CODE = "<dynamic>";
+export interface ExtractedMessage {
+    file: string;
+    code: string | null;
+    message: string;
+    line: number;
+    literal: boolean;
+}
+export interface ContractSnapshot {
+    files: Record<string, {
+        codes: string[];
+        numbers: Record<string, string[]>;
+    }>;
+}
+export declare function extractMessagesFromSource(file: string, text: string): ExtractedMessage[];
+export declare function extractMessages(file: string, root?: string): ExtractedMessage[];
+export declare function loadAllMessages(root?: string): ExtractedMessage[];
+export declare function numericTokens(message: string): string[];
+export declare function buildContractSnapshot(messages: ExtractedMessage[]): ContractSnapshot;
+/** Returns a list of violations; empty means current satisfies the baseline. */
+export declare function compareToBaseline(current: ContractSnapshot, baseline: ContractSnapshot): string[];

package/dist/__tests__/helpers/message-extractor.js

@@ -0,0 +1,135 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import ts from 'typescript';
+export const MESSAGE_FILES = [
+    'src/application/services/WorkflowValidationService.ts',
+    'src/application/services/WorkflowEngineService.ts',
+    'src/adapters/cli/SDDToolAdapter.ts',
+    'src/infrastructure/mcp/ToolRegistry.ts',
+];
+export const DYNAMIC_CODE = '<dynamic>';
+/** readRequired(path, message) throws this code with the caller's message. */
+const READ_REQUIRED_CODE = 'StateInvariantViolation';
+/** Returns folded literal text, or undefined when the expression is not a literal. */
+function literalText(node) {
+    if (ts.isParenthesizedExpression(node))
+        return literalText(node.expression);
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    if (ts.isTemplateExpression(node)) {
+        return node.head.text + node.templateSpans.map((s) => `X${s.literal.text}`).join('');
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const l = literalText(node.left);
+        const r = literalText(node.right);
+        return l !== undefined && r !== undefined ? l + r : undefined;
+    }
+    return undefined;
+}
+export function extractMessagesFromSource(file, text) {
+    let sf;
+    try {
+        sf = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TS);
+    }
+    catch (error) {
+        throw new Error(`Cannot parse ${file}: ${error.message}`);
+    }
+    const parseDiagnostics = sf.parseDiagnostics ?? [];
+    if (parseDiagnostics.length > 0)
+        throw new Error(`Cannot parse ${file}: syntax errors`);
+    const out = [];
+    const visit = (node) => {
+        const isBlocker = ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'blocker';
+        const isGov = ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'GovernanceError';
+        const isReadRequired = ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === 'readRequired';
+        if ((isBlocker || isGov || isReadRequired) && (node.arguments?.length ?? 0) >= 2) {
+            const [codeArg, msgArg] = node.arguments;
+            const code = isReadRequired ? READ_REQUIRED_CODE : literalText(codeArg);
+            const message = literalText(msgArg);
+            out.push({
+                file,
+                code: code === undefined ? null : code,
+                message: message ?? '',
+                line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+                literal: message !== undefined,
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    if (out.length === 0)
+        throw new Error(`No blocker or GovernanceError messages found in ${file}`);
+    return out;
+}
+export function extractMessages(file, root = process.cwd()) {
+    let text;
+    try {
+        text = readFileSync(resolve(root, file), 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Cannot read ${file}: ${error.message}`);
+    }
+    return extractMessagesFromSource(file, text);
+}
+export function loadAllMessages(root = process.cwd()) {
+    return MESSAGE_FILES.flatMap((file) => extractMessages(file, root));
+}
+export function numericTokens(message) {
+    return (message.match(/\d+(?:,\d{3})*(?:\.\d+)*/g) ?? []).map((t) => t.replace(/,/g, ''));
+}
+export function buildContractSnapshot(messages) {
+    const files = {};
+    for (const m of messages) {
+        const entry = (files[m.file] ??= { codes: [], numbers: {} });
+        const code = m.code ?? DYNAMIC_CODE;
+        if (!entry.codes.includes(code))
+            entry.codes.push(code);
+        (entry.numbers[code] ??= []).push(...numericTokens(m.message));
+    }
+    for (const file of Object.keys(files).sort()) {
+        const entry = files[file];
+        entry.codes.sort();
+        for (const code of Object.keys(entry.numbers))
+            entry.numbers[code].sort();
+    }
+    const sorted = {};
+    for (const file of Object.keys(files).sort()) {
+        const entry = files[file];
+        sorted[file] = {
+            codes: entry.codes,
+            numbers: Object.fromEntries(entry.codes.map((c) => [c, entry.numbers[c] ?? []])),
+        };
+    }
+    return { files: sorted };
+}
+/** Returns a list of violations; empty means current satisfies the baseline. */
+export function compareToBaseline(current, baseline) {
+    const problems = [];
+    for (const file of Object.keys(baseline.files)) {
+        const base = baseline.files[file];
+        const cur = current.files[file];
+        if (!cur) {
+            problems.push(`${file}: file missing from current extraction`);
+            continue;
+        }
+        if (JSON.stringify(cur.codes) !== JSON.stringify(base.codes)) {
+            const missing = base.codes.filter((c) => !cur.codes.includes(c));
+            const added = cur.codes.filter((c) => !base.codes.includes(c));
+            problems.push(`${file}: code set changed; missing [${missing}] added [${added}]`);
+        }
+        for (const code of base.codes) {
+            const remaining = [...(cur.numbers[code] ?? [])];
+            for (const token of base.numbers[code] ?? []) {
+                const i = remaining.indexOf(token);
+                if (i === -1)
+                    problems.push(`${file}: code ${code} lost numeric token ${token}`);
+                else
+                    remaining.splice(i, 1);
+            }
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=message-extractor.js.map

package/dist/__tests__/helpers/message-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-extractor.js","sourceRoot":"","sources":["../../../src/__tests__/helpers/message-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,uDAAuD;IACvD,mDAAmD;IACnD,oCAAoC;IACpC,wCAAwC;CAChC,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,8EAA8E;AAC9E,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAcrD,sFAAsF;AACtF,SAAS,WAAW,CAAC,IAAmB;IACtC,IAAI,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5E,IAAI,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,+BAA+B,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC3F,IAAI,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;QACvF,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAY,EAAE,IAAY;IAClE,IAAI,EAAiB,CAAC;IACtB,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,gBAAgB,GAAI,EAAkD,CAAC,gBAAgB,IAAI,EAAE,CAAC;IACpG,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,iBAAiB,CAAC,CAAC;IAExF,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,IAAa,EAAQ,EAAE;QACpC,MAAM,SAAS,GACb,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC;QACtG,MAAM,KAAK,GACT,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,iBAAiB,CAAC;QAC7G,MAAM,cAAc,GAClB,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC;YACzB,EAAE,CAAC,0BAA0B,CAAC,IAAI,CAAC,UAAU,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC;QAC/C,IAAI,CAAC,SAAS,IAAI,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACjF,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,SAAU,CAAC;YAC1C,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACxE,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;YACpC,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI;gBACJ,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;gBACtC,OAAO,EAAE,OAAO,IAAI,EAAE;gBACtB,IAAI,EAAE,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;gBAClE,OAAO,EAAE,OAAO,KAAK,SAAS;aAC/B,CAAC,CAAC;QACL,CAAC;QACD,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,EAAE,CAAC,CAAC;IACjG,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IAChE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IAClD,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAA4B;IAChE,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,CAAC;IACD,MAAM,MAAM,GAA8B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;SACjF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,OAAyB,EAAE,QAA0B;IACrF,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,wCAAwC,CAAC,CAAC;YAC/D,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACjE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/D,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gCAAgC,OAAO,YAAY,KAAK,GAAG,CAAC,CAAC;QACpF,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC7C,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,CAAC,KAAK,CAAC,CAAC;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,UAAU,IAAI,uBAAuB,KAAK,EAAE,CAAC,CAAC;;oBAC5E,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/__tests__/unit/jev/helpers.d.ts

@@ -0,0 +1,84 @@
+import type { GitPort, GitResult, JevHttpPort, JevHttpRequest, JevHttpResponse, LoggerPort } from '../../../domain/ports';
+import { NodeFileSystemAdapter } from '../../../infrastructure/adapters/NodeFileSystemAdapter';
+import { WorkflowEngineService } from '../../../application/services/WorkflowEngineService';
+export declare const TEST_KEY = "sk-test-abcdef123456";
+export declare const FIXTURE_REQUIREMENTS: string;
+export declare const FIXTURE_DESIGN: string;
+export declare const FIXTURE_TASKS: string;
+type Phase = 'requirements' | 'design' | 'tasks';
+export interface EngineProject {
+    root: string;
+    feature: string;
+    engine: WorkflowEngineService;
+    fileSystem: NodeFileSystemAdapter;
+    submit(phase: Phase, content: string, revision?: number, hash?: string | null): ReturnType<WorkflowEngineService['submitPhaseArtifact']>;
+    approve(phase: Phase, result: {
+        revision: number;
+        artifact: {
+            sha256: string;
+        };
+    }): ReturnType<WorkflowEngineService['approve']>;
+    cleanup(): Promise<void>;
+}
+/** A real engine over a temporary project; the feature is initialized and ready for submissions. */
+export declare function createEngineProject(feature?: string): Promise<EngineProject>;
+type Answer = {
+    choice: string;
+} | {
+    score: number;
+} | {
+    noul: number;
+};
+/** A valid, unflagged answer for every posted question, with per-id overrides. */
+export declare function benignAnswers(requestBody: string, overrides?: Record<string, Answer>): string;
+export declare class FakeJevHttpPort implements JevHttpPort {
+    readonly calls: JevHttpRequest[];
+    respond: (request: JevHttpRequest) => Promise<JevHttpResponse>;
+    post(request: JevHttpRequest): Promise<JevHttpResponse>;
+}
+export declare class FakeGitPort implements GitPort {
+    readonly calls: string[][];
+    handler: (args: readonly string[]) => GitResult;
+    run(args: readonly string[]): Promise<GitResult>;
+}
+/** Real filesystem that records every call so tests can prove what was (not) touched. */
+export declare class SpyFileSystem extends NodeFileSystemAdapter {
+    readonly calls: Array<{
+        method: string;
+        path: string;
+    }>;
+    throwOn?: {
+        method: string;
+        match: RegExp;
+    };
+    private record;
+    readFile(target: string): Promise<string>;
+    writeFile(target: string, content: string): Promise<void>;
+    writeFileAtomic(target: string, content: string): Promise<void>;
+    exists(target: string): Promise<boolean>;
+    mkdir(target: string): Promise<void>;
+    readdir(target: string): Promise<string[]>;
+    stat(target: string): Promise<{
+        isFile(): boolean;
+        isDirectory(): boolean;
+    }>;
+    unlink(target: string): Promise<void>;
+}
+export declare const silentLogger: () => LoggerPort & {
+    all(): unknown[];
+};
+/** Sorted `path|dir` and `path|file|sha256` lines for the whole tree. */
+export declare function snapshotTree(root: string): Promise<string[]>;
+export declare function readAllFiles(root: string): Promise<string>;
+export interface TempProject {
+    root: string;
+    cleanup(): Promise<void>;
+}
+/** A project root with `.spec/specs/<feature>/spec.json` and a source file. */
+export declare function createTempProject(feature?: string): Promise<TempProject>;
+/** Scripts a FakeGitPort so the review manifest sees one modified file, `src/a.ts`. */
+export declare function scriptOneChangedFile(git: FakeGitPort, options?: {
+    blob?: string;
+    head?: string | null;
+}): void;
+export {};