marcos-ai-bootstrap 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marcos-ai-bootstrap",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Materialise the AI-Bootstrap agent/skill network (Claude Code, Codex, GitHub Copilot CLI) into any repository from the command line.",
   "bin": {
     "marcos-ai-bootstrap": "src/bin/ai-bootstrap.js"

package/src/.agents/skills/implement/SKILL.md

@@ -65,7 +65,8 @@ For each batch, in order:
 2. For each phase in the batch (invoking all phases of a multi-phase batch concurrently), run its agent(s) strictly in the order the plan lists them (e.g. `code-codex` -> `test-runner-codex` -> `docs-codex`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
 3. After a phase's last agent completes, you (the implement orchestrator, not any subagent) run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
 4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
-5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop; do not start the next batch, even if sibling phases in the same batch succeeded.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop; do not start the next batch, even if sibling phases in the same batch succeeded. An unstated assumption or unconfirmed, non-blocking requirement surfacing mid-phase (e.g. a performance target no one confirmed) is not a failure: it does not trigger this stop. Have the phase's agent log it as a note in the plan's Implementation notes section and continue with the most conservative interpretation of what the user actually stated. Reserve the stop for genuine failures - broken code, failing tests, an explicitly stated acceptance criterion left unmet, or missing information the phase truly cannot proceed without.
+6. After the final batch completes (or the run stops on a genuine failure), compile every logged Implementation note into a single Human Review summary and present it to the user; never pause mid-run to relitigate an assumption.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
@@ -74,4 +75,4 @@ For each batch, in order:
 - Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
 - Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
 - Only you, the orchestrator, run the full test suite; every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
-- Stop immediately on a failed phase and report clearly.
+- Stop immediately on a genuine failed phase and report clearly. Never stop a batch solely because an agent surfaced an unconfirmed assumption; log it in Implementation notes and continue.

package/src/.agents/skills/planner/SKILL.md

@@ -35,9 +35,10 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke `planner-codex` with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Implementation notes, then a trailing Human Review section (Open questions, Assumptions made, Risks).
 - Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
 - For phases that change code, specify the smallest set of tests the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task — never an inferred, unconfirmed property (a latency bound, scale target, etc.). Record those as assumptions in Human Review instead, phrased as desired, not required.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
 - A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.

package/src/.claude/agents/code-claude.md

@@ -18,3 +18,4 @@ You are the code agent. You implement focused code changes.
 - Use concise comments.
 - Do not update documentation — hand that off to the docs agent.
 - Do not add dependencies without explicit instruction and a documentation update.
+- If an acceptance criterion or plan detail turns out to rest on an unstated assumption (e.g. an unconfirmed performance target), do not halt to ask: implement the smallest change that satisfies what the user actually stated, log the assumption as a note in the plan's Implementation notes / Human Review section, and continue. Stop outright only when the phase truly cannot proceed without the missing information (e.g. missing credentials, an irreversible or destructive choice).

package/src/.claude/agents/planner-claude.md

@@ -14,8 +14,10 @@ Before drafting the plan, check whether any discovered, policy-approved MCP serv
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its
 section structure exactly (title, metadata block, Goal, Constraints +
-Cross-references, Phases, Open questions, Risks). If the template is missing
-from the target repo, fall back to the "Plan structure" section below.
+Cross-references, Phases, Implementation notes, and a trailing Human Review
+section containing Open questions, Assumptions made, and Risks). If the
+template is missing from the target repo, fall back to the "Plan structure"
+section below.
 
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
@@ -25,12 +27,15 @@ from the target repo, fall back to the "Plan structure" section below.
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
 3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
-4. Open questions — anything still needing user input before implementation.
-5. Risks — known unknowns or risky assumptions.
+4. Implementation notes — empty placeholder section for agents to log discoveries during execution.
+5. Human Review, placed last — Open questions, Assumptions made (unconfirmed), Risks.
+
+**All human-facing content goes last:** open questions and unconfirmed assumptions belong in the single trailing Human Review section, never earlier in the plan. Nothing in Goal, Constraints, or Phases should require a mid-implementation decision from the user; a phase that truly cannot proceed without one is the rare exception, not the default.
 
 ## Phase discipline
 - Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
 - For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task. Never encode an inferred, unconfirmed property (a latency bound, a scale target, a specific UX choice, etc.) as a blocking acceptance criterion — record it as an assumption in the Human Review section instead, phrased as a desired outcome, not a requirement.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
 - Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
 - A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
@@ -49,3 +54,4 @@ When naming phase agents, mention only custom agents materialised under `.claude
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
 - Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.
+- Never invent or assert a requirement the user did not state — any inferred nonfunctional target (latency, throughput, scale, uptime, etc.) is a desired outcome recorded under Human Review, never a blocking acceptance criterion.

package/src/.claude/agents/planner-discovery-claude.md

@@ -23,3 +23,4 @@ You are the planner-discovery agent. You run Stage 1 of the two-stage planning p
 - Never write the full implementation plan — that is Stage 2 (the planner agent).
 - Do not write to documents/plans/ — only the planner agent does that.
 - If the task is clearly trivial (single-file, no architecture impact), say so and note that a full plan is unnecessary.
+- Never invent or assert a requirement the user did not state — including implicit nonfunctional targets (latency, throughput, scale, uptime, etc.) that seem "obviously" desirable. If such a property seems relevant, raise it as an explicit open question instead of assuming an answer.

package/src/.claude/skills/implement/SKILL.md

@@ -65,7 +65,8 @@ For each batch, in order:
 2. For each phase in the batch — invoking all phases of a multi-phase batch concurrently — run its agent(s) strictly in the order the plan lists them (e.g. `code-claude` → `test-runner-claude` → `docs-claude`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
 3. After a phase's last agent completes, you — the implement orchestrator, not any subagent — run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
 4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
-5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded. An unstated assumption or unconfirmed, non-blocking requirement surfacing mid-phase (e.g. a performance target no one confirmed) is not a failure: it does not trigger this stop. Have the phase's agent log it as a note in the plan's Implementation notes section and continue with the most conservative interpretation of what the user actually stated. Reserve the stop for genuine failures — broken code, failing tests, an explicitly stated acceptance criterion left unmet, or missing information the phase truly cannot proceed without.
+6. After the final batch completes (or the run stops on a genuine failure), compile every logged Implementation note into a single Human Review summary and present it to the user — never pause mid-run to relitigate an assumption.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
@@ -74,4 +75,4 @@ For each batch, in order:
 - Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
 - Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
 - Only you, the orchestrator, run the full test suite — every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
-- Stop immediately on a failed phase and report clearly.
+- Stop immediately on a genuine failed phase and report clearly. Never stop a batch solely because an agent surfaced an unconfirmed assumption — log it in Implementation notes and continue.

package/src/.claude/skills/planner/SKILL.md

@@ -35,9 +35,10 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke the `planner-claude` agent with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Implementation notes, then a trailing Human Review section (Open questions, Assumptions made, Risks).
 - Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
 - For phases that change code, specify the smallest set of tests the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task — never an inferred, unconfirmed property (a latency bound, scale target, etc.). Record those as assumptions in Human Review instead, phrased as desired, not required.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
 - A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.

package/src/.codex/agents/code-codex.toml

@@ -17,5 +17,6 @@ You are the code agent. You implement focused code changes.
 - Use concise comments.
 - Do not update documentation — hand that off to the docs agent.
 - Do not add dependencies without explicit instruction and a documentation update.
+- If an acceptance criterion or plan detail turns out to rest on an unstated assumption (e.g. an unconfirmed performance target), do not halt to ask: implement the smallest change that satisfies what the user actually stated, log the assumption as a note in the plan's Implementation notes / Human Review section, and continue. Stop outright only when the phase truly cannot proceed without the missing information (e.g. missing credentials, an irreversible or destructive choice).
 - You are not alone in the codebase. Do not revert edits made by the user or other agents; adapt to concurrent changes.
 """

package/src/.codex/agents/planner-codex.toml

@@ -13,8 +13,10 @@ Before drafting the plan, check whether any discovered, policy-approved MCP serv
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its
 section structure exactly (title, metadata block, Goal, Constraints +
-Cross-references, Phases, Open questions, Risks). If the template is missing
-from the target repo, fall back to the "Plan structure" section below.
+Cross-references, Phases, Implementation notes, and a trailing Human Review
+section containing Open questions, Assumptions made, and Risks). If the
+template is missing from the target repo, fall back to the "Plan structure"
+section below.
 
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
@@ -24,12 +26,15 @@ from the target repo, fall back to the "Plan structure" section below.
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
 3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
-4. Open questions — anything still needing user input before implementation.
-5. Risks — known unknowns or risky assumptions.
+4. Implementation notes — empty placeholder section for agents to log discoveries during execution.
+5. Human Review, placed last — Open questions, Assumptions made (unconfirmed), Risks.
+
+**All human-facing content goes last:** open questions and unconfirmed assumptions belong in the single trailing Human Review section, never earlier in the plan. Nothing in Goal, Constraints, or Phases should require a mid-implementation decision from the user; a phase that truly cannot proceed without one is the rare exception, not the default.
 
 ## Phase discipline
 - Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
 - For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task. Never encode an inferred, unconfirmed property (a latency bound, a scale target, a specific UX choice, etc.) as a blocking acceptance criterion — record it as an assumption in the Human Review section instead, phrased as a desired outcome, not a requirement.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
 - Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
 - A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
@@ -48,4 +53,5 @@ When naming phase agents, mention only custom agents materialised under `.codex/
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
 - Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.
+- Never invent or assert a requirement the user did not state — any inferred nonfunctional target (latency, throughput, scale, uptime, etc.) is a desired outcome recorded under Human Review, never a blocking acceptance criterion.
 """

package/src/.codex/agents/planner-discovery-codex.toml

@@ -22,4 +22,5 @@ You are the planner-discovery agent. You run Stage 1 of the two-stage planning p
 - Never write the full implementation plan — that is Stage 2 (the planner agent).
 - Do not write to documents/plans/ — only the planner agent does that.
 - If the task is clearly trivial (single-file, no architecture impact), say so and note that a full plan is unnecessary.
+- Never invent or assert a requirement the user did not state — including implicit nonfunctional targets (latency, throughput, scale, uptime, etc.) that seem "obviously" desirable. If such a property seems relevant, raise it as an explicit open question instead of assuming an answer.
 """

package/src/.github/agents/code-copilot.agent.md

@@ -18,3 +18,4 @@ You are the code-copilot agent. You implement focused code changes.
 - Use concise comments.
 - Do not update documentation — hand that off to the docs-copilot agent.
 - Do not add dependencies without explicit instruction and a documentation update.
+- If an acceptance criterion or plan detail turns out to rest on an unstated assumption (e.g. an unconfirmed performance target), do not halt to ask: implement the smallest change that satisfies what the user actually stated, log the assumption as a note in the plan's Implementation notes / Human Review section, and continue. Stop outright only when the phase truly cannot proceed without the missing information (e.g. missing credentials, an irreversible or destructive choice).

package/src/.github/agents/planner-copilot.agent.md

@@ -14,8 +14,10 @@ Before drafting the plan, check whether any discovered, policy-approved MCP serv
 ## Plan template
 Before drafting, read `documents/templates/plan-template.md` and follow its
 section structure exactly (title, metadata block, Goal, Constraints +
-Cross-references, Phases, Open questions, Risks). If the template is missing
-from the target repo, fall back to the "Plan structure" section below.
+Cross-references, Phases, Implementation notes, and a trailing Human Review
+section containing Open questions, Assumptions made, and Risks). If the
+template is missing from the target repo, fall back to the "Plan structure"
+section below.
 
 ## File naming
 - Name the plan file `<YYYYMMDD>-<topic>.md` using today's date with no separators in the date, e.g. `20260408-calendar.md`.
@@ -25,12 +27,15 @@ from the target repo, fall back to the "Plan structure" section below.
 1. Goal — one paragraph describing what success looks like.
 2. Constraints — guardrails, dependencies, deadlines, branch name.
 3. Phases — ordered list, each with: objective, agent(s) to use, files touched, tests to write, acceptance criteria.
-4. Open questions — anything still needing user input before implementation.
-5. Risks — known unknowns or risky assumptions.
+4. Implementation notes — empty placeholder section for agents to log discoveries during execution.
+5. Human Review, placed last — Open questions, Assumptions made (unconfirmed), Risks.
+
+**All human-facing content goes last:** open questions and unconfirmed assumptions belong in the single trailing Human Review section, never earlier in the plan. Nothing in Goal, Constraints, or Phases should require a mid-implementation decision from the user; a phase that truly cannot proceed without one is the rare exception, not the default.
 
 ## Phase discipline
 - Keep each phase as small and tightly scoped as possible — one coherent outcome per phase, not a bundle of unrelated changes.
 - For any phase that changes code, specify the smallest set of tests that covers the change — no more than necessary, but never skip coverage the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task. Never encode an inferred, unconfirmed property (a latency bound, a scale target, a specific UX choice, etc.) as a blocking acceptance criterion — record it as an assumption in the Human Review section instead, phrased as a desired outcome, not a requirement.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the project's full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
 - Identify phases that touch disjoint files with no ordering dependency on each other and mark them explicitly as parallelizable (e.g. "Can run in parallel with Phase 3").
 - A single phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work. Otherwise, prefer separate phases over bundling agents.
@@ -49,3 +54,4 @@ When naming phase agents, mention only custom agents materialised under `.github
 - Do not begin implementation. Present the written plan and ask for explicit user approval.
 - Prefer more, smaller phases over fewer large ones; only chain agents within a single phase when the work cannot be usefully split.
 - Cross-reference related notes in agents/ or existing plans in documents/plans/.
+- Never invent or assert a requirement the user did not state — any inferred nonfunctional target (latency, throughput, scale, uptime, etc.) is a desired outcome recorded under Human Review, never a blocking acceptance criterion.

package/src/.github/skills/implement/SKILL.md

@@ -61,7 +61,8 @@ For each batch, in order:
 2. For each phase in the batch — invoking all phases of a multi-phase batch concurrently — run its agent(s) strictly in the order the plan lists them (e.g. `code-copilot` → `test-runner-copilot` → `docs-copilot`), passing each agent the phase objective, relevant files, the tests to write, and the acceptance criteria. Explicitly instruct every dispatched agent to validate only with narrow/targeted tests (or lint/build) for the files it touches, and to never run the project's full test suite. Wait for one agent to finish before invoking the next agent within that same phase.
 3. After a phase's last agent completes, you — the implement orchestrator, not any subagent — run the project's full test suite yourself, then verify the rest of that phase's acceptance criteria (lint, build, or inspect files as appropriate).
 4. Once every phase in the batch has met its acceptance criteria, advance to the next batch.
-5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded.
+5. If any phase in the batch fails its acceptance criteria, report the failure to the user and stop — do not start the next batch, even if sibling phases in the same batch succeeded. An unstated assumption or unconfirmed, non-blocking requirement surfacing mid-phase (e.g. a performance target no one confirmed) is not a failure: it does not trigger this stop. Have the phase's agent log it as a note in the plan's Implementation notes section and continue with the most conservative interpretation of what the user actually stated. Reserve the stop for genuine failures — broken code, failing tests, an explicitly stated acceptance criterion left unmet, or missing information the phase truly cannot proceed without.
+6. After the final batch completes (or the run stops on a genuine failure), compile every logged Implementation note into a single Human Review summary and present it to the user — never pause mid-run to relitigate an assumption.
 
 ## Guardrails
 - Always work on the branch the plan names. Never work on `main`.
@@ -70,4 +71,4 @@ For each batch, in order:
 - Never substitute a different agent than what the plan designates, and run a phase's chained agents strictly in the plan's listed order.
 - Never batch together phases the plan did not mark mutually parallelizable, or phases with overlapping files even if the plan marks them parallelizable.
 - Only you, the orchestrator, run the full test suite — every dispatched agent is instructed to run narrow/targeted tests only, never the full suite.
-- Stop immediately on a failed phase and report clearly.
+- Stop immediately on a genuine failed phase and report clearly. Never stop a batch solely because an agent surfaced an unconfirmed assumption — log it in Implementation notes and continue.

package/src/.github/skills/planner/SKILL.md

@@ -35,9 +35,10 @@ Present the outline to the user. **Stop and explicitly ask for approval before p
 
 Only after the user approves the outline, invoke the `planner-copilot` agent with the approved outline and any answers the user provided to open questions. That agent will:
 - Write a complete, structured plan to `documents/plans/<YYYYMMDD>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Implementation notes, then a trailing Human Review section (Open questions, Assumptions made, Risks).
 - Keep phases small and tightly scoped; mark phases with no shared files or ordering dependency as parallelizable.
 - For phases that change code, specify the smallest set of tests the change needs.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task — never an inferred, unconfirmed property (a latency bound, scale target, etc.). Record those as assumptions in Human Review instead, phrased as desired, not required.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests — never the full suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job.
 - A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate; otherwise split into separate phases.
 - Include code snippets for load-bearing changes.

package/src/MARCOS-AI-BOOTSTRAP.md

@@ -130,13 +130,14 @@ cannot edit locally, so it watches, diagnoses, and reports the fix back to the u
 ### planner
 **Purpose:** Formalise the two-stage planning flow into a single command. Runs the `planner-discovery` agent (Stage 1: clarifying questions + outline), gates on explicit user approval, then runs the `planner` agent (Stage 2: full implementation plan written to `documents/plans/<YYYYMMDD>-<topic>.md`).
 **Pipeline:** `planner-discovery` → (user approval) → `planner`.
-**Guardrails:** Never implements or writes code. Stage 2 runs only after the user approves the Stage 1 outline. Only the `planner` agent writes to `documents/plans/`. Hands off to the `implement` skill for execution.
+**Guardrails:** Never implements or writes code. Stage 2 runs only after the user approves the Stage 1 outline. Only the `planner` agent writes to `documents/plans/`. Never asserts a requirement the user did not state — any inferred nonfunctional target (latency, throughput, scale, uptime, etc.) is recorded as a desired outcome in the plan's trailing Human Review section, never as a blocking acceptance criterion. Hands off to the `implement` skill for execution.
 
 ### implement
 **Purpose:** Execute an existing plan from `documents/plans/` (path passed by the user, e.g. `documents/plans/20260622-ui-bugs.md`), dispatching each phase's agent(s) to the plan's designation and using the branch the plan names.
 **Target resolution:** Required plan file path. Parses branch, phases, designated agent(s) per phase, parallelizability, files, tests to write, and acceptance criteria from the plan.
 **Pipeline:** Groups phases into batches — phases the plan marks mutually parallelizable (and that touch disjoint files) run concurrently within a batch; all others run alone. Within a phase, chained agents (e.g. code → test-runner → docs) run strictly in the order the plan lists them, each instructed to validate only with narrow/targeted tests for the files it touches. Once a phase's agents complete, the implement orchestrator itself — never a dispatched subagent — runs the full test suite before checking that phase's acceptance criteria and letting its batch advance.
 **Guardrails:** Never commits or pushes — agents edit files, the user commits. Never works on `main` (uses the plan's branch). Honours each phase's agent designation and order exactly; never batches phases the plan did not mark parallelizable, or phases with overlapping files even if marked parallelizable; stops the batch on any failed phase. Only the orchestrator runs the full test suite — every dispatched subagent is instructed to run narrow/targeted tests only, never the full suite.
+**Unverified assumptions:** an unstated assumption or an unconfirmed, non-blocking requirement (e.g. a performance target no one confirmed) surfacing mid-phase is not a failed acceptance criterion — the phase's agent implements the smallest change that satisfies what the user actually stated, logs the assumption as a note in the plan's Human Review section, and continues. Only genuine failures (broken code, failing tests, an explicitly stated acceptance criterion left unmet, or a phase that truly cannot proceed without missing information such as credentials) stop a batch. At the end of the run, the orchestrator compiles every logged note into one Human Review summary for the user — it never pauses mid-run to relitigate an assumption.
 
 ### initialize
 **Purpose:** One-time environment reconciliation. First ensures the tool's instruction file (`CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`) references the shipped `MARCOS-AI-BOOTSTRAP.md` rules — appending a short `@MARCOS-AI-BOOTSTRAP.md` include (never overwriting existing content), or creating the file if it does not exist. Discovers applicable MCP servers (via the MCP Servers discovery → policy-check → install flow) and, with user approval, installs and wires them into the `infra` and `planner` agents. Discovers where plan documents actually live in the repo and, after explicit user confirmation, wires the `planner`, `implement`, and `docs` agents/skills to that location. Scans the repository's history (past merged PRs, branch names, commit subjects, and any CONTRIBUTING / PR-template / commit-lint / release-automation config) and, after user confirmation, customises the `pull-request` skill's convention profile to match. Then always prompts the user, via a dropdown, to choose the model for each tier/role — pre-selecting the currently configured model when it is available, or the closest available match when it is not — and rewrites the agent files.
@@ -205,20 +206,24 @@ Model tiers used below:
 
 **Stage 1 — Discovery & Outline (Standard tier)**
 - Ask lots of clarifying questions — be exhaustive. The goal of Stage 1 is to find out everything about what the user has asked for: scope and boundaries, expected behaviour and edge cases, inputs and outputs, affected components, constraints, dependencies, and success criteria. Do not assume — surface every ambiguity and keep asking until nothing material about the task is left unknown.
+- Never invent or assert a requirement the user did not state — this includes implicit nonfunctional targets (latency, throughput, scale, uptime, etc.) that seem "obviously" desirable. If such a property seems relevant, raise it as an explicit open question rather than assuming an answer.
 - Explore the codebase and any relevant context.
 - Produce a concise outline: goal, high-level phases, open questions.
 - Stop and present the outline. Ask the user for explicit approval to proceed to Stage 2.
 
 **Stage 2 — Full Implementation Plan (High tier)**
 - Using the approved outline, produce a complete plan written to `documents/plans/<date>-<topic>.md`.
-- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), Open questions, Risks.
+- Plan structure: Goal, Constraints, Phases (objective / agent(s) / files / tests / acceptance criteria), then a single Human Review section placed last (Open questions, Assumptions made, Risks) — see the "All human-facing content goes last" rule below.
 - Keep phases as small and tightly scoped as possible — one coherent outcome per phase.
 - For each phase that changes code, specify the smallest set of tests needed to cover the change.
+- Every acceptance criterion must be a requirement the user explicitly stated or one strictly implied by the task. Never encode an inferred, unconfirmed property (a latency bound, a scale target, a specific UX choice, etc.) as a blocking acceptance criterion — record it instead as an assumption in the Human Review section, phrased as a *desired* outcome, not a requirement.
 - State explicitly, per phase, that its agent(s) run only narrow/targeted tests for the files they touch — never the full test suite. Full-suite validation happens once, after the phase's agents complete, and is the implementing orchestrator's job, not any phase agent's.
 - Identify phases with no shared files or ordering dependency and mark them as parallelizable.
 - A phase may chain multiple agents in sequence (e.g. code → test-runner → docs) when the hand-off is immediate and splitting would break an atomic unit of work; otherwise prefer separate phases.
 - Stop and present the plan. Ask the user for explicit approval before any implementation begins.
 
+**All human-facing content goes last:** every section that asks something of a human — open questions and unconfirmed assumptions — belongs in one "Human Review" section at the very end of the plan, after Risks. Nothing earlier in the plan (Goal, Constraints, Phases) should require a mid-implementation decision from the user; if a phase truly cannot proceed without one, that is the rare exception, not the default.
+
 **Rules:**
 - Never begin implementation.
 - Specify a branch name in the plan.
@@ -235,6 +240,7 @@ Model tiers used below:
 - Validate with the narrowest relevant test or lint command after each edit.
 - Use concise comments.
 - Do not touch documentation — hand that off to the docs agent.
+- If an acceptance criterion or plan detail turns out to rest on an unstated assumption (e.g. an unconfirmed performance target), do not halt to ask: implement the smallest change that satisfies what the user actually stated, log the assumption as a note for the plan's Human Review section, and continue. Stop outright only when the phase truly cannot proceed without the missing information (e.g. missing credentials, an irreversible or destructive choice).
 
 ### docs
 **Tier:** Fast

package/src/documents/templates/plan-template.md

@@ -48,14 +48,49 @@ run once, after the phase's agents complete, by the implementing orchestrator it
 **Design:** <!-- optional: fenced code snippets for load-bearing changes -->
 
 **Acceptance criteria:**
+<!-- Every criterion here must be a requirement the user explicitly stated, or one strictly implied
+by the task. Never encode an inferred, unconfirmed property (a latency bound, a scale target, a
+specific UX choice, etc.) as a blocking acceptance criterion — record it as an assumption in
+Human Review below instead, phrased as a desired outcome, not a requirement. -->
 - <verifiable outcome>
 
-## Open questions
+## 4. Implementation notes
 
-<!-- Anything still needing user input before implementation. -->
+<!--
+Filled in during execution, not during planning. If an implementing agent discovers an unstated
+assumption, an ambiguity, or an unverified/unconfirmed requirement (e.g. a performance target no
+one actually confirmed), it does not pause the phase to ask — it proceeds with the most
+conservative interpretation that satisfies what the user actually stated, and appends a note here.
+Only a genuine failure (broken code, failing tests, an explicitly stated acceptance criterion left
+unmet, or missing information the phase truly cannot proceed without) stops a phase.
+-->
+- <note, or leave empty if none arose>
+
+## 5. Human Review
+
+<!--
+Everything a human needs to weigh in on lives here, and only here, at the end of the plan. Nothing
+above this section should require the user's input mid-implementation. This section is read once,
+after planning (Open questions, Risks) and again after implementation (Assumptions made) — it is
+never a mid-run blocker.
+-->
+
+### Open questions
+
+<!-- Anything still needing user input before implementation begins. -->
 - <question>
 
-## Risks
+### Assumptions made (unconfirmed)
+
+<!--
+Anything the planner or an implementing agent inferred rather than the user stating it outright —
+phrased as a desire, not a requirement. Populated during planning and appended to during
+implementation (mirrors "Implementation notes" above). Never treat an entry here as met/unmet;
+it is a flag for the user to confirm or reject, not a pass/fail gate.
+-->
+- <assumption> — treated as: desired, not required, until confirmed
+
+### Risks
 
 <!-- Known unknowns or risky assumptions. -->
 - <risk>