Refine staged planning and evidence reuse; freeze validation candidates and scope execution holds

.nvmrc

@@ -0,0 +1 @@
+22

AGENTS.md

@@ -0,0 +1,38 @@
+- Before doing anything get general project context by reading README.md and plugins/staged-implementation/README.md
+
+- Always make a Plan before implementing. 
+
+  For example:
+
+  • Updated Plan
+    └ Created an implementation plan for WsLite integration and wiring in Bootstrapper.
+      □ Add WsLite module in brain-core
+      □ Implement broadcast binding (guarded)
+      □ Register WsLite in Bootstrapper
+      □ Set ui_state callback (g_ota_bs)
+      □ Remove stub and adjust flags
+      □ Sanity compile Bootstrapper target
+      □ Update docs on flags/endpoint
+
+- Always favor a clean implementation or fix over a quick fix or bandaid solution
+
+When asked for a commit message always provide a oneline commit message and separate sentences with `;`
+
+When asked to write a markdown file the specified path might contain a date followed by `-${name}` .. e.g. 28.12.2025-${name}.md .. replace ${name} with a suitable name for the document.
+
+You do not ever run any destructive commands unless you have explicitely been asked to do so.
+
+## Change Discipline
+
+- If the prompt is a question and verifying in-repo first would improve answer quality, do so.
+- Treat questions, observations, and suggestions as analysis-only; only implement changes when the user explicitly says to implement/apply a patch.
+- No freeform edits: use apply_patch with ≥3 context lines; keep diffs surgical; do not mix unrelated changes.
+- Use spaces (no tabs) for indentation; keep indentation consistent with surrounding code and avoid whitespace-only churn in diffs
+- Plan discipline: keep update_plan synced; exactly one step in_progress; revise when scope shifts.
+- Ambiguity rule: if any symbol/endpoint/data source is unclear, stop and ask — do not guess.
+- Preserve contracts: do not change public API schemas, event semantics, or observable behavior unless explicitly requested.
+- Minimal glue: add only imports/exports/helpers strictly required for the change; no opportunistic refactors.
+- Validate changes: build/typecheck affected targets and run quick verifications relevant to the edit.
+- No legacy/backward‑compat migrations or auto‑fallback heuristics unless explicitly requested.
+- Do not change route paths, auth checks, or CORS policy unless explicitly in scope.
+- Clean cutover only by default; never implement legacy/dual-format parsing or fallback behavior unless explicitly requested.

README.md

@@ -1,6 +1,6 @@
 # Arcana Codex Plugins
 
-This repository is a Codex plugin marketplace for Arcana workflows.
+Codex plugin marketplace for reusable agent workflows.
 
 ## Included Plugins
 
@@ -11,7 +11,7 @@ This repository is a Codex plugin marketplace for Arcana workflows.
 Add this Git repository as a Codex marketplace:
 
 ```bash
-codex plugin marketplace add ssh://git@your-git-server/path/arcana-codex-plugins.git --ref main
+codex plugin marketplace add dayowe/arcana-codex-plugins --ref master
 ```
 
 Install the staged implementation plugin:
@@ -41,9 +41,16 @@ plugins/
 
 ## Updating
 
-After changing a plugin, commit and push the repository, then refresh the marketplace:
+After pushing changes, refresh the marketplace snapshot:
 
 ```bash
 codex plugin marketplace upgrade arcana-codex-plugins
+```
+
+If `plugins/staged-implementation/` changed, reinstall the plugin:
+
+```bash
 codex plugin add staged-implementation@arcana-codex-plugins
 ```
+
+Start a new Codex session after reinstalling so updated skills are loaded.

plugins/staged-implementation/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "staged-implementation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Planner, implementer, validator, and orchestrator skills for staged implementation workflows.",
   "author": {
     "name": "Local developer"

plugins/staged-implementation/README.md

@@ -31,7 +31,7 @@ staged-implementation/
 Codex installs plugins from a marketplace catalog. To publish this from Git, put the plugin inside a marketplace repository:
 
 ```text
-codex-plugins/
+arcana-codex-plugins/
   .agents/
     plugins/
       marketplace.json
@@ -50,9 +50,9 @@ Example `.agents/plugins/marketplace.json`:
 
 ```json
 {
-  "name": "my-codex-plugins",
+  "name": "arcana-codex-plugins",
   "interface": {
-    "displayName": "My Codex Plugins"
+    "displayName": "Arcana Codex Plugins"
   },
   "plugins": [
     {
@@ -76,13 +76,13 @@ Example `.agents/plugins/marketplace.json`:
 Add the marketplace repository:
 
 ```bash
-codex plugin marketplace add ssh://git@your-git-server/path/codex-plugins.git --ref main
+codex plugin marketplace add dayowe/arcana-codex-plugins --ref master
 ```
 
 Install the plugin:
 
 ```bash
-codex plugin add staged-implementation@my-codex-plugins
+codex plugin add staged-implementation@arcana-codex-plugins
 ```
 
 Start a new Codex session after installation so the bundled skills are available.
@@ -126,4 +126,6 @@ Validate an individual skill:
 python3 /path/to/skill-creator/scripts/quick_validate.py /path/to/staged-implementation/skills/planner
 ```
 
-When updating an installed local plugin, bump or cache-bust the plugin version and reinstall it from the marketplace so Codex picks up the new files.
+After pushing marketplace changes, run `codex plugin marketplace upgrade arcana-codex-plugins`.
+
+If this plugin changed, reinstall it with `codex plugin add staged-implementation@arcana-codex-plugins`, then start a new Codex session so updated skills are loaded.

plugins/staged-implementation/skills/implementer/SKILL.md

@@ -53,6 +53,7 @@ The prompt should define scope, non-goals, requirements, invariants, validation,
 5. Validate.
    - Run the validation commands requested in the prompt when feasible.
    - Run targeted additional checks only when they directly reduce risk for the edited surface.
+   - For corrections, identify affected behavior/consumers and rerun affected checks. Reuse evidence only when the assignment permits it and relevant inputs still match; retain original limits. Rerun if applicability is uncertain. Never skip a required fresh check or broaden into unrelated matrices/harnesses.
    - If a command must be adjusted, report the exact adjustment and why.
    - If validation cannot run, report the blocker clearly.
 
@@ -65,7 +66,7 @@ The prompt should define scope, non-goals, requirements, invariants, validation,
 
 7. Report results.
    - Summarize changed files and behavior.
-   - List validations run and their results.
+   - Distinguish fresh validation from verified reused evidence; give results/artifact paths instead of repeating full logs. Retain raw evidence and inspect failures/unexpected output.
    - List blockers, ambiguities, or residual risk.
    - Include the requested contract verification matrix for contract-heavy chunks.
    - Always propose a one-line commit message unless the user explicitly asks not to. If the prompt defines a chunk ID, start the message with that exact prefix.

plugins/staged-implementation/skills/orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: "End-to-end staged implementation orchestrator for any codebase. Use when Codex should run a planner-reviewer-implementer-validator loop across chunks: choose the next prompt from a plan/checklist/prompt map, delegate implementation to a fresh sub-agent using the implementer role, review actual diffs against frozen contracts, invoke validator evidence checks when needed, issue follow-up prompts until accepted or blocked, optionally commit accepted chunks when explicitly authorized, and continue until the checklist is complete."
+description: "End-to-end staged implementation orchestrator for any codebase. Use when Codex should run a planner-reviewer-implementer-validator loop across chunks: audit readiness and ambiguities before implementation, choose the next prompt from a plan/checklist/prompt map, delegate implementation to a fresh sub-agent using the implementer role, review actual diffs against frozen contracts, invoke validator evidence checks when needed, issue follow-up prompts until accepted or blocked, optionally commit accepted chunks when explicitly authorized, and continue until the checklist is complete."
 ---
 
 # Orchestrator
@@ -23,12 +23,14 @@ Prefer a task packet containing:
 - plan path
 - implementation checklist path
 - prompt map path
+- readiness audit path or permission to create/update one beside the plan/checklist
 - prompt output directory or naming convention
 - validation expectations
-- whether commits are authorized
+- commit policy: `authorized-for-accepted-chunks`, `ask-before-each-commit`, or `do-not-commit`
 - stopping conditions
 
-If any required path, contract, data source, validation target, or output location is unclear, stop and ask. Do not guess.
+Resolve required paths and output locations from explicit instructions and established repository/workflow conventions first. For saved prompts, use the identified companion plan/checklist location and a descriptive filename if no narrower convention exists; state the chosen path and do not overwrite unrelated artifacts. Ask when a required location cannot be established or conflicting instructions remain. Do not guess unresolved contracts, data sources or validation targets.
+Resolve and normalize commit authorization under **Commit Rules** before implementation. A missing literal policy label does not require clarification when existing instructions already establish its meaning.
 
 ## Authority Boundaries
 
@@ -36,62 +38,96 @@ If any required path, contract, data source, validation target, or output locati
 - Implementer sub-agents own one scoped implementation pass at a time.
 - Implementer sub-agents must not commit.
 - Validator sub-agents or validator passes gather evidence only; they do not decide final acceptance.
-- Commit only when the user explicitly authorizes committing accepted chunks.
+- Commit only according to the explicit commit policy.
 - Do not push, reset, discard, or revert unrelated changes unless explicitly asked.
 - Stop on contract ambiguity instead of pushing an implementer to guess.
 
 ## High-Level Loop
 
-For each ready chunk:
+Before delegating implementation, run a readiness preflight:
 
 1. Establish current state.
    - Read project instructions first.
-   - Read the plan, checklist, prompt map, recent review notes, and relevant git/worktree state.
+   - Establish context from the plan, checklist, prompt map, current handoff/review and relevant git/worktree state. On continuation, read changed instructions/contracts and affected scope rather than reloading unchanged history.
-   - Identify the next ready chunk from the checklist and prompt map.
+   - Read any existing readiness audit. If no readiness audit exists, create one before writing the first implementer prompt.
+   - Initially classify every chunk as `ready`, `blocked-by-contract-decision`, `blocked-by-dependency`, `blocked-by-environment`, or `needs-small-freeze-before-prompt`. Subsequently verify affected entries/dependencies; broaden when a shared contract changes or applicability is uncertain.
+   - Surface all contract blockers and small freezes to the user before implementation starts.
+   - Stop if any `blocked-by-contract-decision` item remains unresolved, unless the user explicitly authorizes implementing only the `ready` subset while blocked chunks remain held.
+   - Hold the affected chunk and dependents if a required engineering freeze cannot be resolved from written docs; apply **Stopping Conditions** to any independent continuation.
+
+For each authorized ready chunk:
+
+2. Select the next chunk.
+   - Identify the next ready chunk from the checklist, prompt map, and readiness audit.
    - Verify the chunk has not already landed.
    - Run `git status --short` and relevant `git log --oneline` checks to verify the chosen chunk has not already landed and that the review target matches the current worktree.
 
-2. Write the implementer prompt.
+3. Write the implementer prompt.
    - Produce one surgical prompt for that chunk only.
    - Save official prompts beside the companion plan/checklist unless the user requests another output path.
    - Re-read the saved prompt before delegating.
 
-3. Delegate implementation.
+4. Delegate implementation.
    - Spawn a fresh implementer sub-agent when possible.
    - Give the sub-agent the saved prompt and explicitly tell it to use `$implementer`.
    - Pass only the context needed for that chunk.
    - Tell the sub-agent not to commit and to report changed files, validation, blockers, and proposed commit message.
 
-4. Review the result.
+5. Review the result.
    - Inspect the actual diff/worktree, not just the sub-agent summary.
    - Compare against the frozen plan, checklist, prompt, and declared scope.
    - Verify the implementer's self-audit claims against the diff.
    - Lead review with findings ordered by severity.
    - Save or update review outcomes beside the companion plan/checklist when the run is maintaining staged workflow artifacts.
 
-5. Handle review outcome.
+6. Handle review outcome.
-   - If contract ambiguity exists, stop and identify the exact missing decision.
+   - If contract ambiguity exists, hold the affected chunk and identify the exact missing decision; apply **Stopping Conditions** before continuing other work.
    - If implementation violates the prompt or frozen contracts and the docs are clear, write a surgical follow-up prompt.
    - Send the follow-up to the same implementer sub-agent when continuity helps; spawn a new implementer if a fresh pass is safer.
    - Repeat review/follow-up until accepted, blocked, or stopped by the user.
 
-6. Validate when evidence is required.
+7. Validate when evidence is required.
    - Run direct validation yourself for simple build, test, or diff checks.
+   - Keep direct checks on the same stable-candidate/provenance boundary required below for delegated validation.
    - Invoke `$validator` for feature acceptance, regression, contract, UI/browser, runtime, API, device, or integration evidence when a separate validation pass would reduce risk.
-   - Give the validator the frozen plan/checklist/prompt/review findings and exact validation target.
+   - Give the validator the exact target, applicable frozen requirements, findings and evidence limits; avoid unrelated planning/history context.
    - Treat validator results as evidence for the orchestrator's acceptance decision, not as acceptance by themselves.
 
-7. Accept the chunk.
+8. Accept the chunk.
-   - Confirm required validation passed or that the user accepted the validation gap.
+   - Confirm required validation passed under the current recorded acceptance contract; handle explicit user-approved exceptions under **Commit Rules**, never as fabricated PASS evidence.
+   - Recheck that the candidate source/diff and relevant build still match the reviewed/validated identity; changes invalidate affected evidence until reconciled and revalidated.
    - Confirm no out-of-scope work remains.
-   - Commit only if the user authorized commits.
+   - Apply the explicit commit policy.
    - Use the chunk's proposed commit message when acceptable; otherwise write a one-line commit message with the chunk ID prefix when one exists.
 
-8. Continue.
+9. Continue.
-   - Update or report checklist, prompt-map, and review-outcome state as appropriate.
+   - Update one live handoff and the chunk's current outcome; update checklist/map/readiness entries when their state/dependencies change, without copying the running journal into each artifact.
    - Choose the next ready chunk.
    - Stop when all chunks are complete, blocked, or no ready chunk remains.
 
+## Readiness Audit Rules
+
+The readiness audit exists to resolve blockers before implementation, not during the first failed prompt.
+
+Record each chunk's ID and readiness classification. For non-ready chunks, record the applicable details below; reuse a shared blocker entry for affected chunks rather than duplicating its analysis. Dependency-only holds need the missing predecessor and acceptance link, not an options essay.
+
+- chunk ID/name
+- readiness classification: `ready`, `blocked-by-contract-decision`, `blocked-by-dependency`, `blocked-by-environment`, or `needs-small-freeze-before-prompt`
+- exact missing decision, dependency, or environment blocker
+- why an implementer must not decide it
+- recommended default when the written docs support one
+- options and tradeoffs when the user must decide
+- plan/checklist/prompt-map updates required after the decision
+
+Before implementation starts, require one of:
+
+- contract blockers are resolved and the intended chunk's required engineering freezes are recorded in authoritative artifacts
+- or the user explicitly authorizes a ready-subset run while unrelated contract-blocked chunks remain held
+
+Complete later mechanism freezes before their first dependent chunk; independent ready work need not await every later implementation detail. Investigate major feasibility/irreversible risks early. Do not spawn implementers for blocked chunks or let them decide missing parent-route, API, persistence, timebase, ownership or cleanup contracts.
+
+Bound further investigation by a question and an observation that distinguishes mechanisms. When equivalent experiments cannot resolve missing contract, access or authority, record one focused decision/blocker and continue only independently authorized ready work.
+
 ## Prompt Writing Rules
 
 Every implementer prompt must include:
@@ -134,7 +170,7 @@ In the final summary, include a contract verification matrix and explicitly conf
 Keep the implementer `Read these first:` list focused:
 
 - include project instruction/context docs required by the repo
-- include the feature plan
+- include relevant feature-plan sections, not unrelated phases/history
 - include the implementation checklist only when it adds chunk-relevant boundaries or state not restated in the prompt
 - include chunk-specific docs/artifacts the implementer actually needs
 - do not include the prompt map by default
@@ -151,21 +187,35 @@ When spawning an implementer sub-agent:
 - instruct it to edit files directly if the runtime supports sub-agent code edits
 - instruct it not to commit
 - keep the task narrow and self-contained
+- where supported, use scoped context instead of a full-history fork, carrying all applicable instructions, authority and contract references; preserve model/effort choices
 - avoid delegating planner/reviewer decisions
 - wait only when the result is needed for the next critical-path step
 - close sub-agents when their chunk is accepted or permanently blocked
 
-If sub-agent edits are not visible in the main workspace after completion, stop and report the integration limitation instead of reviewing a summary as if it were a diff.
+If sub-agent edits are not inspectable as the actual candidate diff, hold that chunk and report the integration limitation instead of reviewing a summary as if it were a diff. Apply **Stopping Conditions** before continuing other work.
 
 When invoking a validator pass:
 
 - instruct it to use `$validator`
-- provide the exact expected behavior, frozen contracts, and validation target
+- provide the exact expected behavior, frozen contracts and candidate identity: baseline revision plus scoped changes (including relevant untracked inputs), and the relevant build/artifact and its source provenance
+- release implementer writes before validation; prevent overlapping writes to the validated scope, relevant harness/configuration inputs, or replacement of the tested build/target until the pass is released
 - provide approved credential or environment sources only when needed
 - ask for pass/fail/blocked evidence, residual risk, and untested areas
 - do not ask the validator to edit production code or commit
 - review the validator's evidence before accepting the chunk
 
+Use lightweight provenance sufficient to identify what was tested, such as a scoped diff/input digest and build identifier; do not require exhaustive repository/dependency hashing by default. If relevant inputs change during a pass, stop affected validation, preserve the old evidence with its limits, and establish the corrected candidate before revalidation. Non-overlapping work is safe only when it cannot alter those inputs, target or results.
+
+## Review and Validation Effort
+
+Keep roles distinct: implementer self-audit; parent actual-diff/integration/contract review; validator independent checks of assigned behavior/risks. Do not automatically add a general reviewer for each correction. Reuse a validator for bounded corrections while context remains valid; a changed mechanism, disputed finding, new risk or explicit gate may require a fresh challenge. All mandated independent reviews remain required.
+
+For corrections, put a short impact note in the existing prompt/review: changed behavior/files, affected consumers, reruns and proposed evidence reuse. Reuse only after verifying relevant source, harness, dependencies, build configuration and environment match, preserving original limits. A commit ID alone is insufficient. Rerun if applicability is uncertain; shared owners/styles may affect many consumers. Required fresh checks cannot be skipped.
+
+Use automation for repeatable regression/mechanical checks and browser inspection for relevant visual/focus behavior and discrepancies. Do not automatically repeat the full matrix with every tool. Retain each required case at its assigned evidence layer/gate. Matching builds/evidence satisfy a requirement only when it permits reuse; later platform/device checks remain pending until observed. Never silently rewrite acceptance to avoid a blocker.
+
+Report concise results, failures and evidence paths; retain raw logs/artifacts and inspect unexpected output. Link evidence instead of duplicating logs/galleries across reviews. Efficiency does not authorize model changes, missed cases, weaker contracts or unsafe rollback.
+
 ## Review Rules
 
 Review against:
@@ -195,37 +245,72 @@ If there are no findings, state an acceptable verdict clearly before summaries.
 
 ## Commit Rules
 
-Commit accepted chunks only when the user has explicitly authorized commits for the run.
+Commit behavior is controlled only by the explicit commit policy. Supported policies are:
+
+- `authorized-for-accepted-chunks`
+- `ask-before-each-commit`
+- `do-not-commit`
+
+Resolve the policy from current user instructions, still-applicable earlier explicit authorization for this run, or an unambiguous project/workflow policy. Normalize clear ordinary language into a supported value and record it with its source in the handoff or current execution record. Later explicit instructions take precedence. Do not ask the user to repeat authorization or spell the exact label.
+
+For example, "commit each accepted chunk after validation" authorizes `authorized-for-accepted-chunks`; "ask me before every commit" means `ask-before-each-commit`; "do not commit" means `do-not-commit`. General permission to implement, a hypothetical workflow example, or permission for a single commit does not authorize committing all chunks.
+
+If authority remains missing, conflicting or ambiguous after checking those sources, stop and ask before starting implementation. Do not invent a default. A normalized commit policy does not override a user pause or authorize pushing, publishing or unrelated changes.
+
+For `authorized-for-accepted-chunks`:
+
+- commit after each accepted chunk once review and required validation pass
+- never commit unrelated dirty changes
+- use one-line commit messages with the chunk ID prefix when one exists
+
+For `ask-before-each-commit`:
+
+- stop after each accepted chunk
+- report the proposed one-line commit message
+- ask the user before committing
+
+For `do-not-commit`:
+
+- do not commit
+- report the proposed one-line commit message for each accepted chunk
+
+If the user explicitly approves a validation exception, first record its exact scope, residual risk and missing evidence as a change to the acceptance contract. It is not a PASS for the omitted check, does not waive other gates, and cannot override higher-priority safety/authority constraints. Efficiency or permission to continue working is not such an exception.
 
 Before committing:
 
 - inspect the diff
+- recheck the exact changes to be committed and relevant build against the accepted candidate identity; exclude held/unrelated work and resolve any affected evidence mismatch before committing
 - confirm the reviewed chunk is acceptable
-- confirm validation passed or that the user accepted the validation gap
+- confirm required validation passed under the current recorded acceptance contract
 - confirm no unrelated changes are included
 - use a one-line commit message
 - preserve the chunk ID prefix when one exists
 - separate sentence-like clauses with semicolons when needed
 
-Do not commit if:
+Do not commit the target chunk if:
 
 - review findings remain
 - a contract ambiguity is unresolved
-- required validation failed or could not run
+- validation required by that acceptance contract failed or could not run
 - unrelated dirty changes cannot be separated safely
-- the user did not authorize commits
+- the commit policy is `do-not-commit`
+- the commit policy is `ask-before-each-commit` and the user has not approved that specific commit
+- commit authority remains unresolved or cannot be normalized to a supported policy
 
 ## Stopping Conditions
 
-Stop and report clearly when:
+Hold the affected chunk and its dependents, leaving them unaccepted, when:
 
-- a contract, symbol, endpoint, data source, or output path is ambiguous
+- a contract, symbol, endpoint or data source is ambiguous, or a required output location remains unresolved after checking instructions and established conventions
 - the plan/checklist/prompt map disagree and the correct contract cannot be inferred from written docs
+- a `needs-small-freeze-before-prompt` decision affects the next implementation path
 - implementation needs scope widening
-- validation cannot run and the risk cannot be resolved locally
+- required validation fails or cannot run at that chunk's assigned gate
 - sub-agent changes are not inspectable as an actual diff
-- no ready chunks remain
+
-- all chunks are complete
+Record the blocker and preserve held work/evidence. Continue independent ready work only under existing authorization and after verifying it neither depends on the held implementation nor changes the validated scope, build/test inputs or shared runtime state. Separate its acceptance and commit from held work. Different filenames alone do not establish independence; when safe separation is unproven, hold that candidate too.
+
+Stop the entire run and report when the user pauses/stops it, required run authority remains unresolved, a global safety/integrity issue prevents safe work, or no safe authorized ready chunk remains (including completion). Unresolved contract decisions still require explicit ready-subset authorization to continue unaffected work. A chunk-specific environment/validation hold alone does not cancel an otherwise authorized run; it never waives the blocked requirement.
 
 ## Final Response
 
@@ -233,6 +318,7 @@ For each orchestration run, report:
 
 - chunks completed
 - chunks blocked and why
+- readiness audit status
 - commits made, if any
 - validations run
 - residual risk

plugins/staged-implementation/skills/planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: planner
-description: Staged implementation planner/reviewer workflow for any codebase. Use when Codex should prepare or update a plan/checklist/prompt map, choose the next implementation chunk, write an implementer prompt, review staged or supplied diffs against frozen docs, clarify contracts, control scope, or define the next handoff. Do not use for direct implementation unless the user explicitly asks the planner to implement.
+description: Staged implementation planner/reviewer workflow for any codebase. Use when Codex should prepare or update a plan/checklist/prompt map, run a readiness or ambiguity audit, choose the next implementation chunk, write an implementer or orchestrator handoff prompt, review staged or supplied diffs against frozen docs, clarify contracts, control scope, or define the next handoff. Do not use for direct implementation unless the user explicitly asks the planner to implement.
 ---
 
 # Planner
@@ -19,7 +19,7 @@ Treat questions, observations, and suggestions as analysis-only unless the user
 
 - Read the relevant plan, checklist, prompt map, surrounding code, and recent git state needed for the requested action.
 - Own design clarity, scope boundaries, staged review, and next-chunk definition.
-- Freeze contracts, invariants, schemas, routes, event semantics, error mappings, and observable behavior before implementation starts.
+- Freeze applicable contracts, invariants, schemas, routes, event semantics, error mappings, and observable behavior before their dependent implementation starts.
 - Keep chunks narrow, reviewable, and testable.
 - Review against written docs and the actual diff, not intent, summaries, or memory.
 - If a review finding exposes a real contract gap, stop treating it as implementation work and clarify the docs first.
@@ -38,11 +38,14 @@ For planner/reviewer tasks, prefer a task packet containing:
 - current ground truth, such as plan, checklist, prompt map, recent review notes, or git verification notes
 - requested action: write next implementer prompt, review staged diff, clarify docs, update prompt map, prepare checklist, or similar
 - output path, when saving an official artifact is requested or expected
+- commit policy, when writing an orchestrator handoff prompt
 
 If a path, contract, data source, diff target, or output location is required and cannot be discovered safely, stop and ask for the exact missing information. Do not guess.
 
 ## Workflow
 
+Use existing artifacts when they satisfy the requested step. A scoped update or review does not require recreating the entire planning sequence.
+
 1. Prepare or read the plan.
    - Identify the design, contracts, invariants, and semantics that implementation must preserve.
    - Identify what must not be guessed during implementation.
@@ -51,29 +54,38 @@ If a path, contract, data source, diff target, or output location is required an
    - Split work into gates or chunks.
    - Keep the checklist operational, with exit criteria and validation surfaces, not aspirational.
 
-3. Choose the next chunk.
+3. Prepare or read the prompt map.
+   - Map gates/chunks to implementer prompt artifacts.
+   - Track readiness, sequencing, dependencies, and blocked chunks.
+
+4. Run the implementation readiness audit.
+   - Initially inspect every chunk in the plan, checklist and prompt map; subsequently verify changed scope and affected dependencies, broadening when shared contracts change or impact is uncertain.
+   - Surface contract blockers, dependencies, environment blockers, and small decisions that should be frozen before prompting.
+   - Resolve blockers on the intended implementation path; unrelated contract blockers require an explicitly authorized ready-subset run. Follow the readiness rules below for later engineering freezes.
+
+5. Choose the next chunk.
    - Pick one coherent behavioral, contract, or validation unit.
    - Prefer chunks that are independently reviewable and testable.
    - Define in-scope work, explicit non-goals, invariants, validation, and test posture.
 
-4. Write the implementer prompt.
+6. Write the implementer prompt.
    - Write one surgical prompt for the chosen chunk only.
    - Save official next-chunk prompts beside the companion plan/checklist unless the user explicitly asks for chat-only output or gives another path.
    - Do not save ad hoc follow-up/fix prompts unless explicitly asked.
    - Re-read any saved official prompt before finishing.
 
-5. Review implementation.
+7. Review implementation.
    - Inspect the actual diff target. Use `git diff --cached` for staged review unless the user asks for another target.
    - Compare the diff to frozen docs, the prompt, and scope boundaries.
    - Start with findings ordered by severity. If no findings exist, start with a clear acceptable verdict.
 
-6. Resolve ambiguity through docs.
+8. Resolve ambiguity through docs.
    - If docs allow multiple interpretations, identify the exact missing decision.
    - Clarify or request clarification before writing a fix prompt.
    - Do not leave important contract clarifications only in chat when docs should be updated.
 
-7. Define the next handoff.
+9. Define the next handoff.
-   - Continue only after the current chunk is accepted, corrected, or blocked on a documented ambiguity.
+   - Hand off corrections to the current chunk, or record acceptance/a documented contract, dependency or environment hold before selecting another chunk. Continue only independently authorized ready work; preserve held work and honor run-wide pauses/authority limits.
 
 ## Chunk Sizing
 
@@ -104,6 +116,16 @@ Prefer splitting work when:
 
 Do not create separate prompts just because a second file is touched, a helper is extracted, or a checklist has multiple bullets that share the same risk and validation surface.
 
+## Planning and Evidence Proportionality
+
+Give each artifact one job: plan = architecture/rationale; checklist = work/dependencies/acceptance; prompt map = assignment routing/inputs; prompt = bounded execution pass. Link authoritative contracts or restate the exact applicable subset instead of copying whole contracts into every artifact. Preserve all applicable obligations and make them accessible to a fresh worker.
+
+Design validation alongside chunk boundaries. Assign each obligation to the first gate that needs it: local implementation, integrated behavior, or actual platform/device/release. Record its target and prerequisites. Do not require later release evidence before a local chunk unless correctness or safe activation depends on it. An unavailable mandatory check remains pending at its assigned gate; emulation/local success cannot pass that gate.
+
+Prefer existing tests/harnesses and the smallest validation surface that credibly proves the contract. Expand for shared-owner impact or newly found risk. Do not prescribe every appearance × viewport × state combination, another harness or another general review without a coverage need. Retain required integration/independent review and any explicitly mandated matrix or fresh run unless expressly amended.
+
+Specify evidence reuse conditions: relevant source, harness, dependencies, configuration and environment must match, retaining original limits. Changed inputs require affected checks; uncertain applicability requires a rerun. A correction need not repeat unrelated builds/screenshots/reviews, but efficiency cannot weaken an acceptance case.
+
 ## Checklist Artifacts
 
 When asked to write or update an implementation checklist from a plan, make it operational enough for fresh implementer sessions. Include, as applicable:
@@ -114,7 +136,7 @@ When asked to write or update an implementation checklist from a plan, make it o
 - frozen contracts, invariants, exact fields, routes, states, event semantics, persistence formats, and error mappings
 - implementation tasks grouped by behavior or contract surface
 - exit criteria
-- validation commands or validation posture
+- validation commands/posture, acceptance level and required environment; distinguish local, integration and platform/release gates
 - test posture: extend existing tests, add minimal local tests, or no new test harness
 - ambiguity/blocker notes with the exact missing decision
 
@@ -136,6 +158,38 @@ When asked to write or update a prompt map, map checklist gates/chunks to implem
 
 Use the prompt map to preserve sequencing for the planner/reviewer. Do not include the prompt map in downstream implementer prompts by default unless the chosen chunk uses prompt-map readiness or may update the prompt map.
 
+## Readiness / Ambiguity Audit
+
+After the plan, checklist and prompt map exist, audit all chunks once before the first implementer prompt or orchestration, including major feasibility risks and environment availability. Reuse a current audit; subsequently inspect changes and affected dependencies instead of repeating the entire audit. Broaden when a shared contract changes or the affected scope cannot be established.
+
+Classify every chunk as one of:
+
+- `ready`
+- `blocked-by-contract-decision`
+- `blocked-by-dependency`
+- `blocked-by-environment`
+- `needs-small-freeze-before-prompt`
+
+For every non-ready or weakly-ready chunk, produce a decision ledger entry with:
+
+- chunk ID/name
+- exact missing decision, dependency, or environment blocker
+- why the implementer must not decide it
+- recommended default when the written docs support one
+- options and tradeoffs when the user must decide
+- plan/checklist/prompt-map updates required after the decision
+
+One shared blocker can name all affected chunks. Dependency-only holds need the missing predecessor and acceptance link, not a repeated options/decision essay.
+
+Before implementation starts, require one of these outcomes:
+
+- contract blockers are resolved and the intended chunk's required engineering freezes are written into the authoritative artifacts
+- or the user explicitly authorizes starting only the `ready` subset while unrelated contract-blocked chunks remain held
+
+Schedule later mechanism freezes before their first dependent chunk, using actual predecessor code. Incomplete later implementation detail need not block independent ready work; investigate architectural feasibility and irreversible migration risks early. Never relabel an unresolved product/API contract as a routine engineering choice to bypass approval.
+
+Do not treat dependency-pending chunks as contract-ambiguous unless a missing decision blocks their future prompt. Summarize actual blockers clearly. Each further experiment should identify the question and an observation that distinguishes mechanisms. If equivalent experiments cannot resolve it, report the blocker/decision and continue only independently authorized ready work.
+
 ## Implementer Prompt Rules
 
 Before writing the prompt:
@@ -143,13 +197,15 @@ Before writing the prompt:
 - verify the correct next chunk from the checklist, prompt map, recent git history, and current worktree state when available
 - use `git status --short` and relevant `git log --oneline` checks before claiming a chunk is next, landed, or ready for review
 - state which chunk you chose and why
+- verify readiness covers the intended chunk and current dependencies; update affected entries, or complete the initial audit if missing
+- do not write an execution prompt for a chunk affected by unresolved `blocked-by-contract-decision` or `needs-small-freeze-before-prompt` items; ready-subset authorization permits only unaffected ready chunks
 - stop if an ambiguity blocks an implementer-quality prompt
 - include current-state context only to the extent needed for the implementer to execute the chunk without relying on prior chat memory
 
 Keep the implementer `Read these first:` list focused:
 
 - include project instruction/context docs required by the repo
-- include the feature plan
+- include relevant feature-plan sections, not unrelated phases/history
 - include the implementation checklist only when it adds chunk-relevant boundaries or state not restated in the prompt
 - include chunk-specific docs/artifacts the implementer actually needs
 - do not include the prompt map by default; it is mainly a planner/reviewer sequencing artifact
@@ -198,6 +254,46 @@ End implementer prompts by asking for a proposed commit message. When a chunk ID
 
 When the user asks the planner for a commit message, output a one-line commit message. If multiple sentence-like clauses are needed, separate them with semicolons.
 
+## Orchestrator Handoff Prompts
+
+When asked to write, produce, or prepare an orchestrator prompt, treat it as an official durable handoff artifact, not casual chat output.
+
+Save official orchestration handoff prompts at the user's specified path, or follow the established repository/workflow output location and naming convention. Otherwise, save beside the identified plan/checklist/prompt map with a descriptive filename. State the chosen path; do not ask solely because the user omitted a filename. Ask only if the companion location cannot be established or conflicting instructions leave the destination ambiguous. Do not overwrite an unrelated existing artifact. Honor an explicit chat-only request. Re-read the saved file before finishing.
+
+Every orchestrator prompt must include:
+
+- repo root
+- feature/fix name or slug
+- plan path
+- implementation checklist path
+- prompt map path
+- readiness audit path or permission to create/update one beside the plan/checklist
+- prompt output directory or naming convention
+- validation expectations
+- commit policy
+- stopping conditions
+
+The commit policy must be explicit and must use one of:
+
+- `authorized-for-accepted-chunks`
+- `ask-before-each-commit`
+- `do-not-commit`
+
+Resolve commit behavior from the user's current instructions, still-applicable earlier explicit authorization for this run, or an unambiguous project/workflow policy. Normalize clear ordinary-language instructions to one of the supported values and briefly identify their source in the handoff. The user need not supply the exact label. Later explicit instructions take precedence; do not ask again for authorization already given and not withdrawn.
+
+Ask before saving only when commit authority remains missing, conflicting or ambiguous after checking those sources. General permission to implement, an example of a possible workflow, or permission for one specific commit is not authorization to commit every accepted chunk. Do not silently select a policy merely to avoid asking.
+
+If the user says to orchestrate implementation and their stated workflow preference says the orchestrator should commit accepted chunks, use `authorized-for-accepted-chunks` and include this exact policy text:
+
+```text
+Commit policy: authorized-for-accepted-chunks
+Commits are authorized for accepted chunks only. Commit after each accepted chunk once review and required validation pass. Do not commit unrelated dirty changes. Use one-line commit messages with the chunk ID prefix when one exists.
+```
+
+For `ask-before-each-commit`, require the orchestrator to stop after each accepted chunk and ask before committing.
+
+For `do-not-commit`, require the orchestrator to avoid commits and report the proposed one-line commit message for each accepted chunk.
+
 ## Prompt Output Hygiene
 
 Before presenting or saving a prompt:
@@ -228,6 +324,8 @@ A review outcome should capture:
 - validation status and residual risk
 - next recommended action
 
+Maintain one current outcome per chunk and one live execution handoff. Link raw evidence and distinct reviewer verdicts instead of duplicating their narratives across plan/checklist/map. Preserve historical failures; update scheduling artifacts when contracts or dependency state change, not after every tool call.
+
 ## Review Rules
 
 When asked to review staged work:

plugins/staged-implementation/skills/validator/SKILL.md

@@ -45,12 +45,15 @@ Support these modes:
 
 Choose the lightest validation surface that proves the requested behavior with credible evidence.
 
+Follow the assigned acceptance level: local implementation, integration, or actual platform/device/release. Do not import later gate requirements into local acceptance unless the contract makes them prerequisites. Conversely, local or emulated evidence cannot pass an actual-platform gate; report missing mandatory evidence as pending/blocked at the proper level.
+
 ## Workflow
 
 1. Read context.
    - Read project instructions first.
-   - Read the relevant plan, checklist, prompt, review findings, and changed-surface context.
+   - Read the assigned requirements, relevant plan/checklist sections, prompt, findings and changed-surface context; expand when dependencies or applicability are unclear, not to repeat unrelated planning audits.
    - Identify the exact behavior and contracts to validate.
+   - Verify the candidate's baseline/scoped changes, relevant test/build inputs and build/artifact provenance. Confirm writes to that scope and replacement of the target are held for the pass; do not assume a URL or HEAD alone identifies what is being tested.
 
 2. Create a validation plan.
    - List the validation items.
@@ -67,17 +70,20 @@ Choose the lightest validation surface that proves the requested behavior with c
 
 4. Capture evidence.
    - Record commands or tools used.
-   - Summarize relevant output.
+   - Summarize results/failures and artifact paths; retain full logs and inspect unexpected output. Distinguish newly run checks from verified reused evidence with its original limitations.
    - Capture screenshots only when they support the verdict.
    - Note relevant console errors, network failures, logs, or API responses.
    - Do not print secrets, tokens, passwords, or sensitive env values.
 
 5. Report verdict.
+   - Recheck candidate identity before reporting. If relevant inputs changed during validation, stop the affected checks, notify the parent and qualify old evidence; do not claim it validates the changed candidate. Resume affected validation only after a stable candidate is established.
    - Mark each validation item as pass, fail, blocked, or not tested.
    - Explain failures with concrete observed behavior.
    - State residual risk and untested areas.
    - Do not claim acceptance beyond what was validated.
 
+For a correction/revalidation, independently verify the change's impact and reuse only permitted evidence whose relevant source, harness, dependencies, build configuration and environment still match. Do not trust the implementer's PASS alone. Rerun affected checks, new failure cases and explicitly required fresh checks; rerun when applicability is uncertain. Preserve original failed evidence and avoid recreating unchanged reports/galleries. Shared-owner changes may require broader coverage.
+
 ## Browser/UI Validation
 
 When validating a UI with browser or Playwright tools:
@@ -93,6 +99,8 @@ When validating a UI with browser or Playwright tools:
 - Prefer stable selectors and accessible roles when interacting with UI.
 - Stop if the target appears to be production or destructive actions are required without explicit permission.
 
+Give automation and browser inspection complementary roles instead of repeating every assertion through each tool. Capture representative affected visual/state cases plus identified regressions; retain any explicitly mandated viewport/state matrix. Broaden for a concrete uncovered risk, not merely because another tool or reviewer is available.
+
 ## Contract Validation
 
 When validating contracts, check the exact specified behavior: