thoth-agents 0.2.2 → 0.2.4

package/src/skills/sdd-constitution/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: sdd-constitution
+description: Guide a semver constitution amendment and Sync-Impact Report entry.
+metadata:
+  author: thoth-agents
+  version: 1.0.0
+---
+
+# SDD Constitution Skill
+
+Perform a guided, human-confirmed amendment of `openspec/memory/constitution.md`
+ONLY — a semver version bump, an updated `Last-Amended` date, and one prepended
+`## Sync-Impact Report` entry. This skill closes the constitution lifecycle by
+adding its AMENDMENT side; it never edits any other bundled asset.
+
+## Shared Conventions
+
+- [../_shared/openspec-convention.md](../_shared/openspec-convention.md)
+- [../_shared/persistence-contract.md](../_shared/persistence-contract.md)
+- [../_shared/thoth-mem-convention.md](../_shared/thoth-mem-convention.md)
+
+## Persistence Mode
+
+The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
+`hybrid`). Follow the persistence contract for read/write rules per mode.
+
+- `thoth-mem`: record the amendment as a governance observation only — do NOT
+  create or modify `openspec/` files.
+- `openspec`: write `openspec/memory/constitution.md` only — do NOT call
+  thoth-mem save tools.
+- `hybrid`: do both — write the file AND record the governance observation
+  (default).
+
+## When to Use
+
+- A native principle must be added, redefined, removed, or its guidance
+  materially expanded or clarified, and the constitution must record it.
+- A report-only suggestion from `sdd-verify` or `sdd-archive` flagged a
+  completed change as governance-touching and a human chooses to record an
+  amendment.
+
+## Prerequisites
+
+- An existing `openspec/memory/constitution.md` (bootstrapped by `sdd-init`).
+- A human-described principle change (what changed and why).
+- `change-name` — OPTIONAL context only; the skill may run standalone and is not
+  a per-change pipeline phase.
+- Selected persistence mode (default: `hybrid`).
+
+## Workflow
+
+1. Read the shared conventions, especially `openspec-convention.md` >
+   Constitution Governance (amendment doctrine, read-only-asset rules, and the
+   Sync-Impact Report entry format).
+2. Load `openspec/memory/constitution.md` and read its `Version:`, `Ratified:`,
+   `Last-Amended:` header fields and the existing `## Sync-Impact Report`
+   section. If the file is absent, instruct the user to run `sdd-init` first;
+   do NOT create the constitution here.
+3. Determine the principle change from the human description. If no principle
+   change is warranted, report a no-op and stop — write nothing.
+4. Classify the bump per policy: MAJOR = a principle is removed or redefined;
+   MINOR = a principle is added or guidance materially expanded; PATCH =
+   clarification or wording with no behavioral change. Present the
+   classification for confirmation via the harness blocking-input surface
+   (AskUserQuestion-equivalent). Do NOT write any version bump before the user
+   confirms, and NEVER use a runtime parser to auto-select the bump.
+5. Apply the amendment to `openspec/memory/constitution.md` ONLY: bump the
+   `Version:` field, set `Last-Amended:` to the current date, and PREPEND
+   exactly one entry to the top of the `## Sync-Impact Report` section in the
+   canonical format
+   `- X.Y.Z | change type | principles touched | downstream gates/artifacts affected`.
+   Preserve all existing content and ALL prior Sync-Impact Report entries.
+6. Emit REPORT-ONLY impact: name the live-read consuming gates (`sdd-design`,
+   `plan-reviewer`) in the Sync-Impact entry, and FLAG any in-flight change
+   `openspec/changes/{name}/design.md` or `tasks.md` that reference now-changed
+   principles for HUMAN re-review. Do NOT edit those artifacts or any other
+   bundled asset.
+7. Persist per the selected mode: in modes that include OpenSpec write the
+   constitution file; in modes that include thoth-mem record a governance
+   observation per the persistence contract.
+
+## Output Format
+
+Return:
+
+- `Constitution Version`: old `X.Y.Z` -> new `X.Y.Z` (or unchanged on no-op)
+- `Bump`: MAJOR, MINOR, PATCH, or no-op
+- `Sync-Impact Entry`: the single prepended line (or none on no-op)
+- `Consuming Gates`: live-read gates that consume the changed principles
+  (e.g. `sdd-design`, `plan-reviewer`)
+- `In-Flight Artifacts Flagged`: change `design.md` / `tasks.md` flagged for
+  human re-review, or none
+- `Files Written`: `openspec/memory/constitution.md` only, or none
+- `Status`: amended or no-op
+
+## Rules
+
+- NEVER edit, create, or delete any other `SKILL.md`, any file under `src/`, or
+  any bundled/template asset — the ONLY writable target is
+  `openspec/memory/constitution.md`.
+- NEVER auto-bump: there is no runtime parser, and no `Version:` change is
+  written without explicit human confirmation via the blocking-input surface.
+- No-op when no principle change is warranted: report it and write nothing.
+- Preserve all existing constitution content and ALL prior `## Sync-Impact
+  Report` entries; only PREPEND the new entry and update the version/date.
+- Propagation is report-only: document the consuming gates and flag in-flight
+  change artifacts for human re-review; NEVER auto-fix them.

package/src/skills/sdd-design/SKILL.md

@@ -78,7 +78,60 @@ technical write-capable role such as `deep`.
    and required metadata fields: `title`, `topic_key`, `type`, `project`,
    `scope`, and `content`.
 
-## Output Format
+## Optional Sub-Artifacts
+
+Beyond the always-present `design.md`, `sdd-design` MAY produce optional plan
+sub-artifacts. They are gated by BOTH conditions, config as the hard floor and
+author judgment within the gate:
+
+- **Hard gate (config)**: `rules.design.sub_artifacts` MUST be `true`. When
+  `false` or absent, NO sub-artifacts are ever produced (back-compat default).
+- **Complexity gate (config threshold, author-evaluated)**: when enabled, the
+  change MUST meet `rules.design.complexity_threshold` (e.g. `affected_domains`,
+  `affected_files`, `external_research` — eligible when ANY trigger is met). The
+  threshold is the reviewable hard floor; the author still selects which (if any)
+  sub-artifacts add value within the gate. An eligible change MAY still produce
+  zero sub-artifacts.
+
+`design.md` is ALWAYS produced regardless of the gate. The optional types are:
+
+- `research.md` — only when there is genuine unknown investigation.
+- `data-model.md` — only when there is a non-trivial data shape.
+- `contracts/` (subdir) — only when there are interfaces to pin; follow the
+  `checklists/` subdir as the precedent for change-dir subdirectory layout.
+- `quickstart.md` — only when a runnable smoke path helps.
+
+Note: the `clarify` phase now precedes design (`spec -> clarify -> design`), so
+design consumes the already-clarified spec.
+
+## Constitution Check and Handoff Hints
+
+    ### Consume upstream handoffHints
+
+    At design start, surface the spec phase's `handoffHints` (recorded
+    `## Assumptions` and `[NEEDS CLARIFICATION]` resolutions) and treat them as
+    constraints the design must preserve. When the spec declared no hints, surface
+    nothing. Surfacing is gated by `rules.handoffs.surface_hints`.
+
+    ### Constitution Check self-review
+
+    Before finalizing the design, run a Constitution Check self-review: evaluate the
+    emerging design against EACH principle in `openspec/memory/constitution.md` —
+    delegate-first coordination, read-only role boundaries, governed persistence,
+    multi-harness parity, and evidence-led verification. Report any principle the
+    design would violate.
+
+    - On a detected violation, BLOCK finalization and surface the violated
+      principle through the harness blocking-input surface (the
+      AskUserQuestion-equivalent primitive). An explicit user override MUST be
+      logged with the violated principle before proceeding. Gated by
+      `rules.constitution.enforce_check`; when disabled, note the skip and do not
+      block.
+    - This self-review does not replace `plan-reviewer`'s independent Constitution
+      Check; both run. See `_shared/openspec-convention.md` (Constitution
+      Governance, Handoff Hints) for the canonical, harness-agnostic semantics.
+
+    ## Output Format
 
 Return:
 

package/src/skills/sdd-init/SKILL.md

@@ -31,6 +31,11 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 ## When to Use
 
 - SDD is needed but `openspec/` is not initialized
+- `openspec/` exists but is stale: missing `config.yaml` mechanism sections
+  (`constitution` / `consistency` / `requirements_quality` / `clarification` /
+  `handoffs`), missing `tasks.traceability` / `tasks.parallel_markers` /
+  `design.sub_artifacts` / `design.complexity_threshold` / `verify` toggles, or a
+  missing `openspec/memory/constitution.md`
 - A new project needs initial OpenSpec conventions
 - The team wants detected stack/context captured before `sdd-propose`
 
@@ -63,9 +68,38 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    - `openspec/config.yaml`
    - `openspec/specs/`
    - `openspec/changes/`
-5. If all required OpenSpec paths already exist, report what exists and ask the
-   orchestrator whether `config.yaml` should be updated. Do not overwrite by
-   default.
+5. If the required OpenSpec paths already exist, do not dead-end. Compute
+   whether the project is fully aligned or stale, then realign additively:
+   - **Fully aligned** (all paths present AND `config.yaml` already carries
+     every mechanism section / toggle AND `openspec/memory/constitution.md`
+     exists) -> report a no-op and return. Never overwrite by default.
+   - **Stale / partial** (any piece below is absent) -> proceed to the
+     additive backfill in steps 5a-5c. Never overwrite a value that is
+     already present.
+
+    5a. Compute the per-piece *absent set* (detect each independently; treat a
+        partially-present `openspec/` per-piece, not all-or-nothing):
+        - missing `openspec/specs/`
+        - missing `openspec/changes/` (and `changes/archive/`)
+        - missing `config.yaml` mechanism sections: `constitution`,
+          `consistency`, `requirements_quality`, `clarification`, `handoffs`
+        - missing `config.yaml` toggles: `rules.tasks.traceability`,
+          `rules.tasks.parallel_markers`, `rules.design.sub_artifacts`,
+          `rules.design.complexity_threshold`,
+          `rules.verify` (`test_command` / `build_command` /
+          `coverage_threshold`)
+        - missing `openspec/memory/constitution.md`
+
+    5b. For each absent piece, additively create or merge ONLY that piece using
+        the canonical shapes defined in step 7 (`config.yaml`) and step 7a
+        (`constitution.md`). Merge missing `config.yaml` sections into the
+        existing file, preserving every present key and value verbatim. Never
+        rewrite a value that is already present. Never renumber or recreate an
+        existing `constitution.md` (see step 7a idempotency).
+
+    5c. Report exactly what was added (list each created path and each merged
+        `config.yaml` section / toggle). If the absent set was empty, report a
+        no-op instead.
 6. If any required OpenSpec path is missing and mode includes OpenSpec, create
    only the minimum structure:
 
@@ -79,40 +113,87 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 
 7. Generate `openspec/config.yaml` dynamically with this shape:
 
-   ```yaml
-   schema: spec-driven
-
-   context: |
-     Tech stack: {detected}
-     Architecture: {detected}
-     Testing: {detected}
-     Style: {detected}
-
-   rules:
-     proposal:
-       - Include rollback plan for risky changes
-       - Identify affected modules/packages
-     specs:
-       - Use Given/When/Then format for scenarios
-       - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
-     design:
-       - Include sequence diagrams for complex flows
-       - Document architecture decisions with rationale
-     tasks:
-       - Group tasks by phase (infrastructure, implementation, testing)
-       - Use hierarchical numbering (1.1, 1.2, etc.)
-       - Keep tasks small enough to complete in one session
-     apply:
-       - Follow existing code patterns and conventions
-       tdd: false
-       test_command: ''
-     verify:
-       test_command: ''
-       build_command: ''
-       coverage_threshold: 0
-     archive:
-       - Warn before merging destructive deltas
-   ```
+       ```yaml
+       schema: spec-driven
+
+       context: |
+         Tech stack: {detected}
+         Architecture: {detected}
+         Testing: {detected}
+         Style: {detected}
+
+       rules:
+         proposal:
+           - Include rollback plan for risky changes
+           - Identify affected modules/packages
+         spec:
+           - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
+           - Use Given/When/Then scenarios
+         design:
+           guidance:
+             - Document architecture decisions with rationale
+             - Require a File Changes section
+           sub_artifacts: false        # optional design sub-artifacts (default off)
+           complexity_threshold:       # author-evaluated eligibility triggers (OR)
+             affected_domains: 3
+             affected_files: 12
+             external_research: true
+         tasks:
+           guidance:
+             - Group tasks by phase with hierarchical numbering
+             - Keep tasks small enough to complete in one session
+           tdd: false                  # TDD ordering flag (sdd-tasks-format)
+           traceability: true          # require [USN] + Spec: tag + Independent Test per task
+           parallel_markers: false     # [P] emission + executing-plans consumption (default off)
+         apply:
+           guidance:
+             - Follow existing code patterns and conventions
+           test_command: ''
+         verify:
+           test_command: ''
+           build_command: ''
+           coverage_threshold: 0
+         archive:
+           - Warn before merging destructive deltas
+
+         # --- mechanism sections (spec-kit-rigor) ---
+         constitution:
+           path: openspec/memory/constitution.md
+           enforce_check: true         # Constitution Check gate blocks on violation
+           version_policy: semver      # MAJOR=remove/redefine, MINOR=add, PATCH=clarify
+         consistency:
+           enforce_block: true         # CRITICAL findings block plan-review
+           require_coverage_percentage: true
+         requirements_quality:
+           enforce_block: true         # incomplete checklist blocks tasks phase
+           dimensions: [completeness, clarity, measurability, testability]
+         clarification:
+           max_markers_per_spec: 3     # [NEEDS CLARIFICATION] cap enforced by plan-reviewer
+         handoffs:
+           surface_hints: true         # surface SddPhaseContract.handoffHints at transitions
+       ```
+
+       Mixing bare `- item` list entries with `key: value` scalars under one key is
+       invalid YAML; when a phase carries scalar toggles (`tasks`, `apply`,
+       `verify`), put its guidance strings under a `guidance:` subkey.
+
+    7a. Bootstrap the project constitution at `openspec/memory/constitution.md`
+        (mode includes OpenSpec):
+        - **Absent** -> create it at `Version: 1.0.0` with `Ratified`/`Last-Amended`
+          dates, the five native principles (delegate-first coordination, read-only
+          role boundaries, governed persistence, multi-harness parity, evidence-led
+          verification) each with Statement/Rationale/Gate Implications, and an empty
+          `## Sync-Impact Report` section.
+        - **Present** -> preserve the existing content AND its existing version
+          unchanged; do NOT recreate or renumber it. This step is idempotent: a
+          second `sdd-init` run on a repo whose `constitution.md` is at `2.1.0`
+          leaves it at `2.1.0`.
+        - **Semver bump policy** (manual, by whoever edits the constitution): MAJOR
+          = a principle removed or redefined; MINOR = a principle added or guidance
+          materially expanded; PATCH = clarification/wording. Each edit also appends
+          a `## Sync-Impact Report` entry. No tooled auto-bump exists.
+        - See `_shared/openspec-convention.md` (Constitution Governance) for the
+          canonical artifact and gate semantics.
 
 8. Never create placeholder SDD artifacts (`proposal.md`, `design.md`,
    `tasks.md`, or spec files) during initialization.
@@ -141,7 +222,11 @@ Return:
 
 ## Rules
 
-- Be idempotent: if OpenSpec already exists, report and ask before updates.
+- Realignment is strictly additive: when `openspec/` already exists, backfill
+  only the absent pieces and NEVER overwrite a value that is already present.
+- An existing `constitution.md` is never renumbered or recreated; create it
+  only when absent and otherwise preserve its content and version unchanged.
+- A re-run on a fully-aligned project is a reported no-op (no writes).
 - In `thoth-mem` mode, never create `openspec/` directories or files.
 - Keep `config.yaml` context concise (max 10 lines).
 - Detect and include CI, test, and style conventions in the context summary.

package/src/skills/sdd-spec/SKILL.md

@@ -28,6 +28,10 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 - A proposal is approved and must be converted into testable requirements
 - Existing change specs need to be expanded or corrected
 
+> Boundary: residual ambiguity that surfaces after spec authoring is resolved by
+> the `sdd-clarify` phase (between `spec` and `design`), not here — spec
+> authoring behavior itself is unchanged.
+
 ## Prerequisites
 
 - `change-name`
@@ -73,12 +77,51 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    and required metadata fields: `title`, `topic_key`, `type`, `project`,
    `scope`, and `content`.
 
-## Output Format
+## Clarification Discipline and Requirements-Quality Checklist
+
+    Follow these mechanisms (canonical definitions in
+    `_shared/openspec-convention.md` — Clarification Discipline and
+    Requirements-Quality Checklist). All are gated by their `config.yaml rules:`
+    sections.
+
+    ### `[NEEDS CLARIFICATION]` markers and Assumptions
+
+    - Use `[NEEDS CLARIFICATION: <concrete question>]` ONLY for a genuine decision
+      fork where no single default is defensible. The marker text MUST name the
+      specific unresolved decision, not a vague placeholder.
+    - Cap markers at `rules.clarification.max_markers_per_spec` (default 3) per spec
+      file.
+    - Informed-guess-first: when an ambiguity has a defensible default, APPLY the
+      default and record it in an `## Assumptions` section of the spec rather than
+      emitting a marker. Do not silently default a genuine fork.
+
+    ### Generate `checklists/requirements.md`
+
+    At or after authoring the delta specs, generate
+    `openspec/changes/{change-name}/checklists/requirements.md` ("unit tests for
+    English"):
+
+    - One `## Domain: {domain}` section per authored delta domain.
+    - Each domain section carries checkbox items across the four dimensions:
+      completeness, clarity, measurability, testability.
+    - Items use the task checkbox states (`- [ ]` / `- [x]` / `- [-] waived:
+      reason`).
+    - The spec->tasks transition is gated on every item being `- [x]` or explicitly
+      waived (gated by `rules.requirements_quality.enforce_block`).
+
+    ### Declare handoffHints
+
+    Declare `handoffHints` for the design phase: the recorded `## Assumptions` and
+    any unresolved `[NEEDS CLARIFICATION]` resolutions the design phase must
+    preserve. Surfacing is gated by `rules.handoffs.surface_hints`.
+
+    ## Output Format
 
 Return:
 
 - `Change`
 - `Artifacts`: list of domain spec paths written
+- `Checklist`: `openspec/changes/{change-name}/checklists/requirements.md`
 - `Topic Key`: `sdd/{change-name}/spec`
 - `Coverage Summary`: requirements and scenarios added or modified
 - `Next Step`: usually `sdd-design`

package/src/skills/sdd-tasks/SKILL.md

@@ -66,18 +66,34 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 
     ## Phase 1: Foundation
     - [ ] 1.1 Set up project structure — `src/config/`
+      **[USN-1]** | Priority: P1
+      **Spec:** `config-domain/Project Structure`
+      **Independent Test:** Inspect `src/config/` exists and typechecks in isolation.
       **Verification**:
       - Run: `pnpm run typecheck`
       - Expected: No TypeScript errors in config files
 
     ## Phase 2: Core Implementation
-    - [ ] 2.1 Implement core logic — `src/core/handler.ts`
+    - [ ] 2.1 Author core-logic tests — `src/core/handler.test.ts`
+      **[USN-2]** | Priority: P1
+      **Spec:** `core-domain/Core Logic`
+      **Independent Test:** Run the new handler test file; it is red before 2.2.
+      **Verification**:
+      - Run: `pnpm test -- -t "core handler"`
+      - Expected: New tests run (red before 2.2)
+    - [ ] 2.2 Implement core logic — `src/core/handler.ts`
+      **[USN-2]** | Priority: P1
+      **Spec:** `core-domain/Core Logic`
+      **Independent Test:** Run the handler tests; they pass against the impl.
       **Verification**:
       - Run: `pnpm test -- -t "core handler"`
       - Expected: All handler tests pass
 
     ## Phase 3: Integration
-    - [ ] 3.1 Integrate with API — `src/api/client.ts`
+    - [ ] 3.1 [P] Integrate with API — `src/api/client.ts`
+      **[USN-3]** | Priority: P2
+      **Spec:** `api-domain/Client Integration`
+      **Independent Test:** Run the API client lint in isolation.
       **Verification**:
       - Run: `pnpm run lint src/api/`
       - Expected: No linting errors in API module
@@ -113,7 +129,51 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 11. The orchestrator handles the `[OKAY]` / `[REJECT]` review loop and any
      necessary fixes before proceeding to execution.
 
-## Output Format
+## Traceability, TDD Ordering, and Handoff Hints
+    
+    Canonical definitions live in `_shared/openspec-convention.md`. These fields are
+    ADDITIVE to the existing `Verification` block, not a replacement, and they are
+    optional for back-compat (legacy `tasks.md` without them still executes).
+    
+    - **`[USN-<n>]`** — a user-story-number grouping label (a coarse story/epic
+      bucket). It is NOT the requirement linkage.
+    - **Priority** — one of `P1`, `P2`, `P3`.
+    - **`Spec:` trace tag** — names the exact requirement the task implements, in
+      `{domain}/{Requirement Name}` format (optionally `#{Scenario Name}`). This is
+      the requirement linkage `plan-reviewer` counts for coverage %; keep it
+      greppable and one requirement per tag.
+    - **`Independent Test`** — how the task's outcome is verified in isolation,
+      without depending on other tasks being complete.
+    
+    ### `tasks.tdd` ordering
+    
+    When `rules.tasks.tdd` is enabled in `config.yaml`, sequence test-authoring
+    tasks BEFORE their corresponding implementation tasks within the same phase (see
+    the Phase 2 example: 2.1 authors tests, 2.2 implements). When `tasks.tdd` is
+    disabled, impose no test-first ordering constraint. `plan-reviewer` enforces
+    this ordering when the flag is enabled.
+    
+    ### `[P]` parallel markers
+
+    When `rules.tasks.parallel_markers` is enabled in `config.yaml`, an optional
+    `[P]` marker MAY be placed AFTER the `N.M` number (`- [ ] 2.1 [P] Title`),
+    never before it (`[P] 2.1` would break the task-numbering validator). Emit
+    `[P]` ONLY on tasks that are intra-phase, dependency-free of every other task
+    in the same phase, and assigned to the SAME execution agent — never across
+    phases and never on tasks with intra-phase dependencies. `[P]` is
+    back-compatible: when `parallel_markers` is disabled or the marker is absent,
+    the plan executes exactly as it does today (absence = today's behavior). It
+    annotates an explicit parallel batch; it does not change `N.M`, `[USN]`, the
+    `Spec:` tag, or introduce flat `T001` ids.
+
+    ### Consume upstream handoffHints
+    
+    At task-generation start, surface the spec/design phases' `handoffHints` and
+    treat them as preservation constraints (coverage decisions, architecture
+    constraints, recorded Assumptions). When no hints were declared, surface
+    nothing. Surfacing is gated by `rules.handoffs.surface_hints`.
+    
+    ## Output Format
 
 Return:
 

package/src/skills/sdd-verify/SKILL.md

@@ -38,6 +38,7 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
 - Design artifact (full pipeline only)
 - Proposal artifact (accelerated pipeline — used as the verification reference)
 - Ability to run the relevant checks or tests
+- Expected `round N` from the dispatch envelope (the verify-loop round counter; defaults to round 1 for the first verify after apply)
 
 ## Workflow
 
@@ -59,13 +60,31 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
     ```md
     # Verification Report: {Change Title}
 
+    ## Round
+    round N  <!-- stamped from the dispatch envelope's expected round; source of truth for the loop counter -->
+
     ## Completeness
     ## Build and Test Evidence
     ## Compliance Matrix
     <!-- Full pipeline: map Given/When/Then scenarios from spec -->
     <!-- Accelerated pipeline: map success criteria from proposal -->
     ## Design Coherence (full pipeline only)
+
     ## Issues Found
+
+    ### Critical
+    - **[C1]** {one-line problem statement}
+      - file: `path/to/file.ts:LINE` (or `path/to/file.ts` when line is N/A)
+      - scenario: `{Requirement title} › {Scenario name}` (full pipeline) OR
+        criterion: `{proposal success-criterion id/text}` (accelerated pipeline)
+      - fix: {imperative remediation instruction}
+
+    ### Warnings
+    - **[W1]** {one-line problem statement}
+      - file: `path/to/file.ts:LINE`
+      - scenario / criterion: {anchor}
+      - fix: {imperative remediation instruction}
+
     ## Verdict
     ```
 
@@ -77,6 +96,15 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    Use the memory tool binding for `mem_save` with the canonical SDD topic key
    and required metadata fields: `title`, `topic_key`, `type`, `project`,
    `scope`, and `content`.
+8. Stamp the expected `round N` from the dispatch envelope into the report's
+   `## Round` field and the `Round` return field. The orchestrator treats this
+   `round N` marker as the source of truth for the verify-loop round counter
+   when enforcing the round bound across iterations.
+9. Apply the governance-touched heuristic from
+   `_shared/openspec-convention.md` > Constitution Governance > Amendment
+   Auto-Suggest. When it matches, surface the shared report-only
+   `sdd-constitution` suggestion. This is advisory and MUST NOT change the
+   verdict or block verification.
 
 ## Output Format
 
@@ -85,9 +113,11 @@ Return:
 - `Change`
 - `Artifact`: `openspec/changes/{change-name}/verify-report.md`
 - `Topic Key`: `sdd/{change-name}/verify-report`
+- `Round`: `round N` (mirrors the report's `## Round` marker)
 - `Verdict`: pass, pass with warnings, or fail
 - `Compliance Summary`: compliant vs total scenarios
-- `Critical Issues`: bullets or `None`
+- `Critical Issues`: anchored compact lines (`id — file:line — scenario/criterion — fix`), one per issue, or `None`
+- `Constitution Suggestion`: surfaced or none
 
 ## Rules
 
@@ -96,4 +126,6 @@ Return:
   scenarios in full pipeline, proposal success criteria in accelerated pipeline.
 - Distinguish blockers from warnings clearly.
 - Do not fix issues inside this phase; report them.
+- Every Critical Issue MUST carry at least one remediation anchor (file: and/or scenario:/criterion:); prose-only Critical Issues are invalid output.
+- Stamp the `round N` marker from the dispatch envelope into `## Round`.
 - Recover full artifacts with the protocol in the persistence contract.