State Management

How RStack stores and manages run state, specs, and traceability.

Run state directory

Every RStack run creates a versioned directory under .rstack/runs/:

.rstack/
  memory/
    learnings.jsonl           # Manual cross-run learnings (sdlc_memory append)
    <project-slug>/
      episodes.jsonl          # Validator-gated episodic memory (BFT signed)
  registry/
    registry.json
    agents.json
    skills.json
    plugins.json
    routing.json
  runs/
    <run_id>/
      manifest.json           # Run metadata, status, mode, rstack_version
      context.md              # Goal + clarification answers
      plan.md
      tasks.json
      approvals.json
      traceability.json
      events.jsonl            # Append-only tool call/result log
      evidence.jsonl          # Append-only validator-grounded evidence ledger
      metrics.json            # Cumulative cost, duration, tool calls per stage
      dashboard.html          # Generated by sdlc_dashboard
      artifacts/
        stages/
          00-environment/     # One folder per canonical stage
          01-transcript/
          ...
      checkpoints/
        00-environment/       # Snapshot for sdlc_rollback
        01-transcript/
        ...
      tasks/
        <task_id>/
          prompt.md
          builder.json
          validation.json

Runs are isolated from each other. Previous runs are never modified.

Registry files

The registry is generated on demand and indexes all available assets:

File	Contents
registry.json	Full combined manifest of all assets
agents.json	All agents with role, domain, and tools
skills.json	All skills with tags and location
plugins.json	All plugin packs with domain mapping
routing.json	Pipeline-stage-to-agent routing map

Generate or refresh the registry:

rstack-agents validate

Spec artifacts

RStack generates first-class spec files — not just task JSON:

specs/
  product-brief.md         ← Goal, context, constraints
  requirements.json        ← Functional and non-functional requirements
  architecture.md          ← System design and implementation plan
  implementation-report.json
  qa-report.json
  security-review.md
  handoff.md
  release-readiness.json

Traceability

traceability.json maps every requirement through the entire lifecycle:

{
  "requirement_id": "REQ-001",
  "description": "Users can authenticate with email/password",
  "design_decision": "JWT with 24h expiry, refresh tokens",
  "tasks": ["task_003", "task_004"],
  "files_changed": ["src/auth.js", "tests/auth.test.js"],
  "tests": ["tests/auth.test.js#L45"],
  "validation_evidence": "tasks/task_003/validation.json"
}

This makes it possible to audit: “Was this requirement actually implemented and tested?”

Approvals

approvals.json records explicit human decisions:

{
  "approvals": [
    {
      "artifact": "plan.md",
      "status": "APPROVED",
      "timestamp": "2024-05-25T10:30:00Z",
      "run_id": "run_20240525_001"
    },
    {
      "artifact": "architecture.md",
      "status": "APPROVED",
      "timestamp": "2024-05-25T11:00:00Z",
      "run_id": "run_20240525_001"
    }
  ]
}

Events log

events.jsonl is an append-only log of every lifecycle event:

{"type":"run_start","timestamp":"...","goal":"..."}
{"type":"plan_created","timestamp":"...","task_count":8}
{"type":"approval","artifact":"plan.md","status":"APPROVED","timestamp":"..."}
{"type":"task_start","task_id":"task_001","timestamp":"..."}
{"type":"tool_call","tool":"write","path":"src/auth.js","timestamp":"..."}
{"type":"task_complete","task_id":"task_001","timestamp":"..."}

Evidence ledger

evidence.jsonl is a separate append-only file that records only validator-approved task results. Unlike events.jsonl (which logs everything), evidence.jsonl is a compliance-grade ledger — every entry requires task_id, kind, status, and an evidence path:

{"ts":"2024-05-25T10:30:00Z","task_id":"003-architecture","kind":"validation","status":"PASS","evidence":"tasks/003-architecture/validation.json"}
{"ts":"2024-05-25T11:15:00Z","task_id":"004-implementation","kind":"validation","status":"PASS","evidence":"tasks/004-implementation/validation.json"}

Metrics

metrics.json tracks cumulative run-level metrics updated after each task:

{
  "cumulative_duration_ms": 14250,
  "cumulative_cost_usd": 0.0082,
  "cumulative_tool_calls": 23,
  "stage_elapsed_ms": { "00-environment": 1200, "01-transcript": 890 },
  "stage_status": { "00-environment": "PASS", "01-transcript": "PASS" }
}

Used by sdlc_dashboard to populate the live metrics panels.

Stage checkpoints

After each successful sdlc_validate, RStack snapshots the stage artifact directory to checkpoints/<stage-id>/. This enables point-in-time rollback without losing prior work:

sdlc_rollback(stage_id="06-architecture")

Rollback restores the checkpoint copy over the live stage directory and appends a stage_checkpoint_reverted event to events.jsonl. If no checkpoint exists, the tool returns NO_CHECKPOINT and makes no changes.

Memory

learnings.jsonl accumulates cross-run learnings. Each entry is one learning:

{"run_id":"run_001","learning":"JWT refresh tokens must be stored in httpOnly cookies, not localStorage","timestamp":"..."}
{"run_id":"run_001","learning":"Always run npm audit before release","timestamp":"..."}

Future runs can search learnings with sdlc_memory() before planning to avoid repeating mistakes.

Project-local overrides

Projects can extend or override package defaults without forking:

# Agent overrides
.rstack/agents/my-custom-builder.md
.pi/rstack/agents/my-custom-builder.md

# Skill overrides
.rstack/skills/my-skill/SKILL.md

# Plugin overrides
.rstack/plugins/my-plugin/plugin.json

# Prompt overrides
.rstack/prompts/my-workflow.md

Local files take precedence over the package defaults. The registry picks them up automatically on the next rstack-agents validate run.