Allow source-direct MoonSpec verification - #7
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the moonspec-assess skill and command to assess source acceptance coverage and generate an acceptance assessment artifact before planning. It also updates the moonspec-verify workflow to support source-direct and issue-brief verification baselines, removing the strict requirement for a spec.md or feature directory. The review feedback is highly constructive, pointing out a duplicated instruction line in moonspec-orchestrate.yaml and minor capitalization errors in the markdown documentation for the orchestrate and tasks skills.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| When source-backed requirements are present, ensure moonspec-specify writes artifacts/moonspec/source-acceptance.json for the assessment stage. | ||
| Do not classify this input into a different workflow and do not run moonspec-breakdown from this preset; any story splitting must already be complete before MoonSpec Orchestrate starts. | ||
| Preserve the original request or source design in spec.md so final verification can compare against it. | ||
| When source-backed requirements are present, ensure moonspec-specify writes artifacts/moonspec/source-acceptance.json for the assessment stage. | ||
| When source-backed requirements are present, ensure moonspec-specify writes artifacts/moonspec/source-acceptance.json for the assessment stage. |
There was a problem hiding this comment.
The instruction line about writing source-acceptance.json is duplicated three times within this step (lines 50, 53, and 54). Removing the redundant lines will clean up the orchestration instructions.
When source-backed requirements are present, ensure moonspec-specify writes artifacts/moonspec/source-acceptance.json for the assessment stage.
Do not classify this input into a different workflow and do not run moonspec-breakdown from this preset; any story splitting must already be complete before MoonSpec Orchestrate starts.
Preserve the original request or source design in spec.md so final verification can compare against it.| - Before starting downstream stages, validate that the input is already exactly one independently testable story or an active feature directory with an existing one-story `spec.md`. | ||
| - If the input is a broad design, names multiple stories/features, asks to split or implement all stories, or otherwise cannot be bounded to one independently testable story without selection, stop immediately and report that a higher-level workflow must route it through `moonspec-breakdown` or another upstream selector first. | ||
| - Single-story requests go through `moonspec-specify`. | ||
| - Run `moonspec-assess` after `moonspec-specify` when source acceptance evidence exists. Preserve The original source acceptance matrix, the bounded backlog, and any note that A single story may span multiple implementation surfaces. |
There was a problem hiding this comment.
There are minor capitalization issues in this sentence: 'Preserve The original' should be 'Preserve the original', and 'note that A single' should be 'note that a single'.
| - Run `moonspec-assess` after `moonspec-specify` when source acceptance evidence exists. Preserve The original source acceptance matrix, the bounded backlog, and any note that A single story may span multiple implementation surfaces. | |
| - Run moonspec-assess after moonspec-specify when source acceptance evidence exists. Preserve the original source acceptance matrix, the bounded backlog, and any note that a single story may span multiple implementation surfaces. |
|
|
||
| ## Source Acceptance Coverage | ||
|
|
||
| When `artifacts/moonspec/acceptance-assessment.json` exists, Every missing, partial, conflict, or required-unverified row must map to tests and implementation or verification tasks. Each negative constraint row must be preserved as a test, verification task, or explicit non-repo-verifiable exclusion. |
There was a problem hiding this comment.
The word 'Every' is capitalized after a comma. It should be lowercase 'every' to maintain correct grammar.
| When `artifacts/moonspec/acceptance-assessment.json` exists, Every missing, partial, conflict, or required-unverified row must map to tests and implementation or verification tasks. Each negative constraint row must be preserved as a test, verification task, or explicit non-repo-verifiable exclusion. | |
| When artifacts/moonspec/acceptance-assessment.json exists, every missing, partial, conflict, or required-unverified row must map to tests and implementation or verification tasks. Each negative constraint row must be preserved as a test, verification task, or explicit non-repo-verifiable exclusion. |
a40b988 to
037ebfd
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a40b98857d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Run moonspec-assess after moonspec-specify when artifacts/moonspec/source-acceptance.json exists or when the spec preserves source-backed requirements. | ||
| Verify artifacts/moonspec/acceptance-assessment.json exists before planning continues. |
There was a problem hiding this comment.
For ordinary one-story orchestration inputs that are not backed by a source acceptance matrix, this preset step has no enabled guard, but it still tells the runner to verify artifacts/moonspec/acceptance-assessment.json before planning. That can block the existing orchestrate workflow before moonspec-plan whenever moonspec-specify legitimately did not create source-acceptance.json; make the step conditional/no-op when no source-backed requirements are present.
Useful? React with 👍 / 👎.
| name: MoonSpec Assess | ||
| instructions: Use the moonspec-assess skill to produce artifacts/moonspec/acceptance-assessment.json from source acceptance evidence. |
There was a problem hiding this comment.
All other exported OpenAI skill wrappers use the interface.display_name / short_description / default_prompt schema, but this new exported wrapper uses top-level name and instructions instead. Consumers that parse the existing wrapper schema will project moonspec-assess without display/default-prompt metadata, so the new skill may not be selectable or invoked consistently with the rest of the bundle.
Useful? React with 👍 / 👎.
|
|
||
| ## Source Acceptance Matrix | ||
|
|
||
| When the request is backed by a source document, issue, or external acceptance record, write `artifacts/moonspec/source-acceptance.json` using `"schemaVersion": "v1"`. Preserve source rows such as `SRC-AC-*`, implementation surfaces such as `SRC-SURFACE-*`, negative constraints such as `SRC-NEG-*`, and expected tests such as `SRC-TEST-*`. Mark rows with `repoVerifiable: false` when they require manual, provider, or external evidence, and include `statusHint` only as advisory input for assessment. |
There was a problem hiding this comment.
This adds source-acceptance.json generation only to the skill path, but the exported markdown /moonspec.specify command is still a standalone prompt with no source-acceptance or artifacts/moonspec instruction. In consumers using the markdown slash command path, source-backed specs will never create the matrix that /moonspec.assess and the new orchestrate stage depend on, so the bounded source rows can be silently skipped before planning.
Useful? React with 👍 / 👎.
| Use this skill after `moonspec-specify` and before `moonspec-plan` when a source-backed spec may include `artifacts/moonspec/source-acceptance.json`. | ||
|
|
||
| ## Output | ||
|
|
||
| Write `artifacts/moonspec/acceptance-assessment.json` with schema version `v1`. |
There was a problem hiding this comment.
When a checkout has multiple specs/<feature> directories, these fixed repo-root artifact paths are shared by every source-backed story. A later /moonspec.specify or /moonspec.assess run can overwrite a previous story's matrix, and downstream planning reads the same artifacts/moonspec/* files whenever they are present, so stale acceptance rows can be applied to the wrong feature; make the artifact path feature-specific or require a matching feature identifier before consuming it.
Useful? React with 👍 / 👎.
| 1. Explicit original instructions or an explicitly referenced declarative document in the current request or workflow step. | ||
| 2. Issue-brief verification inputs. | ||
| 3. An explicitly provided `spec.md` or feature directory. | ||
| 4. An active feature directory discovered from repository context. |
There was a problem hiding this comment.
When moonspec-verify is invoked from the orchestrate preset, the current workflow step supplies generic operational text such as “run the final gate,” not the story's original acceptance source. Placing workflow-step instructions ahead of an explicit or discovered feature directory lets that orchestration prose become the selected baseline and makes the real spec.md supplemental, so final verification can skip the feature's FR/SC rows; only treat the original feature request or a referenced source document as source-direct authority.
Useful? React with 👍 / 👎.
| skill: | ||
| id: moonspec-specify | ||
| args: {} | ||
| - title: Assess source acceptance coverage |
There was a problem hiding this comment.
This adds an assess stage to the preset lifecycle, but the exported markdown /moonspec.orchestrate command still lists the flow as specify → plan → tasks with no moonspec-assess step. Consumers that use the markdown slash-command surface instead of the preset will skip the assessment before planning, so source-backed acceptance rows won't feed the bounded backlog even though the new skill and preset expect them to.
Useful? React with 👍 / 👎.
2 participants
Summary
This branch also contains the MoonSpec acceptance-assessment commits already pinned and consumed by MoonMind main.
Root cause
The verifier supported only feature-directory and issue-brief modes. Feature-directory mode required disposable execution artifacts even when authoritative instructions or a canonical declarative document were available, contradicting the MoonSpec document model.
Validation