@hanzlaa/rcode 4.13.0 → 4.15.0

package/rcode/workflows/new-project-research-decision.md

@@ -243,7 +243,69 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
-**If "Skip research":** Continue to Step 7.
+## 6b. Stack confirmation gate — HARD STOP
+
+**The stack is never decided for the user. Not by research, not by a
+recommendation, not by "the obvious choice for this domain."** Research produces
+a *suggestion*; only the user turns it into a decision.
+
+This gate runs whether research ran or was skipped. If research was skipped, ask
+with no recommendation attached — you have no grounds for one.
+
+```
+AskUserQuestion:
+  header: "Stack"
+  question: "Research suggests {STACK} because {the one reason that actually drove it}. Confirm?"
+  options:
+    - label: "Confirm {STACK}"
+      description: "{the trade-off the user is accepting, stated plainly}"
+    - label: "I'll choose the stack"
+      description: "Tell me what to build on and I'll record that instead."
+    - label: "Research more first"
+      description: "Compare against {the closest alternative} before deciding."
+```
+
+**Nothing proceeds until the user answers.** Not requirements, not the roadmap,
+not a single file. An unanswered question is not a confirmation, and neither is
+silence, `--auto`, or `auto_advance`. **Auto mode does NOT bypass this gate** —
+every other question in this workflow has an auto default; this one does not,
+because a wrong stack is the most expensive thing in the project to reverse.
+
+State the reason the suggestion exists, in one sentence, in the user's terms.
+"Research recommends WordPress" is not a reason. "WordPress because a
+non-technical client will update content themselves, with no dev retainer" is —
+and stated that way the user can see immediately whether the premise is true.
+
+Record the answer with `state add-decision`, including the premise it rests on:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state add-decision \
+  "Stack: {chosen}. Premise: {the one reason}. Confirmed by user {date}."
+node ".rcode/bin/rcode-tools.cjs" memlog append --type decision \
+  --text "Stack: {chosen}. Premise: {the one reason}. User-confirmed at the stack gate."
+```
+
+### The premise is part of the decision
+
+**A stack decision is only valid while its premise holds.** Write the premise
+into the decision, then re-open the decision the moment the premise changes.
+
+Confirmed live: a site was scoped for a non-technical client, so research picked
+WordPress and the roadmap locked it. The project later pivoted to a model with no
+client at all — the maintainer was the technical owner. Every planning doc was
+rewritten for the pivot and the stack stayed "Locked", because nothing in the
+loop treats a locked decision as re-openable. A PHP theme got built and then
+migrated wholesale to a static generator to undo it.
+
+**On any pivot, re-run this gate** for every decision whose stated premise the
+pivot invalidated. A decision whose reason has expired is not locked, it is
+stale.
+
+**If "Research more first":** run the comparison against the named alternative,
+then return to this gate. Do not proceed past it.
+
+**If "Skip research":** Continue to Step 6b — you still need the stack gate,
+you just have no suggestion to offer.
 
 
 ## Next Up

package/rcode/workflows/new-project.md

@@ -475,7 +475,12 @@ Proceed to Step 4 (skip Steps 3 and 5).
 
 ## 3. Deep Questioning
 
-**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
+**If auto mode:** extract project context from the provided document instead of
+asking. **You still owe the user the Mandatory decision set** — resolve each item
+from the document where it answers one, and where it does not, list what you are
+assuming before Step 4 writes PROJECT.md. Auto mode removes the conversation, not
+the accountability. If the document leaves the maintainer or the stack unanswered,
+stop and ask those two regardless of mode.
 
 **Display stage banner:**
 
@@ -491,6 +496,20 @@ Ask inline (freeform, NOT AskUserQuestion):
 
 "What do you want to build?"
 
+**Then, before any deeper questioning, run two short probes from
+`@.rcode/references/questioning.md` — in this order:**
+
+1. **Stakes calibration** — hobby/solo, internal tool, or launch? Scale every
+   artifact and gate below to the answer. Do not run the launch-grade pipeline on
+   a weekend project.
+2. **Working mode** — Fast path (batched questions, draft with `[ASSUMPTION]`
+   tags) or Coaching path (walk the decisions together)? **Ask it. Never infer it
+   from `auto_advance`, from how detailed their opening message was, or from your
+   own read of their hurry.** Only `--auto`/yolo picks Fast path without asking.
+
+These two answers govern the rest of this workflow. Record them with
+`state add-decision` so a later resume does not re-guess them.
+
 Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
 
 **Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in `.rcode/config.yaml` (via `node .rcode/bin/rcode-tools.cjs config-get workflow.research_before_questions`). When enabled, before asking follow-up questions about a topic:
@@ -527,6 +546,11 @@ Mentally check the context checklist. If gaps remain, weave questions naturally.
 
 **Decision gate:**
 
+**Before the decision gate, show your coverage.** State plainly which items of the
+Mandatory decision set (`@.rcode/references/questioning.md`) the user actually
+answered and which you are assuming, with each assumption spelled out in one line.
+An assumption the user never saw is a decision you made for them.
+
 When you could write a clear PROJECT.md, use AskUserQuestion:
 
 - header: "Ready?"
@@ -601,16 +625,61 @@ Synthesize all context into `.planning/PROJECT.md`. If `.rcode/templates/project
 - [ ] {Requirement 2}
 - [ ] {Requirement 3}
 
-### Out of Scope
+### Out of Scope (Non-Goals)
+
+*What this project is NOT and will NOT do. This does outsized work downstream —
+it is what prevents the "let me also add this nearby thing" failure at every
+level: phase, sprint, task, and code. An unstated exclusion reappears later as a
+gap; a stated one ends the argument before it starts.*
 
 - {Exclusion 1} — {why}
 - {Exclusion 2} — {why}
 
+**Scope dial:** hobby/solo — the two or three things you keep being tempted by.
+Internal tool — plus anything a stakeholder has already asked for and been told
+no. Launch — plus the "we are not becoming X" statements about the product's
+identity.
+
+## Glossary
+
+*Every domain noun this project uses, defined once. Downstream agents and
+documents use these terms verbatim — introducing a synonym anywhere is a
+discipline violation, because two names for one thing is how a codebase ends up
+with two implementations of it.*
+
+- **{Term}** — {definition}. {relationship to other terms, cardinality if it matters}
+
+**Scope dial:** hobby/solo — only terms that are genuinely ambiguous, often 2-3.
+Internal tool — every domain noun. Launch — every domain noun plus the ones the
+team argues about.
+
 ## Key Decisions
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| {Choice} | {Why} | — Pending |
+| Decision | Premise (what makes it right) | Rationale | Outcome |
+|----------|-------------------------------|-----------|---------|
+| {Choice} | {the condition this rests on} | {Why} | — Pending |
+
+*The **Premise** column is load-bearing. A decision is valid only while its
+premise holds — when the project pivots, every decision whose premise the pivot
+invalidated goes back to the user. A decision whose reason has expired is not
+locked, it is stale.*
+
+## Assumptions Index
+
+*Every `[ASSUMPTION]` tag in this document and in REQUIREMENTS.md, gathered here
+for explicit confirmation. An assumption the user never saw is a decision nobody
+made.*
+
+| # | Assumption | Where | Status |
+|---|-----------|-------|--------|
+| A-1 | {what was inferred} | §{section} | unconfirmed |
+
+**This table is walked with the user before the document is treated as settled.**
+Each row ends as confirmed, corrected, or deferred with an owner. Auto mode does
+not skip the walk; it defers it to the first interactive turn.
+
+**Scope dial:** the table exists at every stakes level. Hobby/solo may resolve it
+in one exchange; launch resolves it row by row.
 
 ## Constraints
 
@@ -628,19 +697,44 @@ This document evolves at phase transitions and milestone boundaries.
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
+4. Decisions to log? → Add to Key Decisions, WITH its premise
 5. "What This Is" still accurate? → Update if drifted
+6. New domain nouns introduced? → Add to Glossary in the same pass
+7. Any `[ASSUMPTION]` resolved or added? → Update the Assumptions Index
+8. Did anything invalidate a recorded premise? → That decision reopens
 
 **After each milestone** (via `/rcode-complete-milestone`):
 1. Full review of all sections
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
 4. Update Context with current state
+5. Assumptions Index — any row still `unconfirmed` after a whole milestone is a
+   finding, not a formality. Resolve or escalate it
+6. Key Decisions — check every premise still holds
+7. **Memlog audit** — `rcode-tools.cjs memlog open` lists every assumption,
+   override, and blocker logged during the milestone. Walk it: each one is
+   captured in PROJECT.md, resolved, or explicitly deferred with an owner.
+   Entries that survive a whole milestone unexamined are the ones that turn into
+   "nobody knows why this is like this" 
 
 ---
 *Last updated: {date} after initialization*
 ```
 
+**Scale every section to the stakes answer from Step 3.** The template is one
+document that serves a weekend project and a launch; the scope dials on each
+section say how. Running the launch-grade depth on a hobby project is its own
+failure — the user abandons the process, not the project.
+
+| Stakes | PROJECT.md target |
+|---|---|
+| Hobby / solo | About a page. Glossary only where terms are ambiguous |
+| Internal tool | Two to four pages. Every section present, lightly filled |
+| Launch | As long as the requirements and concerns need |
+
+Never pad a section to look thorough, and never drop one silently — if a section
+genuinely does not apply, say so in one line where it would have been.
+
 **For greenfield projects:** Initialize requirements as hypotheses (all Active).
 
 **For brownfield projects (codebase map exists):** Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`. Identify what the codebase already does — these become the initial Validated set.

package/rcode/workflows/plan.md

@@ -100,6 +100,24 @@ drafting tasks inline, the run has lost its orchestrator — spawn the planner
 instead. A SPRINT.md with no planner `Task()` behind it is the failure this rule
 exists to prevent (see step 8).
 
+## 0.4. Record the authorized scope
+
+```bash
+# Project overrides for this workflow — appended after everything below, and
+# they win on conflict. The installer never writes .rcode/custom/, so these
+# survive `rcode install`.
+node ".rcode/bin/rcode-tools.cjs" customize resolve plan
+node ".rcode/bin/rcode-tools.cjs" state set-intent plan --source plan.md
+node ".rcode/bin/rcode-tools.cjs" memlog append --type event --text "Planning started for phase ${PHASE}" --phase "${PHASE}"
+```
+
+**Log as you go from here.** Every decision the panel forces, every checker issue
+you accept or reject, every assumption the planner had to make — one
+`memlog append` line each, at the moment it happens.
+
+This is what the user asked for on THIS invocation, and it is what `resume-work`
+will restore later. Planning does not authorize building — see step 15.
+
 ## 0.5. Project-Status Preflight
 
 ```bash
@@ -306,11 +324,11 @@ If `TEXT_MODE` is true, present as a plain-text numbered list:
 ```
 No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included.
 
-1. Continue without context — Plan using research + requirements only
 [If DISCUSS_MODE is "assumptions":]
-2. Gather context (assumptions mode) — Analyze codebase and surface assumptions before planning
+1. Gather context (assumptions mode) [recommended] — Analyze codebase and surface assumptions before planning
 [If DISCUSS_MODE is "discuss" or unset:]
-2. Run discuss-phase first — Capture design decisions before planning
+1. Run discuss-phase first [recommended] — Capture design decisions before planning
+2. Continue without context — Plan using research + requirements only; your design preferences will not be in the plan
 
 Enter number:
 ```
@@ -319,11 +337,13 @@ Otherwise use AskUserQuestion:
 - header: "No context"
 - question: "No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?"
 - options:
-  - "Continue without context" — Plan using research + requirements only
+  (Recommended option FIRST — rcode was recommending the skip, which is how phases
+  got planned with the user's design decisions never captured.)
   If `DISCUSS_MODE` is `"assumptions"`:
-  - "Gather context (assumptions mode)" — Analyze codebase and surface assumptions before planning
+  - "Gather context (assumptions mode) (Recommended)" — Analyze codebase and surface assumptions before planning
   If `DISCUSS_MODE` is `"discuss"` (or unset):
-  - "Run discuss-phase first" — Capture design decisions before planning
+  - "Run discuss-phase first (Recommended)" — Capture design decisions before planning
+  - "Continue without context" — Plan using research + requirements only; your design preferences will not be in the plan
 
 If "Continue without context": Proceed to step 5.
 If "Run discuss-phase first":
@@ -926,7 +946,30 @@ Returns (else branch only):
 
 After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan.
 
-**Skip if:** `phase_req_ids` is null, `TBD`, or an empty array/list (no requirements mapped to this phase) — `[[ -z "$phase_req_ids" || "$phase_req_ids" == "TBD" || "$phase_req_ids" == "[]" || "$phase_req_ids" == "null" ]]` — proceed to step 14.
+**If `phase_req_ids` is empty, the gate does NOT silently skip — it reports why.**
+An empty array has two very different causes and they must not look the same:
+
+1. This phase genuinely maps to no requirements. Fine, say so and continue.
+2. REQUIREMENTS.md HAS a traceability table and nothing parsed out of it. That is
+   a broken gate reporting as a passing one.
+
+Distinguish them before proceeding:
+
+```bash
+if [ -f .planning/REQUIREMENTS.md ] && grep -qE '\b[A-Z][A-Z0-9]{1,15}-[0-9]+\b' .planning/REQUIREMENTS.md; then
+  echo "⚠ Requirements coverage gate SKIPPED but REQUIREMENTS.md contains requirement IDs."
+  echo "  phase_req_ids came back empty — the phase→requirement mapping in ROADMAP.md"
+  echo "  is missing or unparseable, so nothing is verifying coverage for this phase."
+  echo "  Fix the phase's **Requirements:** line in ROADMAP.md, then re-run."
+fi
+```
+
+Surface that warning to the user; do not bury it. Confirmed live: a project's
+requirement IDs were all domain-prefixed (`FOUND-01`, `RENT-04`), the extractor
+only matched `REQ-*`, and this gate skipped itself on every phase while
+appearing to pass.
+
+Then proceed to step 14 when the array really is empty.
 
 **Step 1: Extract requirement IDs claimed by plans**
 ```bash
@@ -1028,7 +1071,34 @@ if ([[ "$ARGUMENTS" =~ --auto ]] || [[ "$ARGUMENTS" =~ --chain ]]) && [[ "$AUTO_
 fi
 ```
 
-**If `--auto` or `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**`AUTO_CFG` alone is NOT sufficient.** A persistent `workflow.auto_advance: true`
+in settings must never silently turn "plan this" into "plan and build this". The
+user's invocation is their declared scope: they typed a planning command, so
+planning is what was authorized. A config flag set weeks ago is not consent for
+this build.
+
+Confirmed live: a user asked for a project to be planned, `auto_advance` was on,
+and the session planned and then built a WordPress theme, then migrated the whole
+thing to Astro to undo its own stack choice. The user's words were "plan karo".
+Nothing in the loop stopped at the boundary they actually drew.
+
+**If `AUTO_CFG` is true but neither `--auto`/`--chain` nor `AUTO_CHAIN` is set:**
+ask before advancing, and default to stopping:
+
+```
+AskUserQuestion:
+  question: "Plans are ready. auto_advance is on in your config — execute phase {N} now?"
+  options:
+    - label: "Stop here (Recommended)"
+      description: "Plans written and verified. Review them, then run /rcode-execute {N} when ready."
+    - label: "Execute now"
+      description: "Chain straight into execution, as auto_advance requests."
+```
+
+In `--text` mode present this as a numbered list. If the user does not answer,
+STOP — an unanswered question is not approval.
+
+**If `--auto` or `--chain` flag present OR `AUTO_CHAIN` is true:**
 
 Display banner:
 ```
@@ -1156,6 +1226,7 @@ ${WINDOWS === 'true' ? '@.rcode/references/plan-windows-troubleshooting.md' : ''
 - [ ] Phase directory created if needed
 - [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
 - [ ] Research completed (unless --skip-research or --gaps or exists)
+- [ ] Auto-advance fired only on an explicit `--auto`/`--chain` or an answered confirmation, never on `auto_advance` config alone
 - [ ] Specialist review panel spawned (Waleed + Fatima + domain agents) and its blocking issues fed into the revision loop, or `workflow.specialist_review: false` recorded
 - [ ] rcode-phase-researcher spawned with CONTEXT.md
 - [ ] Existing plans checked

package/rcode/workflows/resume-work.md

@@ -197,6 +197,24 @@ Based on project state, determine the most logical next action:
 </step>
 
 <step name="offer_options">
+**"Resume" restores position, never scope.** It tells you WHERE the work stopped;
+it does not tell you what the user authorized. Present options and wait — do not
+pick one and start.
+
+The failure this prevents: a user asks for a project to be planned, the session
+plans it, the user later types "resume", and the session reads that as "keep
+going" and starts building. The standing instruction was still "plan". Confirmed
+live, and the cleanup cost more than the work.
+
+Two rules:
+
+- **Never begin implementation from a resume.** If the state says the phase is
+  ready to execute, that is an option to OFFER, not an action to take. Execution
+  starts when the user runs `/rcode-execute`, not when a menu suggests it.
+- **Say what the last authorized scope was**, if the state records one (see
+  `state read` → `last_intent`, written by plan.md and execute.md). If it does not, say that plainly rather than
+  inferring one: `Last recorded scope: unknown — tell me plan or build.`
+
 Present contextual options based on project state:
 
 ```