npm - @hanzlaa/rcode - Versions diffs - 3.6.16 → 4.1.0 - Mend

@hanzlaa/rcode 3.6.16 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1493) hide show

package/rihal/agents/rules/sprint-checker/process.md DELETED Viewed

@@ -1,377 +0,0 @@
-## Step 1: Load Context
-Load phase operation context:
-```bash
-INIT=$(node ".rihal/bin/rihal-tools.cjs" init phase-op "${PHASE_ARG}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
-Orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas.
-```bash
-ls "$phase_dir"/*-SPRINT.md 2>/dev/null
-# Read research for Nyquist validation data
-cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
-node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "$phase_number"
-ls "$phase_dir"/*-BRIEF.md 2>/dev/null
-```
-**Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.
-## Step 2: Load All Plans
-Use rihal-tools to validate plan structure:
-```bash
-for plan in "$PHASE_DIR"/*-SPRINT.md; do
-  echo "=== $plan ==="
-  PLAN_STRUCTURE=$(node ".rihal/bin/rihal-tools.cjs" verify plan-structure "$plan")
-  echo "$PLAN_STRUCTURE"
-done
-```
-Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`
-Map errors/warnings to verification dimensions:
-- Missing frontmatter field → `task_completeness` or `must_haves_derivation`
-- Task missing elements → `task_completeness`
-- Wave/depends_on inconsistency → `dependency_correctness`
-- Checkpoint/autonomous mismatch → `task_completeness`
-## Step 3: Parse must_haves
-Extract must_haves from each plan using rihal-tools:
-```bash
-MUST_HAVES=$(node ".rihal/bin/rihal-tools.cjs" frontmatter get "$PLAN_PATH" --field must_haves)
-```
-Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
-**Expected structure:**
-```yaml
-must_haves:
-  truths:
-    - "User can log in with email/password"
-    - "Invalid credentials return 401"
-  artifacts:
-    - path: "src/app/api/auth/login/route.ts"
-      provides: "Login endpoint"
-      min_lines: 30
-  key_links:
-    - from: "src/components/LoginForm.tsx"
-      to: "/api/auth/login"
-      via: "fetch in onSubmit"
-```
-Aggregate across plans for full picture of what phase delivers.
-## Step 4: Check Requirement Coverage
-Map requirements to tasks:
-```
-Requirement          | Plans | Tasks | Status
----------------------|-------|-------|--------
-User can log in      | 01    | 1,2   | COVERED
-User can log out     | -     | -     | MISSING
-Session persists     | 01    | 3     | COVERED
-```
-For each requirement: find covering task(s), verify action is specific, flag gaps.
-**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
-## Step 5: Validate Task Structure
-Use rihal-tools plan-structure verification (already run in Step 2):
-```bash
-PLAN_STRUCTURE=$(node ".rihal/bin/rihal-tools.cjs" verify plan-structure "$PLAN_PATH")
-```
-The `tasks` array in the result shows each task's completeness:
-- `hasFiles` — files element present
-- `hasAction` — action element present
-- `hasVerify` — verify element present
-- `hasDone` — done element present
-**Check:** valid task type (auto, checkpoint:*, tdd), auto tasks have files/action/verify/done, action is specific, verify is runnable, done is measurable.
-**For manual validation of specificity** (rihal-tools checks structure, not content quality):
-```bash
-grep -B5 "</task>" "$PHASE_DIR"/*-SPRINT.md | grep -v "<verify>"
-```
-## Step 6: Verify Dependency Graph
-```bash
-for plan in "$PHASE_DIR"/*-SPRINT.md; do
-  grep "depends_on:" "$plan"
-done
-```
-Validate: all referenced plans exist, no cycles, wave numbers consistent, no forward references. If A -> B -> C -> A, report cycle.
-## Step 7: Check Key Links
-For each key_link in must_haves: find source artifact task, check if action mentions the connection, flag missing wiring.
-```
-key_link: Chat.tsx -> /api/chat via fetch
-Task 2 action: "Create Chat component with message list..."
-Missing: No mention of fetch/API call → Issue: Key link not planned
-```
-## Step 8: Assess Scope
-```bash
-grep -c "<task" "$PHASE_DIR"/$PHASE-01-SPRINT.md
-grep "files_modified:" "$PHASE_DIR"/$PHASE-01-SPRINT.md
-```
-Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required).
-## Step 9: Verify must_haves Derivation
-**Truths:** user-observable (not "bcrypt installed" but "passwords are secure"), testable, specific.
-**Artifacts:** map to truths, reasonable min_lines, list expected exports/content.
-**Key_links:** connect dependent artifacts, specify method (fetch, Prisma, import), cover critical wiring.
-## Step 9.5: Verify File References (NEW)
-Before step 10, add pre-flight reference verification:
-```bash
-PLAN_TEXT=$(cat "$PLAN_PATH")
-VERIFY_RESULT=$(node -e "
-const cr = require('.rihal/bin/lib/code-references.cjs');
-const fs = require('fs');
-const text = fs.readFileSync(process.argv[1], 'utf8');
-const refs = cr.extractReferences(text);
-const result = cr.verifyReferences(refs, process.cwd());
-console.log(JSON.stringify(result, null, 2));
-" "$PLAN_PATH")
-```
-Check result:
-- If `summary.ratio < 0.5`: **BLOCKER** — "Plan references files/symbols that don't exist. Plan was built on hallucinated findings."
-- If `summary.ratio >= 0.5 AND < 0.8`: **WARNING** — List missing files/symbols, suggest re-planning with /rihal-debug
-- If `summary.ratio >= 0.8`: **INFO** — Most references verified, proceed
-Append to verification output:
-```markdown
-## File References Verification
-**Verified:** {summary.verified} / {summary.total} ({summary.ratio}%)
-**Status:** ✅ PASS / ⚠️  WARNING / ❌ FAIL
-{if missing refs:}
-Missing files: {list}
-Missing symbols: {list}
-{hint}
-```
-## Step 10: Determine Overall Status
-**passed:** All requirements covered, all tasks complete, dependency graph valid, key links planned, scope within budget, must_haves properly derived.
-**issues_found:** One or more blockers or warnings. Plans need revision.
-Severities: `blocker` (must fix), `warning` (should fix), `info` (suggestions).
-</verification_process>
-<examples>
-## Scope Exceeded (most common miss)
-**Plan 01 analysis:**
-```
-Tasks: 5
-Files modified: 12
-  - prisma/schema.prisma
-  - src/app/api/auth/login/route.ts
-  - src/app/api/auth/logout/route.ts
-  - src/app/api/auth/refresh/route.ts
-  - src/middleware.ts
-  - src/lib/auth.ts
-  - src/lib/jwt.ts
-  - src/components/LoginForm.tsx
-  - src/components/LogoutButton.tsx
-  - src/app/login/page.tsx
-  - src/app/dashboard/page.tsx
-  - src/types/auth.ts
-```
-5 tasks exceeds 2-3 target, 12 files is high, auth is complex domain → quality degradation risk.
-```yaml
-issue:
-  dimension: scope_sanity
-  severity: blocker
-  description: "Plan 01 has 5 tasks with 12 files - exceeds context budget"
-  plan: "01"
-  metrics:
-    tasks: 5
-    files: 12
-    estimated_context: "~80%"
-  fix_hint: "Split into: 01 (schema + API), 02 (middleware + lib), 03 (UI components)"
-```
-</examples>
-<issue_structure>
-## Issue Format
-```yaml
-issue:
-  plan: "16-01"              # Which plan (null if phase-level)
-  dimension: "task_completeness"  # Which dimension failed
-  severity: "blocker"        # blocker | warning | info
-  description: "..."
-  task: 2                    # Task number if applicable
-  fix_hint: "..."
-```
-## Severity Levels
-**blocker** - Must fix before execution
-- Missing requirement coverage
-- Missing required task fields
-- Circular dependencies
-- Scope > 5 tasks per plan
-**warning** - Should fix, execution may work
-- Scope 4 tasks (borderline)
-- Implementation-focused truths
-- Minor wiring missing
-**info** - Suggestions for improvement
-- Could split for better parallelization
-- Could improve verification specificity
-Return all issues as a structured `issues:` YAML list (see dimension examples for format).
-</issue_structure>
-<structured_returns>
-## VERIFICATION PASSED
-```markdown
-## VERIFICATION PASSED
-**Phase:** {phase-name}
-**Plans verified:** {N}
-**Status:** All checks passed
-### Coverage Summary
-| Requirement | Plans | Status |
-|-------------|-------|--------|
-| {req-1}     | 01    | Covered |
-| {req-2}     | 01,02 | Covered |
-### Plan Summary
-| Plan | Tasks | Files | Wave | Status |
-|------|-------|-------|------|--------|
-| 01   | 3     | 5     | 1    | Valid  |
-| 02   | 2     | 4     | 2    | Valid  |
-Plans verified. Run `/rihal-execute {phase}` to proceed.
-```
-## ISSUES FOUND
-```markdown
-## ISSUES FOUND
-**Phase:** {phase-name}
-**Plans checked:** {N}
-**Issues:** {X} blocker(s), {Y} warning(s), {Z} info
-### Blockers (must fix)
-**1. [{dimension}] {description}**
-- Plan: {plan}
-- Task: {task if applicable}
-- Fix: {fix_hint}
-### Warnings (should fix)
-**1. [{dimension}] {description}**
-- Plan: {plan}
-- Fix: {fix_hint}
-### Structured Issues
-(YAML issues list using format from Issue Format above)
-### Recommendation
-{N} blocker(s) require revision. Returning to planner with feedback.
-```
-</structured_returns>
-<anti_patterns>
-**DO NOT** check code existence — that's rihal-verifier's job. You verify plans, not codebase.
-**DO NOT** run the application. Static plan analysis only.
-**DO NOT** accept vague tasks. "Implement auth" is not specific. Tasks need concrete files, actions, verification.
-**DO NOT** skip dependency analysis. Circular/broken dependencies cause execution failures.
-**DO NOT** ignore scope. 5+ tasks/plan degrades quality. Report and split.
-**DO NOT** verify implementation details. Check that plans describe what to build.
-**DO NOT** trust task names alone. Read action, verify, done fields. A well-named task can be empty.
-</anti_patterns>
-<success_criteria>
-Plan verification complete when:
-- [ ] Phase goal extracted from ROADMAP.md
-- [ ] All SPRINT.md files in phase directory loaded
-- [ ] must_haves parsed from each plan frontmatter
-- [ ] Requirement coverage checked (all requirements have tasks)
-- [ ] Task completeness validated (all required fields present)
-- [ ] Dependency graph verified (no cycles, valid references)
-- [ ] Key links checked (wiring planned, not just artifacts)
-- [ ] Scope assessed (within context budget)
-- [ ] must_haves derivation verified (user-observable truths)
-- [ ] Context compliance checked (if CONTEXT.md provided):
-  - [ ] Locked decisions have implementing tasks
-  - [ ] No tasks contradict locked decisions
-  - [ ] Deferred ideas not included in plans
-- [ ] Overall status determined (passed | issues_found)
-- [ ] Cross-plan data contracts checked (no conflicting transforms on shared data)
-- [ ] CLAUDE.md compliance checked (plans respect project conventions)
-- [ ] Structured issues returned (if any found)
-- [ ] Result returned to orchestrator
-</success_criteria>
-## Constraints
-- Apply Karpathy guidelines (see @-included reference) as hard rules. Reference the principle number when refusing a change.
-- validate YAML frontmatter exactly as specified
-- check task structure against execution-protocol.md
-- verify all dependencies and checkpoint placement
-- return PASS/FAIL with specific issues listed
-- never modify the plan — only report findings

package/rihal/agents/rules/verifier/anti-patterns.md DELETED Viewed

@@ -1,94 +0,0 @@
-# Verifier — Anti-Pattern Scanning (Step 7) + Stub Detection Patterns
-## Step 7: Scan for Anti-Patterns
-Identify files modified in this phase from SUMMARY.md key-files section, or extract commits and verify:
-```bash
-# Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ".rihal/bin/rihal-tools.cjs" summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
-# Option 2: Verify commits exist (if commit hashes documented)
-COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-SUMMARY.md | head -10)
-if [ -n "$COMMIT_HASHES" ]; then
-  COMMITS_VALID=$(node ".rihal/bin/rihal-tools.cjs" verify commits $COMMIT_HASHES)
-fi
-# Fallback: grep for files
-grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
-```
-## Anti-pattern detection on each file
-```bash
-# TODO/FIXME/placeholder comments
-grep -n -E "TODO|FIXME|XXX|HACK|PLACEHOLDER" "$file" 2>/dev/null
-grep -n -E "placeholder|coming soon|will be here|not yet implemented|not available" "$file" -i 2>/dev/null
-# Empty implementations
-grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null
-# Hardcoded empty data (common stub patterns)
-grep -n -E "=\s*\[\]|=\s*\{\}|=\s*null|=\s*undefined" "$file" 2>/dev/null | grep -v -E "(test|spec|mock|fixture|\.test\.|\.spec\.)" 2>/dev/null
-# Props with hardcoded empty values (React/Vue/Svelte stub indicators)
-grep -n -E "=\{(\[\]|\{\}|null|undefined|''|\"\")\}" "$file" 2>/dev/null
-# Console.log only implementations
-grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)"
-```
-**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging.
-Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable)
----
-## Stub Detection Reference Patterns
-### React Component Stubs
-```javascript
-// RED FLAGS:
-return <div>Component</div>
-return <div>Placeholder</div>
-return <div>{/* TODO */}</div>
-return null
-return <></>
-// Empty handlers:
-onClick={() => {}}
-onChange={() => console.log('clicked')}
-onSubmit={(e) => e.preventDefault()}  // Only prevents default
-```
-### API Route Stubs
-```typescript
-// RED FLAGS:
-export async function POST() {
-  return Response.json({ message: "Not implemented" });
-}
-export async function GET() {
-  return Response.json([]); // Empty array with no DB query
-}
-```
-### Wiring Red Flags
-```typescript
-// Fetch exists but response ignored:
-fetch('/api/messages')  // No await, no .then, no assignment
-// Query exists but result not returned:
-await prisma.message.findMany()
-return Response.json({ ok: true })  // Returns static, not query result
-// Handler only prevents default:
-onSubmit={(e) => e.preventDefault()}
-// State exists but not rendered:
-const [messages, setMessages] = useState([])
-return <div>No messages</div>  // Always shows "no messages"
-```

package/rihal/agents/rules/verifier/artifact-verification.md DELETED Viewed

@@ -1,69 +0,0 @@
-# Verifier — Observable Truths + 3-Level Artifact Verification (Steps 3–4)
-## Step 3: Verify Observable Truths
-For each truth, determine if codebase enables it.
-**Verification status:**
-- ✓ VERIFIED: All supporting artifacts pass all checks
-- ✗ FAILED: One or more artifacts missing, stub, or unwired
-- ? UNCERTAIN: Can't verify programmatically (needs human)
-For each truth:
-1. Identify supporting artifacts
-2. Check artifact status (Step 4)
-3. Check wiring status (Step 5)
-4. Determine truth status
-## Step 4: Verify Artifacts (Three Levels)
-Use rihal-tools for artifact verification against must_haves in PLAN frontmatter:
-```bash
-ARTIFACT_RESULT=$(node ".rihal/bin/rihal-tools.cjs" verify artifacts "$PLAN_PATH")
-```
-Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
-For each artifact in result:
-- `exists=false` → MISSING
-- `issues` contains "Only N lines" or "Missing pattern" → STUB
-- `passed=true` → VERIFIED
-### Artifact status mapping
-| exists | issues empty | Status      |
-| ------ | ------------ | ----------- |
-| true   | true         | ✓ VERIFIED  |
-| true   | false        | ✗ STUB      |
-| false  | -            | ✗ MISSING   |
-### Wiring verification (Level 3)
-For artifacts that pass Levels 1-2, check imports/usage manually:
-```bash
-# Import check
-grep -r "import.*$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l
-# Usage check (beyond imports)
-grep -r "$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l
-```
-**Wiring status:**
-- WIRED: Imported AND used
-- ORPHANED: Exists but not imported/used
-- PARTIAL: Imported but not used (or vice versa)
-### Final Artifact Status (Levels 1-3)
-| Exists | Substantive | Wired | Status      |
-| ------ | ----------- | ----- | ----------- |
-| ✓      | ✓           | ✓     | ✓ VERIFIED  |
-| ✓      | ✓           | ✗     | ⚠️ ORPHANED |
-| ✓      | ✗           | -     | ✗ STUB      |
-| ✗      | -           | -     | ✗ MISSING   |
-For Level 4 (data flow), see `data-flow-trace.md`.

package/rihal/agents/rules/verifier/context-loading.md DELETED Viewed

@@ -1,84 +0,0 @@
-# Verifier — Context Loading (Steps 0–2)
-## Step 0: Check for Previous Verification
-```bash
-cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
-```
-**If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
-1. Parse previous VERIFICATION.md frontmatter
-2. Extract `must_haves` (truths, artifacts, key_links)
-3. Extract `gaps` (items that failed)
-4. Set `is_re_verification = true`
-5. **Skip to Step 3** with optimization:
-   - **Failed items:** Full 3-level verification (exists, substantive, wired)
-   - **Passed items:** Quick regression check (existence + basic sanity only)
-**If no previous verification OR no `gaps:` section → INITIAL MODE:**
-Set `is_re_verification = false`, proceed with Step 1.
-## Step 1: Load Context (Initial Mode Only)
-```bash
-ls "$PHASE_DIR"/*-SPRINT.md 2>/dev/null
-ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
-node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "$PHASE_NUM"
-grep -E "^| $PHASE_NUM" .rihal/REQUIREMENTS.md 2>/dev/null
-```
-Extract phase goal from ROADMAP.md — this is the outcome to verify, not the tasks.
-## Step 2: Establish Must-Haves (Initial Mode Only)
-In re-verification mode, must-haves come from Step 0.
-### Option A: Must-haves in PLAN frontmatter
-```bash
-grep -l "must_haves:" "$PHASE_DIR"/*-SPRINT.md 2>/dev/null
-```
-If found, extract and use:
-```yaml
-must_haves:
-  truths:
-    - "User can see existing messages"
-    - "User can send a message"
-  artifacts:
-    - path: "src/components/Chat.tsx"
-      provides: "Message list rendering"
-  key_links:
-    - from: "Chat.tsx"
-      to: "api/chat"
-      via: "fetch in useEffect"
-```
-### Option B: Use Success Criteria from ROADMAP.md
-If no must_haves in frontmatter, check for Success Criteria:
-```bash
-PHASE_DATA=$(node ".rihal/bin/rihal-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
-```
-Parse the `success_criteria` array from the JSON output. If non-empty:
-1. **Use each Success Criterion directly as a truth** (they are already observable, testable behaviors)
-2. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
-3. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
-4. **Document must-haves** before proceeding
-Success Criteria from ROADMAP.md are the contract — they take priority over Goal-derived truths.
-### Option C: Derive from phase goal (fallback)
-If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
-1. **State the goal** from ROADMAP.md
-2. **Derive truths:** "What must be TRUE?" — list 3-7 observable, testable behaviors
-3. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
-4. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
-5. **Document derived must-haves** before proceeding

package/rihal/agents/rules/verifier/gap-output.md DELETED Viewed

@@ -1,51 +0,0 @@
-# Verifier — Status Determination + Gap Output (Steps 8–10)
-## Step 8: Identify Human Verification Needs
-**Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
-**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.
-**Format:**
-```markdown
-### 1. {Test Name}
-**Test:** {What to do}
-**Expected:** {What should happen}
-**Why human:** {Why can't verify programmatically}
-```
-## Step 9: Determine Overall Status
-**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
-**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
-**Status: human_needed** — All automated checks pass but items flagged for human verification.
-**Score:** `verified_truths / total_truths`
-## Step 10: Structure Gap Output (If Gaps Found)
-Structure gaps in YAML frontmatter for `/rihal-plan --gaps`:
-```yaml
-gaps:
-  - truth: "Observable truth that failed"
-    status: failed
-    reason: "Brief explanation"
-    artifacts:
-      - path: "src/path/to/file.tsx"
-        issue: "What's wrong"
-    missing:
-      - "Specific thing to add/fix"
-```
-- `truth`: The observable truth that failed
-- `status`: failed | partial
-- `reason`: Brief explanation
-- `artifacts`: Files with issues
-- `missing`: Specific things to add/fix
-**Group related gaps by concern** — if multiple truths fail from the same root cause, note this to help the planner create focused plans.