@hanzlaa/rcode 4.8.0 → 4.9.0

package/rcode/workflows/plan-research-validation.md

@@ -157,9 +157,12 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Skip if `workflow.security_enforcement` is explicitly `false`. Absent = enabled.
 
 ```bash
-SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
-SECURITY_ASVS=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null || echo "1")
-SECURITY_BLOCK=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null || echo "high")
+SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null)
+SECURITY_CFG=${SECURITY_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+SECURITY_ASVS=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null)
+SECURITY_ASVS=${SECURITY_ASVS:-1}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+SECURITY_BLOCK=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null)
+SECURITY_BLOCK=${SECURITY_BLOCK:-high}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 ```
 
 **If `SECURITY_CFG` is `false`:** Skip to step 5.6.
@@ -183,8 +186,10 @@ Continue to step 5.6. Security config is passed to the planner in step 8.
 > Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.rcode/config.yaml`. If keys are absent, treat as enabled.
 
 ```bash
-UI_PHASE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
+UI_PHASE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_phase 2>/dev/null)
+UI_PHASE_CFG=${UI_PHASE_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+UI_GATE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null)
+UI_GATE_CFG=${UI_GATE_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 ```
 
 **If both are `false`:** Skip to step 6.

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

@@ -114,7 +114,7 @@ ${AGENT_SKILLS_PLANNER}
 <downstream_consumer>
 Output consumed by /rcode-execute. Plans need:
 - Frontmatter (wave, depends_on, autonomous, **files_modified** — aggregated list of all file paths from `<files>` blocks across every task; used by executor for intra-wave parallel-safety overlap detection)
-- Tasks in XML format with read_first, files, acceptance_criteria, verify (with `<automated>` child), and done fields (MANDATORY on every task)
+- Tasks in XML format with read_first, files, evidence, verify (with `<automated>` child), and done fields (MANDATORY on every task)
 - Verification criteria
 - must_haves for goal-backward verification
 - **`## Files Touched`** section (see below) — required on every SPRINT.md
@@ -257,17 +257,13 @@ Every task MUST include these fields — they are NOT optional:
    - Executor checkpoint (knows what to stage after each task)
    - Example: `src/auth/auth.service.ts`, `tests/auth/auth.service.test.ts`
 
-3. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
-   - Every criterion must be checkable with grep, file read, test command, or CLI output
-   - NEVER use subjective language ("looks correct", "properly configured", "consistent with")
-   - ALWAYS include exact strings, patterns, values, or command outputs that must be present
-   - Examples:
-     - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
-     - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
-     - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
-     - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
-
-4. **`<verify>`** — Shell commands that PROVE the acceptance 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:
+3. **`<evidence>`** — REQUIRED (issue #649). Must show codebase grounding proving the task is real, not theoretical. At minimum one of:
+   - `grep:` a literal grep/Glob pattern + count of matches that justified this task (e.g. `` `rg '\.alert' apps/web/src` → 13 hits across 9 files ``)
+   - `lines:` exact `path:line-line` ranges of code being modified
+   - `creates:` the file paths being created from scratch (with one-line justification why no existing file fits)
+   A task without `<evidence>` is theoretical and MUST NOT be written. (Matches `rcode/references/planner-playbook.md`'s "Task Anatomy" section — single source of truth for this rule.)
+
+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
    - Keep commands short and composable — one check per line
@@ -325,7 +321,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] Tasks are specific and actionable
 - [ ] Every task has `<read_first>` with at least the file being modified
 - [ ] Every task has `<files>` listing exact files this task will modify or create
-- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
+- [ ] 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 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)

package/rcode/workflows/plan.md

@@ -49,8 +49,8 @@ Read all files referenced by the invoking prompt's execution_context before star
 ${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/karpathy-guidelines.md
 <!-- Read .rcode/references/agent-contracts.md only if defining or debugging agent contracts -->
-<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic -->
-@.rcode/references/thinking-models-planning.md
+<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic; thinking-models-planning.md (127 lines) only if features.thinking_partner is enabled -->
+${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/thinking-models-planning.md' : ''}
 </required_reading>
 
 <available_agent_types>

package/rcode/workflows/scaffold-skill.md

@@ -117,6 +117,21 @@ if [ -n "$fails" ]; then
 fi
 ```
 
+## Step 3.5 — Prove It Moved the Needle
+
+Passing the 5-component check in Step 3 only proves the file has the right shape — a triggers block, an Overview, a Workflow, an Output Format, and Examples. It says nothing about whether loading the skill actually changes what an agent does. A skill can be structurally perfect and still be a no-op in practice: the model reads it, nods along, and then falls back to its untrained default the moment a real scenario hits.
+
+Do not mark a new or edited skill as ready to ship until you've run this gate:
+
+1. **Write the pressure scenario.** Take the exact situation the skill's triggers describe — the moment the skill is supposed to change the agent's behavior — and phrase it as a concrete task an agent could be handed cold, with no mention of the skill.
+2. **Run the control.** Spawn a fresh subagent with no memory of this conversation and the skill NOT loaded (do not mention it, do not point at its path). Give it the pressure scenario. Record what it does by default — this is almost always the suboptimal or wrong behavior the skill exists to correct.
+3. **Run the treatment.** Spawn a second fresh subagent, same scenario, this time with the skill loaded (either by having it available for the model to invoke, or by including its content directly in the prompt). Record what it does.
+4. **Compare.** The treatment run must diverge from the control run in the specific direction the skill claims to produce. "Both agents produced fine-looking output" is not a pass — the question is whether the skill was the reason for the difference. If the two runs land on the same behavior, the skill has no measurable effect yet, no matter how clean its markdown is.
+
+If the comparison shows no behavioral difference, the skill is not done. Go back and sharpen the Workflow section, the triggers, or the examples — whichever part failed to actually steer the model — and rerun this gate. Do not ship on structural compliance alone.
+
+Skip this gate only when scaffolding a brand-new, still-empty skill (Step 2's placeholders haven't been filled in yet — there's no behavior to test). Once real content replaces the placeholders, this gate becomes mandatory before the skill is considered ready.
+
 ## Step 4 — Confirm and Next Up
 
 Print:
@@ -127,13 +142,16 @@ Print:
 
   All 5 required components are present (triggers, Overview, Workflow,
   Output Format, Examples). The placeholders need real content before
-  the skill becomes useful.
+  the skill becomes useful — and once they're filled in, run Step 3.5
+  (Prove It Moved the Needle) before calling the skill done.
 
 ▶ Next Up
   $EDITOR rcode/skills/actions/<group>/rcode-<NAME>/SKILL.md
                                                   # fill in placeholders
   npx @hanzlaa/rcode install --force              # install to .claude/skills/
   node --test test/compliance.test.cjs            # verify compliance
+                                                  # then: control vs. treatment
+                                                  # subagent run (Step 3.5)
 ```
 
 ## Next Up

package/rcode/workflows/secure-phase.md

@@ -3,7 +3,8 @@ Verify threat mitigations for a completed phase. Confirm SPRINT.md threat regist
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 </required_reading>
 
 <available_agent_types>
@@ -50,6 +51,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-security-auditor --raw)
 SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+
+# Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
+PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
+  .planning/phases/*${phase_number}*/*-CONTEXT.md \
+  .planning/ROADMAP.md 2>/dev/null | head -1)
 ```
 
 If `SECURITY_CFG` is `false`: exit with "Security enforcement disabled. Enable via /rcode-settings."

package/rcode/workflows/validate-phase.md

@@ -3,7 +3,8 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/karpathy-guidelines.md
 </required_reading>
 
@@ -32,6 +33,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-nyquist-auditor --raw)
 NYQUIST_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.nyquist_validation --raw)
+
+# Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
+PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
+  .planning/phases/*${phase_number}*/*-CONTEXT.md \
+  .planning/ROADMAP.md 2>/dev/null | head -1)
 ```
 
 If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /rcode-settings."