User-visible changes to RAC, by release. Follows the spirit of Keep a Changelog: user impact over implementation details, release history over commit history.
-
Opt-in Guide telemetry (v0.10.4):
rac mcp --telemetryrecords tool-call counts and metadata — never arguments or repository content — to a local log under$XDG_STATE_HOME/rac/; off by default and announced on stderr when on. Tool responses are byte-identical with telemetry on and off. A newrac mcp-statscommand summarizes the log (--jsonis the shareable export;--shareprints a prefilled GitHub usage-report issue URL you review and submit yourself — RAC contains no network code). -
Review impact and the first-run editor (v0.8.11): every
rac reviewfinding now carries animpactsentence — why it matters — owned by Core and present in the JSON contract (additive field;schema_versionunchanged), so the CLI, automation, and the Explorer all read identical text. Explorer onboarding gains one optional editor step after the welcome: Enter accepts (an empty value keeps the$VISUAL/$EDITORfallback), typing persists theeditorpreference, Esc skips — and returning users never see it. -
Explorer creation, stats, and the directory view (v0.8.10): the sidebar now mirrors the repository's actual directory structure by default — directories as collapsible nodes (name, trailing
/, artifact count), nested exactly as on disk, with expansion and cursor surviving reloads at any depth and/openrevealing a nested artifact along its filesystem path; theartifact_groupingsetting cyclesfolders|type|flat./new <type> <path>creates an artifact from its canonical template: preview first,yconfirms, the ID is minted by the same Core service asrac new, and nothing ever overwrites — on success the Explorer reloads and opens the new file, ready fore./statsopens a portfolio dashboard (per-type validity, requirement and quality totals, decision status and category breakdowns, relationship counts), collected off the UI thread./browse <type>now lists that type in the filterable results view in every grouping mode; bare/browsefocuses the sidebar. -
Explorer live workspace and validation depth (v0.8.9): the Explorer now watches the repository and reloads itself when artifacts change on disk — a cheap path/mtime comparison every two seconds, with the sidebar keeping its expansion, the open artifact keeping its tab and scroll position, and the health chip updating; the watcher holds while a terminal editor owns the screen and rescans the moment the Explorer resumes, so a saved edit shows immediately. Invalid artifacts now explain themselves where they are shown: a health attention item opens the artifact on its Inspection tab — whose badge counts the validation diagnostics — and a recommendation opens the artifact's Findings tab, which also gains an Improvement group from the improve service (one suggestion per missing section, with the schema's guidance question as the action; rendered, never applied). The command surface deepens:
/schemalists the registered artifact types and/schema <type>renders the expected structure; the palette offers the last artifacts you opened in this repository before you type a character (Enter reopens one); and artifact results can be narrowed by type withf— all → each type present → all. -
Explorer command palette and settings (v0.8.8): pressing
/summons a command palette — an input with a live, navigable menu below it that lists every command when empty, filters and completes them as you type, and quick-opens matching artifacts for any other text;Escdismisses it and?opens help./settings(aliaspreferences) changes everything in place — theme with live preview, mascot, animations, artifact grouping, and a new default-editor command; terminal editors (vim, nvim, emacs, nano, …) now run with the Explorer suspended and resume it on exit. Reading is first-class: the Content tab takes the keyboard (j/kscrolls, capped reading width), artifact references inside the rendered document open in place so the corpus reads like a wiki, and the Links and Findings tabs carry count badges. The mascot animates through per-state frame sequences (searching plays while loading; static with animations off), the sidebar leads with artifact titles and marks invalid artifacts✗, keeps its expansion across reloads, and opens the highlighted artifact in your editor withe; resume restores the last view as well as the last artifact, andEscalways has somewhere to go (home, at worst). -
Explorer visual overhaul (v0.8.7): one persistent workspace frame replaces the screen-per-view shell — a navigation sidebar of type-tagged artifacts (
REQADRRMPPRMDSG, grouped with counts or flat by preference), a context panel whose views swap in place withEscunwinding history, an always-visible/command bar, and a status line of key chips with the health score. Opening an artifact now shows the document itself: a tabbed context view with the rendered Markdown first (read-only), then Inspection, Links (the relationship traversal moved in here), and Findings. Ships the rac-lantern theme — lantern amber on near-black, from the Explorer mascot's palette — as the default; thethemepreference selects any Textual theme, and every state keeps its text label under any palette. Key meanings are unchanged (/,Enter,Esc,h,r,.,g,e,x,y,q), and the sidebar hides below 80 columns so narrow terminals keep reading room. -
Explorer maturity (v0.8.6): workspace continuity — Explorer remembers recently opened repositories and the last artifact per repository, and
.//resumereopens it; optional file-based preferences (theme,mascot,animations,artifact_grouping) under XDG config with/preferencesto view them; and a lantern-carrying mascot in the welcome and empty states. Disabling the mascot or animations loses no information (every state carries text), and nothing requires login, cloud, or sync. -
Explorer relationship navigation (v0.8.5):
gfrom a context view (or/relationships <ref>) opens a knowledge-graph view — the artifact's outgoing relationships, its impact ("what depends on this?"), and its lineage (Supersedes / Superseded By). Connected artifacts are selectable, so the graph can be traversed one hop at a time. Rendered from Core's relationship model; Explorer infers nothing. -
Explorer action workflows (v0.8.4): open the current artifact in your editor (
e, via$VISUAL/$EDITOR; Explorer never edits — ADR-024); a guided/import <source> [target]that converts a document through the ingest service, previews the Markdown, and writes only on confirmation (never overwriting); andxto export recommendations to a Markdown file with the same preview-and-confirm flow. Conversions report progress. -
Explorer recommendations (v0.8.3):
/recommendations(orrfrom the health view) presents RAC Core's review findings grouped by category (Validation, Relationships, Repository Health, Quality), each with its impact, a suggestedraccommand, and navigation to the affected artifact. Severities map to Critical / Warning / Suggestion. Advisory only — Explorer applies nothing and invents no findings. -
Explorer health view (v0.8.2):
hor/healthopens a repository health screen — Core's score with a text label, the four health areas (Completeness, Relationships, Validation, Coverage), and a prioritized attention list whose items open the affected artifact's context view. Explorer adds no scoring; every value comes from existing Core results. -
Explorer navigation (v0.8.1): browse every artifact grouped by type, open any artifact's context view (identity, validation state, completeness, relationships, diagnostics), and reach anything through the
/command surface —open,find,browse,home,help,quit, with bare text treated as a search usingrac resolve/rac findsemantics. -
Explorer first-run onboarding (v0.8.1): launch states derive from repository content (existing, empty, or invalid repository); returning users skip onboarding via a marker under the XDG state directory — the only state Explorer persists.
-
rac explorernow defaults to therac/root when present (ADR-018), falling back to the current directory (v0.8.1). -
rac explorer [directory]— interactive terminal Explorer application shell (Textual): loads a repository without blocking the interface, shows live progress and a repository summary (artifact counts, relationships, diagnostics, health score), and recovers from failures in place with reload. Ships as the optionalexplorerextra (pip install 'requirements-as-code[explorer]'); without it the command prints an install hint (v0.8.0). -
First-class repository model in the service layer:
load_repositorycomposes index, validation, relationships, and portfolio over a single corpus walk into one navigable object (artifacts, relationships with resolution outcomes, unified diagnostics) for Explorer and future consumers; no CLI or JSON output changes (v0.8.0). -
Operation primitives for long-lived consumers: progress reporting and cooperative cancellation across repository loading, validated against 1000+ artifact corpora (v0.8.0).
-
CI battery integrity (v0.7.14): eight test files (~1,300 lines, including all coverage for
rac newandrac migrate) were missing from the CI battery matrix and never ran; they are restored, and a new guard test fails the suite if any test file is ever orphaned again. -
Static quality gates (v0.7.14): ruff (lint + format) and mypy now gate CI; pull requests run the gates plus a fast smoke battery (ADR-027 amended), while the full battery grid stays merge-gated on
main. CLI output is unchanged — all golden files are byte-identical. -
Test coverage is reported on every CI run (report-only, currently 97%) (v0.7.14).
-
The Explorer's persistent bottom command bar is gone (v0.8.8):
/summons the palette instead, returning two rows to the content. The/preferencescommand became/settings(the old spelling still routes), status chips use one casing everywhere (✓ Valid,! Warning,✗ Error), key hints live only in the status-line chips, sidebar rows show artifact titles rather than opaque IDs, and the app bar shows the short version with~-contracted paths. -
Explorer command results, lookups, help, and preferences now render inside the context panel instead of a modal overlay, so the layout never jumps (v0.8.7). The default Explorer theme preference is
rac-lantern(wastextual-dark); setthemein$XDG_CONFIG_HOME/rac/explorer.jsonto keep a different one. -
Repository corpus traversal is defined once in core (
walk_corpus) and consumed by every repository command — behavior and output unchanged (v0.7.14). -
rac migrate metadata <directory>— migrate existing recognized artifacts onto canonical frontmatter identity: idempotent, byte-preserving, with--dry-runpreview; unrecognized documents are reported, never guessed at (v0.7.13). -
rac resolve <ID>— resolve any artifact ID (canonical or legacy alias) to its type, title, and path; duplicates are reported with every path, never silently resolved (v0.7.12). -
rac find <query>— deterministic artifact search by ID, title, filename, or path, with--typefiltering and JSON output (v0.7.12). -
rac relationshipshuman output resolves references to human-friendly labels —Title (type · ID)— while JSON keeps stored references unchanged (v0.7.12). -
rac indexentries gain an additivealiasesfield: every identifier an artifact answers to, canonical first (v0.7.12). -
rac init— establish the repository identity namespace (.rac/config.yamlwith arepository_key); idempotent, and an established key is never silently changed (v0.7.11). -
Hybrid artifact metadata: a leading YAML frontmatter block (
schema_version,id,type,relationships) is parsed, strictly schema-validated, and exposed as canonical machine-operational metadata; artifacts without frontmatter remain fully supported (v0.7.11). -
System-assigned opaque artifact IDs (e.g.
RAC-01JY4M8X2QZ7): branch-safe, offline, stable across renames, moves, and type changes;rac newassigns one automatically andrac indexreports it (v0.7.11). -
Identity validation: conflicting frontmatter/legacy identity and duplicate canonical IDs are deterministic errors — RAC never silently picks one (v0.7.11).
-
Relationship references resolve against legacy identity aliases (
## IDvalues, filename prefixes, stems), so adopting canonical IDs does not break existing human-readable references; RAC's own corpus now carries canonical frontmatter identity (v0.7.11). -
rac new <type> <output-path>— create a valid artifact from its canonical bundled template; deterministic, AI-free, and never overwrites an existing file (v0.7.10). -
rac templates— list the canonical artifact templates available torac new, with--jsonfor tools (v0.7.10). -
rac validate <directory>— validate every recognized artifact in a tree in one command; unrecognized documents are skipped, not failed. -
rac review <directory>— full repository review: validation, relationship integrity, and completeness as one prioritized worklist (invalid artifacts first, then broken relationships, then advisory findings), each finding with a concrete suggested action. Exits1only on blocking issues. -
CI trust gates: RAC's own
rac/corpus must passrac validate,rac relationships --validate, andrac review(dogfood battery), and CLI output is pinned byte-for-byte by golden tests. -
README build badge, "How RAC earns trust" section, CHANGELOG.md, and CONTRIBUTING.md.
-
rac portfolio --jsonnow listsartifacts.unknown_paths(additive). -
rac index— flat artifact inventory (id, type, title, path) for tools and agents (v0.7.5).
- Documentation restructured around task-focused guides under
docs/(quickstart, CLI reference, artifacts, relationships, repository workflow, testing); README simplified to an overview (v0.7.6–v0.7.7).
- RAC's own planning corpus now passes its own validation: one invalid roadmap repaired and all cross-artifact references resolve.
rac portfolio— one-screen repository intelligence: counts by type, validity, completeness, relationship coverage, attention list, health score.
rac relationships --validate— resolve every cross-artifact reference and report broken, ambiguous, self-referencing, or duplicate-identifier findings.
rac relationships— discover and report the explicit references artifacts declare to each other.
- Relationship metadata: artifacts can declare
## Related Requirements,## Related Decisions, and similar sections that RAC recognizes and counts.
- Design artifact type: validate and inspect product-design documents.
- Prompt artifact type: validate and inspect reusable AI prompts.
- Guided improvement for roadmaps (
rac improveunderstands roadmap sections).
- Roadmap artifact type: validate and inspect roadmap documents.
rac schema— show the expected structure of any artifact type, with--templateto emit a starting document.
rac improve— actionable suggestions (and templates) for incomplete artifacts.
- Decision (ADR) artifact type with status/category metadata.
rac inspect— classify a document and report its completeness.
- More ingest formats (HTML, PPTX, XLSX).
rac ingest— convert DOCX/PDF documents into RAC-compatible Markdown.
rac stats— summarize a directory of artifacts: counts, quality signals, missing recommended sections.
- Initial release:
rac validateandrac difffor requirement documents, human and--jsonoutput, stable exit codes (0ok,1validation failed,2usage error).