feat(numencore-core): harden pipeline from orchestrate dogfood feedback

Address five friction points from first full orchestrate run:
- implementor: add interfaces_changed report field for contract shifts
- validator: read spec files directly instead of relying on inlined contracts
- decompose: support section-level context file references
- orchestrate: section extraction, interface change propagation, structured
  retry prompt assembly, build verification at group boundaries only
- sprint: add success criteria to doc template, build verification on
  in-session execution, explicit implementor agent hand-off, conventions
  path in implementation prompt

Bump to v0.5.0.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plugins/numencore-core/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "numencore-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Core development toolkit — workflow skills, agents, and project conventions",
   "author": {
     "name": "Parley Hatch",

plugins/numencore-core/agents/implementor.md

@@ -24,6 +24,7 @@ background: You are an implementor. You build exactly what the brief asks. No sc
 - Follow conventions. If a decision isn't covered, make a reasonable choice and flag it in your report.
 - If blocked, stop and report. Do not work around blockers silently.
 - If the brief conflicts with the codebase, report the conflict. Do not resolve it yourself.
+- If you change a function signature, type, trait, or public API that other components consume, note it in `interfaces_changed` in your report.
 - Do not install dependencies not listed in conventions without flagging it.
 
 ## Before Reporting Complete
@@ -44,7 +45,12 @@ When done, respond with:
 status: complete | failed | blocked
 files_written:
   - <path>
+interfaces_changed:
+  - file: <path>
+    what: <function/type/trait that changed and how>
 summary: <one paragraph — what you did and why>
 issues: <concerns, conflicts, deviations — or "none">
 conventions_gaps: <decisions made not covered by conventions — or "none">
 ```
+
+`interfaces_changed` may be empty. Only include entries when a public interface consumed by other components was added, removed, or had its signature changed.

plugins/numencore-core/agents/validator.md

@@ -12,8 +12,9 @@ background: You are a validator. You verify, you do not fix. Report only.
 
 ## On Start
 
-1. Read the success criteria and interface contract provided in your prompt.
-2. Read the source files listed in the implementor's completion report.
+1. Read the success criteria provided in your prompt.
+2. Read the spec file(s) listed in your prompt. Extract the interface contract from the component spec — this is your validation baseline.
+3. Read the source files listed in the implementor's completion report.
 
 ## Verification Steps
 

plugins/numencore-core/skills/decompose/SKILL.md

@@ -67,13 +67,17 @@ What the agent must produce. Name files, functions, modules.
 How to verify. Must address each element of the relevant interface contract.
 
 ## Context Files
-- spec/components/<relevant>.md
+- spec/components/<relevant>.md (section: <heading text>)
 - spec/stack.md
 
 ## Constraints
 What the agent must respect.
 ```
 
+### Context file references
+
+Context files may include an optional `(section: <heading text>)` qualifier. When present, the orchestrator extracts only the content under that heading (up to the next heading of equal or higher level) instead of loading the entire file. Use section qualifiers for large spec files where a task only needs a specific component or contract. Omit the qualifier when the full file is relevant.
+
 ### Goal detail
 
 Match goal detail to implementor context. If the implementor will have the full spec, an outline of files and functions is sufficient. If the task must stand alone (implementor works from the task file only), include implementation guidance — algorithm sketches, edge cases, integration points.

plugins/numencore-core/skills/orchestrate/SKILL.md

@@ -57,8 +57,10 @@ When dispatching an implementor, assemble the prompt in this order:
 
 1. **Project root**: State the working directory and project root path.
 2. **Task body**: Full markdown from the task file.
-3. **Context files**: Full contents of each file listed in the task's Context Files section, with file path headers.
-4. **Dependency outputs**: For tasks with completed dependencies, list the `files_written` from each dependency's completion report. Instruct the implementor: "Read these files for actual interfaces you depend on — code against the real implementations, not the spec." Do not inline the source — provide paths.
+3. **Context files**: For each file in the task's Context Files section:
+   - If the entry has a `(section: <heading>)` qualifier, extract only the content under that heading (up to the next heading of equal or higher level) and include it with a file path + section header.
+   - Otherwise, include the full file contents with a file path header.
+4. **Dependency outputs**: For tasks with completed dependencies, list the `files_written` from each dependency's completion report. Instruct the implementor: "Read these files for actual interfaces you depend on — code against the real implementations, not the spec." Do not inline the source — provide paths. If a dependency reported `interfaces_changed`, include those entries so the implementor knows what shifted.
 5. **Conventions**: Full contents of `.dev/conventions.md`.
 
 This structure is the contract between orchestrator and implementor. Follow it consistently.
@@ -77,35 +79,54 @@ For each task:
 
 ### Build verification
 
-After each task completes (implementor + validator pass), run a project-level build check if a build tool is available (e.g., `cargo check`, `npm run build`, `go build ./...`). This catches integration issues between tasks that per-task validation may miss.
+Implementors and validators already run per-task builds. The orchestrator runs project-level builds only at **group boundaries** — after all tasks in a parallel group complete and pass validation. This catches cross-task integration issues without redundant per-task builds.
 
-If the build fails after a task that passed validation, treat it as a validator miss — triage and re-dispatch or escalate.
+If the build fails at a group boundary, triage which task's output caused the failure and re-dispatch or escalate. Also run a project-level build during final completion (see Completion section).
 
 ### Handling results
 
 **Implementor returns success:**
 1. Update status to `complete`.
 2. Record the `files_written` list in `state/progress.md` under the task entry — downstream tasks need this.
-3. Dispatch a `numencore-core:validator` agent with: success criteria, interface contract from component spec, files written.
+3. If `interfaces_changed` is non-empty, record it in `state/progress.md` under the task entry. Downstream tasks that depend on this task should be made aware of the change.
+4. Dispatch a `numencore-core:validator` agent with:
+   - Success criteria from the task file
+   - Spec file path(s) from the task's Context Files (the validator reads the contract directly — do not inline it)
+   - Files written by the implementor
 
 **Validator returns pass:**
 1. Confirm `complete` in progress.
-2. Run build verification (see above).
-3. Commit work with a coherent message.
-4. Update `CLAUDE.md`.
+2. Commit work with a coherent message.
+3. Update `CLAUDE.md`.
+4. If this is the last task in a parallel group, run build verification (see above).
 5. Next task.
 
 **Validator returns fail:**
 1. Read the structured report.
 2. Triage:
-   - Clear, localized error → add failure summary to brief, dispatch fresh implementor
+   - Contradicts spec → halt, escalate to user
    - Ambiguous or systemic → escalate to user
-   - Contradicts spec → halt, escalate
+   - Clear, localized error → retry (see below)
 3. Max two retries per task. After two failures → status `blocked`, escalate.
 
+### Retry prompt assembly
+
+When retrying a failed task, assemble the retry prompt in this order:
+
+1. **Original prompt**: The full implementor prompt from the initial dispatch (project root, task body, context files, dependency outputs, conventions).
+2. **Failure context**: Append a `## Previous Attempt` section containing:
+   - `status`: The validator's pass/fail status
+   - `contract_violations`: The full list from the validator report
+   - `convention_violations`: The full list from the validator report
+   - `fix_suggestion`: The validator's fix suggestion
+   - `files_written`: The files from the failed attempt (the implementor should read these as its starting point, not start from scratch)
+3. **Instruction**: "Fix the issues listed above. The files from the previous attempt are already on disk — read them and correct the problems rather than reimplementing from scratch."
+
+This eliminates manual triage-to-prompt translation. The validator report feeds directly into the retry prompt.
+
 ### Commit strategy
 
-Commit after each task passes validation and build verification. Individual task commits provide clean rollback points.
+Commit after each task passes validation. Individual task commits provide clean rollback points.
 
 If a later task reveals that a previously committed task's output is subtly wrong (integration issue the validator missed), note it in `state/progress.md`, set the earlier task back to `blocked`, and escalate. Do not silently amend prior commits.
 

plugins/numencore-core/skills/sprint/SKILL.md

@@ -76,17 +76,22 @@ What this sprint accomplishes. One paragraph.
 ## Architecture Decisions
 Decisions made for this sprint. Stack choices, patterns, rationale in one line each.
 
+## Success Criteria
+Explicit, checkable criteria. Each one passes or fails independently.
+Used for validation after implementation — keep them concrete.
+
 ## Constraints
 - From conventions.md (cite relevant rules)
 - Sprint-specific (scope boundaries, things to avoid)
 
 ## Implementation Prompt
 <self-contained prompt for a fresh context. Includes everything an implementor needs:
-project structure summary, relevant conventions, file plan, specific instructions,
-success criteria. A fresh agent should be able to execute this without asking questions.>
+project root path, codebase-summary.md reference, .dev/conventions.md path (instruct
+the agent to read it first), file plan, specific instructions, and the success criteria
+from above. A fresh agent should be able to execute this without asking questions.>
 ```
 
-The implementation prompt is the core artifact. Write it for a machine, not a human.
+The implementation prompt is the core artifact. Write it for a machine, not a human. Always include the path to `.dev/conventions.md` and instruct the implementor to read it before writing code.
 
 ### 4. Review
 
@@ -97,14 +102,16 @@ Present the sprint doc to the user. Wait for approval or revisions.
 On approval, assess your current session:
 
 - **Context is light, work is scoped** → offer to implement now
-- **Context is heavy or work is large** → recommend a fresh session, point to the sprint doc path
+- **Context is heavy or work is large** → recommend dispatching a `numencore-core:implementor` agent with the implementation prompt from the sprint doc. If context is too heavy even for agent dispatch, recommend a fresh session and point to the sprint doc path.
 
 State your assessment clearly. Let the user decide.
 
 If implementing in-session:
 - Follow the sprint doc as written
 - If you hit a blocker, stop and report it — do not deviate from the plan
-- On completion, summarize what was done and flag any conventions gaps
+- Before reporting complete, run the project build tool (`cargo check`, `npm run build`, `go build ./...`, etc.) to verify the code compiles
+- Check each success criterion from the sprint doc — every one must pass
+- Summarize what was done and flag any conventions gaps
 
 ### 6. Update Conventions