RAC v0.19.0 — the "kitchen sink" release

Everything since the last time the changelog was dated lands at once. Over this stretch RAC stopped being a requirements linter and became a place your product knowledge lives - browsable, addressable, graph-checked, and enforceable in CI. This release collects the whole arc into one formal cut.

pip install --upgrade requirements-as-code

Why "kitchen sink"

The changelog hadn't carried a dated release since v0.7.3. The work didn't stop, I just focused on building so it just piled into one long Unreleased block while the shape of the tool changed underneath it. Rather than pretend each piece shipped on its own quiet day, this release names the pile for what it is and dates it. The (vX.Y.Z) marker on each changelog line still tells you exactly where a capability landed.

A place to look

The Explorer is an interactive terminal UI over your corpus — artifacts in a sidebar by title (not opaque IDs), validation status as chips (✓ Valid, ! Warning, ✗ Error), and a / command palette instead of a persistent command bar.

pip install "requirements-as-code[explorer]"
rac explorer

Identity that survives a rename

Artifacts now carry canonical YAML frontmatter - a schema_version, a system-assigned opaque id (RAC-01JY4M8X2QZ7), and a type - minted by rac new and stable across renames, moves, and type changes. Your human-readable references keep resolving through legacy aliases, so nothing breaks on the way in.

rac find "telemetry"     # search by id, title, filename, or path
rac resolve RAC-…        # id → type, title, path (duplicates reported, never guessed)
rac migrate metadata .   # adopt canonical identity, idempotent and byte-preserving

The corpus is a graph now

rac relationships --validate stopped being a reference checker and became a graph checker. It reports a ## Related <Type> link that resolves to the wrong artifact type, a section an artifact's type doesn't even support (instead of silently dropping it), a cycle in supersedes, and anything live still pointing at a retired artifact.

rac relationships . --validate

One screen of repository intelligence

rac portfolio gives you counts by type, validity, completeness, relationship coverage, an attention list, and a health score — the whole repository at a glance. rac review turns that into a prioritized worklist (invalid first, then broken relationships, then advisory), and rac watchkeeper reviews what changed in product knowledge between two repository states.

rac portfolio
rac review .

Standards, checked - not just structure

Validation now lints requirement quality against the standards RAC cites: BCP-14 keyword discipline (only uppercase MUST/SHALL/SHOULD/MAY are normative), ISO 29148 singularity, and EARS clause shape - all deterministic, no AI in the core. New to a legacy repo? A validation section in .rac/config.yaml downgrades any finding to a warning, repository-wide, so you can keep CI green and tighten the gate over time.

It travels

The corpus exports as a deterministic JSON payload, a self-contained HTML Portal you can hand to anyone, an OKF v0.1 bundle (RAC repos are conformant Open Knowledge Format bundles), and SARIF 2.1.0 for GitHub Code Scanning.

rac export . --html      # self-contained portal
rac export . --okf       # OKF v0.1 bundle
rac validate . --sarif   # SARIF for code scanning

It meets you in CI

A composite GitHub Action runs rac validate --sarif and annotates pull requests inline through Code Scanning and errors fail the check, warnings annotate without failing. A second action brings rac watchkeeper to PRs. Both are thin wrappers over the CLI (ADR-058): no logic lives in the action that doesn't live in the tool.

Roadmaps can be done

The headline for v0.19.0 itself: a roadmap whose scope has shipped can declare ## Status: Achieved — a validated live terminal state (ADR-061). The intent was delivered, so the roadmap reads as done, but it isn't treated as retired, and inbound references to it still resolve.

Already in your hands

This release also carries the "count me in" telemetry from v0.10.6 (rac telemetry on — three anonymous facts, nothing without consent) and the bundled Claude Code skills and git hooks (rac skill, rac hook).

Upgrading

pip install --upgrade requirements-as-code

uv tool upgrade requirements-as-code

Everything is additive. Existing commands, JSON contracts, and exit codes work as before; the new identity frontmatter is optional and recognized artifacts without it are still fully supported. If you've been on v0.10.6, this is the catch-up release — most of the arc above is new to you in one step.

RAC v0.10.6 - the "count me in" release

The "count me in" release - if you want Lore to keep getting better, you can now say so in one word, and we learn exactly three things: you exist, what version you run, and how many repositories you're grounding. Nothing else, and nothing at all unless you ask.

pip install --upgrade requirements-as-code
rac telemetry on

One honest question

v0.10.5 gave you telemetry you could read before you share it - a local log and a prefilled GitHub issue you submit yourself. That works while we can talk to every user individually. It doesn't tell us the thing that decides where the next month of work goes: do installs come back?

So this release asks. Once, plainly, at the moment you set up a repository:

$ rac init
Initialized repository (key: PROJ).

Share anonymous usage to help shape Lore? [y/N]

Default is No. Empty answer is No. Not a real terminal — CI, pipes, --json — and the question never appears. Either answer is persisted, so you're asked at most once per machine. Change your mind any time:

rac telemetry status   # exactly what is shared, and whether sending is even possible
rac telemetry on       # opt in
rac telemetry off      # opt out

The entire transmission, verbatim

With consent on, rac mcp sends at most one ping per 24 hours. This is the whole thing - not a sample, the complete payload:

{
  "api_key": "phc_…",
  "event": "lore-daily-ping",
  "timestamp": "2026-06-12T20:37:04Z",
  "properties": {
    "distinct_id": "cd03eed3dd98b784834485e27a436914",
    "$process_person_profile": false,
    "schema_version": "1",
    "rac_version": "0.10.6",
    "active_repos": 2
  }
}

What the fields are: the install id is a random token minted when you opt in — derived from nothing, so it identifies nothing (we deliberately rejected hashing machine attributes: derivable is the opposite of anonymous). active_repos is a count of distinct repositories Lore served in the last 30 days, tracked locally as salted digests — the salt never leaves your machine, only the integer does. $process_person_profile: false tells the sink to create no person profile, so the event stays anonymous on the receiving side too.

What is never sent, under any setting: paths, queries, tool arguments, artifact text, or a single byte of your repository's content. Adding any field to this payload requires a new recorded decision (ADR-041, the way decisions are recorded here) — and the test suite pins the exact key set, so it can't drift in quietly.

Trust, enforced rather than promised

The v0.10.5 notes said "RAC still contains no network code." That sentence is retired honestly, not eroded - ADR-041 amends it on the record, and the replacement claim is one the code enforces:

• The network surface of RAC is one readable file (rac/mcp/ping.py). A test fails the build if any other module imports a network client - "what does this tool phone home" is answerable by reading one page of source.
• Sharing is never silent. When it's on, the server says so on stderr at startup, names what's sent, and tells you how to turn it off.
• It can never get in your way. The ping is fire-and-forget: three-second timeout, failures dropped without retries, and tool responses are byte-identical with sharing on or off.
• Two switches, not one. Remote sharing is independent of the local --telemetry log - each is its own opt-in, and neither implies the other.

Upgrading

pip install --upgrade requirements-as-code

uv tool upgrade requirements-as-code

Everything is additive: one new command (rac telemetry) and one one-time question at rac init on a real terminal — the first interactive prompt this CLI has ever had, which is itself recorded in ADR-041. Every existing command, file, JSON contract, and exit code works exactly as in v0.10.5, and without consent (the default), nothing is ever sent — behaviour is byte-for-byte what it was before.

RAC v0.10.5 - the "batteries included" release

The "batteries included" release — the package now carries the agent skills to work a RAC repository properly, installable into any project from the wheel alone. No repository checkout, no network, no AI. And the server your agent talks to now goes by the product's name: lore.

pip install --upgrade requirements-as-code
rac skill install
claude mcp add lore -- rac mcp

Your agent's working habits, in the box

Lore taught your agent to read recorded knowledge. These skills teach it to work on it. Three Claude Code skills now ship inside the package itself:

• rac-artifacts — author and maintain RAC artifacts with the CLI: the right command, the right template, IDs minted properly
• rac-review — work rac review findings worst-first until validation passes, instead of fixing whatever is nearest
• rac-ingest — convert DOCX, PDF, HTML, PPTX, XLSX, or Markdown documents into valid, linked artifacts

rac skill install              # all three, into .claude/skills/
rac skill install rac-review   # one by name
rac skill list                 # what is bundled

Install never overwrites: if any target file already exists, the no-arg install refuses and writes nothing — the named form is the additive path.

Why you care: the workflow this repository uses to maintain its own corpus is now a one-command install in yours — straight from the wheel, so it works offline and in CI. And because the skills are package resources, the copy you install is the copy we dogfood: each bundled skill is kept byte-identical to this repository's own by test, and the rac skill output — human and --json — is pinned by golden tests like every other contract.

The server is named lore

v0.10.3 shipped the MCP server under the label rac-guide — an internal codename that leaked into the most visible seam of the product. As of this release the agent-facing identity is lore: the config key in every documented block, the name the server reports to your client, and the namespace your agent's tool calls appear under (recorded as ADR-039, the way decisions are recorded here).

What this is not: a rename of anything you script against. The command is still rac mcp, the package is still requirements-as-code, and the four tools and every response contract are byte-for-byte unchanged. Already configured rac-guide? It keeps working — re-add as lore when convenient:

claude mcp remove rac-guide
claude mcp add lore -- rac mcp --root /path/to/your/repo

This release also carries the assets for the official MCP registry — a server.json declaring io.github.tcballard/lore and the ownership marker the registry validates. Look for the listing under that name.

Telemetry you can read before you share it

Want to tell us how the server is actually used? Now you can — on your terms:

rac mcp --telemetry    # off by default
rac mcp-stats          # summarise the local log
rac mcp-stats --share  # prefilled usage-report issue URL — you review it, you submit it

What it records: tool-call counts and metadata (timestamps, durations, outcomes). What it never records: arguments, queries, or a single byte of your repository's content. The log is a local file you can open, the server announces the log path on stderr so enablement is never silent, and tool responses are byte-identical with telemetry on or off. RAC still contains no network code — the only way data leaves your machine is you reading a URL and clicking it.

Also in this release (since v0.10.3)

• The growth plan is now a corpus. The repository's own forward plan lives as RAC artifacts — seven requirements, two designs, an umbrella roadmap — queryable the same way every other decision here is.
• "How this relates to spec-driven development" — a new README section placing RAC against the tools you already know, every comparison claim cited to the named tool's own documentation.
• docs/ecosystem.md seeds the ecosystem reading list, and a consolidated traceability gap report captures real authoring friction as recorded findings rather than folklore.
• The banner renders on PyPI now (image URLs are absolute), and Python-version and license badges join the README.
• This repository grounds its own agents: a checked-in .mcp.json serves the dogfood corpus through lore, per the team setup in docs/mcp.md.

Full details: CHANGELOG.md and #73.

Upgrading

pip install --upgrade requirements-as-code

uv tool upgrade requirements-as-code

Everything is additive: new commands (rac skill, rac mcp-stats), one new opt-in flag (rac mcp --telemetry), and the server's new name. Every existing command, file, JSON contract, and exit code works exactly as in v0.10.3 — and with telemetry off (the default), the server's behaviour is byte-for-byte what it was before.

RAC v0.10.3 - the "meet Lore" release

The "meet Lore" release — your coding agent now reads the decisions your team already made, and cites them instead of violating them. Deterministic. Read-only. No RAG, no guessing.

pip install --upgrade requirements-as-code
claude mcp add rac-guide -- rac mcp

Your agent reintroduces an approach you rejected months ago. It rebuilds something you deliberately removed. The decision was written down — in an ADR nobody, human or agent, ever reopened. Lore fixes that: RAC now ships an MCP server that serves your requirements, decisions, designs, and roadmaps to Claude Code, Claude Desktop, and Cursor — mid-task, at the moment they matter.

Your agent, grounded

rac mcp starts a server from any RAC repository — no flags, no daemon, no account. Your agent client spawns it and gets four read-only tools:

• search_artifacts — find the decisions that cover what it's about to build
• get_artifact — read one artifact by any ID it encounters
• get_related — what connects to it, in both directions
• get_summary — what recorded knowledge exists at all

Nothing tells the agent to look. The tool descriptions name the moment ("call this before designing or implementing…"), and the agent reaches for your decisions on its own — then cites them by ID.

Why you care: you write the decision once, in Markdown, in your repo. Every agent session from then on respects it — and when one of its proposals conflicts with a recorded decision, you hear about the conflict instead of shipping it.

One config block per client, verified walkthroughs, and troubleshooting live in docs/mcp.md.

Honest answers, by construction

Everything the server tells your agent is reproducible:

• Read-only by construction. The server cannot create, modify, or delete files — enforced in code and pinned by tests, not promised by convention.
• Never stale. Every tool call re-reads the repository, so the agent can't act on a decision it just changed.
• Never floods the context. Responses are capped (10,000 characters), truncated at whole-item boundaries, and always say what was omitted and how to narrow.
• Fails as data. A missing or ambiguous ID comes back as a structured answer the agent can recover from — never a protocol error.

Search that finds the decision, not the noise

Search — rac find and search_artifacts alike — got two upgrades:

• Token-boundary matching. Queries match whole words and prefixes, not raw substrings: lore no longer matches every artifact with "Explorer" in its path, while relation still finds relationships.
• Body text counts now. A decision whose body settles your question is found even when its title doesn't carry the keyword — and the match arrives with a snippet (the matching line and its section), so the agent can judge relevance without opening every candidate.

Heads up — this is a behavior change: search results differ from earlier versions wherever substring matching produced mid-word hits, and an empty or punctuation-only query now returns no matches instead of everything. Ranking stays deterministic and explainable: ID, then title, then path, then heading, then body.

Try it without writing a thing

A complete worked corpus ships in examples/guide/: a true-to-life soft-delete decision, its connected requirement, design, and roadmap, plus a small code task whose obvious implementation violates the decision. demo.md scripts the whole contrast — the same prompt with and without Lore — so you can watch an agent violate the decision, then cite and respect it.

Also in this release (since v0.8.11)

• Zero-flag startup that fails helpfully: pointing rac mcp at an empty directory starts the server, says so on stderr, and get_summary reports the empty state — the first run is the one most likely to be misconfigured.
• Team setup via CLAUDE.md routing: record your agent guidance as a validated RAC prompt artifact and @import it — the instructions for using your knowledge become governed knowledge themselves (docs/mcp.md §6).
• A new README that leads with what this is for — and with Lore, the product name for the grounding experience, built on RAC underneath (recorded as ADR-036, like every other decision here).
• rac find shows snippets under body-matched results, the same ones the agent sees.

Upgrading

pip install --upgrade requirements-as-code

uv tool upgrade requirements-as-code

The MCP server is a standard part of the package — no extra to install (the upgrade pulls one new dependency, the official mcp SDK). Every existing command, file, JSON contract, and exit code keeps working exactly as before, with one announced exception: search matching semantics changed as described above. Search JSON gains optional section/snippet fields on body-matched entries only; all other entries are byte-identical to before.

RAC v0.8.11 - the "why it matters" release

The "why it matters" release - every finding RAC reports now carries the reason it matters, in every place you might read it. And new users get their editor sorted in the first minute.

pip install --upgrade 'requirements-as-code[explorer]'
rac explorer

Every finding explains itself, everywhere

Explorer's recommendations have always told you why a finding matters - "a declared reference does not resolve, leaving traceability incomplete" - but that explanation lived only in Explorer. Run rac review --json in CI and you got the finding without the why.

Now the impact sentence belongs to RAC itself. Every finding from rac review carries an impact field - in the JSON, available to your scripts and pipelines, and rendered in Explorer from the very same source. One sentence, identical everywhere, maintained in one place.

Why you care: if you pipe rac review --json into a dashboard, a bot, or a PR comment, you can now show your team why each finding deserves attention - not just that it exists. And the addition is purely additive: every existing field is untouched, so nothing you've built on the contract changes.

Your editor, from the first minute

e has always handed an artifact to your own editor. New in this release: the first time you launch Explorer, onboarding asks. One line, prefilled from your environment - press Enter to keep what $VISUAL/$EDITOR already says, type a command (code, vim, whatever you use) to set a preference, or Esc to skip entirely. Asked once, never again; /settings can change it any time.

Also in this release (since v0.8.9)

This tag carries v0.8.10, and it's a substantial one:

• The sidebar tells the truth (v0.8.10): by default it now mirrors your repository's actual directory structure - roadmaps/ opens to reveal the folders inside it, nested exactly as on disk, with artifact counts on every directory. Your place survives reloads at any depth, and opening an artifact reveals it along its real path. Prefer the old views? Grouping cycles folders, type, and flat in /settings.
• Create without leaving (v0.8.10): /new decision path/to/adr.md previews the canonical template, y confirms, and the ID is minted by the same machinery as rac new - nothing ever overwrites, and the new artifact opens ready for e.
• The portfolio in numbers (v0.8.10): /stats opens a dashboard - per-type validity, requirement and quality totals, decision status breakdowns, relationship counts - the same facts rac stats reports.
• Browsing by type got better (v0.8.10): /browse decision now lists every decision in the filterable results panel, whatever grouping the sidebar is in.

Upgrading

With pip:

pip install --upgrade 'requirements-as-code[explorer]'
rac explorer

With uv:

uv tool upgrade requirements-as-code
rac explorer

(First time with uv, or if the upgrade can't see the new version yet: uv tool install --reinstall --refresh 'requirements-as-code[explorer]'.)

Everything is backward-compatible: existing files, commands, scripts, and preference files keep working exactly as before. The rac review --json change is additive - new impact key, same schema_version, no existing field touched.

RAC v0.8.9 - the "live workspace" release

The "live workspace" release - save a file in your editor and Explorer already knows. The gap between editing your knowledge base and seeing it is gone.

pip install --upgrade 'requirements-as-code[explorer]'
rac explorer

v0.8.6 gave your knowledge base a home. v0.8.9 makes that home live: Explorer now watches the repository while you work, invalid artifacts explain themselves on the spot, and the suggestions don't just say what's missing - they tell you what to write.

Your edits show up by themselves

The RAC loop has always been: edit Markdown in your editor, check it in the tool. Until now there was a keystroke in the middle of that loop. Not anymore - Explorer notices when artifacts change on disk and refreshes itself: the document you're reading, the sidebar, the health score, all current within a couple of seconds. Your place is kept - same artifact, same tab, same scroll position.

It's careful about it, too. The check is just file names and timestamps - nothing is re-read until something actually changed. Press e, edit in Vim, save, quit - the moment Explorer comes back, the edit is on screen.

Why you care: keep Explorer open in a split pane while you write, and it becomes a live review of your work - health score and all - with zero keystrokes spent asking for it.

Invalid artifacts explain themselves

Before: the health view told you an artifact was invalid, and then you went to the CLI to find out why. Now selecting an attention item lands you on that artifact's Inspection tab, where the actual reasons are listed - the same issues rac validate reports. The tab even carries a count badge, so you know there's something to read before you open it.

Suggestions that tell you what to write

An artifact's Findings tab now includes improvement suggestions: one per missing section, each with the schema's own guidance question as the suggested action. Not "add a Risks section" but the question that section is meant to answer. Explorer shows the suggestions; your files stay yours - it never writes a word of them.

Ask the schema, not the docs

"What sections does a decision need?" is now a palette question. /schema lists every artifact type; /schema decision lays out the required, recommended, and optional sections with their descriptions - the same facts rac schema reports, without leaving the screen.

The palette remembers

Tap / and, before you type a single character, the artifacts you've been working in are right there - Enter reopens the most recent. And when a search comes back broad, f narrows the results by type: all, then each type present, then back to all.

Also in this release (since v0.8.6)

This tag carries the two unreleased versions in between, and they're big ones:

• One persistent workspace (v0.8.7): a navigation sidebar of type-tagged artifacts, a context panel that swaps views in place, and a status line that always shows the keys that matter - no screen jumps, ever. Plus the rac-lantern theme, drawn from the mascot's palette.
• Read documents where they live (v0.8.7-v0.8.8): opening an artifact shows the document itself, rendered and scrollable, with the references inside it walkable like a wiki - and Esc retraces your steps.
• A summoned command palette (v0.8.8): / floats an input with live suggestions - empty teaches every command, a prefix completes it, anything else quick-opens matching artifacts.
• Settings you can touch (v0.8.8): /settings changes theme (live preview), mascot, animations, grouping, and your default editor in place - terminal editors like Vim now run with Explorer suspended and resume it on exit.

Upgrading

pip install --upgrade 'requirements-as-code[explorer]'
rac explorer

All your existing files, commands, and scripts keep working exactly as before - and the preferences and workspace files written by earlier versions load unchanged.

RAC v0.8.6 - the "meet Explorer" release

The "meet Explorer" release — see your whole knowledge base, understand how it connects, and fix what's wrong, all without leaving the terminal.

pip install 'requirements-as-code[explorer]'
rac explorer

RAC has always treated the product docs you already write in Markdown - requirements, decisions, roadmaps, prompts, designs - as a knowledge base. Until now you worked with it one command at a time. Explorer gives that knowledge base a home: an interactive screen you open in your terminal and move through like a workspace. Press / and ask for anything.

See everything, without hunting through folders

Open Explorer in any repository and you get the whole picture at once: every artifact, grouped by type, with the repository's health and what needs attention up front. Pick any one to see it in full - its details, whether it's valid, what it links to, and anything wrong with it. First time in a repo? Explorer shows you around. Coming back? It drops you right back where you left off.

Press / for anything

No commands to memorize. Tap / and start typing - search and actions share one box:

/health             how healthy is this repository?
/find checkout      search by title, ID, or keyword
/open ACME-01JY...  jump straight to an artifact
/import notes.docx  bring an outside document in

Type a name and it searches; type a command and it runs. You don't have to decide which - Explorer figures out what you mean.

Know what needs attention

/health (or just h) reads the repository at a glance: an overall score, broken down into completeness, relationships, validation, and coverage, plus a ranked list of what to look at. Every item on that list is live - select it and you land on the exact artifact it's about.

Understand how it all connects

Product knowledge is a web, not a list. From any artifact you can see what it links to, what depends on it, and how it evolved. Step from one artifact to the next and follow the thread across your whole repository.

Why you care: before you change a decision, you can answer "what's affected if I do this?" in a couple of keystrokes - instead of guessing, or finding out later.

Get from "something's wrong" to "fixed"

Explorer doesn't just point at problems - it helps you act on them. Each recommendation explains what's wrong, why it matters, and what to do about it. When you're ready to edit, one key opens the artifact in your own editor - VS Code, Cursor, Vim, whatever you use. Bringing in an outside document? /import converts it and shows you exactly what it will add before anything is written. Explorer never changes your files without showing you first.

Make it yours

Explorer remembers the repositories you've opened and the last thing you were looking at, so returning is one keystroke. Set a theme, switch the mascot on or off - it's a small preferences file, no account, no cloud, nothing to sign into. (Yes, there's a mascot: a little lantern-carrying explorer. You can turn it off.)

Built to stay out of your way

Everything works from the keyboard - no mouse, happy over SSH, readable in any terminal, and nothing depends on color. And everything Explorer shows you is still available as a plain command, so your scripts and CI keep working exactly as before.

Also in this release (since v0.7.3)

Upgrading from the last published version brings everything from the releases in between, too: start new artifacts from built-in templates (rac new), permanent IDs that survive renames and moves, search and lookup (rac find, rac resolve), whole-repository checks (rac validate docs/ and rac review docs/), and a one-command upgrade for existing repos (rac migrate metadata).

Upgrading

Explorer is an optional add-on, so nothing changes unless you opt in:

pip install --upgrade 'requirements-as-code[explorer]'
rac explorer

Already using RAC? All your existing files, commands, and scripts keep working exactly as before.

v0.7.13 - your repository, organized

The "your repository, organized" release - and the first release on PyPI since v0.7.3.

pip install requirements-as-code

RAC turns the product documents you already write in Markdown - requirements, decisions,
roadmaps, prompts, designs - into a knowledge base your whole team (and your tooling) can
trust. This release is about three things: making artifacts easier to create, giving
them an identity that doesn't break, and letting you find anything without digging
through folders.

Start a new artifact in seconds

No more copying an old file and gutting it. RAC now ships the canonical structure for
every artifact type:

rac new decision docs/decisions/use-postgres.md

You get a ready-to-edit document with the right sections in the right order - fill in the
TODOs and it passes validation. rac templates lists what's available. No AI, no
internet, no surprises: the same command always produces the same structure, and it will
never overwrite a file you already have.

Artifacts now have permanent IDs

Rename a file, move it to another folder, even reclassify it - its identity stays put.
Run rac init once to pick your repository's prefix (say, ACME), and every artifact RAC
creates gets a permanent ID like ACME-01JY4M8X2QZ7, stored in a small metadata header at
the top of the file.

Why you care: references between documents stop rotting. A decision that links to a
requirement keeps pointing at it through every reorg. And nothing about your existing
documents breaks - files without the header keep working exactly as before, and old-style
references (like ADR-015) still resolve.

Already have a repository full of artifacts? One command upgrades them:

rac migrate metadata docs/ --dry-run   # see what would change
rac migrate metadata docs/             # do it

It only adds the header - your words are untouched, byte for byte. Run it as many times as
you like; it never touches a file twice, and it tells you which documents it couldn't
recognize so you can fix them and re-run.

Find anything

Stop grepping. Ask:

rac find onboarding              # search by title, ID, or filename
rac find checkout --type decision
rac resolve ACME-01JY4M8X2QZ7    # what is this ID? → type, title, location
rac index                        # the full inventory of every artifact

Relationship listings now speak human, too - instead of a bare ID, you see
"Markdown Is the Canonical Source Format (decision)".

Review the whole repository at once

• rac validate docs/ — check every artifact in one pass; one command, one exit code,
  CI-ready.
• rac review docs/ — a prioritized worklist: what's invalid, what's broken, what to fix
  first, with a suggested action for each finding.

A more trustworthy project

• Proper documentation under docs/ (quickstart, CLI reference, guides) and a README you
  can read in a minute.
• A CHANGELOG, contribution guide, and CI that runs RAC against RAC's own planning
  documents on every change - we manage this project with the tool itself, IDs and all.
• Every command's output (human and JSON) is pinned by tests, so the contracts your
  scripts depend on don't drift silently.

Upgrading from v0.7.3

Everything is additive - your existing files and scripts keep working. To adopt the new
identity features in an existing repository:

pip install --upgrade requirements-as-code
rac init                      # pick your repository prefix
rac migrate metadata docs/    # give existing artifacts their IDs

RAC v0.7.3 - Intelligence Summary

RAC v0.7.3 brings artifact, validation, and relationship insights together into a single repository-level view.

RAC can now answer:

What is the state of this product knowledge repository?

---

Added

Repository Summary

A new repository intelligence layer combines:

• Artifact coverage
• Relationship health
• Validation results
• Attention items

providing a single view of repository quality.

---

Repository Health

RAC now reports overall repository health.

Health considers:

• Artifact completeness
• Validation issues
• Relationship integrity

The score is calculated by RAC Core and exposed consistently to all consumers.

---

Attention Items

RAC highlights areas requiring attention:

Missing artifact sections

Broken relationships

Validation issues

Helping teams understand where product knowledge needs improvement.

---

Machine-Readable Output

Repository intelligence supports structured output for:

• Automation
• CI workflows
• Future RAC Explorer integration

---

Principles

Repository intelligence remains:

• Deterministic
• Read-only
• Markdown-first
• Owned by RAC Core

---

What's Next

v0.7.4 introduces the Repository Index:

What artifacts exist, and where are they?

providing the navigation foundation for future RAC interfaces.

RAC v0.7.2 - Relationship Validation

Previous releases allowed RAC repositories to describe how product knowledge connects. v0.7.2 answers the next question:

Are those connections actually valid?

RAC can now verify relationships across a repository, detecting broken references before they become stale documentation.

---

Added

Relationship Validation

The existing relationships command can now validate declared references:

rac relationships . --validate

RAC resolves artifact references such as:

REQ-001
ADR-004
ROADMAP-Q3

against artifacts in the repository.

---

Broken Reference Detection

Detect relationships pointing to missing artifacts.

Example:

## Related Decisions

- ADR-999

Output:

✗ ADR-999 not found

---

Duplicate Identifier Detection

RAC now detects ambiguous artifact identities.

Example:

adr-004.md

adr-004-alternative.md

Rather than guessing, RAC reports the conflict.

Product knowledge should be explicit.

---

Self Reference Detection

Detect artifacts that incorrectly reference themselves.

Example:

ADR-004

supersedes → ADR-004

---

Added JSON Support

Relationship validation supports structured output:

rac relationships . --validate --json

Designed for:

• CI checks
• Automation
• Future RAC Explorer integration

---

Improved

Deterministic Artifact Resolution

Relationships are resolved using predictable identifiers:

1. Explicit artifact ID
2. Artifact schema identifier
3. Filename identifier prefix
4. Filename

Matching is case-insensitive.

No AI.

No guessing.

---

Unknown Artifact Handling

Unknown files are handled safely.

They can exist in repositories without breaking validation.

---

Principles

Relationship validation is:

• Read-only
• Deterministic
• File-first
• Markdown-native

RAC validates what you declared.

It does not infer what you meant.

---

Upgrade Notes

No migration required.

Existing RAC repositories continue to work unchanged.

Relationship validation is optional.

---

Repository Intelligence Milestone

v0.7.x now allows RAC to answer:

v0.7.0

What relationships are declared?


v0.7.1

What relationships exist?


v0.7.2

Are relationships valid?

RAC repositories are no longer collections of documents.

They are connected product knowledge systems.

---

What's Next

v0.7.3 builds on this foundation with repository intelligence summaries:

What is the overall state of this product knowledge repository?

combining artifacts, relationships, validation, and health into a single view.