@hanzlaa/rcode 4.12.1 → 4.14.0

package/rcode/workflows/new-project-define-requirements.md

@@ -111,6 +111,41 @@ Create `.planning/REQUIREMENTS.md` with:
 
 **REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
 
+**Every requirement carries its testable consequences.** This is the shape:
+
+```markdown
+- [ ] **AUTH-01**: User can log in with email and password and stay logged in
+      across sessions.
+  - **Consequences (testable):**
+    - A valid credential pair returns a session cookie with a 30-day expiry
+    - An invalid password returns 401 and does not reveal whether the email exists
+    - A logged-in user reloading the page stays logged in
+```
+
+**Why the consequences live here and not in the plan.** rcode's verifier derives
+`must_haves` at verification time, long after the requirement was written — so it
+is guessing at what "done" meant for a requirement someone else authored. That
+guess is where verification quietly goes wrong: a phase passes because the
+verifier's invented criterion was met, not the one the requirement intended.
+
+Writing the consequences with the requirement moves that decision to the moment
+the person actually knows the answer. The planner then copies them into
+`must_haves.truths` instead of inventing them, and the verifier checks the
+requirement's own criteria rather than its own reconstruction.
+
+A requirement whose consequences you cannot state is a requirement you have not
+finished writing. "Handle authentication properly" has no consequences because it
+has no meaning — that is the signal to push for specificity, not to move on.
+
+**Scope dial:** hobby/solo — one consequence per requirement is usually enough,
+and it can be a sentence. Internal tool — the happy path plus the one failure
+mode that matters. Launch — every condition a reviewer would ask about, including
+the negative cases.
+
+**Do not change the traceability table's shape.** `requirements mark-complete`
+rewrites the status cell of a `| ID | ... | status |` row; consequences are nested
+under the requirement in the list above, not added as table columns.
+
 **Requirement quality criteria:**
 
 Good requirements are:
@@ -119,6 +154,7 @@ Good requirements are:
 - **User-centric:** "User can X"
 - **Atomic:** One capability per requirement
 - **Independent:** Minimal dependencies on other requirements
+- **Consequential:** you can name what must be true for it to be done
 
 Reject vague requirements. Push for specificity:
 

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

@@ -243,7 +243,67 @@ 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}."
+```
+
+### 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,39 @@ 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
 
 ---
 *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-research-validation.md

@@ -70,10 +70,16 @@ Answer: "What do I need to know to PLAN this phase well?"
 <files_to_read>
 - {context_path} (USER DECISIONS from /rcode-discuss-phase)
 - {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
 </files_to_read>
 
-${AGENT_SKILLS_RESEARCHER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.researcher}
 
 <additional_context>
 **Phase description:** {phase_description}

package/rcode/workflows/plan-spawn-planner.md

@@ -34,14 +34,20 @@ When `GAPS_MODE=true`, use the prompt below in place of the standard planner pro
 
 <files_to_read>
 - {VERIFICATION_FILE} (Authoritative verification report — source of truth for gaps)
-- {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
 - Existing plan files in this phase: {EXISTING_PLAN_FILES}
 - Existing summary files in this phase: {EXISTING_SUMMARY_FILES}
 </files_to_read>
 
-${AGENT_SKILLS_PLANNER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.planner}
 
 <gap_list>
 {Serialized GAP_LIST — for each gap include id, title, expected behavior, actual behavior, status (gap_found|partial), and source section.}
@@ -86,7 +92,6 @@ Default: `phase` (one SPRINT.md, up to 8 stories — see Scope-Driven Sizing in
 **Self-upgrade to `initiative` mid-decomposition** if, once you've read CONTEXT.md/ROADMAP.md and started breaking down the work, it splits into independent waves or work-streams (e.g. shared-primitive foundation → feature-local migrations → cleanup/tests) and total stories would exceed 8. When that happens, emit multiple SPRINT.md files (`{phase}-1-SPRINT.md`, `{phase}-2-SPRINT.md`, ...) in this same run instead of one oversized plan. Do not wait for rcode-sprint-checker's "scope exceeds context budget" rejection to force a resharding pass — that costs a full extra planner run. Decide the split now, while you're already looking at the file/story list.
 
 <files_to_read>
-- {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
 - {context_path} (USER DECISIONS from /rcode-discuss-phase — read `<decisions>` for locked choices AND `<code_context>` for existing code patterns, reusable assets, and architectural notes gathered during discuss-phase)
@@ -102,7 +107,14 @@ ${CONTEXT_WINDOW >= 500000 ? `
 ` : ''}
 </files_to_read>
 
-${AGENT_SKILLS_PLANNER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.planner}
 
 **Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
 
@@ -266,6 +278,21 @@ Every task MUST include these fields — they are NOT optional:
 4. **`<verify>`** — Shell commands that PROVE the `<done>` criteria are met. Run by executor after task completes and by verifier during post-execution check. The block MUST contain an `<automated>` child with the exact commands to run (Dimension 8 hard-blocks without it). Rules:
    - `<automated>` commands must exit 0 on success, non-zero on failure
    - Prefer `grep -q` for presence checks, `test -f` for file existence, project test runner for behavior
+   - **A task that adds or changes a guard test MUST prove the test fails on the
+     unfixed code first ("red first").** A guard test is any test whose job is to
+     make a class of mistake impossible: meta-tests, schema invariant tests,
+     forbidden-pattern scans, coverage/manifest tests, lint-rule tests. Write the
+     task so the `<action>` states the red step explicitly ("run the new test on
+     the current tree and record that it fails, then apply the fix") and the
+     `<verify><automated>` block asserts the green state. A guard test that has
+     never been observed red is indistinguishable from one that greps the wrong
+     path — that is exactly how a `route.ts`-only glob left every Server Action
+     unguarded for nine phases while CI stayed green the whole time.
+   - **Absence checks use `! grep -q PATTERN FILE`, never `grep -qv`.** `-v` inverts per-line
+     matching, so `grep -qv PATTERN FILE` exits 0 as soon as ANY line fails to match — i.e. it
+     passes on virtually every file, including one that contains the forbidden pattern. This is a
+     silently-always-green assertion, the worst possible verify command. Same for "file must not
+     exist": `! test -f path`.
    - Keep commands short and composable — one check per line
    - If test file doesn't exist yet (TDD tasks), write `<automated>MISSING</automated>` and add a Wave 0 task to create the test
    - Example structure:
@@ -323,6 +350,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] Every task has `<files>` listing exact files this task will modify or create
 - [ ] Every task has `<evidence>` with grep/lines/creates codebase grounding per issue #649 — not a prose checklist tag (none exists in the real plan schema)
 - [ ] Every task has `<verify>` with an `<automated>` child containing at least one shell command (Dimension 8 blocker)
+- [ ] Every guard-test task states its red-first step in `<action>` (Dimension 8 blocker)
 - [ ] Every task has `<done>` with a single observable acceptance sentence (Dimension 2 requirement)
 - [ ] Every `<action>` contains concrete values (no "align X with Y" without specifying what)
 - [ ] Tasks extending existing code have `<interfaces>` with relevant signatures