refactor: harden implementation-plan contract for lower-tier execution

.github/internal-prompts/tsh-review-plan.prompt.md

@@ -15,7 +15,7 @@ Before starting, load and follow these skills:
 
 1. **Read the research file** (`.research.md`) — understand the full set of requirements, acceptance criteria, and constraints that the plan must address.
 
-2. **Read the plan file** (`.plan.md`) — understand the proposed architecture, phases, tasks, and definitions of done.
+2. **Read the plan file** (`.plan.md`) — understand the proposed architecture, phases, tasks, and definitions of done. Stop immediately if any row in `## Open Questions` has Status = `❓ Open`; this is a blocker and review cannot proceed until the architect resolves it.
 
 3. **Challenge-domains pass** — Before diving into general failure modes, systematically attack the plan's most consequential decisions using the challenge domains defined in the agent. For each domain, explicitly state whether an issue was found or not. Pay special attention to technology/stack choices that deviate from research context or prior iterations — these are the highest-value challenges.
 
@@ -42,6 +42,7 @@ Before starting, load and follow these skills:
 - Attribute at least 2-3 findings to the challenge-domains pass when the evidence supports them.
 - Do not pad the report with cosmetic, wording, or style-only notes.
 - Do not fall back to generic quality audits or pattern-consistency checks.
+- Flag any `❓ Open` item in the plan's `## Open Questions` table as a blocker requiring resolution before approval.
 - Treat unexplained deviations from research context or prior established direction as likely `BLOCKERS` until justified.
 
 <output-specification>

.github/skills/tsh-creating-implementation-plans/SKILL.md

@@ -13,10 +13,13 @@ This skill turns a designed solution into a phased, verifiable implementation pl
 This skill is the single owner of the plan template (`./plan.example.md`), the plan-structure procedure, and the definition-of-done rules for implementation plans. Other skills and agents MUST reference this skill instead of duplicating plan-structure rules.
 </plan-structure-ownership>
 <goal-hierarchy>
-Every plan defines one Wildly Important Goal, stated explicitly as the single most important outcome the whole plan must achieve. Every phase defines a Goal that clearly advances the Wildly Important Goal, followed by a Description that explains the broader why for reviewers and implementors. The plan itself, after the Wildly Important Goal, also includes a description of the overall approach.
+Every plan defines one Wildly Important Goal, stated explicitly as the single most important outcome the whole plan must achieve. The Wildly Important Goal section must keep that main goal as one sentence and also include an explicit Success Measure plus a Do NOT touch / do NOT add list to reduce scope creep. Every phase defines a Goal that clearly advances the Wildly Important Goal, followed by a Description that explains the broader why for reviewers and implementors. The plan itself, after the Wildly Important Goal, also includes a description of the overall approach.
 </goal-hierarchy>
+<open-questions-dispatch-gate>
+Plans must not be dispatched to an implementor while any Open Questions row has Status = ❓ Open; unresolved questions must be routed back to `tsh-architect` before execution.
+</open-questions-dispatch-gate>
 <no-real-code>
-The plan must not contain real implementation code. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged.
+The plan must not contain real implementation code or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged.
 </no-real-code>
 </principles>
 
@@ -26,13 +29,16 @@ Before drafting, read [`./plan.example.md`](./plan.example.md) in full first —
 
 1. Confirm inputs: a designed solution, typically from `tsh-architecture-designing`, plus task research and context. Do not design the solution here; this skill structures an already-designed solution into a plan.
 2. Define the Wildly Important Goal and the plan description.
-3. Divide the work into small phases. Each phase must have a Goal, a Description, and a list of tasks with checkboxes to mark finished tasks later. After each phase is finished, only fast-running tests and quality checks should be run to verify the implementation is on track: unit tests, integration tests, static code analysis, linters, formatting checks, and project build.
-4. Define each task. Each task must have a Description, a Definition of Done as a checkbox list, and optional Clues that help the implementor (file paths, line ranges, reference patterns, gotchas).
+3. Divide the work into small phases. Each phase must have a Goal, a Description, a `**Verification:**` field listing the exact fast-running checks to run after the phase completes, and a list of tasks with checkboxes to mark finished tasks later. Keep phase verification reviewer-verifiable and limited to fast checks such as unit tests, integration tests, static code analysis, linters, formatting checks, and project build. Source these checks from the plan's Technical Context → Tech Stack / Testing Patterns rather than assuming Node/npm.
+4. Define each task. Each task must have a Description, a `**Files:**` field, and a Definition of Done as a checkbox list. Phase Description states the broader why for reviewers and implementors. Task Description should use a near-imperative form that names the files and the behavior to change. The `**Files:**` field must name every file the task will touch and label each one with `create`, `modify`, or `reuse`. If a file was produced or last touched by an earlier task in the same plan, include an inline back-reference such as `(modify — created in Task 1.1)`; if a file is created and consumed within the same task, no back-reference is needed. Tasks may also include an optional `**Stop Rule:**` sentence near `Clues` that tells the implementor to stop, report, and avoid improvising if the task cannot proceed safely or an expected seam is missing; do not turn this into a formal dependency graph or a `Depends on:` field. Optional Clues should still help the implementor with file paths, line ranges, reference patterns, and gotchas.
 5. Add the mandatory cross-cutting tasks required by the plan rules.
 6. Save the plan as a document following the `./plan.example.md` template. Do not add or remove any sections from the template. Follow the structure and naming conventions strictly.
 
 <definition-of-done-rules>
 Each task must include a definition of done as a checkbox list.
+Each task's Definition of Done must include at least one objectively reviewer-verifiable check.
+When a task changes code, that check must include at least one runnable command taken verbatim from the task's app stack as recorded in Technical Context → Tech Stack / Testing Patterns, matched to the app the task's Files belong to, never assumed from Node/npm (for example `tsc --noEmit` for a Node app, or `uv run pytest <path>` for a Python app).
+For a docs, config, content, or asset task that has no runnable command, the Definition of Done may instead use a deterministic check a reviewer can confirm by inspecting the changed file, such as a grep-style content assertion (for example `docs/<file>.md contains an "## Usage" section`).
 Definition of done must not include deployment steps.
 Definition of done must not include manual QA steps.
 Definition of done must not include steps that cannot be verified by a code reviewer during code review.

.github/skills/tsh-creating-implementation-plans/plan.example.md

@@ -14,13 +14,17 @@
 
 <one-sentence-statement-of-the-single-most-important-outcome-this-plan-must-achieve>
 
+**Success Measure**: <one-sentence-stating-the-condition-that-proves-the-goal-is-achieved>
+
+**Do NOT touch / do NOT add**: <compact-clause-list-or-short-bullet-list-of-out-of-scope-items>
+
 ## Proposed Solution
 
 <description-of-proposed-solution-explaining-the-approach-and-the-why-for-reviewers-and-implementors>
 
 <necessary-diagrams>
 
-> Note: The plan must not contain real implementation code. Pseudo-code is allowed only for genuinely complicated algorithms or ideas. Diagrams and explanations are encouraged.
+> Note: The plan must not contain real implementation code or full implementation bodies/function logic. Pseudo-code is allowed only to explain genuinely complicated algorithms or ideas, and task-boundary seam artifacts such as type definitions, function signatures, DTOs, interfaces, and API shapes are allowed when they clarify the contract without supplying implementation bodies. Diagrams, explanations, and the Technical Context chapter content are allowed and encouraged.
 
 ## Current Implementation Analysis
 
@@ -92,24 +96,57 @@ Project conventions, coding standards, and patterns discovered during planning.
 
 **Description**: <broader-explanation-of-what-should-be-done-and-why>
 
+**Verification:** <fast checks from Technical Context → Tech Stack / Testing Patterns; never assumed from Node/npm>
+
+<!-- Source every Verification and DoD command from Technical Context → Tech Stack / Testing Patterns. Examples by stack:
+	Node:   pnpm test:unit -- <spec>; tsc --noEmit
+	Python: uv run pytest <path>; uv run ruff check
+-->
+
+<!-- Phase Description states the broader why for reviewers and implementors. Task Description uses a near-imperative form that names the files and the behavior. -->
+
 #### Task 1.1 - [CREATE/MODIFY/REUSE] <task-name>
 
 **Description**: <brief description of what the task entails>
 
+**Files:** `src/<feature>.ts` (create), `src/<feature>.types.ts` (reuse)
+
 **Definition of Done**:
 
-- [ ] <specific verifiable criterion>
-- [ ] <specific verifiable criterion>
+- [ ] <specific verifiable criterion in the listed files>
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
+
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
 
 **Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
 
 #### Task 1.2 - [CREATE/MODIFY/REUSE] <task-name>
 
 **Description**: <brief description>
 
+**Files:** `src/<feature>.ts` (modify — created in Task 1.1), `src/<feature>.test.ts` (reuse)
+
 **Definition of Done**:
 
-- [ ] <specific verifiable criterion>
+- [ ] <specific verifiable criterion in the listed files>
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
+
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
+
+**Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
+
+#### Task 1.3 - [CREATE/MODIFY] <docs-or-config-task-name>
+
+**Description**: <brief description of a docs, config, content, or asset change that has no runnable command>
+
+**Files:** `docs/<file>.md` (modify)
+
+**Definition of Done**:
+
+- [ ] <specific verifiable criterion in the listed files>
+- [ ] `docs/<file>.md contains an "## Usage" section` _(deterministic reviewer check — a docs-only task has no runnable command)_
+
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
 
 **Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
 
@@ -119,30 +156,41 @@ Project conventions, coding standards, and patterns discovered during planning.
 
 **Description**: <broader-explanation-of-what-should-be-done-and-why>
 
+**Verification:** <fast checks from Technical Context → Tech Stack / Testing Patterns; never assumed from Node/npm>
+
 #### Task 2.1 - [CREATE/MODIFY] <ui-component-name>
 
 **Description**: <implementation of the UI component based on Figma design>
 
+**Files:** `src/components/<ui-component-name>.tsx` (modify), `src/components/<ui-component-name>.types.ts` (reuse)
+
 **Figma URL**: <figma-url-for-this-component>
 
 **Definition of Done**:
 
-- [ ] <specific verifiable criterion>
-- [ ] <specific verifiable criterion>
+- [ ] <specific verifiable criterion in the listed files>
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
+
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
 
 **Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
 
 #### Task 2.2 - [REUSE] UI Verification of <ui-component-name> by `tsh-ui-reviewer` agent
 
 **Description**: Run `tsh-ui-reviewer` agent via `tsh-review-ui.prompt.md` to verify <ui-component-name> against Figma design. Pass the Figma URL and dev server URL. If verification fails, delegate fix to `tsh-software-engineer` and re-verify (max 5 iterations per component).
 
+**Files:** `src/components/<ui-component-name>.tsx` (reuse), `src/components/<ui-component-name>.test.tsx` (reuse)
+
 **Figma URL**: <figma-url-for-this-component>
 
 **Definition of Done**:
 
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
 - [ ] UI verification passes or escalated to user after 5 iterations
 - [ ] Verification report documented in Changelog
 
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
+
 **Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
 
 ### Phase 3: <phase-name>
@@ -151,13 +199,20 @@ Project conventions, coding standards, and patterns discovered during planning.
 
 **Description**: <broader-explanation-of-what-should-be-done-and-why>
 
+**Verification:** <fast checks from Technical Context → Tech Stack / Testing Patterns; never assumed from Node/npm>
+
 #### Task 3.1 - [CREATE/MODIFY/REUSE] <task-name>
 
 **Description**: <brief description>
 
+**Files:** `src/<feature>.ts` (modify — created in Task 1.1), `src/<feature>.spec.ts` (reuse)
+
 **Definition of Done**:
 
-- [ ] <specific verifiable criterion>
+- [ ] <specific verifiable criterion in the listed files>
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
+
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
 
 **Clues**: <optional-hints-for-the-implementor-file-paths-reference-patterns-gotchas>
 
@@ -167,16 +222,23 @@ Project conventions, coding standards, and patterns discovered during planning.
 
 **Description**: Final verification of the full implementation. This phase is mandatory and always comes last.
 
+**Verification:** <fast checks from Technical Context → Tech Stack / Testing Patterns; never assumed from Node/npm>
+
 #### Task 4.1 - [REUSE] Code review by `tsh-code-reviewer` agent
 
 **Description**: Run `tsh-code-reviewer` agent via `tsh-review.prompt.md` to review the complete implementation. Pass e2e test execution to that agent as part of the prompt — do not run e2e tests outside this review.
 
+**Files:** `src/<feature>.ts` (reuse), `src/<feature>.spec.ts` (reuse)
+
 **Definition of Done**:
 
+- [ ] Run `<verification command from Technical Context → Testing Patterns>`
 - [ ] Code review passes with no blocking findings
 - [ ] E2e tests executed by the reviewer pass
 - [ ] Review outcome documented in Changelog
 
+**Stop Rule:** <optional one-sentence condition telling the implementor to stop, report, and not improvise if the task cannot proceed safely or an expected seam is missing>
+
 **Clues**: <optional-pointers-to-review-scope-or-risk-areas>
 
 ## Security Considerations

.github/skills/tsh-orchestrating-implementation/SKILL.md

@@ -108,6 +108,7 @@ Check the current state before creating or executing any plan.
 | --- | --- | --- |
 | `*.research.md` | It exists for the current task and contains enough context to explain scope, constraints, requirements, and referenced inputs or links | Route to `tsh-context-engineer` with `tsh-research.prompt.md` |
 | `*.plan.md` | It exists for the current task and contains ordered, actionable tasks that can be delegated | Route to `tsh-architect` with `tsh-plan.prompt.md` |
+| Open questions gate | It exists and contains no `❓ Open` rows in `## Open Questions`, so unresolved questions are not blocking execution readiness | Route to `tsh-architect` with `tsh-plan.prompt.md` |
 | Technical Context | The plan has a populated `Technical Context` section with conventions, patterns, stack, and testing guidance relevant to implementation | Route to `tsh-architect` with `tsh-review-codebase.prompt.md` |
 | Plan approval state | The current plan is already reviewed, approved, and unchanged since approval | Route to `tsh-architect` with `tsh-plan.prompt.md` to return a finished reviewed plan |