rac-core 2026.6.5__tar.gz

rac_core-2026.6.5/.agent-context/BRIEF.md

@@ -0,0 +1,88 @@
+# RAC growth programme — shared brief
+
+Read `.agent-context/SCHEMA.md` first. Every deliverable lands as RAC
+artifacts in this repository (requirements first, supporting artifacts
+second, linked via `## Related …` sections where the schema allows).
+A deliverable that exists only as a loose Markdown note has failed.
+
+## Repo reality (overrides anything you assume)
+
+- Version v0.10.3. Product identity is recorded in **ADR-036
+  (`rac/decisions/adr-036-lore-product-identity.md`): Lore is the product
+  ("agents that know why", MCP grounding); RAC is the engine.** The README
+  first screen leads with Lore and MUST NOT be repositioned. This was
+  confirmed by the maintainer on 2026-06-12.
+- The corpus is already fully dogfooded (38 ADRs, requirements, designs,
+  roadmaps, prompts under `rac/`, validated in CI).
+- Relationships/traceability shipped in v0.7.x (ADR-016). Gap records now
+  motivate FUTURE roadmap work, not "v0.8.0".
+- Read `rac/decisions/` before designing; recorded decisions take
+  precedence. If your task conflicts with one, stop and report the
+  conflict — do not override it.
+
+## Positioning thesis (adapted; use verbatim where comparison framing is needed)
+
+Primary positioning is ADR-036's: Lore gives coding agents the decisions a
+team already made, served deterministically over MCP from a typed Markdown
+corpus in Git.
+
+Secondary positioning, for comparison content only (below the README fold
+or in `docs/`): spec-driven tools (GitHub Spec Kit, OpenSpec, Kiro) manage
+the *change* — proposal, design, tasks — and treat requirements as
+ephemeral inputs that are consumed and archived. RAC manages the
+*requirements* as a durable, versioned, governed corpus that persists
+across changes. RAC is the layer above SDD tools, not a competitor to
+them. Comparison framing is "complements, owns a different layer", never
+"better than".
+
+## Global constraints (verbatim, apply to all agents)
+
+1. **Schema fidelity.** Do not invent a requirement format. SCHEMA.md is
+   extracted from the codebase; use exactly that. If the schema lacks a
+   field you want, note it as a gap, do not add it ad hoc.
+2. **Voice.** Conservative, execution-focused language. No promotional
+   framing, no superlatives, no "blazingly", no emoji. UK spelling
+   throughout. Observation before conclusion. If a claim about a
+   competitor cannot be verified from their repo or docs, it is not made.
+3. **Restraint.** Prefer the smallest artifact that does the job. A
+   three-requirement change beats a twelve-requirement change covering
+   the same ground.
+4. **Human gates.** Two decisions are reserved for Tom and must be
+   flagged, never resolved by an agent:
+   - GATE-1: nothing intended for public posting (X/LinkedIn/HN) ships
+     until employer external-communications and personal-project IP
+     policies have been reviewed. Agents may draft; drafts are marked.
+   - GATE-2: the contribution policy and any "PRs welcome" language does
+     not go live until a CLA is in place. Same marking convention.
+   Gate marking convention (the real schema has no status field for
+   this — that is itself a recorded gap): keep `## Status` as `Proposed`
+   and add a body line directly under it:
+   `Blocked: GATE-1 (employer external-communications / IP review)` or
+   `Blocked: GATE-2 (CLA not yet in place)`.
+5. **No fabrication.** Where you need a fact about spec-kit, OpenSpec,
+   Kiro, or any tool, read the actual repo/README/docs (web fetch).
+   Uncited competitor claims are deleted at integration review.
+6. **Verification.** Finish by running the validation commands in
+   SCHEMA.md against your outputs and fixing failures before reporting
+   done.
+
+## Gap recording (first-class output)
+
+When you need something RAC cannot express, do NOT work around it
+silently. Append a record to `.agent-context/gaps/<your-agent-name>.md`:
+
+```
+## Gap: <relationship or capability needed>
+- Instance: <concrete case from this programme or the existing corpus>
+- Instance: ...
+- Minimal schema addition that would have sufficed: <one sentence>
+```
+
+## Working rules
+
+- Write files only; do NOT run `git commit` or `git push` — the
+  orchestrator commits.
+- Stay inside your assigned paths.
+- New requirement files: `rac/requirements/rac-growth-<slug>.md`, created
+  with `/tmp/racenv/bin/rac new requirement <path>`.
+- UK spelling in all artifact prose.

rac_core-2026.6.5/.agent-context/CHANGES_SUMMARY.md

@@ -0,0 +1,95 @@
+# Growth programme — changes summary
+
+Branch `claude/rac-growth-orchestration-obphpo`, 2026-06-12. The
+programme was adapted before execution: ADR-036 (Lore product identity)
+governs positioning, so the layer-above-SDD thesis appears only as
+comparison content below the README fold; the dogfood-conversion
+workstream was re-scoped to a corpus gap audit because the corpus is
+already fully RAC-native; gap records motivate future roadmap work, not
+"v0.8.0". Adaptation confirmed by the maintainer on 2026-06-12.
+
+## Agent 1 — positioning and comparison
+
+Authored `rac-growth-positioning` (REQ-001..005), then satisfied it
+with one README section, "How this relates to spec-driven development",
+inserted below "Who it's for": layer-above thesis, a five-dimension
+comparison table against GitHub Spec Kit and OpenSpec, every cell
+verified against the tools' own repos with sources in an adjacent HTML
+comment. Kiro is named in prose only — its docs returned HTTP 403 at
+verification time, so no Kiro capability claims are made. First screen
+byte-identical; pure 36-line insertion.
+
+## Agent 2 — adoption surface
+
+Authored `rac-growth-adoption` (REQ-001..005: pipx/uv zero-config
+install, sub-five-minute cold start, timing evidence, ≤20 s demo GIF;
+REQ-005 is the one item needing a core change, left Proposed) and
+`rac-growth-agent-skill` (REQ-001..004). Implemented the Claude Code
+skill at `.claude/skills/rac-artifacts/SKILL.md` per Anthropic's
+documented project discovery path, constrained to the host project's
+RAC directory. Measured cold start: ≈13.8 s machine time
+(`.agent-context/cold-start-timing.md`). Demo shot list recorded as the
+`growth-demo-gif` design (5 shots, 20 s).
+
+## Agent 3 — gap audit and contribution policy (re-scoped)
+
+Audited the existing corpus and recorded seven traceability gaps with
+3–4 concrete instances each (`.agent-context/gaps/agent3.md`). Authored
+`rac-growth-contribution-policy` (REQ-001..005): proposal-gated
+substantial changes modelled on OpenSpec's verified flow, draft
+CONTRIBUTING.md text embedded in the artifact body, the live file
+untouched, marked Blocked: GATE-2.
+
+## Agent 4 — essay–artifact bridge
+
+Authored `rac-growth-essay-bridge` (REQ-001..004, Blocked: GATE-1) and
+the `growth-essay-mapping` design: six Article 1 claims mapped to
+verified capabilities or explicitly flagged absences, least-promotional
+link placements, and five dogfood article slots (titles and one-line
+premises only). Zero prose written in the maintainer's voice.
+
+## Agent 5 — ecosystem seed
+
+Authored `rac-growth-extensibility` (REQ-001..005: entry-point
+discovery of third-party schemas/templates, byte-identical behaviour
+when absent, designed within ADR-012/015/021/024; GATE-2-blocked
+standalone-repo bundle convention draft embedded) and
+`rac-growth-ecosystem-list` (REQ-001..005). Created `docs/ecosystem.md`
+with exactly three verified entries (dogfood corpus, the
+`rac-artifacts` skill, `examples/guide/`) and no solicitation language.
+
+## Requirement artifacts created
+
+| Artifact | Id | REQs | Status |
+| --- | --- | --- | --- |
+| rac/requirements/rac-growth-positioning.md | RAC-KTYB8944G7TN | REQ-001..005 | Proposed |
+| rac/requirements/rac-growth-adoption.md | RAC-KTYB6QBZNTD0 | REQ-001..005 | Proposed |
+| rac/requirements/rac-growth-agent-skill.md | RAC-KTYB6R0DM280 | REQ-001..004 | Proposed |
+| rac/requirements/rac-growth-contribution-policy.md | RAC-KTYBCCTFG5JW | REQ-001..005 | Proposed, Blocked: GATE-2 |
+| rac/requirements/rac-growth-essay-bridge.md | RAC-KTYBHXKBWZGZ | REQ-001..004 | Proposed, Blocked: GATE-1 |
+| rac/requirements/rac-growth-extensibility.md | RAC-KTYBK6T1NQMY | REQ-001..005 | Proposed (bundle section GATE-2) |
+| rac/requirements/rac-growth-ecosystem-list.md | RAC-KTYBK7FSW6HS | REQ-001..005 | Proposed |
+
+Supporting corpus artifacts: `rac/roadmaps/future/growth-programme.md`
+(RAC-KTYB8RVVQ1HX, umbrella, links all of the above),
+`rac/designs/growth-demo-gif.md` (RAC-KTYB6RMYBQ5X),
+`rac/designs/growth-essay-mapping.md` (RAC-KTYBHY87XKV8).
+
+Non-corpus artifacts: README comparison section,
+`.claude/skills/rac-artifacts/SKILL.md`, `docs/ecosystem.md`,
+`.agent-context/` (brief, schema, timing log, five gap files, this
+summary, `GAPS_TRACEABILITY.md`).
+
+## Integration review results
+
+- `rac validate rac/`: 113 valid, 0 invalid, exit 0.
+- `rac relationships rac/ --validate`: 277 checked, 0 issues, exit 0.
+- `rac review rac/`: health 80/100, zero priority 1–2 findings.
+- Every produced artifact traces to a requirement (recorded in prose —
+  the structural link is itself gap 1 of `GAPS_TRACEABILITY.md`).
+- All competitor claims source-cited; the OpenSpec packaging quote and
+  contribution-model claims were independently re-verified against the
+  live README at integration. No uncited claim survived.
+- Gate check: `Blocked: GATE-1/GATE-2` markers present on all four
+  gated artifacts; grep confirms no gate-blocked content in README,
+  docs/, examples/, or the skill.

rac_core-2026.6.5/.agent-context/GAPS_TRACEABILITY.md

@@ -0,0 +1,130 @@
+# Traceability gaps — consolidated report
+
+Growth programme, 2026-06-12, corpus at v0.10.3. Twenty raw gap records
+from five agents (`.agent-context/gaps/agent1..5.md`) consolidate into
+eight schema gaps and two authoring-friction findings. Every instance
+cites a real file in this repository; none is speculative. The original
+programme framed this report as justification for "the v0.8.0
+traceability work"; that shipped as the v0.7.x relationships series
+(ADR-016), so each gap instead names the future work it motivates.
+
+The linking mechanisms that exist today: untyped `## Related <Type>`
+sections (corpus-internal, by id) and `## Supersedes` (decisions only).
+
+## 1. Links from artifacts to non-artifact repo files
+
+The most frequently hit gap — all five agents recorded it independently.
+
+- Instances: `rac-growth-positioning` REQ-001..005 are satisfied by a
+  README section it cannot reference; `rac-growth-agent-skill` REQ-001
+  is satisfied by `.claude/skills/rac-artifacts/SKILL.md`;
+  `rac-growth-ecosystem-list` governs `docs/ecosystem.md`; pre-existing:
+  `rac-documentation-structure` places testable requirements on eight
+  doc files by bare path, and `adr-027` governs four CI workflow files
+  the same way. Renames break these silently.
+- Minimal addition: an optional `## Related Files` (or `## Satisfied
+  By`) section accepting repo-relative paths, validated for existence
+  by `rac relationships --validate`.
+- Motivates: requirement→artifact traceability in a future
+  relationships milestone; also gives Guide's `get_related` a way to
+  answer "what file satisfies this requirement".
+
+## 2. External source and URL references as structured data
+
+- Instances: the README comparison table's competitor sources
+  (spec-kit, OpenSpec) live in an HTML comment invisible to validation
+  and MCP; Kiro's exclusion (docs returned HTTP 403 on 2026-06-12)
+  has no machine-readable "re-verify later" marker; the essay series
+  mapped in `growth-essay-mapping` is unpublished and external, so the
+  article side of every mapping row is an unresolvable label.
+- Minimal addition: an optional `## Sources` section, one URL per line
+  with an optional status token, extracted and exposed via
+  `get_artifact` (not fetched by the engine — determinism holds).
+- Motivates: evidence-grounded artifacts; staleness checking as a
+  deterministic review finding.
+
+## 3. Typed edge semantics (implements / satisfies / depends-on / derived-from)
+
+- Instances: `adr-028` invents unvalidated `### Implements`
+  sub-headings inside a non-schema section; the Explorer requirement
+  invents `### Depends On`; `v0.10.3-search-quality` lists the
+  decisions it implements (ADR-037/038) and the standing constraints it
+  must not break (ADR-007/027) in one flat `## Related Decisions` list;
+  `growth-essay-mapping`'s claim→capability mapping is unqueryable
+  table prose.
+- Minimal addition: validated optional edge-label sub-headings
+  (`### Implements`, `### Depends On`, `### Satisfies`) inside existing
+  `Related <Type>` sections, defaulting to untyped when absent.
+- Motivates: relationship semantics in a post-v0.10 series; directly
+  improves `rac relationships` output and `get_related` answer quality.
+
+## 4. Machine-readable lifecycle and gate status
+
+- Instances: `rac-product-intent-ci-watchkeeper` carries Status
+  "Deferred", outside any vocabulary, accepted silently; shipped
+  requirements still read "Proposed" with no transition to record;
+  this programme's GATE-1/GATE-2 markers are free-text lines
+  (`Blocked: GATE-2 (CLA not yet in place)`) in four artifacts —
+  nothing can enumerate "everything blocked behind GATE-1", and the
+  section-level block on `rac-growth-extensibility`'s bundle convention
+  is pure prose.
+- Minimal addition: a validated Status vocabulary for requirements
+  (Proposed | Accepted | Implemented | Deferred | Blocked) with one
+  reason line for Blocked.
+- Motivates: the review engine (`future/v1.1-review-engine`) and CI
+  Watchkeeper intent analysis, both of which need lifecycle state.
+
+## 5. Supersession outside decisions
+
+- Instances: `archive/v0.8.0-service-api.md` and
+  `v0.8.x-explorer/v0.8.0-explorer-foundation.md` both claim the v0.8.0
+  identity with no marker between them; the entire archived v0.9 plan
+  was replaced by `v0.9.x-watchekeeper/` via directory move only;
+  `v0.10.0-guide-foundation` supersedes the deleted `v1.2-mcp-server`
+  stub in prose that now dangles invisibly.
+- Minimal addition: permit `## Supersedes` on roadmap artifacts,
+  validated for target existence including archived targets.
+- Motivates: roadmap lifecycle hygiene; makes `archive/` queryable
+  instead of conventional.
+
+## 6. Relationship directionality and back-references
+
+- Instances: ADR-036 → v0.10.2 has no reverse edge; six early ADRs
+  cited by `rac-agent-context-guide` carry zero Related sections
+  themselves — an agent at the target cannot discover the citing
+  artifact.
+- Minimal addition: an advisory asymmetric-edge finding in
+  `rac relationships --validate` (no schema change).
+- Motivates: relationship-quality findings in the review engine.
+
+## 7. Scoping / applies-to
+
+- Instances: ADR-018 governs `rac/`; ADR-023 scopes itself to
+  `src/rac/` internals in bold prose; ADR-027 applies to the CI
+  workflows; ADR-033 applies to the Guide tool surface — none of these
+  scopes is data.
+- Minimal addition: an optional `## Applies To` section on decisions
+  accepting paths or component names.
+- Motivates: scoped grounding — Guide could serve "decisions that apply
+  to the file you are editing".
+
+## 8. Validation blind spots in relationship extraction
+
+- Instances: `## Related Artifacts` (a non-schema section) appears in
+  eight artifacts with display-name targets that resolve to nothing
+  while CI stays green; `rac-growth-agent-skill` links
+  `v1.4-claude-skills`, whose file classifies as Unknown type, and
+  validation reports 0 issues — targets are not type-checked.
+- Minimal addition: advisory findings for unrecognised `Related *`
+  sections and for targets resolving to Unknown or mismatched types.
+- Motivates: near-term `rac review` / relationships hardening; cheap
+  relative to the schema gaps above.
+
+## Authoring-friction findings (not schema gaps)
+
+- `[REQ-NNN]` statements cannot hard-wrap: continuation lines raise
+  `req-missing-id`, forcing one-line statements against the corpus's
+  72-column prose convention. Hit by three agents.
+- `rac new` does not create parent directories — the only zero-config
+  snag on the measured cold-start path (covered by Proposed REQ-005 in
+  `rac-growth-adoption`).

rac_core-2026.6.5/.agent-context/SCHEMA.md

@@ -0,0 +1,76 @@
+# RAC schema — extracted from the live codebase (v0.10.3, 2026-06-12)
+
+Source of truth: `docs/artifacts.md`, `docs/relationships.md`, `src/rac/`,
+`rac new` output. Do not invent fields beyond what is listed here.
+
+## Artifact model
+
+Five types, all plain Markdown. Type is **inferred from `##` section
+headings** (deterministic, case/whitespace-insensitive, 50% confidence
+threshold) — never declared. Frontmatter carries identity only:
+
+```yaml
+---
+schema_version: 1
+id: RAC-XXXXXXXXXXXX   # machine-generated, opaque (ADR-026)
+type: requirement       # requirement|decision|roadmap|prompt|design
+---
+```
+
+**Never hand-write an id.** Create artifacts with:
+
+```bash
+/tmp/racenv/bin/rac new <type> <output-path>
+```
+
+(The repo identity namespace `.rac/config.yaml` already exists; `rac new`
+mints the id and writes the canonical template.)
+
+## Sections per type
+
+| Type | Required | Recommended | Optional |
+| --- | --- | --- | --- |
+| Requirement | Problem · Requirements | Success Metrics · Risks · Assumptions | Related Decisions · Related Roadmaps · Related Prompts · Related Designs · Related Requirements |
+| Decision | Context · Decision · Consequences | Status · Category · Alternatives Considered | Supersedes · Related Requirements · Related Roadmaps · Related Designs |
+| Roadmap | Outcomes · Initiatives | Success Measures · Assumptions · Risks | Related Decisions · Related Requirements · Related Prompts · Related Designs |
+| Prompt | Objective · Input · Instructions · Output | Constraints · Examples · Evaluation | Related Requirements · Related Decisions · Related Roadmaps · Related Designs |
+| Design | Context · User Need · Design · Constraints | Rationale · Alternatives · Accessibility · Style Guidance · Open Questions | Related Requirements · Related Decisions · Related Roadmaps · Related Prompts |
+
+Validated decision metadata values:
+- `Status`: Proposed | Accepted | Superseded | Deprecated
+- `Category`: Architecture | Product | Process | Technical | Other
+
+Requirements convention in this repo: a `## Status` section (Proposed /
+Accepted style) and testable `[REQ-NNN]` statements under `## Requirements`.
+
+## Identity and relationships
+
+Id resolution order: explicit `## ID` section → `<letters>-<digits>`
+filename prefix (`adr-004-…` → `adr-004`) → filename stem. Case-insensitive.
+
+The ONLY linking mechanism is the `## Related <Type>` sections (one id per
+line) plus `## Supersedes` on decisions. Links are corpus-internal, by id.
+There is no mechanism for: links to non-artifact files (README sections,
+code, skills), typed edge semantics (derived-from, satisfies, applies-to),
+or machine-readable gate/blocked status. If you need one of these, record
+it as a gap (see BRIEF) — do not improvise frontmatter fields.
+
+## Directory layout (this repo's dogfood corpus)
+
+- `rac/requirements/` — long-lived capabilities (ADR-020), slug `rac-<area>.md`.
+  Existing: rac-agent-context-guide, rac-documentation-structure,
+  rac-product-intent-ci-watchkeeper, rac-product-knowledge-navigator-explorer,
+  rac-repository-review-mode, rac-trust-transparency.
+- `rac/decisions/` — `adr-NNN-slug.md` (next free number: adr-039).
+- `rac/roadmaps/<series>/` — `vX.Y.Z-slug.md`; `rac/roadmaps/future/` for unscheduled.
+- `rac/prompts/`, `rac/designs/` — descriptive slugs.
+- `docs/` — user documentation layer (ADR-022); `README.md` — entry point only.
+- `examples/guide/` — runnable MCP grounding example.
+
+## Validation commands (run before reporting done)
+
+```bash
+/tmp/racenv/bin/rac validate rac/                    # must exit 0
+/tmp/racenv/bin/rac relationships rac/ --validate    # must exit 0
+/tmp/racenv/bin/rac review rac/                      # no priority 1-2 findings
+```

rac_core-2026.6.5/.agent-context/cold-start-timing.md

@@ -0,0 +1,53 @@
+# Cold-start timing — install to first validated artifact
+
+Measured 2026-06-12 on this machine (Linux, Python 3.11 venv), installing
+the local checkout at `/home/user/requirements-as-code` (v0.10.x dev
+build, `rac 0.1.dev74`). Wall-clock, `date +%s.%N` around each step.
+
+## Path A: pip in a fresh venv
+
+| Step | Command | Wall clock |
+| --- | --- | --- |
+| 1 | `python3 -m venv /tmp/coldstart-venv` | 3.43 s |
+| 2 | `pip install /home/user/requirements-as-code` | 9.80 s |
+| 3 | `rac --version` (sanity check) | 0.13 s |
+| 4 | `rac init` | 0.13 s |
+| 5 | `mkdir -p rac/requirements` + `rac new requirement rac/requirements/login-flow.md` | 0.15 s |
+| 6 | Edit (heredoc replacing TODOs, frontmatter preserved) | 0.01 s |
+| 7 | `rac validate rac/requirements/login-flow.md` → PASS, exit 0 | 0.14 s |
+
+Machine total: **≈ 13.8 s**. Result: `PASS`, 0 errors, 1 advisory warning
+(`missing-risks`).
+
+## Path B: uv tool install
+
+`uv tool install --force /home/user/requirements-as-code`: **2.57 s**;
+`rac --version` works immediately. Zero post-install configuration.
+
+## Verdict
+
+Machine time is ~14 s; the five-minute budget is consumed almost entirely
+by human reading and editing. The under-five-minutes cold start
+(rac-growth-adoption REQ-002) holds with a wide margin in this
+environment.
+
+## Caveats
+
+- Local checkout, not the published PyPI package; a published-package run
+  (REQ-003 in `rac/requirements/rac-growth-adoption.md`) should repeat
+  this against `pip install requirements-as-code`.
+- pip's HTTP cache was warm for dependencies (`markdown-it-py`, `pyyaml`,
+  `mcp` and transitive deps); a genuinely cold network adds download time.
+  Network conditions should be stated when the published-package run is
+  recorded.
+- `pipx` is not installed on this machine, so the `pipx install` leg of
+  REQ-001 is unverified here; `uv tool install` verified.
+
+## Friction found
+
+- `rac new` does not create parent directories: `rac new requirement
+  rac/requirements/login-flow.md` in a fresh project fails with
+  `rac: directory does not exist: rac/requirements` until `mkdir -p` is
+  run. This is the only zero-config snag on the path; recorded as a gap
+  in `.agent-context/gaps/agent2.md` and covered by the Proposed REQ-005
+  (guided first-run) in `rac/requirements/rac-growth-adoption.md`.

rac_core-2026.6.5/.agent-context/gaps/agent1.md

@@ -0,0 +1,43 @@
+# Gaps — agent 1 (positioning and comparison)
+
+## Gap: link from a requirement to the non-artifact file that satisfies it
+
+- Instance: `rac/requirements/rac-growth-positioning.md` REQ-001 to
+  REQ-005 are satisfied by the "How this relates to spec-driven
+  development" section of `README.md`. The schema's only linking
+  mechanism is `## Related <Type>` sections pointing at corpus-internal
+  artifact ids, so there is no way to record that the README section is
+  the satisfying surface; a reviewer must rediscover the mapping by
+  hand.
+- Instance: the pre-existing `rac/requirements/rac-trust-transparency.md`
+  has the same problem — FR-6 and FR-10 target README content (CI
+  badge, trust section) with no recorded link to it.
+- Minimal schema addition that would have sufficed: an optional
+  `## Satisfied By` section accepting repo-relative file paths (with
+  optional anchor), validated for file existence.
+
+## Gap: external source citations as structured data
+
+- Instance: REQ-004 in `rac-growth-positioning.md` requires every
+  comparison-table claim to be verifiable from the competitor's own
+  docs. The source URLs (github.com/github/spec-kit,
+  github.com/Fission-AI/OpenSpec README and docs/cli.md) had to be
+  recorded as an HTML comment in `README.md`, invisible to `rac
+  validate`, `rac relationships`, and the MCP tools — the corpus cannot
+  represent "this claim is grounded in that external URL" or check it
+  for staleness.
+- Minimal schema addition that would have sufficed: an optional
+  `## Sources` section on artifacts accepting one URL per line, exposed
+  through `get_artifact`.
+
+## Gap: machine-readable record of a failed verification
+
+- Instance: Kiro was excluded from the comparison table because
+  https://kiro.dev/docs/specs/ returned HTTP 403 to automated fetches
+  on 2026-06-12. That exclusion rationale lives only in prose (a
+  Risks bullet in `rac-growth-positioning.md` and an HTML comment in
+  `README.md`); nothing in the corpus can flag "re-verify this when the
+  source becomes reachable".
+- Minimal schema addition that would have sufficed: none specific —
+  this would be covered by the `## Sources` section above if entries
+  could carry a verified/unverifiable status token.

rac_core-2026.6.5/.agent-context/gaps/agent2.md

@@ -0,0 +1,44 @@
+# Gaps — agent 2 (adoption surface)
+
+## Gap: link from a requirement to the non-artifact file that satisfies it
+- Instance: `rac-growth-agent-skill` REQ-001 is satisfied by
+  `.claude/skills/rac-artifacts/SKILL.md`; no `## Related …` section can
+  reference a file outside the corpus, so the requirement names the path
+  in prose only.
+- Instance: `rac-growth-adoption` REQ-003's evidence is the timing
+  record (`.agent-context/cold-start-timing.md` now; a published-package
+  run later); there is no way to attach evidence to a requirement.
+- Instance: `rac-growth-adoption` REQ-004's deliverable is a README
+  asset (the demo GIF); the requirement cannot reference the README or
+  the asset path.
+- Minimal schema addition that would have sufficed: an optional
+  `## Related Files` section accepting repo-relative paths, with
+  existence checked by `rac relationships --validate`.
+
+## Gap: relationship targets are not type-checked
+- Instance: `rac-growth-agent-skill` lists `v1.4-claude-skills` under
+  `## Related Roadmaps`; that file (`rac/roadmaps/future/v1.4-claude-skills.md`)
+  is a stub that classifies as Unknown (its body says "1.3 Claude
+  Skills"), yet `rac relationships rac/ --validate` reports 0 issues.
+- Minimal schema addition that would have sufficed: a warning from
+  relationship validation when a `## Related <Type>` target resolves to
+  an artifact of a different or unknown type.
+
+## Gap: requirement statements cannot be hard-wrapped
+- Instance: both new requirements initially wrapped `[REQ-NNN]` bullets
+  at ~72 columns, the corpus's prose convention; every continuation line
+  raised `req-missing-id`, forcing each statement onto one long line.
+- Minimal schema addition that would have sufficed: treat indented
+  continuation lines of a `[REQ-NNN]` bullet as part of that
+  requirement during validation.
+
+## Gap: `rac new` does not create parent directories (CLI capability)
+- Instance: cold-start run — in a fresh project after `rac init`,
+  `rac new requirement rac/requirements/login-flow.md` fails with
+  `rac: directory does not exist: rac/requirements` until `mkdir -p` is
+  run; the only zero-config snag on the first-value path (see
+  `.agent-context/cold-start-timing.md`; covered by Proposed REQ-005 in
+  `rac-growth-adoption`).
+- Minimal schema addition that would have sufficed: not schema —
+  `rac new` creating missing parent directories of the output path
+  would have sufficed.