State Management

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.

Overview

Getting Started

Core Concepts

The Pipeline

Business Hub

Adapters

Security & Compliance

Roadmap & Research

Run state directory

Registry files

Spec artifacts

Traceability

Approvals

Events log

Evidence ledger

Metrics

Stage checkpoints

Memory

Project-local overrides

​Run state directory

​Registry files

​Spec artifacts

​Traceability

​Approvals

​Events log

​Evidence ledger

​Metrics

​Stage checkpoints

​Memory

​Project-local overrides

Run state directory

Registry files

Spec artifacts

Traceability

Approvals

Events log

Evidence ledger

Metrics

Stage checkpoints

Memory

Project-local overrides