@hanzlaa/rcode 3.6.16 → 4.1.0

package/rihal/workflows/map-codebase.md

@@ -1,455 +0,0 @@
-<purpose>
-Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
-
-Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
-
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</purpose>
-
-<required_reading>
-@.rihal/references/output-format.md
-</required_reading>
-
-<output_format>
-Open with banner:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► MAPPING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Use TaskCreate at start:
-- TaskCreate: "Spawn 4 parallel codebase mappers"
-- TaskCreate: "Assemble and commit codebase map"
-
-Spawn indicators as each of the 4 agents completes:
-```
-◆ Spawning 4 mappers in parallel...
-  → Map tech stack and integrations
-  → Map architecture and structure
-  → Map conventions and testing
-  → Map concerns and technical debt
-
-✓ Agent "Map tech stack" completed — STACK.md (324 lines)
-✓ Agent "Map architecture" completed — ARCHITECTURE.md (412 lines)
-✓ Agent "Map conventions" completed — CONVENTIONS.md (198 lines)
-✓ Agent "Map concerns" completed — CONCERNS.md (276 lines)
-```
-
-End with closure banner + top findings summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► CODEBASE MAPPED ✓  ({total} lines across {N} docs)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-</output_format>
-
-
-## Step 0 — Usage check
-
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
-
-```
-/rihal-map-codebase <argument-here>
-```
-
-**Examples:**
-```
-/rihal-map-codebase example 1
-/rihal-map-codebase example 2
-```
-
-STOP — do not proceed.
-
-<available_agent_types>
-Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
-- rihal-codebase-mapper — Maps project structure and dependencies
-</available_agent_types>
-
-<philosophy>
-**Why dedicated mapper agents:**
-- Fresh context per domain (no token contamination)
-- Agents write documents directly (no context transfer back to orchestrator)
-- Orchestrator only summarizes what was created (minimal context usage)
-- Faster execution (agents run simultaneously)
-
-**Document quality over length:**
-Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
-
-**Always include file paths:**
-Documents are reference material for the agent when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
-</philosophy>
-
-<process>
-
-<step name="init_context" priority="first">
-Load codebase mapping context:
-
-```bash
-INIT=$(node .rihal/bin/rihal-tools.cjs init map-codebase)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_MAPPER=$(node .rihal/bin/rihal-tools.cjs agent-skills rihal-codebase-mapper 2>/dev/null)
-```
-
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `response_language`.
-
-**If `response_language` is set:** include `Respond in {response_language}.` in all spawned subagent prompts.
-</step>
-
-<step name="check_existing">
-Check if .planning/codebase/ already exists using `has_maps` from init context.
-
-If `codebase_dir_exists` is true:
-```bash
-ls -la .planning/codebase/
-```
-
-**If exists:**
-
-```
-.planning/codebase/ already exists with these documents:
-[List files found]
-
-What's next?
-1. Refresh - Delete existing and remap codebase
-2. Update - Keep existing, only update specific documents
-3. Skip - Use existing codebase map as-is
-```
-
-Wait for user response.
-
-If "Refresh": Delete .planning/codebase/, continue to create_structure
-If "Update": Ask which documents to update, continue to spawn_agents (filtered)
-If "Skip": Exit workflow
-
-**If doesn't exist:**
-Continue to create_structure.
-</step>
-
-<step name="create_structure">
-Create .planning/codebase/ directory:
-
-```bash
-mkdir -p .planning/codebase
-```
-
-**Expected output files:**
-- STACK.md (from tech mapper)
-- INTEGRATIONS.md (from tech mapper)
-- ARCHITECTURE.md (from arch mapper)
-- STRUCTURE.md (from arch mapper)
-- CONVENTIONS.md (from quality mapper)
-- TESTING.md (from quality mapper)
-- CONCERNS.md (from concerns mapper)
-
-Continue to spawn_agents.
-</step>
-
-<step name="detect_runtime_capabilities">
-Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
-
-**How to detect:** Check if you have access to a `Task` tool (may be capitalized as `Task` or lowercase as `task` depending on runtime). If you do NOT have a `Task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
-
-→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
-
-**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
-</step>
-
-<step name="spawn_agents" condition="Task tool is available">
-Spawn 4 parallel rihal-codebase-mapper agents.
-
-Use Task tool with `subagent_type="rihal-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
-
-**CRITICAL:** Use the dedicated `rihal-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
-
-**Agent 1: Tech Focus**
-
-```
-Task(
-  subagent_type="rihal-codebase-mapper",
-  model="{model}",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase tech stack",
-  prompt="Focus: tech
-
-Analyze this codebase for technology stack and external integrations.
-
-Write these documents to .planning/codebase/:
-- STACK.md - Languages, runtime, frameworks, dependencies, configuration
-- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only.
-${AGENT_SKILLS_MAPPER}"
-)
-```
-
-**Agent 2: Architecture Focus**
-
-```
-Task(
-  subagent_type="rihal-codebase-mapper",
-  model="{model}",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase architecture",
-  prompt="Focus: arch
-
-Analyze this codebase architecture and directory structure.
-
-Write these documents to .planning/codebase/:
-- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
-- STRUCTURE.md - Directory layout, key locations, naming conventions
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only.
-${AGENT_SKILLS_MAPPER}"
-)
-```
-
-**Agent 3: Quality Focus**
-
-```
-Task(
-  subagent_type="rihal-codebase-mapper",
-  model="{model}",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase conventions",
-  prompt="Focus: quality
-
-Analyze this codebase for coding conventions and testing patterns.
-
-Write these documents to .planning/codebase/:
-- CONVENTIONS.md - Code style, naming, patterns, error handling
-- TESTING.md - Framework, structure, mocking, coverage
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only.
-${AGENT_SKILLS_MAPPER}"
-)
-```
-
-**Agent 4: Concerns Focus**
-
-```
-Task(
-  subagent_type="rihal-codebase-mapper",
-  model="{model}",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase concerns",
-  prompt="Focus: concerns
-
-Analyze this codebase for technical debt, known issues, and areas of concern.
-
-Write this document to .planning/codebase/:
-- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
-
-Explore thoroughly. Write document directly using template. Return confirmation only.
-${AGENT_SKILLS_MAPPER}"
-)
-```
-
-Continue to collect_confirmations.
-</step>
-
-<step name="collect_confirmations">
-Wait for all 4 agents to complete using TaskOutput tool.
-
-**For each agent task_id returned by the Agent tool calls above:**
-```
-TaskOutput tool:
-  task_id: "{task_id from Agent result}"
-  block: true
-  timeout: 300000
-```
-
-Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
-
-Once all TaskOutput calls return, read each agent's output file to collect confirmations.
-
-**Expected confirmation format from each agent:**
-```
-## Mapping Complete
-
-**Focus:** {focus}
-**Documents written:**
-- `.planning/codebase/{DOC1}.md` ({N} lines)
-- `.planning/codebase/{DOC2}.md` ({N} lines)
-
-Ready for orchestrator summary.
-```
-
-**What you receive:** Just file paths and line counts. NOT document contents.
-
-If any agent failed, note the failure and continue with successful documents.
-
-Continue to verify_output.
-</step>
-
-<step name="sequential_mapping" condition="Task tool is NOT available (e.g. environments that do not support parallel subagents)">
-When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
-
-**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
-
-Perform all 4 mapping passes sequentially:
-
-**Pass 1: Tech Focus**
-- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
-- Write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
-- Write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
-
-**Pass 2: Architecture Focus**
-- Explore directory structure, entry points, module boundaries, data flow
-- Write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
-- Write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
-
-**Pass 3: Quality Focus**
-- Explore code style, error handling patterns, test files, CI config
-- Write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
-- Write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
-
-**Pass 4: Concerns Focus**
-- Explore TODOs, known issues, fragile areas, security patterns
-- Write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
-
-Use the same document templates as the `rihal-codebase-mapper` agent. Include actual file paths formatted with backticks.
-
-Continue to verify_output.
-</step>
-
-<step name="verify_output">
-Verify all documents created successfully:
-
-```bash
-ls -la .planning/codebase/
-wc -l .planning/codebase/*.md
-```
-
-**Verification checklist:**
-- All 7 documents exist
-- No empty documents (each should have >20 lines)
-
-If any documents missing or empty, note which agents may have failed.
-
-Continue to scan_for_secrets.
-</step>
-
-<step name="scan_for_secrets">
-**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
-
-Run secret pattern detection:
-
-```bash
-# Check for common API key patterns in generated docs
-grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
-```
-
-**If SECRETS_FOUND=true:**
-
-```
-⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!
-
-Found patterns that look like API keys or tokens in:
-[show grep output]
-
-This would expose credentials if committed.
-
-**Action required:**
-1. Review the flagged content above
-2. If these are real secrets, they must be removed before committing
-3. Consider adding sensitive files to Claude Code "Deny" permissions
-
-Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
-```
-
-Wait for user confirmation before continuing to commit_codebase_map.
-
-**If SECRETS_FOUND=false:**
-
-Continue to commit_codebase_map.
-</step>
-
-<step name="commit_codebase_map">
-Commit the codebase map:
-
-```bash
-node .rihal/bin/rihal-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
-```
-
-Continue to offer_next.
-</step>
-
-<step name="offer_next">
-Present completion summary and next steps.
-
-**Get line counts:**
-```bash
-wc -l .planning/codebase/*.md
-```
-
-**Output format:**
-
-```
-Codebase mapping complete.
-
-Created .planning/codebase/:
-- STACK.md ([N] lines) - Technologies and dependencies
-- ARCHITECTURE.md ([N] lines) - System design and patterns
-- STRUCTURE.md ([N] lines) - Directory layout and organization
-- CONVENTIONS.md ([N] lines) - Code style and patterns
-- TESTING.md ([N] lines) - Test structure and practices
-- INTEGRATIONS.md ([N] lines) - External services and APIs
-- CONCERNS.md ([N] lines) - Technical debt and issues
-
-
----
-
-## ▶ Next Up
-
-**Initialize project** — use codebase context for planning
-
-`/rihal-new-project`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Re-run mapping: `/rihal-map-codebase`
-- Review specific file: `cat .planning/codebase/STACK.md`
-- Edit any document before proceeding
-
----
-```
-
-End workflow.
-</step>
-
-</process>
-
-<success_criteria>
-- .planning/codebase/ directory created
-- If Task tool available: 4 parallel rihal-codebase-mapper agents spawned with run_in_background=true
-- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
-- All 7 codebase documents exist
-- No empty documents (each should have >20 lines)
-- Clear completion summary with line counts
-- User offered clear next steps in Rihal style
-</success_criteria>
-
-## Success Criteria
-
-- [ ] Task completed as requested
-- [ ] Output saved or reported
-- [ ] State updated if necessary
-- [ ] No errors encountered
-
-## On Error
-
-If arguments are invalid, missing files, or subagent fails:
-- Validate inputs match expected format
-- Check that required files exist
-- Retry with clearer arguments or report the specific error to the user
-

package/rihal/workflows/memory-audit.md

@@ -1,145 +0,0 @@
-# Workflow: rcode-memory-audit
-
-<purpose>
-Audit the Memory Bank for stale entries, contradictions, missing sections, and content that should be archived. Read-only by default with severity-tagged report; `--fix` patches trivial items per Phase 6 D-1 / D-2.
-</purpose>
-
-Audit the Memory Bank. Default mode is read-only (severity-tagged report).
-Optional `--fix` flag patches trivial items in place per Phase 6 D-1 / D-2.
-
----
-
-## Inputs
-
-None required.
-
-Optional flags:
-- `--severity {critical|warn|info}` — filter report output
-- `--fix` — opt-in auto-fix mode. Patches only items the auditor classifies
-  as severity=trivial (typos, stale ISO dates, broken relative paths,
-  factually-wrong-and-mechanically-correctable values). Hard-allowlisted
-  in code: items above trivial are never patched. Default OFF.
-
-```bash
-FIX_MODE=false
-if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix($|[[:space:]]) ]]; then
-  FIX_MODE=true
-fi
-```
-
-## Preconditions
-
-- `.rihal/memory/INDEX.md` exists
-
-## Halt conditions
-
-- Memory Bank not initialised → instruct to run `/rihal-memory-init` first
-
----
-
-## Steps
-
-### Step 1 — Catalogue files
-
-Walk `.rihal/memory/` and build a list of every file plus its size and modification time. Include `.gitkeep` files for empty-subdir detection.
-
-### Step 2 — Check 1: Stale milestone
-
-Read `milestones/current.md`. Parse the "Target close" date. If `(today - target_close).days >= 30`, emit a `warn` finding.
-
-### Step 3 — Check 2: Resolved issues lingering
-
-For each entry in `incidents/known-issues.md`:
-- Parse "Real fix planned for" field
-- If it names a milestone that has been moved to `milestones/archive/`, emit a `warn` finding
-
-### Step 4 — Check 3: Template placeholders unfilled
-
-For each `*.md` file under `.rihal/memory/`:
-- Count occurrences of `{{` literally (template placeholders)
-- Count occurrences of `_(e.g.` (italicised template hints)
-- If either is non-zero, emit an `info` finding listing the file and count
-
-### Step 5 — Check 4: Stack vs decisions contradiction
-
-For each decision entry in `project/decisions.md` that mentions a technology name:
-- Extract candidate tech terms (proper nouns, capitalised + version)
-- Search `project/stack.md` for the term
-- If not found, emit a `critical` finding
-
-### Step 6 — Check 5: Empty subdirectories
-
-For `change-records/`, `incidents/post-mortems/`, `milestones/archive/`:
-- If only file is `.gitkeep`, emit an `info` finding (not a problem, just visibility)
-
-### Step 7 — Check 6: Distillate freshness
-
-For each `distillates/*.distillate.md`:
-- Read frontmatter `source-digest`
-- Recompute digest of current source files (per `rcode-memory-distill` rules)
-- If mismatch, emit a `warn` finding suggesting `/rihal-memory-distill`
-
-### Step 8 — Render report
-
-Group findings by severity (critical → warn → info), then by file within each severity group. For each finding, print:
-- File path
-- One-line description
-- One-line `Fix:` suggestion (which skill to run, or manual action)
-
-If `--severity` filter passed, hide findings below the threshold.
-
-If zero findings: print `✓ Memory Bank is healthy. 0 findings.`
-
-### Step 9 — Apply fixes (only when `--fix` is set)
-
-<step name="apply_fixes">
-Skip if `FIX_MODE` is false.
-
-For each finding from the audit:
-- If severity is `trivial` (typo, stale ISO date, dead relative path,
-  provably-wrong factual value with an unambiguous replacement), patch in place.
-- For all other severities (`info`, `warn`, `critical`), leave for human review
-  and keep them in the report — never patch.
-
-Patching rule (HARD): use file Read+Edit (NOT regex sed) so fixes are exact
-string replacements that fail loudly on ambiguity. Sed-based mass-replace is
-forbidden because it silently rewrites unintended occurrences.
-
-Atomic commit per fix:
-
-```bash
-git add <file>
-git commit -m "fix(memory): <what was stale> → <what's true now>"
-```
-
-After the loop, log: `Memory --fix applied {N} trivial corrections across {M} commits.`
-
-If a finding marked trivial fails to patch (file changed mid-flight, ambiguous
-replacement, etc.), log it under "Skipped fixes" in the final report and
-continue with the next finding — never abort the whole run on a single failure.
-</step>
-
----
-
-## Guardrails
-
-- `--fix` NEVER patches above trivial severity, even with a `--force` flag (don't accept --force here)
-- `--fix` uses Read+Edit, not regex sed
-- `--fix` commits each correction atomically (no batched commits)
-- Default behavior (no `--fix`) is unchanged: report-only
-
-## Post-conditions
-
-- When `--fix` is OFF: no files modified; report printed to stdout
-- When `--fix` is ON: only trivial items modified; each as its own commit; report still printed
-
-## Reversibility
-
-- Default mode: read-only — no state to revert.
-- `--fix` mode: each fix is its own atomic git commit, so individual fixes can be reverted with `git revert <hash>`.
-
-## Success criteria
-
-- [ ] Default behavior unchanged — `--fix` off by default; report-only path preserved
-- [ ] `--fix` patches only trivial items, each as atomic commit prefixed `fix(memory):`
-- [ ] Report still printed even in `--fix` mode (so user sees what was/wasn't patched)

package/rihal/workflows/memory-distill.md

@@ -1,113 +0,0 @@
-# Workflow: rcode-memory-distill
-
-<purpose>
-Regenerate Memory Bank distillates with lossless compression — token-optimized snapshots of source files for fast LLM context loading. Idempotent: re-running on already-distilled content produces identical output.
-</purpose>
-
-Regenerate Memory Bank distillates with lossless compression. Idempotent.
-
----
-
-## Inputs
-
-- `--force` (optional) — regenerate even when source files are unchanged
-- `--target {project|stack|all}` (optional, default `all`) — limit which distillate to regenerate
-
-## Preconditions
-
-- `.rihal/memory/` exists
-- `.rihal/memory/distillates/` exists (created by `rcode-memory-init`)
-
-## Halt conditions
-
-- `.rihal/memory/` missing → instruct to run `/rihal-memory-init` first
-- All sources empty (only template placeholders) → warn and exit; no point distilling empty content
-
----
-
-## Steps
-
-### Step 1 — Resolve source set
-
-For `target = project`:
-- `project/stack.md`, `project/decisions.md`, `project/glossary.md`
-- `people/stakeholders.md`, `people/team.md`
-- `milestones/current.md`
-- `incidents/known-issues.md`
-
-For `target = stack`:
-- `project/stack.md` only
-
-### Step 2 — Compute digest
-
-```
-digest = sha1(concat(file_path + ":" + mtime for each source file in sorted order))
-```
-
-If `--force` not passed and existing distillate's `source-digest:` matches, skip regeneration for that target.
-
-### Step 3 — Compress per target
-
-For each target's source set:
-
-1. Read all source files
-2. Extract: facts, decisions, constraints, relationships, named entities, dates
-3. Produce a dense markdown document organised by topic (not by source file)
-4. Strip overhead: pleasantries, redundant headings, examples that don't add new facts, template placeholders that weren't filled
-5. Preserve: every concrete claim, every decision, every link, every name, every date
-
-Compression target: ~30% of source token count. If output is larger, the source had a lot of substance and that's fine.
-
-### Step 4 — Losslessness check
-
-Walk each source file and confirm every "fact" (sentence containing a name, date, decision, or technical term) appears in the distillate either verbatim or via a directly-equivalent phrase. List any potential drops as warnings; user can `--force` past warnings if confident.
-
-### Step 5 — Write output
-
-For each target distillate, write:
-
-```markdown
----
-generated: true
-do-not-edit: true
-regenerate-with: /rihal-memory-distill
-source-digest: <hash>
-generated-at: <ISO datetime>
-source-files:
-  - project/stack.md
-  - project/decisions.md
-  ...
-token-estimate: <approximate>
----
-
-# Project Distillate — <project-name>
-
-<compressed content>
-```
-
-### Step 6 — Summary
-
-Print per-target:
-- Source file count
-- Output token estimate
-- Digest
-- Skip notice (if no-op)
-
----
-
-## Post-conditions
-
-- `distillates/project.distillate.md` updated (if target includes project)
-- `distillates/stack.distillate.md` updated (if target includes stack)
-- Frontmatter `source-digest` matches the current source set
-- No source files modified
-
-## Reversibility
-
-Distillates are derived artefacts. Reverting a regeneration: `git checkout .rihal/memory/distillates/`.
-
-## On Completion
-
-/rihal-memory-audit — audit all memory files for staleness
-/rihal-next — get suggested next action
-/rihal-resume-work — continue with current work context