Riding Through the Codebase

You are analyzing an existing codebase to generate evidence-grounded Loa artifacts following the v0.6.0 Enterprise-Grade Managed Scaffolding model.

"The Loa rides through the code, channeling truth into the grimoire."

Core Principles

CODE IS TRUTH → Loa channels CODE → Grimoire reflects REALITY

1. Never trust documentation - Verify everything against code
2. Flag, don't fix - Dead code/issues flagged for human decision
3. Evidence required - Every claim needs file:line citation
4. Target repo awareness - Grimoire lives WITH the code it documents

Phase 0: Preflight & Mount Verification

0.1 Verify Loa is Mounted

Check for .loa-version.json. If missing, instruct user to run /mount first. Extract and display framework version.

0.2 System Zone Integrity Check (BLOCKING)

Verify .claude/checksums.json against actual file hashes. If drift detected:

• Display drifted files list
• Offer options: move customizations to .claude/overrides/, --force-restore to reset, /update-loa --force-restore to sync
• BLOCK unless --force-restore passed

If no checksums file exists (first ride), skip with warning.

0.3 Detect Execution Context

if [[ -f ".claude/commands/ride.md" ]] && [[ -d ".claude/skills/riding-codebase" ]]; then
  IS_FRAMEWORK_REPO=true
else
  IS_FRAMEWORK_REPO=false
  TARGET_REPO="$CURRENT_DIR"
fi

0.4 Target Resolution (Framework Repo Only)

If ISFRAMEWORKREPO=true, use AskUserQuestion to select target repo. The Loa rides codebases, not itself.

0.5 Initialize Ride Trajectory

TRAJECTORY_FILE="grimoires/loa/a2a/trajectory/riding-$(date +%Y%m%d).jsonl"
mkdir -p grimoires/loa/a2a/trajectory

Log preflight completion to trajectory.

0.6 Artifact Staleness Check

If grimoires/loa/reality/.reality-meta.json exists:

1. Read generated_at timestamp from the JSON
2. Read ride.staleness_days from .loa.config.yaml (default: 7)
3. If artifacts are fresh (< staleness_days old) AND --fresh flag NOT passed:

- Use AskUserQuestion: "Ride artifacts are N days old. [R]e-analyze or [S]kip?" - If skip: Exit with message "Using existing ride artifacts from [date]"

1. If --fresh flag: proceed regardless of artifact age
2. If .reality-meta.json does not exist: proceed (first ride)

Log staleness check to trajectory:

{"phase": 0.6, "action": "staleness_check", "status": "fresh|stale|first_ride", "artifact_age_days": N}

Enrichment Flags (Opt-In Depth Control)

Parse the user's invocation text for enrichment flags. These control whether optional Phases 12-14 run after the standard ride.

Flag Detection

Scan the user's invocation for these flags:

Parsing Rules

1. If --enriched is present, set ENRICHGAPS=true, ENRICHDECISIONS=true, ENRICHTERMS=true, ENRICHSIMPLICITY=true
2. Individual flags can be combined: --with-gaps --with-decisions
3. If NO enrichment flags are present, all variables remain false — standard ride proceeds unchanged
4. Log parsed flags to trajectory:

{"phase": "flags", "action": "enrichment_flags_parsed", "status": "complete", "details": {"ENRICH_GAPS": false, "ENRICH_DECISIONS": false, "ENRICH_TERMS": false}}

Configuration Defaults

Read enrichment thresholds from .loa.config.yaml (used by Phases 12-14):

# Gap tracker thresholds
GAP_MAX_OPEN=$(yq eval '.ride.enrichment.gaps.max_open // 200' .loa.config.yaml 2>/dev/null || echo "200")
GAP_WARN_AT=$(yq eval '.ride.enrichment.gaps.warn_at // 150' .loa.config.yaml 2>/dev/null || echo "150")

# Decision archaeology thresholds
DECISION_STALE_MONTHS=$(yq eval '.ride.enrichment.decisions.stale_months // 12' .loa.config.yaml 2>/dev/null || echo "12")
DECISION_EXTRA_PATHS=$(yq eval '.ride.enrichment.decisions.extra_paths // []' .loa.config.yaml 2>/dev/null || echo "[]")

# Terminology thresholds
TERM_MAX_TERMS=$(yq eval '.ride.enrichment.terminology.max_terms // 50' .loa.config.yaml 2>/dev/null || echo "50")

QMD Reality Context (Optional)

During drift analysis, if .claude/scripts/qmd-context-query.sh exists and qmd_context.enabled is not false:

1. Build query from module names being analyzed
2. Run: .claude/scripts/qmd-context-query.sh --query "<module_names>" --scope reality --budget 2000 --format text
3. Include output as additional context during drift comparison
4. If script missing, disabled, or returns empty: proceed normally (graceful no-op)

<attention_budget>

Attention Budget

This skill follows the Tool Result Clearing Protocol (.claude/protocols/tool-result-clearing.md).

Token Thresholds

4-Step Clearing

1. Extract: Max 10 files, 20 words per finding, with file:line refs
2. Synthesize: Write to grimoires/loa/reality/ or NOTES.md
3. Clear: Remove raw output from context
4. Summary: "Probe: N files → M relevant → reality/"

RLM Pattern Alignment

• Retrieve: Probe first, don't load eagerly
• Load: JIT retrieval of relevant sections only
• Modify: Synthesize to grimoire, clear working memory

</attention_budget>

Phase 0.5: Codebase Probing (RLM Pattern)

Before loading any files, probe the codebase to determine optimal loading strategy.

0.5.1 Run Codebase Probe

Use .claude/scripts/context-manager.sh probe "$TARGET_REPO" --json to get file count, line count, estimated tokens, and codebase size category. Fall back to eager loading if probe unavailable.

0.5.2 Determine Loading Strategy

0.5.3 Generate Loading Plan

Create grimoires/loa/reality/loading-plan.md with files categorized by should-load decision. For prioritized/excerpts strategies, sort files by relevance score using .claude/scripts/context-manager.sh should-load "$file" --json.

Log probe results to trajectory.

Phase 1: Interactive Context Discovery

1.1 Check for Existing Context

Scan grimoires/loa/context/ for existing documentation files.

1.2 Context File Prompt

Use AskUserQuestion to offer the user a chance to add context files (architecture docs, tribal knowledge, roadmaps) to grimoires/loa/context/ before the interview.

1.3 Analyze Existing Context (Pre-Interview)

If context files exist, analyze them BEFORE the interview. Generate grimoires/loa/context/context-coverage.md listing:

• Files analyzed with key topics
• Topics already covered (will skip in interview)
• Gaps to explore in interview
• Claims extracted to verify against code

1.4 Interactive Discovery (Gap-Focused Interview)

Use AskUserQuestion for each topic, skipping questions answered by context files:

1. Architecture: Project description, tech stack, organization, entry points
2. Domain: Core entities, external services, feature flags
3. Tribal Knowledge (Critical): Surprises, unwritten rules, untouchable areas, scary parts
4. Work in Progress: Intentionally incomplete code, planned features
5. History: Codebase age, architecture evolution

1.5 Generate Claims to Verify (MANDATORY OUTPUT)

YOU MUST CREATE grimoires/loa/context/claims-to-verify.md with tables for:

• Architecture Claims (claim, source, verification strategy)
• Domain Claims
• Tribal Knowledge (handle carefully)
• WIP Status

Even if interview is skipped, create this file from existing context.

1.6 File Persistence Checkpoint (CP-1)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/context/claims-to-verify.md.

After writing, verify with Glob pattern grimoires/loa/context/claims-to-verify.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 1, "action": "write_failed", "artifact": "claims-to-verify.md", "status": "error"}

Do NOT render the artifact inline without also writing it to disk.

1.7 Tool Result Clearing Checkpoint

Clear raw interview data. Summarize captured claims count and top investigation areas.

Phase 2: Code Reality Extraction

Setup

mkdir -p grimoires/loa/reality
cd "$TARGET_REPO"

Apply the loading strategy from Phase 0.5 to control which files get fully loaded, excerpted, or skipped.

Extraction Steps

Execute the following extractions, writing results to grimoires/loa/reality/:

See: resources/references/deep-analysis-guide.md for detailed extraction commands and loading strategy helpers.

2.8 Tool Result Clearing Checkpoint (MANDATORY)

Clear raw tool outputs. Report counts for routes, entities, env vars, tech debt, tests. Include loading strategy results (files loaded/excerpted/skipped, tokens saved).

Phase 2b: Code Hygiene Audit

Generate grimoires/loa/reality/hygiene-report.md flagging potential issues for HUMAN DECISION:

• Files outside standard directories
• Potential temporary/WIP folders
• Commented-out code blocks
• Potential dependency conflicts

See: resources/references/deep-analysis-guide.md for the hygiene report template and dead code philosophy.

2b.1 File Persistence Checkpoint (CP-2b)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/hygiene-report.md.

After writing, verify with Glob pattern grimoires/loa/reality/hygiene-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": "2b", "action": "write_failed", "artifact": "hygiene-report.md", "status": "error"}

Phase 3: Legacy Documentation Inventory

3.1 Find All Documentation

Find all .md, .rst, .txt, .adoc files (excluding node_modules, .git, grimoires/loa). Save to grimoires/loa/legacy/doc-files.txt.

3.2 Assess AI Guidance Quality (CLAUDE.md)

Score existing CLAUDE.md on: length (>50 lines), tech stack mentions, pattern/convention guidance, warnings. Score out of 7; below 5 is insufficient.

3.3 Create Inventory

Create grimoires/loa/legacy/INVENTORY.md listing all docs with type and key claims.

3.4 File Persistence Checkpoint (CP-3)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/legacy/INVENTORY.md.

After writing, verify with Glob pattern grimoires/loa/legacy/INVENTORY.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 3, "action": "write_failed", "artifact": "INVENTORY.md", "status": "error"}

Phase 4: Three-Way Drift Analysis

4.1 Drift Categories

4.2 Legacy Claim Verification (MANDATORY)

Extract claims from legacy docs. For EACH claim, verify against code reality. Determine status: VERIFIED | STALE | HALLUCINATED | MISSING.

4.3 Generate Drift Report

Create grimoires/loa/drift-report.md with summary table, drift score, breakdown by type, critical items with verification evidence.

See: resources/references/analysis-checklists.md for the full drift report template.

Log drift analysis to trajectory.

4.4 File Persistence Checkpoint (CP-4)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/drift-report.md.

After writing, verify with Glob pattern grimoires/loa/drift-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 4, "action": "write_failed", "artifact": "drift-report.md", "status": "error"}

Phase 5: Consistency Analysis (MANDATORY OUTPUT)

YOU MUST CREATE grimoires/loa/consistency-report.md.

Analyze naming patterns (entities, functions, files), compute consistency score (1-10), identify conflicts and improvement opportunities. Flag breaking changes without implementing.

See: resources/references/analysis-checklists.md for the consistency report template.

Log to trajectory.

5.1 File Persistence Checkpoint (CP-5)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/consistency-report.md.

After writing, verify with Glob pattern grimoires/loa/consistency-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 5, "action": "write_failed", "artifact": "consistency-report.md", "status": "error"}

Phase 6: Loa Artifact Generation (WITH GROUNDING MARKERS)

MANDATORY: Every claim in PRD and SDD MUST use grounding markers:

Extended Markers (available when enrichment phases run):

These extended markers complement (not replace) the standard markers above and the BUTTERFREEZONE provenance tags (CODE-FACTUAL, DERIVED, OPERATIONAL). Use them in reality files (grimoires/loa/reality/*.md) and the gap tracker when enrichment phases produce evidence that warrants richer attribution.

6.1 Generate PRD

Create grimoires/loa/prd.md with evidence-grounded user types, features, and requirements. Include Source of Truth notice and Document Metadata.

6.2 Generate SDD

Create grimoires/loa/sdd.md with verified tech stack, module structure, data model, and API surface. All with grounding markers and evidence.

6.3 Grounding Summary Block

Append to BOTH PRD and SDD: counts and percentages of GROUNDED/INFERRED/ASSUMPTION claims, plus assumptions requiring validation.

Quality Target: >80% GROUNDED, <10% ASSUMPTION

See: resources/references/output-formats.md for PRD, SDD, and grounding summary templates.

Log to trajectory.

6.4 File Persistence Checkpoint (CP-6a, CP-6b)

WRITE TO DISK: Use the Write tool to persist BOTH artifacts:

After writing each, verify with Glob — must return 1 match per file. If either missing after Write, retry once. If still missing, log to trajectory:

{"phase": 6, "action": "write_failed", "artifact": "prd.md|sdd.md", "status": "error"}

Phase 6.5: Reality File Generation (Token-Optimized Codebase Interface)

Generate token-optimized reality files for the /reality command in grimoires/loa/reality/:

Also generate .reality-meta.json with token counts and staleness threshold.

Total budget: < 8500 tokens across all files (7000 base + 1500 architecture-overview).

See: resources/references/output-formats.md for all reality file templates.

Log to trajectory.

6.5.1 File Persistence Checkpoint (CP-6.5)

WRITE TO DISK: Use the Write tool to persist ALL reality files:

After writing each file, verify with Glob — each must return 1 match. Log any failures to trajectory:

{"phase": 6.5, "action": "write_failed", "artifact": "{filename}", "status": "error"}

Phase 7: Governance Audit

Generate grimoires/loa/governance-report.md:

7.1 File Persistence Checkpoint (CP-7)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/governance-report.md.

After writing, verify with Glob pattern grimoires/loa/governance-report.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 7, "action": "write_failed", "artifact": "governance-report.md", "status": "error"}

Phase 8: Legacy Deprecation

For each file in legacy/doc-files.txt, prepend a deprecation notice pointing to grimoires/loa/prd.md and grimoires/loa/sdd.md as the new source of truth, with reference to grimoires/loa/drift-report.md.

Checkpoint coverage note: Phases 2 (extraction), 3 (doc-files.txt), and 8 (deprecation) produce intermediate or modified artifacts not covered by write checkpoints. Phase 2 extractions are working data consumed immediately by later phases. Phase 3's INVENTORY.md is covered by CP-3; doc-files.txt is an intermediate file. Phase 8 modifies existing files rather than creating new ones, so existence checks do not apply.

Phase 9: Trajectory Self-Audit (MANDATORY OUTPUT)

YOU MUST CREATE grimoires/loa/trajectory-audit.md.

9.1 Review Generated Artifacts

Count grounding markers ([GROUNDED], [INFERRED], [ASSUMPTION]) in both PRD and SDD.

9.2 Generate Audit

Include: execution summary table (all phases with status/output/findings), grounding analysis for PRD and SDD, claims requiring validation, hallucination checklist, reasoning quality score (1-10).

See: resources/references/analysis-checklists.md for the full self-audit template.

IMPORTANT: If trajectory file is empty at Phase 9, flag as failure.

Log to trajectory.

9.3 File Persistence Checkpoint (CP-9)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/trajectory-audit.md.

After writing, verify with Glob pattern grimoires/loa/trajectory-audit.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 9, "action": "write_failed", "artifact": "trajectory-audit.md", "status": "error"}

Phase 10: Maintenance Handoff

10.0 Artifact Verification Gate (BLOCKING)

Before handoff, verify ALL expected artifacts exist on disk using Glob.

Full Mode Checklist:

Enrichment Artifacts (check only when corresponding flag was set):

Procedure:

1. For each file, use Glob to verify existence
2. Count: passed / total
3. If any missing: attempt to write from context, then re-verify
4. Report final count in completion summary
5. Log verification to trajectory

The ride MUST NOT complete with 0/N artifacts verified. If critical artifacts (drift-report, consistency-report, governance-report, trajectory-audit, hygiene-report) are missing, flag as ride failure.

10.1 Update NOTES.md

Add session continuity entry and ride results (routes documented, entities, tech debt, drift score, governance gaps).

10.2 Completion Summary

The Loa Has Ridden

Artifact Verification: X/Y files persisted

Grimoire Artifacts Created:
- grimoires/loa/prd.md (Product truth)
- grimoires/loa/sdd.md (System truth)
- grimoires/loa/drift-report.md (Three-way analysis)
- grimoires/loa/consistency-report.md (Pattern analysis)
- grimoires/loa/governance-report.md (Process gaps)
- grimoires/loa/reality/* (Raw extractions + token-optimized files)
- grimoires/loa/trajectory-audit.md (Self-audit)

Enrichment Outputs (if enabled):
- grimoires/loa/gaps.md (Gap tracker — if --with-gaps)
- grimoires/loa/reality/decisions.md (Decision archaeology — if --with-decisions)
- grimoires/loa/reality/terminology.md (Domain terminology — if --with-terms)

Next Steps:
1. Review drift-report.md for critical issues
2. Address governance gaps
3. /translate-ride for executive communications
4. Schedule stakeholder PRD review
5. Run /implement for high-priority drift
6. Review gaps.md and resolve open gaps (if enrichment ran)

Phase 11: Ground Truth Generation (--ground-truth only)

This phase runs only when the --ground-truth flag is passed. It produces a token-efficient, deterministically-verified codebase summary for agent consumption.

When --ground-truth --non-interactive is passed, phases 1 (Interactive Context Discovery), 3 (Legacy Doc Inventory), and 8 (Legacy Deprecation) are skipped — only extraction, analysis, and GT generation run.

11.1 Read Reality Extraction Results

Read the reality/ files generated in Phase 2 and Phase 6.5. These contain the code truth that GT will summarize.

11.2 Synthesize GT Files

Generate hub-and-spoke Ground Truth files:

Every factual claim MUST cite a source file and line range (file:line). The grounding ratio must be >= 0.95.

11.3 Generate Checksums

Invoke ground-truth-gen.sh for mechanical operations:

.claude/scripts/ground-truth-gen.sh \
  --reality-dir grimoires/loa/reality/ \
  --output-dir grimoires/loa/ground-truth/ \
  --max-tokens-per-section 2000 \
  --mode checksums

This produces checksums.json with SHA-256 hashes of all referenced source files.

11.4 Validate Token Budget

.claude/scripts/ground-truth-gen.sh \
  --output-dir grimoires/loa/ground-truth/ \
  --max-tokens-per-section 2000 \
  --mode validate

If any section exceeds its token budget, trim content (prioritize most-referenced APIs/components) and re-validate.

11.5 Log to Trajectory

{"phase": 11, "action": "ground_truth_generation", "status": "complete", "details": {"files": 5, "total_tokens": N, "checksums_count": N, "within_budget": true}}

Phase 12: Gap Tracker Generation (ENRICH_GAPS only)

Skip condition: If ENRICH_GAPS == false, skip this entire phase. Log skip to trajectory:

{"phase": 12, "action": "gap_tracker", "status": "skipped", "details": {"reason": "ENRICH_GAPS not set"}}

12.1 Load Existing Gaps and Generate Session Hash

Read grimoires/loa/gaps.md if it exists. Extract the highest GAP-NNN numeric ID to determine the next available ID. If file doesn't exist, start at GAP-001. Generate a session-scoped hash to prevent concurrent ID collisions.

# Extract highest gap ID (handles both GAP-NNN and GAP-NNN-HASH formats)
NEXT_GAP_ID=1
if [[ -f grimoires/loa/gaps.md ]]; then
  HIGHEST=$(grep -oP 'GAP-\K[0-9]+' grimoires/loa/gaps.md | sort -n | tail -1)
  NEXT_GAP_ID=$((HIGHEST + 1))
fi

# Generate 4-character session hash for concurrent safety
SESSION_HASH=$(date +%s%N | sha256sum | head -c 4)

Gap ID format: GAP-{NNN}-{SESSION_HASH} (e.g., GAP-005-a3f2). The session hash ensures that concurrent /ride --with-gaps sessions produce unique IDs even if they read the same highest NNN value before either writes. Existing GAP-NNN entries (without hash) remain valid — the numeric extraction regex accepts both formats.

12.2 Collect Gap Sources

Scan the following ride artifacts for unknowns, unresolved items, and missing context:

For each identified gap, assign:

• Type: Fact | Data | Interview | Context | Technical
• Priority: P0 (blocks agent work) | P1 (degrades agent quality) | P2 (nice to know)
• Source: Phase and artifact where gap was identified

12.3 Write Gap Tracker

Write grimoires/loa/gaps.md with the following schema. If the file already exists, append new gaps to the ## Open Gaps section — never overwrite or remove existing entries.

# Gap Tracker

> Auto-generated by /ride --with-gaps. Gaps are NEVER auto-resolved — only humans close them.
> Generated: YYYY-MM-DD

## Open Gaps

### GAP-NNN-HASH: [Short description]
- **Type**: Fact | Data | Interview | Context | Technical
- **Priority**: P0 | P1 | P2
- **Source**: /ride Phase N, [artifact or file:line]
- **Context**: Why this matters for agent work
- **Status**: OPEN
- **Opened**: YYYY-MM-DD
- **Resolution**: _pending human input_

## Resolved Gaps

_Gaps are moved here by humans only. Agents MUST NOT modify this section._

12.4 Gap Count Validation

Check gap counts against configured thresholds:

IF total_open_gaps >= GAP_MAX_OPEN:
  → Log ERROR to trajectory and NOTES.md:
    "Gap tracker has N open gaps (max: GAP_MAX_OPEN). Review and resolve gaps before adding more."
  → Still write the file, but add warning banner

ELSE IF total_open_gaps >= GAP_WARN_AT:
  → Log WARNING to trajectory:
    "Gap tracker approaching limit: N/GAP_MAX_OPEN open gaps"

12.5 File Persistence Checkpoint (CP-12)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/gaps.md.

After writing, verify with Glob pattern grimoires/loa/gaps.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 12, "action": "write_failed", "artifact": "gaps.md", "status": "error"}

Gap Tracker Rules

Log phase completion to trajectory:

{"phase": 12, "action": "gap_tracker", "status": "complete", "details": {"new_gaps": N, "total_open": N, "highest_id": "GAP-NNN-HASH", "session_hash": "HASH", "threshold_status": "ok|warning|exceeded"}}

Phase 13: Decision Archaeology (ENRICH_DECISIONS only)

Skip condition: If ENRICH_DECISIONS == false, skip this entire phase. Log skip to trajectory:

{"phase": 13, "action": "decision_archaeology", "status": "skipped", "details": {"reason": "ENRICH_DECISIONS not set"}}

13.1 ADR Directory Detection

Search for architectural decision records in these locations (in order):

Also check DECISIONEXTRAPATHS from config for additional search locations.

Log which directories were found:

{"phase": 13.1, "action": "adr_detection", "dirs_checked": 5, "dirs_found": ["docs/adr/"], "total_adrs": N}

13.2 ADR Parsing

For each .md file found in ADR directories, extract:

Heading matching: Case-insensitive. Accept both ## and ### heading levels. MADR variants (marked above) follow the Markdown Architectural Decision Records standard.

13.3 Staleness Computation

For each ADR with a detected date:

age_months = (current_date - adr_date) / 30
IF age_months > DECISION_STALE_MONTHS:
  → Mark as STALE with warning: "N months old, may not reflect current decisions"

13.4 Generate decisions.md

Write grimoires/loa/reality/decisions.md:

# Decision Archaeology

> Extracted from N ADR files across M directories.
> Decisions are claims — verify with HITL before treating as constraints.
> Generated: YYYY-MM-DD

## Active Decisions

### [ADR Title]
- **Status**: [Status] ([Date])
- **File**: [relative/path/to/adr.md]
- **Decision**: [Summary of decision]
- **Rejected**: [Alternatives that were NOT chosen]
- **Constraints for agents**: [What agents should NOT do based on this decision]
- **Reversal condition**: [If present — when to reconsider]

## Stale Decisions (>DECISION_STALE_MONTHS months, no reconfirmation)

### [ADR Title]
- **Status**: [Status] ([Date]) — ⚠️ N months old
- **File**: [relative/path/to/adr.md]
- **Staleness note**: May not reflect current architecture decisions. Recommend HITL reconfirmation.

13.5 No ADRs Found

If no ADR directories or files are found:

• If Phase 12 ran (gap tracker available): Create a gap entry:

`` GAP-NNN-HASH: No ADR/decision records found Type: Context Priority: P1 Source: /ride Phase 13, decision archaeology scan Context: Project has no documented architectural decisions. Future agents will lack trade-off context. ``

• If Phase 12 did NOT run: Log warning to trajectory and NOTES.md

13.6 File Persistence Checkpoint (CP-13)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/decisions.md.

After writing, verify with Glob pattern grimoires/loa/reality/decisions.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 13, "action": "write_failed", "artifact": "decisions.md", "status": "error"}

Log phase completion:

{"phase": 13, "action": "decision_archaeology", "status": "complete", "details": {"adr_dirs_found": N, "adrs_parsed": N, "active": N, "stale": N, "output": "grimoires/loa/reality/decisions.md"}}

Phase 14: Domain Terminology Extraction (ENRICH_TERMS only)

Skip condition: If ENRICH_TERMS == false, skip this entire phase. Log skip to trajectory:

{"phase": 14, "action": "terminology_extraction", "status": "skipped", "details": {"reason": "ENRICH_TERMS not set"}}

14.1 Term Extraction

Scan source code for domain-specific vocabulary from these categories (in priority order):

If tsconfig.json exists at the project root, include TypeScript-enhanced patterns (marked with † below). Otherwise, use base patterns only.

For each term found:

• Record the term name
• Record the source file and line (file:line)
• Extract contextual definition (from comment, type structure, or usage pattern)
• Track frequency (number of references across codebase)

14.2 Deduplication and Ranking

1. Deduplicate terms (case-insensitive match, keep casing from definition site)
2. Rank by frequency (most-referenced first)
3. Cap at TERMMAXTERMS (default: 50)
4. Group by domain (inferred from file path or module structure)

14.3 Generate terminology.md

Write grimoires/loa/reality/terminology.md:

# Domain Terminology

> Extracted from source code. N terms identified.
> Generated: YYYY-MM-DD

## [Domain Group 1]

| Term | Source | Context |
|------|--------|---------|
| `TermName` | path/to/file.ts:NN | Brief definition or usage context |

## [Domain Group 2]

| Term | Source | Context |
|------|--------|---------|
| `TermName` | path/to/file.ts:NN | Brief definition or usage context |

14.4 File Persistence Checkpoint (CP-14)

WRITE TO DISK: Use the Write tool to persist grimoires/loa/reality/terminology.md.

After writing, verify with Glob pattern grimoires/loa/reality/terminology.md — must return 1 match. If missing after Write, retry once. If still missing, log to trajectory:

{"phase": 14, "action": "write_failed", "artifact": "terminology.md", "status": "error"}

Log phase completion:

{"phase": 14, "action": "terminology_extraction", "status": "complete", "details": {"terms_extracted": N, "domains": N, "output": "grimoires/loa/reality/terminology.md"}}

Phase 15: Over-Engineering Audit + Shortcut Ledger (ENRICH_SIMPLICITY only)

Skip condition: If ENRICH_SIMPLICITY == false, skip this phase. Log skip to trajectory:

{"phase": 15, "action": "simplicity_audit", "status": "skipped", "details": {"reason": "ENRICH_SIMPLICITY not set"}}

The complexity-only counterpart to a security audit: a ranked, whole-repo over-engineering pass plus a dedicated loa:shortcut: debt ledger. Reports only, applies no fixes.

15.1 Over-engineering scan (ranked, biggest cut first)

Apply the reviewing-code over-engineering taxonomy (delete / stdlib / native / yagni / shrink) tree-wide instead of to a diff. Hunt: dependencies the stdlib or platform already ships, single-implementation interfaces, factories with one product, wrappers that only delegate, dead flags/config, hand-rolled stdlib. One line per finding, ranked biggest-cut first: <tag>: <what to cut>. <replacement>. [path:line]. End with net: -<N> lines, -<M> deps possible. Nothing to cut: Lean already. Ship.

15.2 loa:shortcut: debt ledger

Harvest deliberate-simplification markers (distinct from the generic TODO/FIXME tech-debt scan in the standard ride):

grep -rnE '(#|//|--) ?loa:shortcut:' . \
  --exclude-dir={.git,node_modules,dist,build} \
  > grimoires/loa/reality/shortcut-ledger.raw 2>/dev/null || true

One row per marker, grouped by file, parsing the loa:shortcut: <ceiling>, <upgrade> convention: <file>:<line> - <what was simplified>. ceiling: <limit>. upgrade: <trigger>. Any marker naming a ceiling with NO upgrade trigger gets a no-trigger tag, those rot silently. End with <N> markers, <M> no-trigger. None found: No loa:shortcut: debt. Clean ledger.

15.3 Write the report

Write both sections to grimoires/loa/reality/over-engineering.md (ranked findings, then ledger). Log completion:

{"phase": 15, "action": "simplicity_audit", "status": "complete", "details": {"findings": N, "net_lines": -N, "markers": N, "no_trigger": N, "output": "grimoires/loa/reality/over-engineering.md"}}

Uncertainty Protocol

If code behavior is ambiguous:

1. State: "I'm uncertain about [specific aspect]"
2. Quote the ambiguous code with file:line
3. List possible interpretations
4. Ask for clarification via AskUserQuestion
5. Log uncertainty in NOTES.md

Never assume. Always ground in evidence.

Trajectory Logging (MANDATORY)

YOU MUST LOG EACH PHASE to grimoires/loa/a2a/trajectory/riding-{date}.jsonl.

Log Format

Each phase appends a JSON line:

{"timestamp": "ISO8601", "agent": "riding-codebase", "phase": N, "action": "phase_name", "status": "complete", "details": {...}}

Phase-Specific Details