reality: publish OSS baseline artifacts

.gitignore

@@ -61,8 +61,8 @@ archive/
 .sdp/checkpoints/
 !.sdp/evidence/
 !.sdp/checkpoints/
-.sdp/log/events.jsonl
-sdp-plugin/.sdp/log/events.jsonl
+.sdp/log/
+sdp-plugin/.sdp/log/
 **/events.jsonl
 
 # Build output

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the Spec-Driven Protocol (SDP).
 
+## [Unreleased]
+
+### Reality OSS Publication Polish
+
+- Published open `reality` schemas under `schema/reality/`
+- Added `sdp reality validate` for emitted OSS artifact checks
+- Aligned CLI/help/completions with the actual OSS `reality` baseline
+- Added public `reality` spec docs and a focused OSS reference/checklist
+
 ## [0.9.8] - 2026-02-26
 
 ### Skills Sync, Beads Integration

CLAUDE.md

@@ -8,7 +8,7 @@ Quick reference for using SDP CLI v0.9.8 with Claude Code.
 
 ```bash
 @vision "AI-powered task manager"    # Strategic planning
-@reality --quick                     # Codebase analysis
+@reality --quick                     # Local codebase baseline
 @feature "Add user authentication"   # Plan feature
 @build 00-001-01                     # Execute workstream
 @review <feature-id>                 # Quality check
@@ -67,15 +67,15 @@ New project?
 | Level | Orchestrator | Purpose | Output |
 |-------|-------------|---------|--------|
 | **Strategic** | @vision (7 agents) | Product planning | VISION, PRD, ROADMAP |
-| **Analysis** | @reality (8 agents) | Codebase analysis | Reality report |
+| **Analysis** | @reality (single-repo baseline) | Local codebase analysis | Reality artifacts |
 | **Feature** | @feature (roadmap pre-check + @discovery + @idea + @ux + @design) | Requirements + WS | Workstreams |
 | **Execution** | @oneshot (@build) | Parallel execution | Implemented code |
 
 ### When to Use Each Level
 
 **@vision** — New project, major pivot, quarterly strategic review
 
-**@reality** — New to project, before @feature, track tech debt, quarterly review
+**@reality** — New to project, before @feature, establish a local baseline, track tech debt, quarterly review
 
 **@feature** — Feature idea but no workstreams, need interactive planning (full discovery flow)
 
@@ -96,7 +96,7 @@ New project?
 | Skill | Purpose | Phase |
 |-------|---------|-------|
 | `@vision` | Strategic product planning (7 expert agents) | Strategic |
-| `@reality` | Codebase analysis (8 expert agents) | Analysis |
+| `@reality` | Local single-repo baseline scan | Analysis |
 | `@feature` | Planning orchestrator (roadmap pre-check + discovery + idea + ux + design) | Planning |
 | `@discovery` | Product discovery gate (roadmap check, research loop) | Planning |
 | `@idea` | Requirements gathering (AskUserQuestion) | Planning |
@@ -152,6 +152,7 @@ New project?
 
 # 2. Codebase analysis
 @reality --quick
+sdp reality emit-oss --quick
 
 # 3. Feature planning (per feature)
 @feature "User can reset password via email"

PRODUCT_VISION.md

@@ -66,7 +66,7 @@ Each level is independently valuable. Upgrade path is additive.
 - Protocol spec with 12 skills (v0.9.8, 18 releases)
 - Evidence log with hash-chain provenance
 - CLI: `sdp doctor`, `sdp guard`, `sdp log`, `sdp status`
-- Multi-agent review (6 agents), strategic planning (7 agents), codebase analysis (8 agents)
+- Multi-agent review (6 agents), strategic planning (7 agents), OSS reality baseline analysis
 - Install script with auto-detect for Claude Code, Cursor, OpenCode
 - 1,004 commits, 16 stars, MIT license
 

README.md

@@ -25,6 +25,7 @@ Skills load from `sdp/.claude/skills/` (Claude) or `sdp/.cursor/skills/` (Cursor
 
 ```bash
 sdp init --auto
+@reality --quick
 @feature "Your feature"
 @oneshot <feature-id>
 @review <feature-id>
@@ -58,6 +59,7 @@ sdp init --auto
 | Skill | Purpose |
 |-------|---------|
 | `@vision` | Strategic planning |
+| `@reality` | Local codebase baseline and SDP readiness scan |
 | `@feature` | Feature planning (→ workstreams) |
 | `@oneshot` | Autonomous execution |
 | `@build` | Single workstream (TDD) |
@@ -67,7 +69,7 @@ sdp init --auto
 
 ## Optional
 
-**CLI:** `sdp doctor`, `sdp status`, `sdp next`, `sdp guard activate`, `sdp log show`, `sdp demo`
+**CLI:** `sdp doctor`, `sdp status`, `sdp next`, `sdp guard activate`, `sdp log show`, `sdp demo`, `sdp reality emit-oss`, `sdp reality validate`
 
 **Beads:** `brew tap beads-dev/tap && brew install beads` — task tracking for multi-session work.
 
@@ -84,6 +86,7 @@ sdp init --auto
 | [ROADMAP.md](docs/ROADMAP.md) | Where SDP is going |
 | [PROTOCOL.md](docs/PROTOCOL.md) | Full specification |
 | [reference/](docs/reference/) | Principles, glossary, specs |
+| [reference/reality-oss.md](docs/reference/reality-oss.md) | OSS reality command, outputs, checklist |
 
 ## License
 

docs/CLI_REFERENCE.md

@@ -10,7 +10,7 @@ Run `sdp --help` for the full command tree and `sdp <command> --help` for flags
 | Planning and execution | `sdp parse`, `sdp plan`, `sdp build`, `sdp apply`, `sdp orchestrate`, `sdp verify`, `sdp tdd`, `sdp deploy` | Parse workstreams, create plans, execute work, verify completion, and record deployment approvals |
 | Guard and context | `sdp guard ...`, `sdp session ...`, `sdp resolve`, `sdp git` | Enforce edit scope, validate context/branch state, resolve task identifiers, and keep session state in sync |
 | Evidence and audit | `sdp log ...`, `sdp decisions ...`, `sdp checkpoint ...`, `sdp coordination ...`, `sdp design record`, `sdp idea record` | Inspect evidence, trace decision history, manage checkpoints, and record design/idea evidence |
-| Quality and diagnostics | `sdp quality {coverage, complexity, size, types, all}`, `sdp drift detect`, `sdp diagnose`, `sdp watch`, `sdp collision check`, `sdp contract ...`, `sdp acceptance run` | Run quality gates, detect drift, inspect failures, watch files, check collisions, validate contracts, and run smoke acceptance checks |
+| Quality and diagnostics | `sdp quality {coverage, complexity, size, types, all}`, `sdp drift detect`, `sdp diagnose`, `sdp watch`, `sdp reality {emit-oss, validate}`, `sdp collision check`, `sdp contract ...`, `sdp acceptance run` | Run quality gates, detect drift, emit or validate OSS reality artifacts, inspect failures, watch files, check collisions, validate contracts, and run smoke acceptance checks |
 | Telemetry and metrics | `sdp telemetry {status, consent, enable, disable, analyze, export, upload}`, `sdp metrics {collect, classify, report}` | Manage local opt-in telemetry and derive benchmark/quality metrics |
 | Workflow support | `sdp beads ...`, `sdp task create`, `sdp memory ...`, `sdp prd ...`, `sdp prototype`, `sdp skill ...` | Integrate with Beads, manage memory/search, work with PRDs, prototype features, and inspect skills |
 
@@ -21,11 +21,13 @@ Run `sdp --help` for the full command tree and `sdp <command> --help` for flags
 | `sdp init --auto` | Initialize prompts and SDP scaffolding without prompts |
 | `sdp doctor` | Run health checks for hooks, config, telemetry, and repository setup |
 | `sdp build <ws-id>` | Execute a single workstream with guard enforcement and tests |
+| `sdp reality emit-oss --quick` | Emit the OSS reality baseline into `.sdp/reality/` and `docs/reality/` |
+| `sdp reality validate` | Validate emitted OSS reality artifacts against the published schema contract |
 | `sdp verify <ws-id>` | Validate workstream completion against evidence and checks |
 | `sdp quality all` | Run all quality gates for the current project |
 | `sdp telemetry status` | Show telemetry consent, event count, and storage path |
 | `sdp telemetry export json` | Export local telemetry to `telemetry_export.json` |
 | `sdp log show` | Show paginated evidence events with filters |
 | `sdp decisions log` | Record a decision in the audit trail |
 
-See [reference/skills.md](reference/skills.md) for the skill catalog and [PROTOCOL.md](PROTOCOL.md) for the full protocol spec.
+See [reference/reality-oss.md](reference/reality-oss.md) for the reality OSS contract and [reference/skills.md](reference/skills.md) for the skill catalog.

docs/README.md

@@ -11,6 +11,8 @@ Protocol specification and reference for SDP (Spec-Driven Protocol).
 | [CLI_REFERENCE.md](CLI_REFERENCE.md) | SDP CLI commands |
 | [MANIFESTO.md](MANIFESTO.md) | Vision, evidence, what exists |
 | [ROADMAP.md](ROADMAP.md) | Where SDP is going, user-facing orientation |
+| [specs/reality/OSS-SPEC.md](specs/reality/OSS-SPEC.md) | OSS reality product scope |
+| [specs/reality/ARTIFACT-CONTRACT.md](specs/reality/ARTIFACT-CONTRACT.md) | Open reality artifact contract |
 
 ## Reference
 
@@ -27,6 +29,7 @@ Protocol specification and reference for SDP (Spec-Driven Protocol).
 | [reference/schema-registry.md](reference/schema-registry.md) | Schema families: contracts, findings, handoffs |
 | [reference/integration-contracts.md](reference/integration-contracts.md) | How to apply contracts, findings, handoffs, provenance in integrations |
 | [reference/skills.md](reference/skills.md) | Skill catalog |
+| [reference/reality-oss.md](reference/reality-oss.md) | OSS reality command, outputs, checklist |
 | [reference/pipeline-hooks-security.md](reference/pipeline-hooks-security.md) | Hook execution hardening |
 
 ## Schemas & Attestation

docs/reference/README.md

@@ -9,6 +9,7 @@ Quick lookup guides for SDP commands, configuration, and quality standards.
 ## Contents
 
 - [Commands](#commands)
+- [Reality OSS](#reality-oss)
 - [Quality Gates](#quality-gates)
 - [Configuration](#configuration)
 - [Pipeline Hooks Security](#pipeline-hooks-security)
@@ -42,6 +43,19 @@ Quick lookup guides for SDP commands, configuration, and quality standards.
 
 ---
 
+## Reality OSS
+
+Local single-repo reality baseline for OSS users:
+
+- `sdp reality emit-oss`
+- `sdp reality validate`
+- `docs/specs/reality/OSS-SPEC.md`
+- `docs/specs/reality/ARTIFACT-CONTRACT.md`
+
+**See:** [reality-oss.md](reality-oss.md) — command surface, outputs, and publish checklist
+
+---
+
 ## Quality Gates
 
 ### Mandatory Checks
@@ -192,6 +206,7 @@ Structured errors with:
 | Need | Doc |
 |------|-----|
 | Command syntax | [../CLI_REFERENCE.md](../CLI_REFERENCE.md) |
+| Reality OSS usage and checklist | [reality-oss.md](reality-oss.md) |
 | Quality standards | [build-spec.md](build-spec.md) |
 | Hook security rules | [pipeline-hooks-security.md](pipeline-hooks-security.md) |
 | Schema map | [schema-registry.md](schema-registry.md) |

docs/reference/reality-oss.md

@@ -0,0 +1,43 @@
+# Reality OSS Reference
+
+Public OSS `reality` is a local, evidence-first baseline for one repository. It emits open artifacts and validates them against the published schema contract.
+
+## Commands
+
+```bash
+sdp reality emit-oss [--quick|--deep|--bootstrap-sdp] [--focus=architecture|quality|testing|docs|security]
+sdp reality validate
+```
+
+## Outputs
+
+Machine-readable outputs:
+
+- `.sdp/reality/reality-summary.json`
+- `.sdp/reality/feature-inventory.json`
+- `.sdp/reality/architecture-map.json`
+- `.sdp/reality/integration-map.json`
+- `.sdp/reality/quality-report.json`
+- `.sdp/reality/drift-report.json`
+- `.sdp/reality/readiness-report.json`
+
+Human-readable outputs:
+
+- `docs/reality/summary.md`
+- `docs/reality/architecture.md`
+- `docs/reality/quality.md`
+- `docs/reality/bootstrap.md`
+
+## Published Contract
+
+- [../specs/reality/OSS-SPEC.md](../specs/reality/OSS-SPEC.md)
+- [../specs/reality/ARTIFACT-CONTRACT.md](../specs/reality/ARTIFACT-CONTRACT.md)
+- `schema/reality/*.schema.json`
+
+## Publish Checklist
+
+1. Run `sdp reality emit-oss` in a representative repository.
+2. Run `sdp reality validate`.
+3. Check that `docs/reality/` and `.sdp/reality/` changed deterministically on rerun.
+4. Confirm docs and help text describe OSS `reality` as a single-repo baseline, not a consulting-grade multi-agent mesh.
+5. If the public contract changes, update `schema/reality/`, `docs/specs/reality/`, and `prompts/skills/reality/SKILL.md` in the same PR.