Add ExecPlan for structured diagnostics with stable E_SEMPAI codes

[leynos]

Summary

• Adds an ExecPlan document for 4.1.2: Structured diagnostics with stable E_SEMPAI_* error codes.
• Establishes a contract for stable diagnostic schema across parser and validator paths to enable snapshot stability and downstream compatibility.

Changes

• Created new file: docs/execplans/4-1-2-structured-diagnostics-with-stable-error-codes.md
• The document outlines:
  • Purpose and observable outcomes
  • Constraints, tolerances, and risks
  • Progress, surprises & discoveries, and decision log
  • Plan of work with stages A–F
  • Concrete steps, validation/acceptance criteria, and interfaces
  • Revision notes and context/orientation

Rationale

• Provides a single, canonical reference for implementing and validating stable diagnostics across the codebase (sempai-core, weaver-cli, and related paths).
• Ensures that diagnostic payloads, codes, and schema remain stable for downstream consumers and for JSON snapshot tests.

Impact

• This is a docs-only change. No code changes or build effects are introduced.
• CI should be unaffected; no test or compilation changes.

Validation plan

• Review the ExecPlan for completeness and alignment with the current diagnostic design (docs/sempai-query-language-design.md and existing tests).
• Use the plan as a reference for upcoming implementation work (Stage A–F) and gate criteria.

How to review

• Read the new ExecPlan document under docs/execplans/4-1-2-structured-diagnostics-with-stable-error-codes.md.
• Verify that Sections cover:
  • Stable JSON contract and E_SEMPAI_* codes
  • Canonical diagnostic shape (code, message, span, notes)
  • Parser vs validator emission path alignment
  • Bare-invocation compatibility considerations
  • Roadmap/roadmap-states references and acceptance criteria

Notes

• The ExecPlan references and reinforces existing code paths and docs (e.g., crates/sempai-core, crates/sempai, docs/roadmap.md, and docs/sempai-query-language-design.md).
• This PR is a planning artifact intended to guide future implementation and validation work.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/9917800a-2e30-465f-bdd6-5bedfc0f8e25

Summary by Sourcery

Documentation:

• Document the execution plan for stabilizing diagnostic JSON schema and E_SEMPAI_* codes across parser and validator paths, including testing, tooling, and roadmap acceptance criteria.

[sourcery-ai]

Reviewer's Guide

Adds a new ExecPlan document that defines the implementation and validation plan for stabilizing structured diagnostics with E_SEMPAI_* error codes, including constraints, risks, work stages, concrete steps, and acceptance criteria across parser, validator, and CLI bare-invocation paths.

Sequence diagram for parser and validator diagnostics using canonical schema

sequenceDiagram
  participant TestRunner
  participant SempaiEngine as Sempai_Engine
  participant Parser as Parser_path
  participant Validator as Validator_path
  participant Core as Sempai_core_Diagnostic
  participant Snapshot as JSON_snapshot_tests

  TestRunner->>SempaiEngine: compile_yaml(yaml_input)
  SempaiEngine->>Parser: parse(yaml_input)
  Parser-->>SempaiEngine: ParserError(parser_error)
  SempaiEngine->>Core: from_parser_error(parser_error)
  Core-->>SempaiEngine: DiagnosticReport{code,message,span,notes}
  SempaiEngine-->>TestRunner: DiagnosticReport
  TestRunner->>Snapshot: assert_parser_snapshot(DiagnosticReport as JSON)

  TestRunner->>SempaiEngine: compile_dsl(dsl_input)
  SempaiEngine->>Validator: validate(dsl_input)
  Validator-->>SempaiEngine: ValidationError(validation_error)
  SempaiEngine->>Core: from_validation_error(validation_error)
  Core-->>SempaiEngine: DiagnosticReport{code,message,span,notes}
  SempaiEngine-->>TestRunner: DiagnosticReport
  TestRunner->>Snapshot: assert_validator_snapshot(DiagnosticReport as JSON)

Loading

Flow diagram for ExecPlan 4.1.2 stages A–F

flowchart TD
  A["Stage A: Lock diagnostic JSON schema in sempai_core via failing tests and snapshots"]
  B["Stage B: Implement canonical Diagnostic schema and parser/validator constructors"]
  C["Stage C: Wire parser and validator emission in sempai Engine entrypoints"]
  D["Stage D: Expand unit, BDD, and snapshot tests (parser, validator, CLI)"]
  E["Stage E: Update design docs, users guide, and roadmap 4.1.2 status"]
  F["Stage F: Run quality gates (check-fmt, lint, test, markdownlint, nixie)"]
  GatesPass["All gates pass and acceptance criteria met"]
  Escalate["Escalate per tolerances (scope, deps, interfaces, failing gates)"]

  A --> B --> C --> D --> E --> F

  F -->|check-fmt, lint, test, markdownlint, nixie all exit 0| GatesPass
  F -->|gate fails or tolerances exceeded| Escalate

Loading

File-Level Changes

Change	Details	Files
Introduce an ExecPlan document describing how to implement stable structured diagnostics and maintain CLI discoverability.	Create a new ExecPlan markdown file for roadmap item 4.1.2 focused on structured diagnostics with stable E_SEMPAI_* codes. Define constraints, tolerances, and risks around diagnostic schema stability, public API changes, test gates, and scope. Document progress checklist, surprises/discoveries, and a decision log capturing key architectural choices. Lay out a staged plan (A–F) covering schema locking, implementation in sempai_core and sempai, wiring emission points, tests, documentation, and validation gates. List concrete implementation steps, validation/acceptance criteria, interfaces, and recovery/idempotence guidance for future work.	docs/execplans/4-1-2-structured-diagnostics-with-stable-error-codes.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2a05291a-7003-4c5c-9659-085e9f01ac45

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch implement-structured-diagnostics-xispyx

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}