Moonspec Verify

---
name: moonspec-verify
description: Verify a completed implementation against the original instructions, a declarative source document, an issue brief, or an optional MoonSpec feature packet, plus AGENTS.md repo guidance and required tests. Use when the user asks to run or reproduce `/moonspec.verify`, perform a final read-only implementation check, audit unit and integration test evidence, classify requirement coverage, or decide whether more code or test work is needed.
metadata:
  required-capabilities:
    - git
---

# MoonSpec Verify

Use this skill to perform the final MoonSpec verification workflow.

Read [the acceptance policy](references/acceptance-policy.md) before selecting
scope, evidence, verdict, reuse, or completion. This bundle owns that policy;
caller instructions and the selected source supply scope, explicit acceptance
requirements, and evidence.

## Scope

Verify only. Do not modify source code, tests, specs, plans, tasks, docs, migrations, or configuration. Normal disposable test artifacts are acceptable only when already ignored by the project.

This skill answers:

- Does the implementation satisfy the original request or declarative design?
- Is the bounded verification scope fully implemented?
- Do unit tests and integration tests provide credible evidence?
- Which requirements, scenarios, source design mappings, or AGENTS.md principles remain partial, missing, conflicting, or unverified?
- Which stable canonical source claims are covered by implementation behavior, test evidence, artifact evidence, or a clear gap reason?
- Did verified implementation evidence contradict claims in the canonical source document, indicating doc drift that reconciliation must handle?

## Source Acceptance Matrix Verification

When `artifacts/moonspec/source-acceptance.json` or `artifacts/moonspec/acceptance-assessment.json` exists and its `featureId`, source, feature directory, issue reference, or requirement IDs match the selected verification baseline, verify every repo-verifiable source row for that baseline. Do not choose `FULLY_IMPLEMENTED` unless every required repo-verifiable source row for the selected baseline is satisfied. In source-direct verification mode, ignore stale or unrelated acceptance artifacts whose source metadata does not match the selected source.

## Inputs

- Treat the user's instructions as a valid verification baseline, not merely optional focus.
- Treat a referenced declarative document as a valid verification baseline. Read it directly and verify its in-scope desired-state claims without requiring a derived MoonSpec feature packet.
- Do not treat ad hoc verifier guidance, such as "focus on API tests", workflow meta-instructions, or review-process instructions, as the verification baseline when an issue brief, `spec.md`, feature directory, original implementation request, or declarative source is available. Use that guidance only to prioritize evidence gathering within the real baseline.
- In issue-brief verification mode, use the provided issue brief artifact, issue reference, acceptance criteria, and assessment artifact as the verification baseline without requiring a MoonSpec feature directory, `spec.md`, `plan.md`, or `tasks.md`.
- When an active feature directory or `spec.md` exists, use it as optional derived context and traceability. `plan.md` and `tasks.md` are also optional process context; their absence is never by itself a verification gap.
- Read `AGENTS.md` when present for project principles, repo constraints, and test discipline.
- Use absolute paths in reports.
- Keep the verdict conservative when evidence is incomplete.

Stop only when no usable verification baseline can be located or the available baseline is genuinely too ambiguous to bound. Do not choose `NO_DETERMINATION`, `BLOCKED`, or `ADDITIONAL_WORK_NEEDED` solely because `spec.md`, `plan.md`, `tasks.md`, or other derived MoonSpec artifacts are absent. If an optional `spec.md` contains multiple stories and no narrower original instruction or declarative scope is available, report `NO_DETERMINATION` and recommend splitting the design with `/moonspec.breakdown` or selecting a narrower verification target.

## Pre-Verify Hooks

Before verification, check for extension hooks:

1. If `.specify/extensions.yml` exists, read it and look for `hooks.before_verify`.
2. If the YAML cannot be parsed or is invalid, skip hook checking silently.
3. Ignore hooks where `enabled` is explicitly `false`; hooks without `enabled` are enabled.
4. Do not evaluate non-empty `condition` expressions. Treat hooks with no condition, null condition, or empty condition as executable. Skip hooks with non-empty conditions.
5. For each executable hook:
   - Optional hook (`optional: true`): print:

```markdown
## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```

   - Mandatory hook (`optional: false`): print:

```markdown
## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to verification.
```

If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently.

## Setup

Resolve the verification baseline in this order:

1. Explicit original implementation 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 by running `.specify/scripts/bash/check-prerequisites.sh --json --paths-only`.

The first usable source defines the bounded scope. Later sources are supplemental context and traceability only. Workflow-stage prose such as "run the final gate", ad hoc verifier guidance such as "focus on API tests", or other process instructions are operational guidance, not source-direct authority; do not let them outrank an explicit feature directory, `spec.md`, original request, issue brief, declarative source document, or discovered active-feature source. When a canonical declarative document and a derived artifact conflict, follow `docs/Workflows/MoonSpecDocumentModel.md`: the canonical document wins unless verified evidence requires reconciliation.

In source-direct verification mode:

1. Preserve the original instruction text or declarative document path as the report's authority reference.
2. Extract requirements, acceptance-critical behavior, constraints, stable claim IDs, explicit non-goals, and test expectations directly from that source.
3. Bound verification to the requested change or the in-scope claims named by the instructions. Do not require unrelated claims from a broad document.
4. Inspect production code and tests directly. Discover test commands from `AGENTS.md`, README, build configuration, CI configuration, and repository conventions when no plan or task packet is available.
5. Do not require a MoonSpec feature directory, `spec.md`, `plan.md`, `tasks.md`, a source-acceptance artifact, or an assessment artifact.

If the user provides issue-brief verification inputs, use issue-brief verification mode. Accept inputs expressed in prose or preset instructions such as:

- issue provider, for example `jira` or `github`
- issue reference, for example `MM-1063` or `owner/repo#123`
- issue brief artifact path, such as `artifacts/jira-implement-brief.json`
- assessment artifact path, such as `artifacts/jira-implement-assessment.json`

In issue-brief verification mode:

1. Read the original issue brief artifact and any supplied assessment artifact. An absent optional assessment does not replace or invalidate a usable original baseline.
2. Use the original issue summary, description, acceptance criteria, and constraints as the verification baseline. The assessment is process context.
3. Use a `PARTIALLY_IMPLEMENTED` assessment to prioritize gaps; verify the complete selected scope, retaining previously met requirements as regression constraints.
4. An initial `FULLY_IMPLEMENTED` assessment only says implementation appears present. Reuse objective evidence only under the acceptance policy; otherwise execute the missing verification.
5. Inspect production code and tests directly; do not treat the assessment itself as proof that new work is complete.
6. Do not require `spec.md`, `plan.md`, `tasks.md`, or a standalone constitution file.

When verification follows a remediation attempt, rebuild every controlling
classification from the current repository head. A previous verifier report,
its `remainingWork`, and the original assessment are hypotheses and process
context only; they are not current implementation evidence. For every prior
`PARTIAL`, `MISSING`, or remaining-work item, inspect the current production
code and tests and replace the old status, evidence, line numbers, and notes
with current findings. Do not carry stale classifications into a new report. Reuse matching objective
evidence under the acceptance policy and explicitly record that reuse. If the current head differs from the head named
by the assessment or previous report, no gap may remain solely because the old
artifact said it existed or because the candidate is not on the base branch.

Verify the candidate state at the boundary where this skill is invoked. In a
pre-publication verification step, an uncommitted workspace, an absent pull
request, an open issue, and an unmerged candidate are expected inputs, not
implementation or documentation gaps. Do not require downstream commit, pull
request, merge, or issue-closure evidence before returning
`FULLY_IMPLEMENTED`. Gate on those outcomes only when the selected baseline
explicitly makes publication itself part of this verification step and the
workflow has already supplied the resulting publication evidence.
This sequencing rule does not waive an acceptance or safety prerequisite that
the source requires before a repository change, such as proving legacy tasks
have drained before removing their handlers. Verify that prerequisite or return
the bounded evidence handoff; do not perform an unauthorized deployment.

## Evidence policy

Apply [the acceptance policy](references/acceptance-policy.md) to every source
requirement and check. Mandatory acceptance remains controlling regardless of
tool availability; optional enrichment and diagnostics remain advisory. Record
actual command results and exact missing evidence. Isolated implementation tests
must proceed independently of any separately authorized production operation.

If the user provides a specific `spec.md` or feature directory, use it and discover sibling artifacts from that directory when present.

To discover any active feature directory or optional derived context, run the prerequisite script from the repository root in paths-only mode. This discovery is non-blocking and must not replace an already selected source-direct, issue-brief, `spec.md`, or feature-directory baseline:

```bash
.specify/scripts/bash/check-prerequisites.sh --json --paths-only
```

If it succeeds, parse `FEATURE_DIR`, then discover whichever sibling artifacts exist:

- `SPEC = FEATURE_DIR/spec.md`
- `PLAN = FEATURE_DIR/plan.md`
- `TASKS = FEATURE_DIR/tasks.md`
- optional docs such as `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, and `checklists/`
- `REPO_GUIDANCE = AGENTS.md` when present

If discovery fails because no active feature exists, the feature directory is absent, or derived artifacts such as `plan.md` or `tasks.md` are missing, continue with any usable selected baseline already available. Derived-artifact discovery failure is not itself a verification failure.

If shell arguments contain single quotes, use shell-safe escaping such as `'I'\''m Groot'`, or double quotes when possible.

## Workspace Projection Preflight

Before running full-suite verification commands, ensure the repository view is not contaminated by a MoonMind active skill projection:

```bash
test ! -L .agents/skills
test ! -L .gemini/skills
test ! -e skills_active || test -L skills_active
git status --porcelain -- .agents/skills .gemini/skills skills_active
```

If `.agents/skills` or `.gemini/skills` is an active projection symlink, repair the checkout view before running full-suite evidence. Prefer restoring the tracked repository files or using a clean reclone/worktree. If repair is not possible in the current runtime, stop with verdict `BLOCKED`, include the diagnostic `ENVIRONMENT_CONTAMINATED_BY_SKILL_PROJECTION`, set `recoverableInCurrentRuntime: false`, set `recommendedNextAction: blocked`, and do not report `NO_DETERMINATION` merely because MoonMind's active projection masked tracked skill files.

Real repo-authored `.agents/skills` directories are valid source input and must not be deleted, moved, or treated as the active selected skill snapshot.

## Load Verification Sources

In source-direct verification mode, read:

- the original instruction text and every explicitly referenced declarative source needed for the bounded scope.
- `AGENTS.md` and README when present for project constraints and documented verification commands.
- relevant production code, tests, build files, CI configuration, contracts, and runtime wiring discovered from the source requirements.
- optional feature artifacts only when they exist and add useful traceability.

In MoonSpec feature-directory mode, read when present:

- `spec.md`: original request in `**Input**`, the single user story, independent test, acceptance scenarios or `SCN-*`, functional requirements `FR-*`, success criteria `SC-*`, edge cases, assumptions, key entities, and source design mappings such as `DESIGN-REQ-*` or `DOC-REQ-*`.
- `plan.md`: intended architecture, project structure, Principles Check, test commands, test tooling, integration dependencies, and constraints. Treat as optional context, not proof.
- `tasks.md`: expected file paths, sequencing, test commands, and process completion. Treat as optional process evidence only, not implementation proof.
- `AGENTS.md` when present: project principles, repo constraints, `MUST` rules, and testing discipline.
- `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, and `checklists/` when present and relevant.
- `specs/breakdown.md` when source design coverage or cross-spec dependencies matter.
- The canonical source document named by `spec.md` `**Source Document**` when present, plus `artifacts/doc-discoveries/<feature>.json` when it exists, so source-document drift can be assessed.

Do not use copied source requirement text in `spec.md` as evidence that behavior exists.

In issue-brief verification mode, read:

- the issue brief artifact: issue key or GitHub issue ref, title, description, acceptance criteria, loaded preset brief, constraints, and source-resolution metadata when present.
- the assessment artifact: verdict, per-requirement statuses, unmet requirements, partially met requirements, blocking evidence, and summary.
- changed production and test files relevant to the issue brief and assessment gaps.
- local implementation artifacts named by the preset, such as pull request handoff artifacts or verification reports, only as process context.

Do not use the issue brief, assessment, or generated handoff text as evidence that behavior exists.

## Canonical Claim Coverage

When a canonical source document is present, report first-class Canonical Claim Coverage over stable canonical claims from that source while preserving the existing Source Document Drift section for reconciliation handoff.

Build the claim inventory from the canonical source document's stable claim headings and durable claim anchors, such as `DOC-REQ-*`, `CONTRACT-*`, `INV-*`, `NON-GOAL-*`, `QUALITY-*`, and `TEST-*`. Use temporary `DESIGN-REQ-*` values only as source-issue traceability, not as stable canonical claim IDs. Preserve source issue traceability or related coverage IDs when the canonical document provides it, but do not treat traceability prose as proof of behavior.

For each in-scope canonical claim, classify the result with separate fields for:

- Implementation status: `VERIFIED`, `PARTIAL`, `MISSING`, `CONFLICT`, or `NO_DETERMINATION`.
- Verification status: `VERIFIED`, `PARTIAL`, `MISSING`, `CONFLICT`, or `NO_DETERMINATION`.
- Drift status: `NONE`, `POSSIBLE_DOC_DRIFT`, or `DEFINITE_DOC_DRIFT`.

Each claim row must include at least one durable reference in one of these fields:

- Code evidence, such as repository file paths with line numbers or named code symbols.
- Test evidence, such as test file paths, test names, and command results.
- Artifact evidence, such as artifact refs, discovery ledger paths, diagnostics refs, or report refs.
- Gap reason, when evidence is missing, ambiguous, contradictory, or out of scope.

Classify gaps separately:

- Implementation gaps mean required behavior or wiring is absent, partial, or contradictory.
- Verification gaps mean tests, command evidence, or inspection evidence are missing or insufficient.
- Doc drift means verified behavior contradicts, supersedes, or reveals ambiguity in the canonical source document.

Doc drift alone does not block `FULLY_IMPLEMENTED` when implementation behavior and required verification are correct for the agreed story scope. In that case, set the claim's drift status and also record the structured drift in Source Document Drift for `moonspec-doc-reconcile`.

Use durable evidence references instead of pasting large source, code, test, artifact, or log content into the report.

## Verification Inventory

Build an internal inventory before inspecting code:

- One row per explicit source-direct requirement or stable declarative claim in scope.
- One row per `FR-*` when a spec provides them.
- One row per acceptance scenario or `SCN-*` when present.
- One row per observable success criterion or `SC-*` when present.
- One row per edge case that affects behavior.
- One row per relevant AGENTS.md principle, repo constraint, or testing-discipline item that affects implementation or verification.
- One row per in-scope `DESIGN-REQ-*` or `DOC-REQ-*`.
- One row per stable canonical source claim in scope for the story.
- In issue-brief verification mode, one row per acceptance criterion and one row per unmet or partially met assessment requirement.

For each row, track:

- Expected behavior.
- Likely production code touchpoints.
- Expected unit test evidence.
- Expected integration test evidence.
- Current status.
- Concrete evidence.
- Remaining gap.
- For canonical claims, separate implementation gaps, verification gaps, and doc drift.

## Inspect Evidence

Persist the inventory in the verification artifact instead of leaving it only in
agent context. Each row carries a stable requirement ID, the production boundary,
executable check commands, required capability, expected terminal evidence and
the exact candidate commit or checkpoint. In issue-brief mode, reuse the
assessment requirements verification map; fill missing historical entries from
visible source requirements before executing checks. Never change acceptance
scope to fit the available environment.

Apply the acceptance policy's setup recovery and attempt accounting. Persist
readiness, setup actions, original errors, and resume commands with the inventory;
reuse supplied history and honor the owning workflow's limits. Missing historical
setup records do not establish exhausted attempts or prevent safe repository
fixes. Use available repository and managed container capabilities before
classifying a controlling dependency as unavailable. Preserve the same saved
candidate on infrastructure failures and distinguish evidence retry from code
remediation. Do not repeat an unchanged rejected setup. Browser tooling follows
the browser-independent defaults below and is never an implicit prerequisite.

Inspect production code before tests so behavior is verified directly.

Use repository search to find:

- Requirement terms.
- Entity names.
- DTOs, commands, endpoint paths, CLI names, UI routes, event names, or public APIs.
- Config keys, migration names, service registrations, background jobs, middleware, persistence code, and external integrations.
- Test names and fixtures tied to `FR-*`, `SCN-*`, success criteria, contracts, or source design IDs.

Evidence rules:

- Production behavior must exist for each functional requirement.
- Startup wiring, registration, configuration binding, routing, migrations, contracts, background jobs, external services, and persistence must be inspected when required behavior depends on them.
- Unit tests should cover domain rules, transformations, validation, edge cases, and failure modes.
- Integration tests should cover acceptance scenarios, workflows, contracts, persistence, external interfaces, CLI/API/UI wiring, and other system interactions.
- Comments, TODOs, dead code, unreferenced helpers, and documentation-only changes are non-evidence unless the requirement is explicitly documentation-only.
- Implementation must not add hidden scope that contradicts the original request, source design, spec, or relevant repo guidance.

## Run Verification Commands

Run commands when available and safe:

- Unit test commands from `AGENTS.md`, README, build or CI configuration, `plan.md`, `tasks.md`, quickstart, or project conventions.
- Integration test commands from `AGENTS.md`, README, build or CI configuration, `plan.md`, `tasks.md`, quickstart, or project conventions.
- Quickstart validation when executable and safe.
- Build, lint, or typecheck commands when they are part of the documented validation path or needed to resolve ambiguity.

Record exact command results as `PASS`, `FAIL`, or `NOT RUN`.

Follow the repository's managed-agent test boundary when `AGENTS.md` defines
one. Before running tests, inspect that guidance for the documented managed-run
signal and required delegated test command. When the current workspace meets
that signal, confirm the required command is available and route every covered
test through it. Do not run an equivalent host-local test command or install a
test runner into the agent host; results from a path the repository forbids are
invalid verification evidence. A missing host-local runner does not make a
test unavailable while the documented delegated capability exists. If that
capability is missing or rejects the job, preserve its explicit evidence and
classify the environment according to `AGENTS.md`.

### Browser-independent verification

Apply the acceptance policy's browser-independent defaults in every mode. Browser
checks are optional diagnostics unless the controlling source or caller
explicitly requires a browser acceptance gate or human visual signoff for this
verification run. Preserve that explicit authority. Missing browsers, Playwright,
browser installation, screenshots, live UI access, or human visual review must never
block the default verifier or fail its workflow. Record unavailable browser
checks as advisory `NOT RUN`; do not put them in Remaining Work or choose a
non-passing verdict or stop action solely for that reason.

Use executed server/API, client-contract, component, and other non-browser
integration checks to prove the same requested behavior across its real
producers and consumers. Reuse valid candidate-bound evidence where available.
Keep functional defects and missing controlling non-browser evidence actionable;
passing unit helpers alone do not prove an end-to-end requirement. Describe
visual diagnostic limits honestly without requiring a browser to close them.

### Discover Docker Test Options

In every verification mode, inspect the repository's testing documentation,
test scripts, build targets, CI jobs, Dockerfiles, and Compose files for Docker
build and test paths relevant to the changed area. Follow references from
`AGENTS.md` and README to the actual testing playbook and entrypoint; a mention
of CI or an absent local compiler is not enough to classify a check as unavailable.
Use an applicable testing Skill if it is in the resolved active snapshot at
`$MOONMIND_ACTIVE_SKILLS_DIR`; outside a managed run, use the host's available
Skills and repository conventions. If no testing Skill is selected, continue
discovery from repository documentation and scripts without broadening or
mutating the active Skill set. Keep repository-specific commands and image
choices in those sources, not in this verifier.

Distinguish the agent's local tools from its authorized execution substrate.
In MoonMind, inspect the exposed container tool contract and CLI help, and use
the repository's managed test entrypoint or
`moonmind container run --spec <job.json> --request-id <stable-phase-id>`
with a job specification derived from documented test commands and approved
image sources. The API-owned Docker Backend supplies the daemon and toolchain;
neither a local Docker executable nor a daemon socket in the agent is required.
Outside MoonMind, use documented Docker or Compose test commands when the host
authorizes direct Docker access. Preserve test isolation, workspace access
policy, bounded resources, and cleanup in either host. Do not bypass the managed
boundary, guess image references, provision credentials, or alter deployment
configuration to make a test runnable.

For generic jobs, persist a stable request ID for the verification phase,
candidate revision or workspace checkpoint, and workload specification. Reuse
that ID when retrying the same job after a client timeout or continuation;
recover the existing job and its terminal evidence instead of creating another
submission identity. Use a new ID when the candidate, phase, or workload changes.

When an applicable authorized container path exists, attempt the targeted build
or test and inspect its terminal result and logs. CLI help, a submitted job ID,
static checks, and a process wrapper's success are not test completion evidence.
For a missing prerequisite, record the owning service's readiness/admission
diagnostic or the explicit missing capability, image configuration, or authority
that prevents submission. A missing local toolchain, an unselected testing Skill,
or a previous report's environment claim alone does not establish that Docker
testing is unavailable. Do not repeat an unchanged rejected request; complete
independent checks and preserve its evidence for the handoff.

Record the discovered entrypoint, execution substrate, exact command, candidate
revision or workspace checkpoint, terminal job/test result and log/artifact refs,
or the concrete pre-submission blocker in Test Results and Diagnostics. Complete
this discovery before using `NOT RUN`, `recoverableInCurrentRuntime: false`,
`needs_human`, or `blocked` on the grounds that build or test tooling is unavailable.

Use `NOT RUN` with exact owning-boundary failure evidence after attempting supported, authorized setup and execution paths.
Use the acceptance policy when interpreting unavailable assets,
services, credentials, or tooling. Preserve explicitly mandatory prerequisites;
report optional diagnostics as advisory limitations.

## Classify Items

Use these statuses:

- `VERIFIED`: implementation and validation evidence satisfy the item.
- `PARTIAL`: some implementation exists, but behavior, wiring, or test coverage is incomplete.
- `MISSING`: no meaningful implementation evidence exists.
- `CONFLICT`: implementation contradicts the spec, original request, source design, or relevant repo guidance.
- `NO_DETERMINATION`: evidence is too ambiguous or unavailable to make a defensible call.

Rules:

- Do not mark the feature `FULLY_IMPLEMENTED` unless every in-scope source requirement, relevant AGENTS.md principle, source design requirement, and acceptance-critical behavior is `VERIFIED`.
- Missing required unit tests or repo-local hermetic checks is a verification failure unless the selected verification baseline clearly makes that test class irrelevant.
- Missing repo-local hermetic integration coverage for acceptance-critical behavior is a verification gap. Unavailable external evidence follows the acceptance policy: mandatory prerequisites require a handoff, while optional diagnostics remain non-blocking.
- Separate missing implementation from missing validation when both matter.
- Treat violated AGENTS.md `MUST` rules as blocking failures.
- Treat original request misalignment as blocking even if later tasks are complete.
- Source-document drift alone does not block `FULLY_IMPLEMENTED` when the implementation is correct per the agreed story scope; record it in the Source Document Drift section as structured input for `moonspec-doc-reconcile`. Drift becomes blocking only when it reveals the implementation itself contradicts agreed scope.
- Canonical claim doc drift alone follows the same rule: it is non-blocking when behavior and verification are correct, but implementation gaps and verification gaps remain blocking until resolved or explicitly out of scope.

## Verdict

Choose exactly one verdict:

- `FULLY_IMPLEMENTED`: implementation, unit tests, repo-local hermetic checks, source design requirements, relevant AGENTS.md principles, and original request alignment all verify.
- `ADDITIONAL_WORK_NEEDED`: concrete implementation or validation gaps remain.
- `NO_DETERMINATION`: required evidence cannot be inspected or commands cannot be run enough to reach a defensible conclusion.
- `BLOCKED`: the execution environment prevents trustworthy verification, such as `ENVIRONMENT_CONTAMINATED_BY_SKILL_PROJECTION` from the workspace projection preflight. Include the diagnostic, whether it is recoverable in the current runtime, and the minimum repair needed.

Prefer `ADDITIONAL_WORK_NEEDED` over `NO_DETERMINATION` when a concrete missing code or test gap is visible. Use `BLOCKED` only for environment failures; it says nothing about implementation completeness.
Do not choose a blocking verdict solely because advisory validation cannot run.
Use `FULLY_IMPLEMENTED` when the acceptance policy is satisfied. Missing required
external evidence uses `NO_DETERMINATION` with an evidence retry when obtainable,
or `blocked` when unavailable after supported attempts. Use `needs_human` only
for an actual human-owned authority or information decision. Missing runtime
capabilities preventing required checks use `BLOCKED` with `blocked`. These stopping
verdicts preserve uncertainty about completeness; they are not assertion failures.

When the verdict is `ADDITIONAL_WORK_NEEDED`, include a structured Remaining Work section that remediation steps can consume. Each item must identify:

- requirement or acceptance criterion
- gap type: `implementation`, `verification`, `documentation`, or `environment`
- concrete remaining work
- suggested files, commands, or evidence to inspect
- whether the gap is recoverable in the current runtime

Distinguish implementation gaps from verification gaps:

- Implementation gaps mean required behavior, wiring, persistence, contracts, UI/API behavior, or configuration is absent, partial, or contradictory.
- Verification gaps mean tests, command evidence, fixture coverage, integration evidence, or inspectable artifacts are missing or insufficient.
- Environment gaps prevent controlling checks: missing runtime capabilities use `BLOCKED`; required external evidence or authority decisions use `NO_DETERMINATION`. Advisory environment gaps remain non-blocking limitations, not Remaining Work.

Emit concrete `remainingWork` for every `ADDITIONAL_WORK_NEEDED` result. Each item must be bounded enough for a remediation step to act on without reinterpreting the whole report.

## Continuation Decision

Include the continuation decision and its evidence in the report. When structured
JSON is requested, use `recommendedNextAction` and
`recoverableInCurrentRuntime` alongside `verdict` and `remainingWork`:

- `FULLY_IMPLEMENTED` uses `advance`; `BLOCKED` and `FAILED_UNRECOVERABLE` use `blocked`.
- `ADDITIONAL_WORK_NEEDED` and `NO_DETERMINATION` may use
  `reattempt_current_step`, `needs_human`, or `blocked`.
- Any other verdict/action pairing is invalid and fails contract validation.
  Correct the inconsistent verdict or action using the evidence; do not expect
  the caller to silently replace a contradictory decision with a default.
- For `ADDITIONAL_WORK_NEEDED`, use `reattempt_current_step` when the remaining
  work is bounded, authorized, and executable by a separate remediation step.
  The verifier remains read-only; it must not rerun itself to implement the fix.
- For `NO_DETERMINATION`, use `reattempt_current_step` only when another
  verification attempt can obtain different controlling evidence.
- Use `needs_human` when progress requires a scope or authority decision, that only a human can supply. Use
  `blocked` when no authorized execution path can currently proceed. Explain
  what must change and preserve the evidence and concrete remaining work.

Before requesting another attempt, identify the concrete change or controlling
check that an authorized remediation step can actually execute. Distinguish
repository work from prerequisites such as a missing container-test capability,
live deployment access, or a required operator decision. Complete feasible
repository work while preserving those prerequisites; once only unavailable
prerequisites remain, use the appropriate stop action from the acceptance policy and name the required owner,
the evidence they must supply, and the check that resumes verification. A newer
commit, more unexecuted tests, or a rewritten report does not resolve an unchanged
prerequisite. Do not spend another attempt repeating that same blocked check
without evidence that its environment or authority changed.

Keep mandatory acceptance conditions visible in this handoff. An explicitly
required deployment drain or permission check cannot be waived as advisory just
because the sandbox lacks access. Conversely, optional deployment diagnostics
remain non-blocking under the test-evidence policy above. Missing test tooling is
an environment limitation, not proof that an implementation or assertion failed.

An explicit `needs_human` or `blocked` decision for `ADDITIONAL_WORK_NEEDED` or
`NO_DETERMINATION` stops automatic verifier retry and implementation remediation.
It does not discard verified progress or authorize publication; the caller's
existing publication policy governs any draft or checkpoint handoff. The caller
owns plan-node routing and must honor this stop decision without substituting a
retry merely because budget remains. Never encode a remediation node, publication
node, or pull request destination in `recommendedNextAction`.

`recoverableInCurrentRuntime` describes the current verifier's ability to recover;
`false` alone is not a stop decision. A read-only verifier can identify work that
a separate authorized remediation step can complete. If the action is omitted,
the caller retains its verdict-based default; omission is not an explicit stop.

## Evidence binding

For objective success, include `validatedRefs.acceptance` using the complete
`acceptance/v1` contract in [the acceptance policy](references/acceptance-policy.md).
Capture subject and scope before checks and confirm content is unchanged afterward.
Preserve source/base identity separately. Bind each mandatory requirement to actual
command/artifact evidence. A dirty workspace needs its content digest or durable
checkpoint; never use HEAD alone. Report candidate success separately from target
completion. Do not overwrite the initial assessment with this later result.

## Report

Return a Markdown report in the response. Do not write a file unless the user explicitly asks for one.

Use this structure:

```markdown
# MoonSpec Verification Report

**Feature**: [name or spec path]
**Spec**: [absolute path]
**Original Request Source**: spec.md `Input`
**Verdict**: FULLY_IMPLEMENTED | ADDITIONAL_WORK_NEEDED | NO_DETERMINATION | BLOCKED
**Confidence**: HIGH | MEDIUM | LOW

## Test Results

| Suite | Command | Result | Notes |
|-------|---------|--------|-------|
| Unit | [command] | PASS/FAIL/NOT RUN | [notes] |
| Integration | [command] | PASS/FAIL/NOT RUN | [notes] |

## Requirement Coverage

| Requirement | Evidence | Status | Notes |
|-------------|----------|--------|-------|
| FR-001 | [file/test/reference] | VERIFIED/PARTIAL/MISSING/CONFLICT/NO_DETERMINATION | [notes] |

## Acceptance Scenario Coverage

| Scenario | Evidence | Status | Notes |
|----------|----------|--------|-------|

## Story Scope, Principles, And Source Claim Coverage

| Item | Evidence | Status | Notes |
|------|----------|--------|-------|
| DOC-REQ-001 / AGENTS.md principle | [file/test/reference] | VERIFIED/PARTIAL/MISSING/CONFLICT/NO_DETERMINATION | [notes] |

## Canonical Claim Coverage

| Claim | Code Evidence | Test Evidence | Artifact Evidence | Implementation Status | Verification Status | Drift Status | Gap Reason |
|-------|---------------|---------------|-------------------|-----------------------|---------------------|--------------|------------|
| DOC-REQ-001 | [file:line or symbol] | [test path/name or command] | [artifact/ref] | VERIFIED/PARTIAL/MISSING/CONFLICT/NO_DETERMINATION | VERIFIED/PARTIAL/MISSING/CONFLICT/NO_DETERMINATION | NONE/POSSIBLE_DOC_DRIFT/DEFINITE_DOC_DRIFT | [clear reason or empty when fully evidenced] |

## Original Request Alignment

- [Pass/fail summary against the verbatim original request]

## Source Document Drift

| Doc Claim | Observed Behavior | Evidence | Severity |
|-----------|-------------------|----------|----------|
| [docs/ path + claim] | [verified behavior] | [file/test/reference] | definite/possible |

## Gaps

- [Blocking gaps first]

## Remaining Work

- [Ordered, concrete code or test changes required before completion]

For source-direct verification mode, set:

- **Feature**: concise source scope or declarative document path
- **Spec**: N/A (source-direct verification mode)
- **Original Request Source**: original instructions or absolute declarative document path

For issue-brief verification mode, set:

- **Feature**: issue reference
- **Spec**: N/A (issue-brief verification mode)
- **Original Request Source**: issue brief artifact path

Use this structured form for each Remaining Work item:

```markdown
- Requirement: [criterion or assessment requirement]
  Gap Type: implementation | verification | documentation | environment
  Remaining Work: [bounded work]
  Suggested Evidence: [files, tests, commands, or artifact refs]
  Recoverable In Current Runtime: true | false
```

## Decision

- Recommended Next Action: advance | reattempt_current_step | needs_human | blocked
- Recoverable In Current Runtime: true | false
- [Final recommendation and smallest credible next step if not complete]
```

Keep the report evidence-backed and concise. Cite file paths and line numbers when possible.

## Post-Verify Hooks

After reporting, check `.specify/extensions.yml` for `hooks.after_verify` using the same parsing, filtering, and condition rules as pre-verify hooks. For each executable hook:

- Optional hook (`optional: true`): print:

```markdown
## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`
```

- Mandatory hook (`optional: false`): print:

```markdown
## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
```

If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently.

## Key Rules

- Verification is read-only except ignored disposable test artifacts.
- Original instructions, a declarative source document, an issue brief, or an optional `spec.md` may define the bounded verification scope.
- `spec.md`, `plan.md`, and `tasks.md` are disposable derived artifacts. Their absence never blocks verification when another usable baseline exists.
- When `spec.md` names a canonical source document, interpret the story against that document's in-scope stable claims; the canonical document remains the durable desired-state authority unless verified drift is handed off to doc reconciliation.
- Do not require unrelated claims from a larger canonical design to verify for this story, but do not let the temporary spec silently override an in-scope canonical conflict.
- Relevant AGENTS.md guidance defines repo principles, constraints, and test discipline for the story.
- `plan.md` and `tasks.md` are useful context but never proof of implementation.
- Apply the shared acceptance policy consistently. Missing optional diagnostics cannot block acceptance; missing explicitly mandatory prerequisites cannot be waived because the environment lacks access.
- Prefer direct, citeable repository evidence from production code, wiring, configuration, and tests.
- Do not mark the feature complete when required behavior is only inferred and not verified.