diff --git a/.cursor/rules b/.cursor/rules index 62b4aa4c..bfaebe30 100644 --- a/.cursor/rules +++ b/.cursor/rules @@ -1,9 +1,16 @@ - + ## Settled decisions (AsDecided) -These decisions are already accepted. Do not re-open or contradict them; ask the `lore` MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +These decisions are already accepted. Do not re-open or contradict them; ask the AsDecided MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +- **RAC-01K8P7A3M5QZ** — ADR-125: Distribute AsDecided as a Local Pilot App _(Architecture)_ +- **RAC-01K8Q7MCP407** — ADR-129: Confine Rename Writes to the Corpus Root _(Technical)_ +- **RAC-01K8Q7MCP408** — ADR-130: Transactional Rename Application _(Technical)_ +- **RAC-01K8Q7MCP411** — ADR-128: Hard MCP Response Budgets _(Technical)_ +- **RAC-01K8Q7MCP413** — ADR-127: Attributable MCP Audit Records _(Technical)_ +- **RAC-01K8Q7MCP431** — ADR-131: Native Telemetry Is Local-Only _(Product)_ +- **RAC-01K8Q7MCP432** — ADR-132: AsDecided MCP Server Identity _(Product)_ - **RAC-KTQ63DPSMF19** — ADR-001 Markdown First - **RAC-KTQ63DPT6008** — ADR-002 AI Optional - **RAC-KTQ63DPVVB37** — ADR-003 Structured Outputs First @@ -84,9 +91,14 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KX04DH293JG8** — ADR-111: Revert to SemVer Release Versioning _(Process)_ - **RAC-KX2WTHEMDEY0** — ADR-112: Cache On by Default, Stat-Proxy Freshness as the Floor _(Technical)_ - **RAC-KX8GEA45HRBM** — ADR-113: Capture Writes Arrive Through a Sibling Surface, Not Guide _(Architecture)_ +- **RAC-KX9H2M7Q4V8C** — ADR-122: OKF v0.2 Is a Truthful Derived Carrier _(Architecture)_ +- **RAC-KXBD3T7Q9M2N** — ADR-123: Deterministic Decision-to-Code Enforcement _(Architecture)_ - **RAC-KXE0M2QBF2MP** — ADR-114: Native Index Workspace Dependencies — memmap2 In, inotify Deferred _(Technical)_ - **RAC-KXFK11FQDN1Y** — ADR-115: The Shared Artifact-Spec Registry Both Engines Read (ADR-063 Guard 1) _(Architecture)_ - **RAC-KXGVR299XY5E** — ADR-116: The Native Rust Engine Is a Sanctioned Second Implementation Under Lockstep Guards _(Architecture)_ +- **RAC-KYVTHFQD44BP** — ADR-124: Publish the Native MCP Server Through OCI and the Official Registry _(Architecture)_ +- **RAC-KYYC7HBFMRBA** — ADR-126: Package the Native MCP Server for Docker's MCP Catalog _(Architecture)_ +- **RAC-MCP20260728A** — ADR-121: Dual-Era MCP Protocol Compatibility _(Architecture)_ - **RAC-P55FRE5HNE55** — ADR-118: Native Event Freshness Acceleration - **RAC-P61BA5EDE7A0** — ADR-119: Base-Plus-Delta Serving Generations - **RAC-PYRE71RECER7** — ADR-120: Rust CI Uses Contract Fixtures and Live-Corpus Invariants diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c8a12a87..bfaebe30 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,9 +1,16 @@ - + ## Settled decisions (AsDecided) -These decisions are already accepted. Do not re-open or contradict them; ask the `lore` MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +These decisions are already accepted. Do not re-open or contradict them; ask the AsDecided MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +- **RAC-01K8P7A3M5QZ** — ADR-125: Distribute AsDecided as a Local Pilot App _(Architecture)_ +- **RAC-01K8Q7MCP407** — ADR-129: Confine Rename Writes to the Corpus Root _(Technical)_ +- **RAC-01K8Q7MCP408** — ADR-130: Transactional Rename Application _(Technical)_ +- **RAC-01K8Q7MCP411** — ADR-128: Hard MCP Response Budgets _(Technical)_ +- **RAC-01K8Q7MCP413** — ADR-127: Attributable MCP Audit Records _(Technical)_ +- **RAC-01K8Q7MCP431** — ADR-131: Native Telemetry Is Local-Only _(Product)_ +- **RAC-01K8Q7MCP432** — ADR-132: AsDecided MCP Server Identity _(Product)_ - **RAC-KTQ63DPSMF19** — ADR-001 Markdown First - **RAC-KTQ63DPT6008** — ADR-002 AI Optional - **RAC-KTQ63DPVVB37** — ADR-003 Structured Outputs First @@ -44,7 +51,7 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KV4ZAGWPAA6X** — ADR-059: Reuse a Single Markdown Parser Instance _(Architecture)_ - **RAC-KV4ZAHVNGH2J** — ADR-060: Share Structural Validation Across Per-Type Validators _(Architecture)_ - **RAC-KV5112MVD0AM** — ADR-061: Roadmaps Carry an "Achieved" Terminal Lifecycle Status _(Architecture)_ -- **RAC-KV5DJYE5FGH0** — ADR-062: The Python SDK's Public Surface Is `asdecided.__all__` _(Architecture)_ +- **RAC-KV5DJYE5FGH0** — ADR-062: The Python SDK's Public Surface Is `rac.__all__` _(Architecture)_ - **RAC-KV68XJGEXBNB** — ADR-064: Multi-Repo Extraction Strategy for the itsthelore Organisation _(Architecture)_ - **RAC-KV6ADYFGC3H4** — ADR-063: Non-Python Clients Are Thin Clients Over the Contract _(Architecture)_ - **RAC-KV6KFBDZ4D23** — ADR-065: Artifact Content Is Untrusted Input; the Trust Boundary Is Human PR Review _(Architecture)_ @@ -84,9 +91,14 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KX04DH293JG8** — ADR-111: Revert to SemVer Release Versioning _(Process)_ - **RAC-KX2WTHEMDEY0** — ADR-112: Cache On by Default, Stat-Proxy Freshness as the Floor _(Technical)_ - **RAC-KX8GEA45HRBM** — ADR-113: Capture Writes Arrive Through a Sibling Surface, Not Guide _(Architecture)_ +- **RAC-KX9H2M7Q4V8C** — ADR-122: OKF v0.2 Is a Truthful Derived Carrier _(Architecture)_ +- **RAC-KXBD3T7Q9M2N** — ADR-123: Deterministic Decision-to-Code Enforcement _(Architecture)_ - **RAC-KXE0M2QBF2MP** — ADR-114: Native Index Workspace Dependencies — memmap2 In, inotify Deferred _(Technical)_ - **RAC-KXFK11FQDN1Y** — ADR-115: The Shared Artifact-Spec Registry Both Engines Read (ADR-063 Guard 1) _(Architecture)_ - **RAC-KXGVR299XY5E** — ADR-116: The Native Rust Engine Is a Sanctioned Second Implementation Under Lockstep Guards _(Architecture)_ +- **RAC-KYVTHFQD44BP** — ADR-124: Publish the Native MCP Server Through OCI and the Official Registry _(Architecture)_ +- **RAC-KYYC7HBFMRBA** — ADR-126: Package the Native MCP Server for Docker's MCP Catalog _(Architecture)_ +- **RAC-MCP20260728A** — ADR-121: Dual-Era MCP Protocol Compatibility _(Architecture)_ - **RAC-P55FRE5HNE55** — ADR-118: Native Event Freshness Acceleration - **RAC-P61BA5EDE7A0** — ADR-119: Base-Plus-Delta Serving Generations - **RAC-PYRE71RECER7** — ADR-120: Rust CI Uses Contract Fixtures and Live-Corpus Invariants diff --git a/.github/workflows/rust-spike.yml b/.github/workflows/rust-spike.yml index 10e85717..46d14de0 100644 --- a/.github/workflows/rust-spike.yml +++ b/.github/workflows/rust-spike.yml @@ -3,6 +3,9 @@ name: rust-spike +permissions: + contents: read + on: pull_request: paths: diff --git a/.mcp.json b/.mcp.json index 131e25d2..67a6237d 100644 --- a/.mcp.json +++ b/.mcp.json @@ -1,8 +1,8 @@ { "mcpServers": { - "lore": { - "command": "rac", - "args": ["mcp", "--root", "."] + "asdecided": { + "command": "decided-mcp", + "args": ["--root", "."] } } } diff --git a/AGENTS.md b/AGENTS.md index 62b4aa4c..bfaebe30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,16 @@ - + ## Settled decisions (AsDecided) -These decisions are already accepted. Do not re-open or contradict them; ask the `lore` MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +These decisions are already accepted. Do not re-open or contradict them; ask the AsDecided MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +- **RAC-01K8P7A3M5QZ** — ADR-125: Distribute AsDecided as a Local Pilot App _(Architecture)_ +- **RAC-01K8Q7MCP407** — ADR-129: Confine Rename Writes to the Corpus Root _(Technical)_ +- **RAC-01K8Q7MCP408** — ADR-130: Transactional Rename Application _(Technical)_ +- **RAC-01K8Q7MCP411** — ADR-128: Hard MCP Response Budgets _(Technical)_ +- **RAC-01K8Q7MCP413** — ADR-127: Attributable MCP Audit Records _(Technical)_ +- **RAC-01K8Q7MCP431** — ADR-131: Native Telemetry Is Local-Only _(Product)_ +- **RAC-01K8Q7MCP432** — ADR-132: AsDecided MCP Server Identity _(Product)_ - **RAC-KTQ63DPSMF19** — ADR-001 Markdown First - **RAC-KTQ63DPT6008** — ADR-002 AI Optional - **RAC-KTQ63DPVVB37** — ADR-003 Structured Outputs First @@ -84,9 +91,14 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KX04DH293JG8** — ADR-111: Revert to SemVer Release Versioning _(Process)_ - **RAC-KX2WTHEMDEY0** — ADR-112: Cache On by Default, Stat-Proxy Freshness as the Floor _(Technical)_ - **RAC-KX8GEA45HRBM** — ADR-113: Capture Writes Arrive Through a Sibling Surface, Not Guide _(Architecture)_ +- **RAC-KX9H2M7Q4V8C** — ADR-122: OKF v0.2 Is a Truthful Derived Carrier _(Architecture)_ +- **RAC-KXBD3T7Q9M2N** — ADR-123: Deterministic Decision-to-Code Enforcement _(Architecture)_ - **RAC-KXE0M2QBF2MP** — ADR-114: Native Index Workspace Dependencies — memmap2 In, inotify Deferred _(Technical)_ - **RAC-KXFK11FQDN1Y** — ADR-115: The Shared Artifact-Spec Registry Both Engines Read (ADR-063 Guard 1) _(Architecture)_ - **RAC-KXGVR299XY5E** — ADR-116: The Native Rust Engine Is a Sanctioned Second Implementation Under Lockstep Guards _(Architecture)_ +- **RAC-KYVTHFQD44BP** — ADR-124: Publish the Native MCP Server Through OCI and the Official Registry _(Architecture)_ +- **RAC-KYYC7HBFMRBA** — ADR-126: Package the Native MCP Server for Docker's MCP Catalog _(Architecture)_ +- **RAC-MCP20260728A** — ADR-121: Dual-Era MCP Protocol Compatibility _(Architecture)_ - **RAC-P55FRE5HNE55** — ADR-118: Native Event Freshness Acceleration - **RAC-P61BA5EDE7A0** — ADR-119: Base-Plus-Delta Serving Generations - **RAC-PYRE71RECER7** — ADR-120: Rust CI Uses Contract Fixtures and Live-Corpus Invariants diff --git a/CLAUDE.md b/CLAUDE.md index b5dfb3e7..3391c0c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,34 +1,41 @@ -# RAC — agent session context +# AsDecided — agent session context -This file is a router. Canonical agent guidance lives in `rac/prompts/`, -where the RAC corpus gates validate it. Do not add rules here — add them +This file is a router. Canonical agent guidance lives in `decisions/prompts/`, +where the AsDecided corpus gates validate it. Do not add rules here — add them to the corpus artifact and they load through the imports below. ## Loaded every session -@rac/prompts/rac-agent-session-start.md -@rac/prompts/rac-agent-commit-guidelines.md +@decisions/prompts/rac-agent-session-start.md +@decisions/prompts/rac-agent-commit-guidelines.md ## Situational prompts — read when the task calls for it, do not import -- Pull request preparation: `rac/prompts/rac-agent-pr-guidelines.md` -- Minor release gate: `rac/prompts/rac-agent-release-gate-minor.md` -- Major release gate: `rac/prompts/rac-agent-release-gate-major.md` -- Refactoring and simplification: `rac/prompts/rac-agent-simplification-guidelines.md` -- Context compression: `rac/prompts/rac-agent-compression.md` +- Pull request preparation: `decisions/prompts/rac-agent-pr-guidelines.md` +- Minor release gate: `decisions/prompts/rac-agent-release-gate-minor.md` +- Major release gate: `decisions/prompts/rac-agent-release-gate-major.md` +- Refactoring and simplification: `decisions/prompts/rac-agent-simplification-guidelines.md` +- Context compression: `decisions/prompts/rac-agent-compression.md` ## Working corpus -- Current series: `rac/roadmaps/v0.22.x-housekeeping/` (next up: v0.22.0) -- Previous series: `rac/roadmaps/v0.21.x-editor/` (complete) -- Decisions (ADRs): `rac/decisions/` +- Current roadmap: `decisions/roadmaps/future/` (release execution is tracked in GitHub) +- Historical roadmaps: `decisions/roadmaps/archive/` +- Decisions (ADRs): `decisions/decisions/` - + ## Settled decisions (AsDecided) -These decisions are already accepted. Do not re-open or contradict them; ask the `lore` MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +These decisions are already accepted. Do not re-open or contradict them; ask the AsDecided MCP tools (`get_artifact`, `search_artifacts`) for the full text before proposing a change that touches one. +- **RAC-01K8P7A3M5QZ** — ADR-125: Distribute AsDecided as a Local Pilot App _(Architecture)_ +- **RAC-01K8Q7MCP407** — ADR-129: Confine Rename Writes to the Corpus Root _(Technical)_ +- **RAC-01K8Q7MCP408** — ADR-130: Transactional Rename Application _(Technical)_ +- **RAC-01K8Q7MCP411** — ADR-128: Hard MCP Response Budgets _(Technical)_ +- **RAC-01K8Q7MCP413** — ADR-127: Attributable MCP Audit Records _(Technical)_ +- **RAC-01K8Q7MCP431** — ADR-131: Native Telemetry Is Local-Only _(Product)_ +- **RAC-01K8Q7MCP432** — ADR-132: AsDecided MCP Server Identity _(Product)_ - **RAC-KTQ63DPSMF19** — ADR-001 Markdown First - **RAC-KTQ63DPT6008** — ADR-002 AI Optional - **RAC-KTQ63DPVVB37** — ADR-003 Structured Outputs First @@ -109,9 +116,14 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KX04DH293JG8** — ADR-111: Revert to SemVer Release Versioning _(Process)_ - **RAC-KX2WTHEMDEY0** — ADR-112: Cache On by Default, Stat-Proxy Freshness as the Floor _(Technical)_ - **RAC-KX8GEA45HRBM** — ADR-113: Capture Writes Arrive Through a Sibling Surface, Not Guide _(Architecture)_ +- **RAC-KX9H2M7Q4V8C** — ADR-122: OKF v0.2 Is a Truthful Derived Carrier _(Architecture)_ +- **RAC-KXBD3T7Q9M2N** — ADR-123: Deterministic Decision-to-Code Enforcement _(Architecture)_ - **RAC-KXE0M2QBF2MP** — ADR-114: Native Index Workspace Dependencies — memmap2 In, inotify Deferred _(Technical)_ - **RAC-KXFK11FQDN1Y** — ADR-115: The Shared Artifact-Spec Registry Both Engines Read (ADR-063 Guard 1) _(Architecture)_ - **RAC-KXGVR299XY5E** — ADR-116: The Native Rust Engine Is a Sanctioned Second Implementation Under Lockstep Guards _(Architecture)_ +- **RAC-KYVTHFQD44BP** — ADR-124: Publish the Native MCP Server Through OCI and the Official Registry _(Architecture)_ +- **RAC-KYYC7HBFMRBA** — ADR-126: Package the Native MCP Server for Docker's MCP Catalog _(Architecture)_ +- **RAC-MCP20260728A** — ADR-121: Dual-Era MCP Protocol Compatibility _(Architecture)_ - **RAC-P55FRE5HNE55** — ADR-118: Native Event Freshness Acceleration - **RAC-P61BA5EDE7A0** — ADR-119: Base-Plus-Delta Serving Generations - **RAC-PYRE71RECER7** — ADR-120: Rust CI Uses Contract Fixtures and Live-Corpus Invariants diff --git a/decisions/decisions/adr-131-native-telemetry-sender-retirement.md b/decisions/decisions/adr-131-native-telemetry-sender-retirement.md new file mode 100644 index 00000000..c0d2a091 --- /dev/null +++ b/decisions/decisions/adr-131-native-telemetry-sender-retirement.md @@ -0,0 +1,72 @@ +--- +schema_version: 1 +id: RAC-01K8Q7MCP431 +type: decision +--- +# ADR-131: Native Telemetry Is Local-Only + +## Status + +Accepted + +## Category + +Product + +## Context + +ADR-041 defined an opt-in anonymous usage ping for the original Python +implementation. The native Rust cutover carries the consent record and the +`decided telemetry` compatibility command, but it does not contain a network +client or a sender. A compiled-in PostHog key therefore creates a misleading +security and procurement signal even though no request can be made. + +The product's current trust boundary is local-first and zero-egress. Public +documentation, CLI output, and source comments must describe the shipped +native binary rather than the historical sender design. + +## Decision + +ADR-041 is amended for the native engine: + +- `decided telemetry` remains a local consent and status record for compatibility + with existing configuration and the local usage read-back commands. +- The native engine sends no telemetry and contains no outbound telemetry + sender. There is no daily ping, endpoint, retry loop, or network side channel. +- The native build carries no PostHog write key. The consent record is retained + only as local state until a separately approved replacement is implemented. +- `decided usage --share` and `decided mcp-stats --share` remain explicit, + user-reviewed URL builders; they do not transmit anything automatically. +- Any future remote collection requires a new decision covering its data flow, + sender, consent, and enterprise/air-gap behavior. It must not be restored by + reintroducing the retired key or by changing documentation alone. + +ADR-086's enterprise lock remains valid: it prevents opt-in and records the +operator's hard-lock choice, but it is no longer the control that prevents a +native network request because the native sender does not exist. + +## Consequences + +The native binary's zero-egress claim is now directly reflected in its CLI, +documentation, and source. Existing consent files remain readable and safe to +remove. The old ADR-041 payload and PostHog design remain historical context; +they are not a promise about the native release line. + +The retention signal described by ADR-041 is not available from the native +binary. If that signal becomes necessary, it must be designed and reviewed as +a new product surface rather than silently revived. + +## Related Decisions + +- adr-040 +- adr-041 +- adr-046 +- adr-086 + +## Applies To + +- rust/rac-engine/src/consent.rs +- rust/rac-engine/src/commands.rs +- docs/cli.md +- docs/index.md +- docs/security.md diff --git a/decisions/decisions/adr-132-asdecided-server-identity.md b/decisions/decisions/adr-132-asdecided-server-identity.md new file mode 100644 index 00000000..567c5ce3 --- /dev/null +++ b/decisions/decisions/adr-132-asdecided-server-identity.md @@ -0,0 +1,57 @@ +--- +schema_version: 1 +id: RAC-01K8Q7MCP432 +type: decision +--- +# ADR-132: AsDecided MCP Server Identity + +## Status + +Accepted + +## Category + +Product + +## Context + +The native cutover completed the move from the historical RAC/Lore product +names to AsDecided. Some older decisions and requirements necessarily retain +the names that were true when they were recorded, but current generated +configuration and public guidance must have one identity. Emitting a retired +server key from the native scaffold makes a fresh install look like a legacy +integration and leaves agents with two competing names for the same service. + +## Decision + +- `asdecided` is the canonical local MCP server key and `decided-mcp` is the + canonical native server binary. +- `asdecided-org` is the canonical key emitted by `decided init + --org-endpoint ` for a shared organisation endpoint. +- New examples, generated configuration, documentation, and agent guidance + MUST use the AsDecided names. The native scaffold MUST NOT emit the retired + `lore` or `lore-org` keys. +- Historical ADRs, fixtures, and migration notes keep their original wording + as evidence. They are not current configuration instructions; a later + amendment or superseding decision is the route for changing their meaning. +- The `decided` CLI and `decided-mcp` server remain the public command surface. + Compatibility state in old records does not create a supported `rac` command. + +## Consequences + +Fresh installs and generated agent configuration now have one unambiguous +server identity. Existing hand-written configurations are not rewritten by +this decision; operators can migrate their keys explicitly, and the current +docs show only the native names. The identity change is configuration-only and +does not alter MCP wire semantics or the read-only serving boundary. + +## Related Decisions + +- ADR-117 +- ADR-121 +- ADR-124 +- ADR-131 + +## Related Requirements + +- rac-org-endpoint-wiring diff --git a/decisions/prompts/rac-agent-pr-guidelines.md b/decisions/prompts/rac-agent-pr-guidelines.md index b9beed0d..31b2f80a 100644 --- a/decisions/prompts/rac-agent-pr-guidelines.md +++ b/decisions/prompts/rac-agent-pr-guidelines.md @@ -11,7 +11,7 @@ Generate a pull request description that acts as durable repository memory after implementation conversations, AI sessions, and local context disappear. -RAC development follows a roadmap-contract workflow: features are planned +AsDecided development follows a roadmap-contract workflow: features are planned through explicit Roadmap artifacts, architectural decisions are captured through ADRs, and implementation happens through small scoped changes. A PR should preserve what changed, why decisions were made, what was @@ -32,7 +32,7 @@ for the RAC change being documented. ## Instructions -Generate a pull request description for a RAC change. Use the implementation +Generate a pull request description for an AsDecided change. Use the implementation details, roadmap item, ADRs, commits, and code changes provided. Structure the PR as a release-contract record, using the format in Output. @@ -68,10 +68,10 @@ Adds: # Roadmap / ADR Trace Roadmap: -- `rac/roadmaps/vX.Y.Z-.md` +- `decisions/roadmaps/.md` Relevant ADRs: -- `rac/decisions/.md` +- `decisions/decisions/.md` # Scope @@ -110,8 +110,8 @@ Fields or shape changes. # Verification ## Ran -Exact verification commands (for example: pytest, rac , -rac --json). +Exact verification commands (for example: `cargo test --workspace --release`, +`decided `, `decided --json`). ## Covered Tested scenarios: positive, negative, boundary. Avoid "tests pass"; diff --git a/decisions/prompts/rac-agent-release-gate-minor.md b/decisions/prompts/rac-agent-release-gate-minor.md index 71cbb4ce..42aea8be 100644 --- a/decisions/prompts/rac-agent-release-gate-minor.md +++ b/decisions/prompts/rac-agent-release-gate-minor.md @@ -39,7 +39,8 @@ Before completing any 0.x.n release, answer each question below. - Are adjacent artifact types tested against each other? - Are incomplete-but-recognizable artifacts tested? - Are CLI human and JSON outputs tested? -- Was pytest run before commit? +- Was the relevant Rust test battery run before commit (normally + `cargo test --workspace --release`)? ## Output diff --git a/decisions/prompts/rac-agent-session-start.md b/decisions/prompts/rac-agent-session-start.md index 12bed8cf..9e282ae5 100644 --- a/decisions/prompts/rac-agent-session-start.md +++ b/decisions/prompts/rac-agent-session-start.md @@ -3,25 +3,25 @@ schema_version: 1 id: RAC-KV2J31Z1EV4T type: prompt --- -# RAC Agent Session Start +# AsDecided Agent Session Start ## Objective -Establish the working frame for an agent session on RAC, so changes stay +Establish the working frame for an agent session on AsDecided, so changes stay correctly scoped, respect recorded decisions, and pass the corpus gates before they are pushed. -RAC is a Python CLI for requirements-as-code. It models product-management -Markdown artifacts as deterministic, typed artifacts. Current artifact -families include Requirements, Decisions, Roadmaps, Prompts, and Design. +AsDecided is a native Rust CLI and MCP server. It models requirements, +decisions, roadmaps, prompts, and designs as deterministic, typed Markdown +artifacts served from the repository that owns them. ## Input -- The RAC repository and its corpus under `rac/` — requirements, decisions +- The AsDecided repository and its corpus under `decisions/` — requirements, decisions (ADRs), roadmaps, prompts, and designs. - The roadmap item relevant to the task, and the ADRs it touches. -- The `lore` MCP tools when available in the session; without them, the - same knowledge via the `rac` CLI (`find`, `resolve`, `relationships`). +- The AsDecided MCP tools when available in the session; without them, the + same knowledge via the `decided` CLI (`find`, `resolve`, `relationships`). ## Instructions @@ -36,9 +36,9 @@ families include Requirements, Decisions, Roadmaps, Prompts, and Design. - Keep classification separate from validation. - Invalid but recognizable artifacts may still classify as their artifact type, then fail validation. - Durable thinking lives in the corpus, not in ephemeral tool scratch space. - Record plans, designs, and decisions as RAC artifacts under `rac/` — a + Record plans, designs, and decisions as AsDecided artifacts under `decisions/` — a Design for the *how*, a Roadmap for the *what/why* (a non-versioned - `rac/roadmaps/future/` item when unscheduled), an ADR for a decision — + `decisions/roadmaps/future/` item when unscheduled), an ADR for a decision — where the gates validate them. A tool's plan or scratch file is working memory only; it has no authority and does not persist. @@ -51,7 +51,7 @@ families include Requirements, Decisions, Roadmaps, Prompts, and Design. 5. Produce an implementation contract. 6. Wait for approval. -### Grounding (when the `lore` MCP tools are available in your session) +### Grounding (when the AsDecided MCP tools are available in your session) - Call `get_summary` once at session start to learn what recorded knowledge exists. @@ -62,14 +62,14 @@ families include Requirements, Decisions, Roadmaps, Prompts, and Design. - Cite decisions by ID. If a task conflicts with a recorded decision, say so and stop — do not silently override it. -Without the tools, the same knowledge lives under `rac/`; use the `rac` CLI +Without the tools, the same knowledge lives under `decisions/`; use the `decided` CLI (`find`, `resolve`, `relationships`) instead. ### Testing - Add negative boundary tests for each new artifact type. - Test that adjacent artifact types do not misclassify as each other. -- Run pytest before commit. +- Run the relevant Rust tests before commit, normally `cargo test --workspace --release`. ## Output @@ -88,9 +88,9 @@ After a GitHub merge, refresh local main; prune merged branches when asked. Before pushing: -- `rac validate rac/` and `rac relationships rac/ --validate` exit 0. -- `rac review rac/` reports no priority 1-2 findings. -- Commits follow `rac/prompts/rac-agent-commit-guidelines.md`: format, +- `decided validate decisions/` and `decided relationships decisions/ --validate` exit 0. +- `decided review decisions/` reports no priority 1-2 findings. +- Commits follow `decisions/prompts/rac-agent-commit-guidelines.md`: format, maintainer identity on author and committer, no tool attribution. ## Related Decisions diff --git a/decisions/prompts/rac-agent-simplification-guidelines.md b/decisions/prompts/rac-agent-simplification-guidelines.md index 4fbd283d..eedd3bbc 100644 --- a/decisions/prompts/rac-agent-simplification-guidelines.md +++ b/decisions/prompts/rac-agent-simplification-guidelines.md @@ -3,14 +3,14 @@ schema_version: 1 id: RAC-KV2J371GG7K7 type: prompt --- -# RAC Module Simplification Refactor Contract +# AsDecided Module Simplification Refactor Contract ## Objective -Reduce implementation complexity in a target RAC module without changing +Reduce implementation complexity in a target AsDecided module without changing user-facing behavior. -RAC has grown quickly through roadmap-led implementation, and some modules +AsDecided has grown quickly through roadmap-led implementation, and some modules now risk accumulating additive paths faster than they are simplified. This prompt is for behavior-preserving module simplification. @@ -21,7 +21,7 @@ prompt is for behavior-preserving module simplification. ## Instructions -We are simplifying the Python modules in `requirements-as-code`. +We are simplifying the native Rust modules in `rust/`. Before editing: diff --git a/decisions/requirements/rac-org-endpoint-wiring.md b/decisions/requirements/rac-org-endpoint-wiring.md index a325b9ca..9f01014c 100644 --- a/decisions/requirements/rac-org-endpoint-wiring.md +++ b/decisions/requirements/rac-org-endpoint-wiring.md @@ -3,7 +3,7 @@ schema_version: 1 id: RAC-KXS19RDVX4DJ type: requirement --- -# Requirement: Org Endpoint Wiring +# Requirement: AsDecided Org Endpoint Wiring > The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are > to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only @@ -16,7 +16,7 @@ Accepted ## Problem The org grounding plane (ADR-117) needs every repository in a fleet wired to -the organisation's shared Lore endpoint, and hand-editing client JSON across +the organisation's shared AsDecided endpoint, and hand-editing client JSON across hundreds of repositories is exactly the per-repo tax the topology exists to remove. The engine already emits client wiring at init time (ADR-088), but only at creation and only for the local stdio server. Wiring the org @@ -27,37 +27,37 @@ file's other content. ## Requirements -- [REQ-001] `rac init` MUST accept an `--org-endpoint ` option. The URL MUST begin with `http://` or `https://`; any other value is a usage error and nothing is written. +- [REQ-001] `decided init` MUST accept an `--org-endpoint ` option. The URL MUST begin with `http://` or `https://`; any other value is a usage error and nothing is written. -- [REQ-002] With the flag, the engine MUST ensure a `lore-org` entry of the shape `{"type": "http", "url": }` exists under `mcpServers` in both `.mcp.json` and `.cursor/mcp.json`, creating a file (with exactly that entry) when it is absent. +- [REQ-002] With the flag, the engine MUST ensure an `asdecided-org` entry of the shape `{"type": "http", "url": }` exists under `mcpServers` in both `.mcp.json` and `.cursor/mcp.json`, creating a file (with exactly that entry) when it is absent. -- [REQ-003] The flag MUST apply on a fresh init and on an already-initialized repository alike: org wiring is an explicit operator action (ADR-117), not creation-time configuration, and `.rac/config.yaml` is not touched by it on either path. +- [REQ-003] The flag MUST apply on a fresh init and on an already-initialized repository alike: org wiring is an explicit operator action (ADR-117), not creation-time configuration, and `.decided/config.yaml` is not touched by it on either path. -- [REQ-004] Merging into an existing client config MUST preserve every byte of meaning the user wrote outside the `lore-org` key: other servers, other top-level keys, and key order are retained; only the `lore-org` entry is added or updated. When the file exists with a different `lore-org` URL, the URL is updated — the operator named the endpoint explicitly. +- [REQ-004] Merging into an existing client config MUST preserve every byte of meaning the user wrote outside the `asdecided-org` key: other servers, other top-level keys, and key order are retained; only the `asdecided-org` entry is added or updated. When the file exists with a different `asdecided-org` URL, the URL is updated — the operator named the endpoint explicitly. - [REQ-005] The operation MUST be idempotent: a second run with the same URL writes no file and reports no file written. - [REQ-006] A client config that cannot be parsed as a JSON object with a `mcpServers` mapping MUST produce a structured error naming the file, exit non-zero, and leave every target file unmodified — no partial writes. -- [REQ-007] Without the flag, `rac init` behaviour and output MUST remain byte-identical to the previous engine (ADR-007); the existing profile and init contracts are unchanged. +- [REQ-007] Without the flag, `decided init` behaviour and output MUST remain byte-identical to the previous engine (ADR-007); the existing profile and init contracts are unchanged. - [REQ-008] The `--json` contract MUST grow additively (ADR-007): an `org_endpoint` field (the URL, or null when the flag was absent) and the org-written files appended to `files_written`. ## Acceptance Criteria -- Fresh directory, `rac init --org-endpoint https://lore.example.com/mcp`: - both client configs exist and carry exactly the `lore-org` HTTP entry; +- Fresh directory, `decided init --org-endpoint https://asdecided.example.com/mcp`: + both client configs exist and carry exactly the `asdecided-org` HTTP entry; `files_written` lists both. - Already-initialized repository: the same command adds the entry to both - files, reports `created: false`, and leaves `.rac/config.yaml` untouched. -- A hand-written `.mcp.json` with its own servers gains the `lore-org` key - and loses nothing; a differing `lore-org` URL is updated in place. + files, reports `created: false`, and leaves `.decided/config.yaml` untouched. +- A hand-written `.mcp.json` with its own servers gains the `asdecided-org` key + and loses nothing; a differing `asdecided-org` URL is updated in place. - Re-running with the same URL is a no-op: no files written, none reported. - An unparseable `.mcp.json` yields a structured error, a non-zero exit, and unmodified files. -- `rac init` without the flag is covered by the existing batteries - unchanged, and `--profile` composes with `--org-endpoint` (local `lore` - and `lore-org` entries side by side). +- `decided init` without the flag is covered by the existing batteries + unchanged, and `--profile` composes with `--org-endpoint` (local `asdecided` + and `asdecided-org` entries side by side). ## Success Metrics @@ -88,6 +88,7 @@ file's other content. - adr-088 - adr-098 - adr-117 +- adr-132 ## Related Roadmaps diff --git a/docs/cli.md b/docs/cli.md index 8d95805c..0a41a522 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -858,16 +858,16 @@ artifacts — existing output is overwritten. decided export decisions/ # viewer JSON to stdout decided export decisions/ --documents # JSONL, one record per artifact decided export decisions/ --graph # typed node+edge graph -decided export decisions/ --html --out lore.html +decided export decisions/ --html --out asdecided.html ``` ### Exporting to external memory / RAG / graph backends -`--documents` and `--graph` exist to feed RAC's recorded decisions into the tools +`--documents` and `--graph` exist to feed AsDecided's recorded decisions into the tools teams already run, so an agent can recall fuzzily there and then **verify in AsDecided**. They are additive (ADR-007): the default viewer JSON is unchanged, and nothing here computes embeddings — that stays in the consuming backend (ADR-002, -ADR-066). The connectors themselves live in the separate `lore-connectors` +ADR-066). The connectors themselves live in the separate `asdecided-connectors` companion, one module per backend rather than a repo per provider (ADR-073). **What it exports to, by name.** The shapes are deliberately the common @@ -883,7 +883,7 @@ ingestion denominators, so most targets need no bespoke code: - **`--graph` (one node+edge JSON object)** — graph / GraphRAG backends (**Neo4j**, **Zep Graphiti**, **Cognee**, **Microsoft GraphRAG**). Nodes are `{id, type, status, title}`; edges carry the real relationship kind - (`supersedes`, `related_*`) and direction, so the backend gets RAC's validated + (`supersedes`, `related_*`) and direction, so the backend gets AsDecided's validated decision graph instead of one inferred from prose. **How the answer is then validated (verify-in-AsDecided).** The backend gives @@ -1118,30 +1118,30 @@ default. `--json` and `--share` are mutually exclusive. ## telemetry -Show or change anonymous usage-sharing consent (ADR-041). With consent on, -the native CLI sends at most one anonymous daily ping — a random install id, the -version, and an active-repo count; never paths, queries, or repository -content. Sharing is independent of MCP serving; `decided-mcp` never sends -product telemetry. +Show or change the local usage-sharing preference (ADR-131). The native +engine records this preference for compatibility with the local usage +read-back commands, but it has no outbound telemetry sender, endpoint, or +network side channel. `decided-mcp` never sends product telemetry. ```bash -decided telemetry # status (default): what is shared, and whether sending is possible -decided telemetry on # opt in; mints a random install id -decided telemetry off # opt out; nothing else changes -decided telemetry off --enterprise # hard-lock the ping off (forces the kill state, refuses 'on') +decided telemetry # status (default): local preference and consent file +decided telemetry on # record local opt-in; mints a random install id +decided telemetry off # record local opt-out +decided telemetry off --enterprise # hard-lock sharing off for regulated installs decided telemetry off --enterprise --unlock # remove the enterprise hard-lock ``` -`status` also reports when the build has no endpoint key configured — in -that state nothing is sent even with consent. Consent lives at -`~/.config/decisions/telemetry.json`. +Consent lives at `~/.config/decisions/telemetry.json`. `status` reports that +the native endpoint is not configured: opting in does not send anything. +Explicit `decided usage --share` and `decided mcp-stats --share` URLs remain +user-reviewed, manual sharing paths. **Enterprise hard-lock (ADR-086).** For regulated installs that must *prove* the -ping is off, `decided telemetry off --enterprise` forces the kill state at runtime -(independent of the build's endpoint key), records a persistent lock, and refuses -`decided telemetry on` until it is removed with `decided telemetry off --enterprise ---unlock`. While locked, `status` reports `Sharing: locked (enterprise)`. The lock -governs the anonymous ping only. +sharing is off, `decided telemetry off --enterprise` records a persistent lock +and refuses `decided telemetry on` until it is removed with `decided telemetry +off --enterprise --unlock`. While locked, `status` reports +`Sharing: locked (enterprise)`. ADR-131 makes this an explicit local state +control; there is no native sender to disable. - **Exit codes:** `0` consent shown or changed · `2` invalid action, or `on` refused while enterprise-locked @@ -1253,13 +1253,13 @@ configuration, not artifact meaning — it never dictates folder structure. is unchanged. A parent-corpus line is added once corpus federation ships (ADR-089); until then the enterprise profile is hollow on it. - **`--org-endpoint URL`** wires the shared **org AsDecided endpoint** (ADR-117): it - ensures a `lore-org` entry — `{"type": "http", "url": URL}` — under + ensures an `asdecided-org` entry — `{"type": "http", "url": URL}` — under `mcpServers` in `.mcp.json` and `.cursor/mcp.json`. Unlike a profile, org wiring is an explicit operator action, so it also applies to an **already-initialized** repository: it merges into an existing file, touches - only the `lore-org` key, never removes what you wrote, and a re-run with the + only the `asdecided-org` key, never removes what you wrote, and a re-run with the same URL writes nothing. The URL must start with `http://` or `https://`. - Composes with `--profile` (local `lore` and `lore-org` side by side). See + Composes with `--profile` (local `asdecided` and `asdecided-org` side by side). See [Org Grounding](org-grounding.md). - **Exit codes:** `0` initialized, or already initialized with the same key (idempotent) · `1` a different key is already established (never silently @@ -1277,7 +1277,7 @@ decided init decided init --key PROJ decided init --key ACME --ticketing jira decided init --key ACME --profile enterprise -decided init --org-endpoint https://lore.example.com/mcp +decided init --org-endpoint https://asdecided.example.com/mcp decided init docs/ --json ``` diff --git a/docs/ecosystem.md b/docs/ecosystem.md index ed80dd98..59ef857b 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -9,12 +9,12 @@ planned or placeholder entries. | --- | --- | --- | | RAC dogfood corpus | This repository's own product knowledge — requirements, decisions, roadmaps, prompts, designs — validated in CI by the engine it specifies | [`decisions/`](https://github.com/asdecided/core/tree/main/decisions/) | | `rac-artifacts` Claude Code skill | A project-level agent skill that teaches Claude Code to create, validate, and update RAC artifacts using the `rac` CLI | [`.claude/skills/rac-artifacts/`](https://github.com/asdecided/core/blob/main/.claude/skills/rac-artifacts/SKILL.md) | -| MCP grounding example | A runnable demo showing an agent connected to RAC Guide over MCP respecting a recorded decision that an unconnected agent violates | [`examples/guide/`](https://github.com/asdecided/core/blob/main/examples/guide/demo.md) | -| Amp setup | A worked setup connecting Sourcegraph's Amp to RAC — it reads the generated `AGENTS.md` natively and queries the `lore` MCP server | [`examples/amp/`](https://github.com/asdecided/core/blob/main/examples/amp/README.md) | -| Claude Code setup | A worked setup connecting Claude Code to RAC — the generated `CLAUDE.md`, the `lore` MCP server, the `rac-artifacts` skill, and the optional pre-edit veto hook | [`examples/claude-code/`](https://github.com/asdecided/core/blob/main/examples/claude-code/README.md) | -| Codex setup | A worked setup connecting OpenAI Codex to RAC — it reads the generated `AGENTS.md` and queries the `lore` MCP server via `config.toml` | [`examples/codex/`](https://github.com/asdecided/core/blob/main/examples/codex/README.md) | -| Cursor setup | A worked setup connecting Cursor to RAC — it reads the generated `AGENTS.md` and queries the `lore` MCP server via `.cursor/mcp.json` | [`examples/cursor/`](https://github.com/asdecided/core/blob/main/examples/cursor/README.md) | -| GitHub Copilot setup | A worked setup connecting Copilot in VS Code to RAC — the generated `.github/copilot-instructions.md` plus the `lore` MCP server in agent mode | [`examples/copilot/`](https://github.com/asdecided/core/blob/main/examples/copilot/README.md) | +| MCP grounding example | A runnable demo showing an agent connected to AsDecided over MCP respecting a recorded decision that an unconnected agent violates | [`examples/guide/`](https://github.com/asdecided/core/blob/main/examples/guide/demo.md) | +| Amp setup | A worked setup connecting Sourcegraph's Amp to RAC — it reads the generated `AGENTS.md` natively and queries the `asdecided` MCP server | [`examples/amp/`](https://github.com/asdecided/core/blob/main/examples/amp/README.md) | +| Claude Code setup | A worked setup connecting Claude Code to RAC — the generated `CLAUDE.md`, the `asdecided` MCP server, the `rac-artifacts` skill, and the optional pre-edit veto hook | [`examples/claude-code/`](https://github.com/asdecided/core/blob/main/examples/claude-code/README.md) | +| Codex setup | A worked setup connecting OpenAI Codex to RAC — it reads the generated `AGENTS.md` and queries the `asdecided` MCP server via `config.toml` | [`examples/codex/`](https://github.com/asdecided/core/blob/main/examples/codex/README.md) | +| Cursor setup | A worked setup connecting Cursor to RAC — it reads the generated `AGENTS.md` and queries the `asdecided` MCP server via `.cursor/mcp.json` | [`examples/cursor/`](https://github.com/asdecided/core/blob/main/examples/cursor/README.md) | +| GitHub Copilot setup | A worked setup connecting Copilot in VS Code to RAC — the generated `.github/copilot-instructions.md` plus the `asdecided` MCP server in agent mode | [`examples/copilot/`](https://github.com/asdecided/core/blob/main/examples/copilot/README.md) | ## Adding an entry diff --git a/docs/governance.md b/docs/governance.md index dfff5521..2a9c6cd5 100644 --- a/docs/governance.md +++ b/docs/governance.md @@ -1,6 +1,6 @@ # Governance: the enforcement policy & `decided gate` -`decided gate` is RAC's single enforcement entry point. It runs validation, +`decided gate` is AsDecided's single enforcement entry point. It runs validation, relationship integrity, and review over a corpus, then classifies every finding as **blocking** or **advisory** under the corpus *enforcement policy*. One command, one exit code, one SARIF document — so a pull-request gate carries the @@ -162,7 +162,7 @@ and the explicitly declared machine-checkable subset of code constraints — - **Context supply.** `decided export --agent-rules` generates committed, drift-guarded rules files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, - `.github/copilot-instructions.md`) plus the `lore` MCP read tools. This reaches + `.github/copilot-instructions.md`) plus the `asdecided` MCP read tools. This reaches *every* agent — including Copilot — with zero per-developer setup. - **Post-edit enforcement.** The same structural diagnostics fire on agent-written artifacts exactly as on human edits. `decided sentry` and diff --git a/docs/index.md b/docs/index.md index a3342460..fc1441fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -102,17 +102,17 @@ AsDecided asks you to trust it with your product knowledge, so it holds itself t - **The MCP server is read-only by construction.** It cannot create, modify, or delete files in your repo — enforced in code and verified by tests, not by convention. - **No AI in the core.** Retrieval is deterministic: the same repo state and the same query always return the same result. The reasoning is your agent's job; AsDecided's job is to hand it the facts. -- **It dogfoods itself.** AsDecided's own planning corpus under [`decisions/`](https://github.com/asdecided/core/tree/main/rac) is validated by RAC in CI — if the tool's rules break the tool's own artifacts, the build fails. +- **It dogfoods itself.** AsDecided's own planning corpus under [`decisions/`](https://github.com/asdecided/core/tree/main/decisions) is validated by the native engine in CI — if the tool's rules break the tool's own artifacts, the build fails. - **Output is a contract.** Golden tests pin CLI and MCP output; any change to what the tools return is reviewed as a product change. -- **Telemetry is opt-in.** Optional anonymous sharing is configured explicitly with `decided telemetry on` (or one honest question at `decided init`): one daily ping with a random install id, the version, and an active-repo count — never paths, queries, or repository content. `decided telemetry status` shows exactly what is shared, the network surface is a single readable module, and ADR-041 records the decision. The native MCP server itself never sends telemetry. +- **No outbound telemetry in the native build.** `decided telemetry` records a local compatibility preference only; the Rust engine contains no sender, endpoint, or network side channel. `decided usage --share` and `decided mcp-stats --share` build explicit URLs for a user to review and submit. ADR-131 records this cutover. ## Sharing the corpus (the Portal) -Agents read your lore over MCP; people get the Portal — a single self-contained HTML file of the whole corpus that opens from `file://` with zero network requests. Attach it to a release, send it to a stakeholder, open it on a plane. +Agents read your governed corpus over MCP; people get the Portal — a single self-contained HTML file of the whole corpus that opens from `file://` with zero network requests. Attach it to a release, send it to a stakeholder, open it on a plane. ```bash decided export decisions/ # canonical JSON to stdout -decided export decisions/ --html --out lore-export.html # the Portal, one file +decided export decisions/ --html --out asdecided-export.html # the Portal, one file ``` The JSON payload is a stable contract (artifacts with ids, aliases, status, rendered bodies; relationships as edges) for anyone building their own viewer. The Portal ships search, type/status filters, and citation cross-links out of the box. @@ -121,4 +121,4 @@ The JSON payload is a stable contract (artifacts with ids, aliases, status, rend AsDecided is early and evolving quickly. The MCP server ships today; feedback from teams running agents in anger is exactly what shapes what comes next. Contributions, ideas, and experiments welcome — see [CONTRIBUTING.md](https://github.com/asdecided/core/blob/main/CONTRIBUTING.md). -[GitHub repository](https://github.com/asdecided/core) · [MIT license](https://github.com/asdecided/core/blob/main/LICENSE) +[GitHub repository](https://github.com/asdecided/core) · [Apache-2.0 license](https://github.com/asdecided/core/blob/main/LICENSE) diff --git a/docs/integration-recipes.md b/docs/integration-recipes.md index 4a9aa5f2..79b49def 100644 --- a/docs/integration-recipes.md +++ b/docs/integration-recipes.md @@ -1,13 +1,13 @@ # Integration recipes — authoring guide RAC meets a coding agent on two surfaces it does not own: a generated -agent-instructions file the agent reads (the **push**), and the `lore` MCP server +agent-instructions file the agent reads (the **push**), and the `asdecided` MCP server the agent connects to for live retrieval (the **pull**). Because both are standard surfaces, connecting a new harness is **documentation, not engine work** — a worked `examples//` setup plus a row in [`docs/ecosystem.md`](ecosystem.md). This guide is the authoring contract for those recipes. The shapes recur — the same -`lore` invocation in three config dialects, the same push/pull/enforcement README +`asdecided` invocation in three config dialects, the same push/pull/enforcement README structure, the same "verify with the grounding demo" close — so a new recipe is filling a template, not reverse-engineering an existing one. Every recipe adds **zero `asdecided-core` engine diff**: it consumes only the two stable surfaces (the @@ -17,7 +17,7 @@ stores and serves nothing new (ADR-024). ## The template Copy [`examples/_recipe-template/`](../examples/_recipe-template/) to -`examples//` and fill it in. It carries the README skeleton and the `lore` +`examples//` and fill it in. It carries the README skeleton and the `asdecided` invocation in all three config dialects; the inline HTML comments tell you what to replace and what to leave alone. You should be able to produce a complete, structurally consistent recipe from the template and this checklist **without @@ -29,20 +29,22 @@ template (ADR-021). A recipe README has these parts, in this order: 1. **Title and framing** — `# RAC with `, then one line naming the two - surfaces (the context file the client reads, and the `lore` MCP server). + surfaces (the context file the client reads, and the `asdecided` MCP server). 2. **Prerequisites** — `brew install asdecided/tap/asdecided-core` and a corpus under `decisions/`. 3. **Context file (the push)** — `decided export decisions/ --agent-rules`, and which generated file this client reads (`AGENTS.md` is the glob-free default; `CLAUDE.md` and `.github/copilot-instructions.md` are the other targets). -4. **The `lore` MCP server (the pull)** — the config path for this client and the - server invocation in the client's dialect (below). Name the five read-only - tools and note the server re-reads the corpus per call and never writes. +4. **The `asdecided` MCP server (the pull)** — the config path for this client and the + server invocation in the client's dialect (below). Name the six read-only + tools (`get_artifact`, `search_artifacts`, `retrieve_grounding`, + `find_decisions`, `get_related`, `get_summary`) and note the server re-reads + the corpus per call and never writes. 5. **Enforcement is separate** — the fixed ADR-067 paragraph (below). Do not reword it. 6. **Verify it** — the grounding demo, [`examples/guide/`](../examples/guide/demo.md). -7. **Summary** — the three-row table (context file, `lore` MCP, CI gate). +7. **Summary** — the three-row table (context file, `asdecided` MCP, CI gate). -### The `lore` invocation, in three dialects +### The `asdecided` invocation, in three dialects Every recipe runs the same server — `decided-mcp --root .` — expressed in whichever config dialect the harness uses. Keep only the one your harness reads. @@ -52,14 +54,14 @@ config dialect the harness uses. Keep only the one your harness reads. ``` ```toml -[mcp_servers.lore] +[mcp_servers.asdecided] command = "decided-mcp" args = ["--root", "."] ``` ```yaml mcpServers: - lore: + asdecided: command: decided-mcp args: [--root, .] ``` @@ -73,7 +75,7 @@ Every recipe's enforcement section describes **context-supply plus post-edit CI only** — never a pre-edit interception hook — restated identically so the boundary never drifts. Copy this paragraph verbatim, swapping only the client name: -> RAC supplies context and enforces *after* the edit (ADR-067). There is no +> AsDecided supplies context and enforces *after* the edit (ADR-067). There is no > platform API to veto a `` agent edit before it lands, so `` > relies on the post-edit guard: `decided validate` / `decided relationships --validate` > and the GitHub Action / pre-merge gate, the same as any contributor. @@ -90,7 +92,7 @@ every other recipe points readers there rather than describing a hook of its own - [ ] Section 1 names `decided export decisions/ --agent-rules` and the exact context file this client reads. - [ ] Section 2 shows the one config dialect and path this client uses, and names - the five read-only tools. + the six read-only tools. - [ ] Section 3 is the fixed ADR-067 paragraph, client name swapped, nothing else changed — no pre-edit hook described. - [ ] The "Verify it" close points at [`examples/guide/`](../examples/guide/demo.md). diff --git a/docs/mcp.md b/docs/mcp.md index 3c4063a7..713f094c 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -11,8 +11,9 @@ brew install asdecided/tap/asdecided-core ``` No Python runtime or extra is needed. The server is read-only and has no -network side channel; optional anonymous product sharing is configured -separately with `decided telemetry` and does not change MCP responses. +network side channel. The native `decided telemetry` command records local +compatibility state only; it has no sender and does not change MCP responses +(ADR-131). ## Protocol compatibility diff --git a/docs/quickstart.md b/docs/quickstart.md index da318d1d..5dae0f42 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,6 +1,6 @@ # Quickstart -Try RAC in about five minutes. You will install the tool, scaffold your first +Try AsDecided in about five minutes. You will install the tool, scaffold your first artifact, and run the three commands you'll use most: `validate`, `inspect`, and `improve`. @@ -30,7 +30,7 @@ In CI, pin a release tag rather than `latest`, or pin by digest for immutable builds (the release run prints the pushed digest in its summary): ```bash -docker pull ghcr.io/asdecided/core:2026.6.1 +docker pull ghcr.io/asdecided/core:v0.26.2 docker pull ghcr.io/asdecided/core@sha256: ``` @@ -41,7 +41,7 @@ can run script steps): ```yaml rac-gate: image: - name: ghcr.io/asdecided/core:2026.6.1 + name: ghcr.io/asdecided/core:v0.26.2 entrypoint: [""] script: - decided gate decisions/ @@ -55,7 +55,7 @@ pipelines: '**': - step: name: decided gate - image: ghcr.io/asdecided/core:2026.6.1 + image: ghcr.io/asdecided/core:v0.26.2 script: - decided gate decisions/ ``` @@ -64,7 +64,7 @@ Jenkins (declarative pipeline, docker agent): ```groovy pipeline { - agent { docker { image 'ghcr.io/asdecided/core:2026.6.1' } } + agent { docker { image 'ghcr.io/asdecided/core:v0.26.2' } } stages { stage('decided gate') { steps { sh 'decided gate decisions/' } @@ -124,7 +124,7 @@ first-class authentication flow, so access control is inconsistent across the ap - Authentication-related support tickets drop by half within one quarter. ``` -> RAC classifies artifacts by their `##` section headings — no front matter to +> AsDecided classifies artifacts by their `##` section headings — no front matter to > memorize. (Identity ids in frontmatter are assigned for you by `decided new` and > `decided quickstart`.) See [artifacts.md](artifacts.md). diff --git a/docs/relationships.md b/docs/relationships.md index 69a5f8cc..977bfcc8 100644 --- a/docs/relationships.md +++ b/docs/relationships.md @@ -79,7 +79,7 @@ the provider is named in config, shape-identical keys across trackers (Linear's engine validates against exactly one format. The engine **never contacts the tracker**: checking that a ticket exists or is in -an allowed state needs a token and lives in a satellite (`lore-atlassian` for Jira, +an allowed state needs a token and lives in a satellite (`asdecided-atlassian` for Jira, ADR-090), not the engine (ADR-002). In `decided export --graph` an external edge carries `"external": true`, diff --git a/docs/repo-workflow.md b/docs/repo-workflow.md index d6576f4b..933f902b 100644 --- a/docs/repo-workflow.md +++ b/docs/repo-workflow.md @@ -25,12 +25,12 @@ easy to read. ### Three documentation layers -RAC's own repository separates concerns into three layers +AsDecided's own repository separates concerns into three layers ([ADR-022](https://github.com/asdecided/core/blob/main/decisions/decisions/adr-022-documentation-boundaries.md)): - **`README.md`** — the front door: what RAC is and how to try it. - **`docs/`** — user-facing guides (this directory). -- **`decisions/`** — RAC's internal, structured product knowledge. +- **`decisions/`** — AsDecided's internal, structured product knowledge. `decisions/` is the corpus RAC manages; `docs/` is documentation *for people*. Keep them distinct: users shouldn't need to read internal roadmaps or ADRs to be productive. diff --git a/docs/scale.md b/docs/scale.md index 5e768ce7..063cf25f 100644 --- a/docs/scale.md +++ b/docs/scale.md @@ -27,7 +27,7 @@ Nothing here uses AI or approximation: retrieval stays deterministic and lexical ## Supported scale envelope -RAC's current recommended production envelope is **up to 5,000 artifacts** on +AsDecided's current recommended production envelope is **up to 5,000 artifacts** on a single node. At that S1 tier, the Rust delta engine targets warm freshness at or below 25 ms p95 and one-file mutation publication at or below 150 ms p95. diff --git a/docs/security.md b/docs/security.md index c3f706cf..b296eff1 100644 --- a/docs/security.md +++ b/docs/security.md @@ -9,8 +9,9 @@ Python runtime. Validation, relationships, review, gate, search, and export operate on the local filesystem. The native MCP server emits no usage telemetry and has no -network side channel. Optional product sharing is configured separately -through the CLI; regulated installations can hard-disable it with: +network side channel. `decided telemetry` records a local compatibility +preference only; the native build has no outbound sender (ADR-131). Regulated +installations can also record an explicit hard-lock with: ```bash decided telemetry off --enterprise diff --git a/docs/validation.md b/docs/validation.md index ecc87784..8f1877da 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -1,6 +1,6 @@ # Validation: overrides & SARIF -`decided validate` is RAC's write-time gate: it fails when any artifact carries an +`decided validate` is AsDecided's write-time gate: it fails when any artifact carries an error-severity finding, and (over a directory) when the corpus is not a conformant OKF v0.2 bundle. Two features make that gate adoptable in CI on a real, pre-existing repository. @@ -20,7 +20,7 @@ Beyond structure, `decided validate` lints each type against the standards it ci | `roadmap-no-advancement-link` | warning | A roadmap should link a `## Related Requirements` or `## Related Decisions` it advances. | The BCP-14 error is the only gate-breaker; the rest are warnings, and all are -overridable below. (RAC's own corpus predates these checks and disables them in +overridable below. (AsDecided's own corpus predates these checks and disables them in its `.decided/config.yaml` — the warnings-first path in action.) ## Severity overrides (warnings-first onboarding) @@ -147,7 +147,7 @@ fail the check; warnings — including findings downgraded in `.decided/config.y annotate without failing, so a legacy repo can adopt the gate green on day one and tighten over time. -> **Extensibility boundary.** RAC's built-in artifact types and relationship +> **Extensibility boundary.** AsDecided's built-in artifact types and relationship > edges are the supported surface, defined in code. Custom artifact types and > custom relationship edges are deferred (ADR-052, ADR-055); a repo-local schema > registry is a future, separately recorded decision. diff --git a/examples/_recipe-template/README.md b/examples/_recipe-template/README.md index 529a4066..543e29c1 100644 --- a/examples/_recipe-template/README.md +++ b/examples/_recipe-template/README.md @@ -12,7 +12,7 @@ go; a finished recipe carries none of them. # RAC with []() consumes RAC on two surfaces — a generated context file - reads, and the `lore` MCP server it connects to. A stranger can reproduce + reads, and the `asdecided` MCP server it connects to. A stranger can reproduce this from the file alone. ## Prerequisites @@ -35,10 +35,10 @@ This writes several agent-context files; reads **``** as plain instructions. The managed block keeps your own content intact; re-run on change (`decided export decisions/ --agent-rules --check` fails CI on drift). -## 2. The `lore` MCP server (the pull) +## 2. The `asdecided` MCP server (the pull) Add **``** with the -`lore` server invocation (a sample is in [``]()): +`asdecided` server invocation (a sample is in [``]()): ```json @@ -50,14 +50,14 @@ Add **``** wit ``` ```toml -[mcp_servers.lore] +[mcp_servers.asdecided] command = "decided-mcp" args = ["--root", "."] ``` ```yaml mcpServers: - lore: + asdecided: command: decided-mcp args: [--root, .] ``` @@ -65,8 +65,8 @@ mcpServers: - **Project:** commit `` to share it with the team. - **Global:** `` — use an absolute `--root` path. -It exposes the five read-only `lore` tools (`get_summary`, `search_artifacts`, -`get_artifact`, `get_related`, `find_decisions`); the server re-reads the corpus on +It exposes the six read-only `asdecided` tools (`get_summary`, `search_artifacts`, +`retrieve_grounding`, `get_artifact`, `get_related`, `find_decisions`); the server re-reads the corpus on every call and never writes to the repo. ## 3. Enforcement is separate, and -agnostic @@ -82,7 +82,7 @@ Claude-Code-specific — see [`examples/claude-code/`](../claude-code/README.md) ## Verify it Run the bundled grounding demo — same task twice, once unconnected and once with -`lore` connected — and watch the connected run respect a recorded decision the +`asdecided` connected — and watch the connected run respect a recorded decision the unconnected run violates: [`examples/guide/`](../guide/demo.md). ## Summary @@ -90,7 +90,7 @@ unconnected run violates: [`examples/guide/`](../guide/demo.md). | Surface | Command | What does with it | | --- | --- | --- | | `` | `decided export decisions/ --agent-rules` | Reads it as project instructions | -| `lore` MCP | `` → `decided-mcp --root .` | Calls `find_decisions` / `get_related` on demand | +| `asdecided` MCP | `` → `decided-mcp --root .` | Calls `find_decisions` / `get_related` on demand | | CI gate | `decided validate` · `decided relationships --validate` | Enforces on every PR |