thoth-agents 0.2.2 → 0.2.3

package/src/skills/_shared/openspec-convention.md

@@ -35,7 +35,15 @@ If any required item is missing:
 - Recommend running the `sdd-init` skill first.
 - Do NOT attempt to create the structure in that skill.
 
-If all required items exist, continue normally.
+If the required items exist but the project is stale (`config.yaml` is missing
+one or more mechanism sections / toggles, or `openspec/memory/constitution.md`
+is absent):
+
+- Recommend running the `sdd-init` skill to additively realign the project.
+- Do NOT attempt to backfill the missing pieces in that skill.
+
+If all required items exist and no mechanism pieces are missing, continue
+normally.
 
 ## Directory Structure
 
@@ -49,8 +57,12 @@ openspec/
     └── {change-name}/
         ├── proposal.md
         ├── specs/
-        │   └── {domain}/spec.md
+        │   └── {domain}/spec.md          # clarified in place by the clarify phase
         ├── design.md
+        ├── research.md                   # optional sub-artifact (gated)
+        ├── data-model.md                 # optional sub-artifact (gated)
+        ├── contracts/                    # optional sub-artifact subdir (gated)
+        ├── quickstart.md                 # optional sub-artifact (gated)
         ├── tasks.md
         └── verify-report.md
 ```
@@ -62,9 +74,12 @@ openspec/
 | Proposal | `openspec/changes/{change-name}/proposal.md` | Intent, scope, approach |
 | Delta specs | `openspec/changes/{change-name}/specs/{domain}/spec.md` | Use one file per domain |
 | Main specs | `openspec/specs/{domain}/spec.md` | Source of truth after archive |
-| Design | `openspec/changes/{change-name}/design.md` | Architecture and file plan |
+| Design | `openspec/changes/{change-name}/design.md` | Architecture and file plan; always produced |
+| Sub-artifacts (optional, gated) | `openspec/changes/{change-name}/{research.md,data-model.md,contracts/,quickstart.md}` | Optional design sub-artifacts; gated by `rules.design.sub_artifacts` + `complexity_threshold` |
 | Tasks | `openspec/changes/{change-name}/tasks.md` | Checkbox checklist updated by apply |
 | Verify report | `openspec/changes/{change-name}/verify-report.md` | Compliance matrix and evidence |
+| Requirements checklist | `openspec/changes/{change-name}/checklists/requirements.md` | Domain-typed requirement-quality gate, consumed before tasks |
+| Constitution | `openspec/memory/constitution.md` | Semver-versioned native principles + Sync-Impact Report |
 
 `apply-progress` and `archive-report` are durable SDD artifacts, but they are
 primarily persisted through thoth-mem topic keys when the mode includes
@@ -94,7 +109,13 @@ above for filesystem artifact recovery.
 
 - `proposal.md` explains why the change exists.
 - `spec.md` uses RFC 2119 keywords and Given/When/Then scenarios (full pipeline only).
+- The `clarify` phase (full pipeline only) resolves residual spec ambiguity in
+  place between `spec` and `design`, editing the delta `spec.md` files under the
+  same path and re-saving the `sdd/{change-name}/spec` key; it produces no new
+  artifact.
 - `design.md` explains how the change will be implemented (full pipeline only).
+  It MAY be accompanied by optional, gated sub-artifacts (`research.md`,
+  `data-model.md`, `contracts/`, `quickstart.md`).
 - `tasks.md` is phase-based and uses Markdown checkboxes.
 - `verify-report.md` maps acceptance criteria to executed evidence: spec
   scenarios in full pipeline, proposal success criteria in accelerated pipeline.
@@ -105,6 +126,12 @@ persistence mode includes OpenSpec.
 
 ## `config.yaml` Shape
 
+`rules:` carries one section per phase or mechanism. A section is EITHER a
+bare list of guidance strings OR a mapping. When a phase needs both human
+guidance and machine-relevant scalar toggles, the guidance list lives under a
+`guidance:` subkey alongside the scalars (mixing bare `- item` sequence entries
+with `key: value` scalars under the same key is invalid YAML).
+
 ```yaml
 schema: spec-driven
 
@@ -113,17 +140,30 @@ context: |
 
 rules:
   proposal:
-    - Proposal-specific guidance
-  specs:
-    - Require RFC 2119 keywords
-    - Require Given/When/Then scenarios
+    - 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:
-    - Document architecture decisions with rationale
+    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:
-    - Use phased checklists with hierarchical numbering
+    guidance:
+      - Group tasks by phase with hierarchical numbering
+      - Require a per-task Verification block
+    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:
-    - Match repository conventions
-    tdd: false
+    guidance:
+      - Follow existing code patterns and conventions
     test_command: ''
   verify:
     test_command: ''
@@ -131,6 +171,176 @@ rules:
     coverage_threshold: 0
   archive:
     - Warn before destructive merges
+
+  # --- 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
 ```
 
 Treat `rules` entries as mandatory phase-specific constraints whenever present.
+Missing `enforce_*` keys default to enforcing; a section that sets its
+`enforce_*` key to `false` downgrades the corresponding block to a report.
+
+## Parallel Task Markers
+
+`sdd-tasks` MAY annotate a task with an optional `[P]` marker placed AFTER the
+`N.M` number (`- [ ] 2.1 [P] Title`), never before it. Placement after the
+number keeps the `tasks-validator` `TASK_NUMBERING` regex green with no
+validator change. `[P]` declares the task is dependency-free of the other
+`[P]`-marked tasks in the SAME phase and targets the same execution agent;
+`executing-plans` consumes a contiguous `[P]` run as one explicit parallel batch
+(recommending worktree isolation for overlapping writers). Both emission and
+consumption are gated by `rules.tasks.parallel_markers` (default off);
+back-compat: an absent marker or disabled toggle executes exactly as today.
+
+## Constitution Governance
+
+The project constitution lives at `openspec/memory/constitution.md` and holds
+NATIVE thoth-agents principles (delegate-first coordination, read-only role
+boundaries, governed persistence, multi-harness parity, evidence-led
+verification). It is NOT spec-kit's articles; only the mechanics of versioned
+governance are adopted.
+
+- **Version**: a semantic version `MAJOR.MINOR.PATCH` in the header, with
+  `Ratified` and `Last-Amended` dates. `sdd-init` bootstraps it at `1.0.0`
+  when absent and preserves the existing content and version when present
+  (idempotent).
+- **Semver bump policy** (manual, performed by the editor): MAJOR = a principle
+  is removed or redefined; MINOR = a principle is added or guidance materially
+  expanded; PATCH = clarification or wording. There is no runtime parser, so
+  the policy is enforced by prose, not tooling.
+- **Sync-Impact Report**: an in-file `## Sync-Impact Report` section (newest
+  entry on top) listing version, change type, principles touched, and the
+  downstream gates/artifacts affected.
+- **Constitution Check gate**: a procedural gate owned jointly by `sdd-design`
+  (self-review while authoring) and `plan-reviewer` (independent enforcement).
+  It reuses the existing `oracle-review` gate plumbing — no new `gate` enum
+  value. On a detected violation it BLOCKS advancement; the block is
+  overridable only through an explicit user decision delivered via the harness
+  blocking-input surface (AskUserQuestion-equivalent), and the override MUST be
+  logged with the violated principle. Gated by `rules.constitution`; when
+  `enforce_check: false`, the check does not block and the skip is noted.
+
+    ### Constitution Amendment
+
+    The AMENDMENT side of the lifecycle is performed by the `sdd-constitution`
+    skill. It executes a guided, human-confirmed semver bump (reusing the Semver
+    bump policy above), updates the `Last-Amended` date, and PREPENDS one
+    `## Sync-Impact Report` entry in the format
+    `- X.Y.Z | change type | principles touched | downstream gates/artifacts affected`
+    (newest entry on top).
+
+    - The ONLY writable target of the amendment is
+      `openspec/memory/constitution.md`.
+    - The bump is human-confirmed via the harness blocking-input surface
+      (AskUserQuestion-equivalent) BEFORE any version is written. There is no
+      runtime parser and no auto-bump; the level is never selected automatically.
+    - When no principle change is warranted the skill performs a reported no-op and
+      writes nothing.
+    - It preserves all existing content and ALL prior Sync-Impact Report entries;
+      it only prepends the new entry and updates the version/date fields.
+
+    ### Read-Only Assets and Report-Only Propagation
+
+    When the plugin is INSTALLED in a harness (OpenCode / Codex), bundled skills are
+    READ-ONLY assets. The `sdd-constitution` skill MUST NOT edit, create, or delete
+    any other `SKILL.md`, any file under `src/`, or any template — its single
+    writable target is the end-user `openspec/memory/constitution.md`.
+
+    Because the enforcement gates (`sdd-design`, `plan-reviewer`) read the
+    constitution LIVE, there are NO static principle copies to realign. Propagation
+    is therefore report-only: the Sync-Impact Report entry DOCUMENTS which
+    downstream gates consume the changed principles, and the skill FLAGS any
+    in-flight change `design.md` / `tasks.md` that reference now-changed principles
+    for HUMAN re-review instead of editing them.
+
+    ### Amendment Auto-Suggest (shared snippet)
+
+    `sdd-verify` and `sdd-archive` REFERENCE this single canonical snippet (they do
+    NOT inline it) to surface a report-only amendment suggestion.
+
+    > **Constitution amendment auto-suggest (report-only).** A completed change is
+    > "governance-touching" when ANY holds: its `proposal.md` Impact/Affected
+    > Areas, `design.md`, `tasks.md`, or delta `spec.md` reference
+    > `openspec/memory/constitution.md`, "the constitution," or a named principle;
+    > OR it modifies `src/skills/_shared/openspec-convention.md` (Constitution
+    > Governance) or `openspec/memory/constitution.md`; OR any artifact names a
+    > constitution principle by title. When governance-touching, surface a
+    > NON-BLOCKING suggestion: "This change touched governance/principles —
+    > consider running `sdd-constitution` to record a constitution amendment." This
+    > suggestion is advisory only; it MUST NOT block verification or archival.
+
+    ### config.yaml mechanism-section backfill
+
+`sdd-init` realignment backfills the `config.yaml` mechanism sections
+(`constitution`, `consistency`, `requirements_quality`, `clarification`,
+`handoffs`) and the `rules.tasks.traceability` / `rules.verify` toggles
+additively, mirroring the constitution idempotency above.
+
+- It MUST detect per-section absence independently and merge ONLY the absent
+  sections / toggles into the existing `config.yaml`.
+- It MUST NOT overwrite any value that is already present; every existing key
+  and value is preserved verbatim.
+- It MUST report which sections / toggles were added.
+- It is idempotent: re-running on a project whose `config.yaml` already carries
+  every mechanism section / toggle is a reported no-op.
+
+## Consistency Severity and Coverage Model
+
+`plan-reviewer` performs cross-artifact consistency analysis across
+proposal<->spec<->design<->tasks IN ADDITION to its executability review (it is
+NOT a new phase). Each finding carries a severity of `CRITICAL`, `HIGH`,
+`MEDIUM`, or `LOW`.
+
+- **Blocking gate**: any `CRITICAL` finding BLOCKS advancement past plan
+  review; non-CRITICAL findings are reported but do not block. The block is
+  overridable only through an explicit, logged user decision via the harness
+  blocking-input surface. Gated by `rules.consistency.enforce_block`.
+- **Requirement-coverage percentage**: `(distinct spec requirements named by
+  >=1 task Spec: tag) / (total ### Requirement: headings across all delta
+  specs)`, e.g. 8 of 10 covered -> 80%. The percentage MUST appear in the
+  review output (gated by `rules.consistency.require_coverage_percentage`).
+
+## Requirements-Quality Checklist
+
+`sdd-spec` generates a domain-typed requirements-quality checklist at
+`openspec/changes/{change-name}/checklists/requirements.md` ("unit tests for
+English"). It has one `## Domain: {domain}` section per authored delta domain,
+each with checkbox items across 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; an incomplete checklist blocks
+(overridable + logged) unless `rules.requirements_quality.enforce_block: false`.
+
+## Clarification Discipline
+
+Spec authoring may use `[NEEDS CLARIFICATION: <question>]` markers for genuine
+unresolved decision forks, capped at `rules.clarification.max_markers_per_spec`
+(default 3) per spec file. Follow an informed-guess-first policy: when an
+ambiguity has a defensible default, apply it and record it in the spec's
+`## Assumptions` section rather than emitting a marker; reserve markers for
+forks with no defensible default. `plan-reviewer` flags any spec file exceeding
+the cap.
+
+## Handoff Hints
+
+`SddPhaseContract` (in `src/harness/core/sdd.ts`) carries an optional
+`handoffHints?: string[]`; a phase declares what the next phase must preserve
+(accepted scope, recorded assumptions, coverage/architecture decisions). The
+field is OPTIONAL — phases without hints stay valid and existing consumers run
+unchanged. SDD skills SURFACE the upstream phase's `handoffHints` in their prose
+at the transition; when absent, no handoff text is surfaced. Gated by
+`rules.handoffs.surface_hints` (when `false`, hints are not surfaced while the
+contract field stays valid).

package/src/skills/executing-plans/SKILL.md

@@ -89,6 +89,17 @@ Before dispatching a task or same-agent batch:
 
 1. Select the next ready task, or the next consecutive ready tasks that target
    the same execution agent and can safely be handled in one dispatch.
+   - **`[P]` parallel batch (toggle-gated)**: when `rules.tasks.parallel_markers`
+     is enabled, consume contiguous `[P]`-marked tasks WITHIN the same phase that
+     target the same execution role as one explicit parallel batch (an upgrade of
+     the implicit same-agent grouping, not a cross-role scheduler). For
+     `[P]` tasks that touch overlapping files, recommend worktree isolation per
+     concurrent writer (or serialize them) to avoid write conflicts; a harness
+     without concurrent dispatch treats the `[P]` batch as an annotated
+     sequential batch and reports the capability gap.
+   - **Back-compat fallback**: when `parallel_markers` is off OR no `[P]` markers
+     are present, fall back to today's implicit consecutive + same-agent grouping
+     unchanged.
 2. Edit the canonical tasks artifact and change each selected task from
    `- [ ]` to `- [~]`.
 3. If the mode is `thoth-mem` or `hybrid`, re-persist the updated tasks
@@ -125,7 +136,25 @@ Every dispatch prompt MUST include these 6 parts:
 `BOUNDARIES` must not contradict accepted proposal or spec scope. Use it to
 limit the current assigned task, not to redefine the approved change scope.
 
-#### C. Receive and Verify
+
+    #### B.1 Traceability Fields (optional, back-compatible)
+    
+    When a task carries the optional `sdd-tasks` traceability fields, SURFACE them
+    during dispatch:
+    
+    - `[USN-<n>]` story id and `Priority:` (P1/P2/P3) — include in the dispatch
+      `CONTEXT`/`TASKS` so the executing agent knows the story grouping and priority.
+    - `Independent Test:` — pass into the dispatch `VERIFICATION` as the in-isolation
+      acceptance check for that task.
+    - `Spec:` trace tag — include as the requirement the task implements.
+    
+    These fields are OPTIONAL. A legacy `tasks.md` whose tasks lack `[USN]`,
+    priority, `Independent Test`, or `Spec:` MUST still execute without error: treat
+    the absent fields as optional and proceed using the task title and
+    `Verification` block alone. Never fail or block a task solely because a
+    traceability field is missing.
+    
+    #### C. Receive and Verify
 
 Read the sub-agent return envelope and respond by status:
 
@@ -188,7 +217,13 @@ After the task list is complete:
    smallest sufficient checks: typecheck, tests, lint, and build when
    appropriate.
 2. Report a completion summary with evidence.
-3. If the work is SDD-backed, suggest `sdd-verify` as the next step.
+3. If the work is SDD-backed, hand off to the bounded verify-loop rather
+   than a single verify shot: dispatch `sdd-verify` as an iterative gate and
+   branch on its verdict — `fail` triggers a targeted fix scoped by the
+   report's remediation anchors and a re-verify; `pass with warnings` and a
+   bound-exhausting `fail` escalate to the user; a clean `pass` proceeds to
+   archive. The loop is capped by the 3-round bound defined in the
+   orchestrator SDD wording (the canonical source of the round number).
 
 ## Return Envelope Contract
 

package/src/skills/plan-reviewer/SKILL.md

@@ -77,7 +77,87 @@ Check only what affects executability:
 10. Task boundaries or non-goals do not contradict accepted proposal/spec
     scope.
 
-## Decision Rules
+## Cross-Artifact Consistency Analysis
+
+    In addition to the executability review above, perform cross-artifact
+    consistency analysis across proposal <-> spec <-> design <-> tasks. This is NOT
+    a new pipeline phase; it rides inside this plan-review gate. All checks below
+    are gated by the corresponding `openspec/config.yaml rules:` sections; a section
+    that disables enforcement downgrades its block to a report.
+
+    ### Severity model
+
+    Every consistency finding carries one severity:
+
+    - `CRITICAL` — a spec requirement with no mapping in tasks, an orphan task with
+      no spec/proposal basis, scope drift contradicting the accepted proposal, or a
+      direct contradiction between artifacts.
+    - `HIGH` / `MEDIUM` / `LOW` — weaker inconsistencies, ambiguity, or
+      presentation issues that are worth reporting but are not on their own
+      blocking.
+
+    Detect and report at least: requirements present in the spec but absent from
+    design or tasks; tasks with no spec basis; scope drift from the proposal; and
+    contradictory statements between artifacts.
+
+    ### Requirement-coverage percentage
+
+    Compute and REPORT a requirement-coverage percentage in the review output
+    (gated by `rules.consistency.require_coverage_percentage`):
+
+    ```
+    coverage % = (distinct spec requirements named by >=1 task `Spec:` tag)
+                 / (total `### Requirement:` headings across all delta specs)
+    ```
+
+    Parse `Spec:` trace tags from `tasks.md` and `### Requirement:` headings from
+    `openspec/changes/{change}/specs/*/spec.md`. Example: 8 of 10 requirements
+    covered -> report `80%`. When no `Spec:` tags are present (legacy tasks), report
+    coverage against what is present rather than failing.
+
+    ### [NEEDS CLARIFICATION] cap enforcement
+
+    Flag any spec file containing more than `rules.clarification.max_markers_per_spec`
+    (default 3) `[NEEDS CLARIFICATION: ...]` markers. Exactly 3 is within the cap
+    and is NOT flagged; 4 or more is flagged as carrying too much unresolved
+    ambiguity to proceed cleanly.
+
+    ### Constitution Check
+
+    Evaluate the design and plan against EACH principle in
+    `openspec/memory/constitution.md` (delegate-first coordination, read-only role
+    boundaries, governed persistence, multi-harness parity, evidence-led
+    verification). Report the specific violated principle(s). Gated by
+    `rules.constitution.enforce_check`; when disabled, note the skip in the output
+    and do not block.
+
+    ### TDD ordering check
+
+    When `rules.tasks.tdd` is enabled, verify that within each phase every
+    implementation task that has a corresponding test task is PRECEDED by that test
+    task. Report a TDD-ordering finding for any implementation task that precedes
+    its test task. When `tasks.tdd` is disabled, impose no ordering constraint.
+
+    ## Blocking Consistency and Constitution Gate
+
+    - Any `CRITICAL` consistency finding OR any Constitution violation BLOCKS
+      advancement past plan review (gated by `rules.consistency.enforce_block` and
+      `rules.constitution.enforce_check` respectively).
+    - Non-CRITICAL findings are reported but do not block on their own.
+    - The block is overridable ONLY through an explicit user decision delivered via
+      the harness blocking-input surface (the AskUserQuestion-equivalent primitive).
+      The override MUST be logged with the finding identity / violated principle and
+      the user's choice before advancement proceeds. If the harness lacks a
+      blocking-input primitive, report an unsupported-capability limitation rather
+      than silently downgrading the block.
+    - Express a blocking outcome through the existing `[REJECT]` token (or a listed
+      CRITICAL finding); a clean analysis adds no friction and proceeds via `[OKAY]`.
+
+    See `_shared/openspec-convention.md` (Consistency Severity and Coverage Model,
+    Constitution Governance, Clarification Discipline) for the canonical, harness-
+    agnostic definitions these checks implement.
+
+    ## Decision Rules
 
 - Default to `[OKAY]`.
 - Use `[REJECT]` only for true blockers.

package/src/skills/requirements-interview/SKILL.md

@@ -84,6 +84,11 @@ scaffolding as user prompts.
    context already answer.
 11. Enforce scope faithfulness: scope calibration must not silently shrink the
     user's stated intent.
+12. Alignment note: a genuine decision fork left unresolved at interview is not
+    settled here — downstream it becomes either a `[NEEDS CLARIFICATION]`
+    marker or a recorded entry in the spec's `## Assumptions` section
+    (informed-guess-first). This note is alignment only; the interview does not
+    own the clarification cap or the Assumptions gate.
 
 ### Phase 3: Complexity Assessment
 
@@ -142,7 +147,7 @@ user to confirm it:
 - 1 dimension is High in logic depth, context span, or discovery need
 - But contract sensitivity and failure cost are not High
 
-**Full SDD** (`sdd-explore -> propose -> spec -> design -> tasks`) — when any of:
+**Full SDD** (`sdd-explore -> propose -> spec -> clarify -> design -> tasks`) — when any of:
 - Contract sensitivity is High
 - Failure cost is High
 - 2 or more dimensions are High
@@ -180,8 +185,10 @@ Collect this choice with the active blocking user input surface rather than
 plain prose.
 
 When the user selects a mode that includes OpenSpec (`openspec` or `hybrid`),
-verify that `openspec/` is initialized. If it is not, recommend running the
-`sdd-init` skill before proceeding.
+verify that `openspec/` is initialized AND not stale. If it is not initialized,
+or it exists but is stale (`config.yaml` missing one or more mechanism sections
+/ toggles, or `openspec/memory/constitution.md` absent), recommend running the
+`sdd-init` skill before proceeding so it can additively realign the project.
 
 Once route, persistence mode, and initialization are confirmed, hand off to the
 corresponding SDD pipeline phase. The handoff MUST include:

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

@@ -57,9 +57,13 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    to `openspec/changes/archive/YYYY-MM-DD-{change-name}/`.
 6. Create an audit trail report summarizing merged domains, archive location,
    verification lineage, and any mode-based skips.
-7. In `thoth-mem` mode, do not create or move `openspec/` artifacts; record the
+7. 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 block archival.
+8. In `thoth-mem` mode, do not create or move `openspec/` artifacts; record the
    archive result only in the audit trail.
-8. If the selected mode includes thoth-mem, persist the audit trail with:
+9. If the selected mode includes thoth-mem, persist the audit trail with:
 
    Use the memory tool binding for `mem_save` with the canonical SDD topic key
    and required metadata fields: `title`, `topic_key`, `type`, `project`,
@@ -74,6 +78,7 @@ Return:
 - `Topic Key`: `sdd/{change-name}/archive-report`
 - `Merged Specs`: list of domains updated in `openspec/specs/`
 - `Audit Summary`: concise bullets
+- `Constitution Suggestion`: surfaced or none
 - `Status`: archived or blocked
 
 ## Rules

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

@@ -0,0 +1,105 @@
+---
+name: sdd-clarify
+description: Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.
+---
+
+# SDD Clarify Skill
+
+Resolve residual ambiguity that survives `sdd-spec` by writing clarified
+resolutions back into the authoritative delta spec, before `sdd-design`
+consumes it.
+
+## 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`: persist to thoth-mem only — do NOT create or modify
+  `openspec/` files.
+- `openspec`: write files only — do NOT call thoth-mem save tools.
+- `hybrid`: persist to both (default).
+
+## When to Use
+
+- The delta specs are authored and residual ambiguity (unresolved
+  `[NEEDS CLARIFICATION]` markers or taxonomy-classified gaps) must be resolved
+  before design.
+- A `full` SDD pipeline run reaches the `clarify` phase between `spec` and
+  `design`. The phase is full-pipeline only; accelerated and direct pipelines
+  skip it.
+
+## Prerequisites
+
+- `change-name`
+- The spec artifact must exist (recoverable under `sdd/{change-name}/spec`).
+- `openspec/changes/{change-name}/checklists/requirements.md` must exist.
+
+## Workflow
+
+1. Read the shared conventions.
+2. Recover `sdd/{change-name}/spec` using the recall funnel in the persistence
+   contract (`mem_recall(mode="compact")` -> `mem_recall(mode="context")` ->
+   `mem_get(...)`), and read the delta spec file(s) under
+   `openspec/changes/{change-name}/specs/{domain}/spec.md`.
+3. **Taxonomy scan** — scan the recovered spec against the ambiguity taxonomy to
+   produce resolution candidates:
+   - ambiguous quantifiers (e.g. "fast", "several", "most")
+   - undefined terms (domain nouns with no pinned meaning)
+   - missing error/edge behavior (no failure/edge path specified)
+   - unresolved decision forks (competing options with no default)
+   - underspecified data shapes (fields, types, or cardinality not pinned)
+   - unstated non-functional bounds (latency, size, concurrency, limits)
+   - plus every unresolved `[NEEDS CLARIFICATION]` marker already in the spec.
+4. **Bounded Q&A** — resolve candidates capped at
+   `rules.clarification.max_markers_per_spec` (default 3) per spec file. With
+   more than the cap, resolve at most the cap's worth, prioritizing the
+   highest-impact ambiguities; leave the rest as explicit markers for a later
+   pass. Prefer an informed-guess default recorded in `## Assumptions` over a
+   blocking question when a defensible default exists.
+5. **Write-back in place** — replace each resolved `[NEEDS CLARIFICATION]`
+   marker / ambiguous statement with its resolved decision directly in the same
+   delta spec file(s) (inline, or folded into the spec's `## Assumptions`
+   section when the resolution is a recorded default). Do NOT create a new
+   artifact (`clarifications.md`, `spec-clarified.md`, etc.). In
+   `hybrid`/`thoth-mem` mode, re-save the edited spec under the SAME canonical
+   key `sdd/{change-name}/spec` (upsert) — no `spec-clarified` key.
+6. **Re-validate** `openspec/changes/{change-name}/checklists/requirements.md`
+   against the clarified spec: flip items that were waived or open due to a
+   now-resolved ambiguity, and declare `handoffHints` for design (the resolved
+   decisions and the re-validated checklist state design must preserve). Do not
+   advance past design with an unresolved checklist.
+
+## Boundary
+
+`sdd-clarify` targets only **post-spec residual** ambiguity. It MUST NOT
+re-run or duplicate the upfront `requirements-interview`, and MUST NOT re-ask
+questions already resolved during requirements discovery. It edits only the
+spec and its requirements checklist; it produces no new permanent artifact.
+
+## Output Format
+
+Return:
+
+- `Change`
+- `Artifact`: clarified delta spec path(s) (edited in place)
+- `Topic Key`: `sdd/{change-name}/spec`
+- `Resolved`: list of ambiguities resolved (marker/taxonomy class -> resolution)
+- `Next Step`: `sdd-design`
+
+## Rules
+
+- Write resolutions back into the authoritative spec in place; never leave a
+  resolved ambiguity standing as unresolved.
+- Reuse the canonical `sdd/{change-name}/spec` topic key (upsert); introduce no
+  new artifact or key.
+- Cap resolutions at `rules.clarification.max_markers_per_spec` per spec file.
+- Re-validate `checklists/requirements.md` before handing off to design.
+- Do not duplicate `requirements-interview`; resolve only residual post-spec
+  ambiguity.
+- Use the recall funnel from the persistence contract for every SDD dependency.