feat: add local requirements browser for OpenSpec

- Introduced a read-only local browser interface for inspecting OpenSpec capabilities, requirements, and changes.
- Implemented a standalone Python module to serve the browser and handle OpenSpec CLI commands.
- Created a structured HTML/CSS/JavaScript interface for displaying specifications and active changes.
- Added functionality for searching and navigating requirements without modifying any OpenSpec artifacts.
- Included comprehensive tests to ensure the reliability of the new browser and its integration with existing OpenSpec functionality.

README.md

@@ -61,6 +61,24 @@ Tests (no model needed):
 pip install -r requirements-dev.txt && pytest -q
 ```
 
+### Browse OpenSpec requirements locally
+
+From the project root, select the Node version from `.nvmrc` and start the read-only viewer:
+
+```bash
+nvm use && .venv/bin/python scripts/requirements_browser.py
+```
+
+Open http://localhost:8765. The page shows the durable specifications and active-change artifacts, supports filtering and keyboard navigation, and reloads the files when **Refresh files** is selected. It binds only to `127.0.0.1`, does not modify the specifications, and makes no external requests.
+
+If port 8765 is occupied, choose another local port:
+
+```bash
+nvm use && .venv/bin/python scripts/requirements_browser.py --port 8766
+```
+
+If startup says `openspec` is missing, install or expose the OpenSpec CLI for the Node version selected by `nvm use`, then confirm `openspec --version` works. If no OpenSpec root is found, run the command from this repository's root. A bind error identifies the occupied port and can be resolved with `--port` as shown above.
+
 ## פועל יוצא (Switch & Speak)
 
 The Games tab contains an RTL, touch-first conjugation drill with two paths: learning new verbs and a daily retrieval workout. Levels 1–3 implement recognition, pronoun matching, and timed switching. Level 4 records a spoken conjugation; Level 5 starts with a controlled Palestinian-Arabic prompt and evaluates the target conjugation in the response.

openspec/changes/add-requirements-browser/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-23

openspec/changes/add-requirements-browser/design.md

@@ -0,0 +1,75 @@
+# Design
+
+## Context
+
+See `proposal.md` for motivation. OpenSpec currently exposes repository state through terminal commands and Markdown files. This repository already requires Python and the OpenSpec CLI, but it has no JavaScript build system and its production FastAPI process loads large scoring dependencies that a requirements viewer does not need.
+
+The viewer handles developer planning material, so its network and rendering boundaries matter even though it runs locally. It must not become a production application route or execute HTML embedded in repository artifacts.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Start quickly with the repository's existing Python and OpenSpec installations.
+- Treat OpenSpec CLI output and resolved artifact paths as the authoritative project inventory.
+- Provide a responsive, keyboard-accessible overview and detailed inspection page.
+- Keep all reads inside the resolved OpenSpec root and all presentation read-only.
+- Make parser and HTTP behavior testable without starting the production application.
+
+**Non-Goals:**
+
+- Editing or approving requirements from the browser.
+- Serving the interface beyond loopback or adding production FastAPI endpoints.
+- Persisting UI preferences or requirement content.
+- Rendering arbitrary Markdown HTML or supporting every Markdown extension.
+- Replacing OpenSpec validation, lifecycle commands, or AI workflows.
+
+## Decisions
+
+### Use a standalone standard-library Python server
+
+Add a developer script that uses Python's HTTP server primitives and binds to `127.0.0.1` by default. It will serve one static client and a small read-only JSON API. A `--port` option allows recovery from port conflicts, while host selection is not exposed as a normal option.
+
+This keeps startup independent of the model-heavy production application and adds no package to `requirements.txt`. Reusing FastAPI was rejected because it would couple local documentation tooling to production dependencies and routing. A Node development server was rejected because the repository has no JavaScript package or build setup.
+
+### Use OpenSpec CLI output for discovery
+
+At startup, invoke `openspec context --json` using a fixed argument vector and no shell. Use the returned root as the only readable project boundary. Inventory refreshes use JSON-capable OpenSpec commands for specifications, changes, status, and structured specification content.
+
+This follows store and root resolution rules already implemented by OpenSpec instead of recreating them. If a command fails or returns invalid JSON, the server returns a typed error that the client can display. The implementation will never interpolate request data into a shell command.
+
+### Read planning artifacts only from CLI-resolved paths
+
+For active changes, use `openspec status --change <id> --json` to obtain artifact paths. Before reading a file, resolve it and verify that it remains inside the OpenSpec root and is one of the paths reported by the CLI. Requests do not accept arbitrary filesystem paths.
+
+This permits proposal, design, task, and delta-spec inspection without creating a general local-file server. Symlink and traversal checks protect the boundary even on localhost.
+
+### Send structured JSON and render with DOM text nodes
+
+The server converts durable specs and planning Markdown into a small document model: headings, paragraphs, lists, requirements, scenarios, and task states. The browser creates elements with `textContent`; artifact-provided HTML is never inserted with `innerHTML`.
+
+This provides enough visual hierarchy for requirements without adding a Markdown dependency. Full-fidelity Markdown rendering was rejected because it increases sanitization complexity and is not needed for inspection.
+
+### Keep browser state ephemeral
+
+Selection, search terms, expanded sections, loading state, and errors live only in page memory. The refresh action retrieves a complete new snapshot and preserves the current selection when it still exists. No local storage, cookies, service worker, or server-side session is used.
+
+### Keep deployment surfaces unchanged
+
+The implementation adds no application API endpoint, Supabase table, environment variable, Docker step, or Hugging Face Space configuration. Documentation clearly labels the tool as local development tooling.
+
+## Risks / Trade-offs
+
+- **OpenSpec JSON output changes between versions** -> Validate required fields, isolate command adapters, and show the failing command and concise diagnostic without crashing the server.
+- **Repeated CLI calls make refresh slow** -> Build one snapshot per refresh request and keep the current repository small; introduce caching only if measured latency becomes disruptive.
+- **A malformed artifact prevents complete structure extraction** -> Return a file-specific warning and preserve raw inert text plus all unaffected documents.
+- **Localhost is mistaken for authorization** -> Bind only to loopback, expose no host override in normal usage, and never return files outside CLI-resolved OpenSpec paths.
+- **Minimal Markdown support omits advanced formatting** -> Preserve content as readable text and prioritize headings, lists, requirements, scenarios, and tasks over visual fidelity.
+- **The OpenSpec executable is unavailable** -> Fail startup with an installation/PATH message rather than silently scanning directories with different semantics.
+
+## Migration Plan
+
+1. Add the standalone server, static client, parser/adapter tests, and developer documentation.
+2. Verify the viewer against the repository's current six specifications and against an active change.
+3. Run focused tests, the full test suite, and a manual keyboard/narrow-window browser check.
+4. Roll back by removing the local tooling files and documentation; production behavior and stored data are unaffected.

openspec/changes/add-requirements-browser/proposal.md

@@ -0,0 +1,31 @@
+# Proposal
+
+## Why
+
+The project's OpenSpec requirements are valid Markdown but are cumbersome to inspect across multiple files. A local browser interface will help maintainers understand capabilities, requirements, scenarios, and active changes without exposing planning material through the deployed application.
+
+## What Changes
+
+- Add a local, read-only requirements browser that binds only to the loopback interface.
+- Present durable specifications and active changes with navigation, counts, search, and expandable requirement scenarios.
+- Reflect files from the repository on refresh and show actionable errors for missing or malformed OpenSpec content.
+- Document a single command for starting the viewer and the local URL it opens.
+- Keep the viewer completely separate from production application routes and deployment.
+- Exclude editing, approval workflows, remote access, authentication, persistence, Supabase, and paid APIs.
+
+## Capabilities
+
+### New Capabilities
+
+- `requirements-browser`: Local, read-only browser inspection of OpenSpec specifications and changes.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- Adds local developer tooling and its focused tests under the repository's scripts/tooling area.
+- Reads `openspec/config.yaml`, `openspec/specs/`, and `openspec/changes/` without modifying them.
+- Adds developer documentation for starting and using the viewer.
+- Does not add production FastAPI endpoints, browser state, Supabase schema, deployment configuration, external services, or runtime dependencies for the learner application.

openspec/changes/add-requirements-browser/specs/requirements-browser/spec.md

@@ -0,0 +1,91 @@
+# Spec Delta
+
+## Purpose
+
+Provide maintainers with a private, local browser interface for understanding OpenSpec capabilities, requirements, scenarios, and work in progress.
+
+## ADDED Requirements
+
+### Requirement: Local-only startup
+The requirements browser SHALL start from the project root with one documented command and SHALL listen only on a loopback address by default.
+
+#### Scenario: Maintainer starts the browser
+- **GIVEN** the repository contains a valid OpenSpec root
+- **WHEN** the maintainer runs the documented startup command
+- **THEN** the tool reports a localhost URL
+- **AND** the interface is reachable from a browser on the same machine
+- **AND** it is not exposed on external network interfaces
+
+#### Scenario: Default port is unavailable
+- **WHEN** the configured port cannot be bound
+- **THEN** the tool exits without starting a partial server
+- **AND** reports an actionable message that explains how to choose another port
+
+### Requirement: Requirements inventory
+The interface SHALL summarize durable specifications and active changes from the repository's resolved OpenSpec root.
+
+#### Scenario: Project contains specifications
+- **WHEN** the requirements page loads
+- **THEN** it lists every durable capability with its requirement count
+- **AND** shows the total specification and requirement counts
+
+#### Scenario: Project contains active changes
+- **WHEN** one or more OpenSpec changes are in progress
+- **THEN** the interface lists each change and its available planning artifacts
+- **AND** distinguishes current changes from durable specifications
+
+#### Scenario: Project has no active changes
+- **WHEN** no change is in progress
+- **THEN** the interface clearly reports that there are no active changes
+- **AND** continues to show durable specifications
+
+### Requirement: Structured requirement inspection
+The interface SHALL present specification and change content as structured, readable HTML without executing markup or scripts contained in an artifact.
+
+#### Scenario: Maintainer opens a capability
+- **WHEN** the maintainer selects a capability
+- **THEN** its purpose, requirements, and scenarios are displayed in document order
+- **AND** requirement and scenario headings remain visually distinguishable
+
+#### Scenario: Artifact contains unsafe markup
+- **WHEN** a Markdown artifact contains embedded HTML or script-like text
+- **THEN** the interface renders that content as inert text or safe markup
+- **AND** does not execute artifact-provided code
+
+### Requirement: Navigation and search
+The interface SHALL let maintainers find content across capability names, requirement names, scenario names, and artifact text without requiring a mouse.
+
+#### Scenario: Search matches requirement content
+- **WHEN** the maintainer enters a search term
+- **THEN** the interface limits or highlights results that contain the term
+- **AND** reports clearly when there are no matches
+
+#### Scenario: Keyboard-only inspection
+- **WHEN** the maintainer navigates with a keyboard
+- **THEN** all specification selection, change selection, search, expansion, and refresh controls are reachable and visibly focused
+
+#### Scenario: Narrow browser window
+- **WHEN** the interface is viewed in a narrow window
+- **THEN** navigation and content remain usable without horizontal page scrolling
+
+### Requirement: Read-only refresh
+The requirements browser SHALL never modify OpenSpec artifacts and SHALL allow the maintainer to reload the latest files without restarting the production application.
+
+#### Scenario: Artifact changes on disk
+- **GIVEN** the requirements browser is running
+- **WHEN** an OpenSpec artifact changes and the maintainer refreshes the view
+- **THEN** the interface displays the latest saved content
+- **AND** no OpenSpec file is written by the viewer
+
+### Requirement: Actionable failure reporting
+The tool SHALL distinguish missing OpenSpec setup, unreadable files, and malformed artifacts while keeping readable content available when possible.
+
+#### Scenario: Command runs outside an OpenSpec project
+- **WHEN** the maintainer starts the tool where no OpenSpec root can be resolved
+- **THEN** startup fails with an explanation that OpenSpec must be initialized or the command must run inside a configured project
+
+#### Scenario: One artifact cannot be parsed
+- **GIVEN** other OpenSpec artifacts remain readable
+- **WHEN** one artifact is malformed or unreadable
+- **THEN** the interface identifies the affected file and problem
+- **AND** continues to display unaffected specifications and changes

openspec/changes/add-requirements-browser/tasks.md

@@ -0,0 +1,23 @@
+# Tasks
+
+## 1. Local data service
+
+- [x] 1.1 Add a standalone Python requirements-browser module that resolves the OpenSpec root and invokes fixed OpenSpec CLI JSON commands without a shell; add focused tests proving valid discovery and actionable missing-CLI/root failures pass.
+- [x] 1.2 Implement snapshot assembly for durable specs and active-change artifact paths, including containment checks, structured Markdown extraction, and partial file warnings; add focused tests for counts, requirements/scenarios/tasks, traversal or symlink refusal, malformed JSON, and one unreadable artifact while other content survives.
+- [x] 1.3 Add the loopback-only HTTP entry point, static asset response, read-only snapshot endpoint, `--port` handling, and concise bind errors; add HTTP tests verifying successful responses, unsupported methods are refused, no arbitrary file path is accepted, and a busy port produces the documented failure.
+
+## 2. Browser interface and usage
+
+- [x] 2.1 Add the dependency-free HTML/CSS/JavaScript interface for summary counts, separate specification/change navigation, structured details, search/no-results feedback, refresh, loading, and partial-error states; verify browser rendering uses DOM text APIs rather than inserting artifact HTML.
+- [x] 2.2 Add responsive layout, semantic controls, visible focus states, and keyboard-operable selection/expansion; manually verify current specs and this active change in a desktop and narrow viewport using keyboard-only navigation, including inert rendering of a script-like fixture.
+- [x] 2.3 Document the single startup command, localhost URL, alternate-port option, read-only/local-only boundary, and troubleshooting in the developer documentation; verify every documented command runs as written from the project root.
+
+## 3. Integration verification
+
+- [x] 3.1 Run the focused requirements-browser tests and `openspec validate add-requirements-browser --strict --no-interactive`, resolving every failure.
+- [x] 3.2 Run the full `pytest -q` suite and confirm the standalone viewer adds no production route, package dependency, Docker change, Supabase migration, or external request.
+
+## Workflow follow-up
+
+- Archive the change after implementation and review are complete.
+- Verify the archived `requirements-browser` capability is present in the durable specifications.

scripts/__init__.py

@@ -0,0 +1 @@
+"""Developer and maintenance scripts that are also exercised by tests."""

scripts/requirements_browser.css

@@ -0,0 +1,91 @@
+:root {
+  color-scheme: light;
+  --ink: #17231d;
+  --muted: #617068;
+  --paper: #f8f6ef;
+  --panel: #fffdf8;
+  --line: #ddd9cb;
+  --green: #275d42;
+  --green-soft: #dfece4;
+  --amber: #a35918;
+  --shadow: 0 14px 45px rgb(42 55 46 / 9%);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; min-width: 280px; background: var(--paper); color: var(--ink); }
+button, input { font: inherit; }
+button:focus-visible, input:focus-visible, summary:focus-visible {
+  outline: 3px solid #e7a341;
+  outline-offset: 3px;
+}
+
+.topbar { display: flex; align-items: end; justify-content: space-between; gap: 24px; padding: 34px clamp(20px, 5vw, 72px) 24px; border-bottom: 1px solid var(--line); }
+.eyebrow { margin: 0 0 5px; color: var(--green); font-size: .72rem; font-weight: 800; letter-spacing: .15em; }
+h1 { margin: 0; font: 700 clamp(2rem, 5vw, 4.2rem)/.96 Georgia, serif; letter-spacing: -.045em; }
+.root-path { margin: 11px 0 0; color: var(--muted); font: .78rem ui-monospace, monospace; overflow-wrap: anywhere; }
+.refresh { border: 1px solid var(--green); border-radius: 999px; padding: 10px 17px; background: var(--green); color: white; cursor: pointer; white-space: nowrap; }
+.refresh[disabled] { opacity: .55; cursor: wait; }
+
+.summary { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); max-width: 960px; margin: 24px auto; padding: 0 20px; gap: 12px; }
+.metric { background: var(--panel); border: 1px solid var(--line); border-radius: 16px; padding: 16px 18px; box-shadow: var(--shadow); }
+.metric strong { display: block; font: 700 1.8rem Georgia, serif; }
+.metric span { color: var(--muted); font-size: .8rem; text-transform: uppercase; letter-spacing: .08em; }
+
+.workspace { display: grid; grid-template-columns: minmax(220px, 310px) minmax(0, 1fr); gap: 22px; max-width: 1440px; margin: 0 auto; padding: 0 20px 50px; }
+.sidebar, main { background: var(--panel); border: 1px solid var(--line); border-radius: 19px; box-shadow: var(--shadow); }
+.sidebar { padding: 18px; align-self: start; position: sticky; top: 14px; max-height: calc(100vh - 28px); overflow: auto; }
+.search-label { display: block; margin: 0 0 7px; font-size: .78rem; font-weight: 700; }
+#search { width: 100%; border: 1px solid var(--line); border-radius: 11px; background: white; padding: 11px 12px; color: var(--ink); }
+.search-status { min-height: 1.2em; margin: 6px 2px 10px; color: var(--muted); font-size: .75rem; }
+.section-title { display: flex; align-items: center; justify-content: space-between; margin: 18px 2px 7px; }
+.section-title h2 { margin: 0; font-size: .76rem; text-transform: uppercase; letter-spacing: .1em; }
+.count { min-width: 25px; padding: 2px 7px; border-radius: 999px; background: var(--green-soft); color: var(--green); text-align: center; font-size: .7rem; font-weight: 800; }
+.nav-list { display: grid; gap: 5px; }
+.nav-button { width: 100%; border: 0; border-radius: 10px; padding: 10px; background: transparent; color: inherit; text-align: left; cursor: pointer; }
+.nav-button:hover { background: #f2efe5; }
+.nav-button[aria-current="page"] { background: var(--green-soft); color: var(--green); }
+.nav-button strong { display: block; overflow-wrap: anywhere; }
+.nav-button small { display: block; margin-top: 2px; color: var(--muted); }
+
+main { min-height: 520px; padding: clamp(22px, 5vw, 58px); overflow: hidden; }
+.document-head { padding-bottom: 20px; border-bottom: 1px solid var(--line); }
+.document-head .type { color: var(--green); font-size: .72rem; font-weight: 800; text-transform: uppercase; letter-spacing: .1em; }
+.document-head h2 { margin: 7px 0 10px; font: 700 clamp(1.8rem, 4vw, 3.1rem)/1 Georgia, serif; overflow-wrap: anywhere; }
+.document-head p { max-width: 760px; margin: 0; color: var(--muted); line-height: 1.65; }
+.requirement { margin-top: 16px; border: 1px solid var(--line); border-radius: 14px; background: white; overflow: hidden; }
+.requirement summary { padding: 16px 18px; cursor: pointer; font-weight: 750; }
+.requirement-body { padding: 0 18px 18px; }
+.requirement-body > p { line-height: 1.65; }
+.scenario { margin-top: 15px; border-left: 3px solid var(--green); padding: 3px 0 3px 15px; }
+.scenario h4 { margin: 0 0 8px; }
+.scenario p { margin: 4px 0; line-height: 1.5; }
+.artifact-tabs { display: flex; flex-wrap: wrap; gap: 7px; margin: 22px 0; }
+.artifact-tabs button { border: 1px solid var(--line); border-radius: 999px; padding: 7px 11px; background: white; cursor: pointer; }
+.artifact-tabs button[aria-pressed="true"] { border-color: var(--green); background: var(--green-soft); color: var(--green); }
+.artifact { max-width: 850px; }
+.artifact h2, .artifact h3, .artifact h4 { margin-top: 1.45em; }
+.artifact p, .artifact li { line-height: 1.65; overflow-wrap: anywhere; }
+.artifact .task { list-style: none; margin-left: 0; padding-left: 0; }
+.artifact .task::before { content: "□"; margin-right: 8px; color: var(--amber); }
+.artifact .task.done::before { content: "■"; color: var(--green); }
+.artifact .code-boundary { font-family: ui-monospace, monospace; color: var(--muted); }
+.empty-state { display: grid; place-items: center; min-height: 390px; color: var(--muted); text-align: center; }
+.empty-state span { font-size: 4rem; color: var(--green); }
+.no-results { padding: 30px 0; color: var(--muted); }
+.warnings { max-width: 1400px; margin: -25px auto 40px; padding: 15px 20px; border: 1px solid #e4b478; border-radius: 14px; background: #fff3df; }
+.warnings h2 { margin: 0 0 7px; font-size: .9rem; }
+.warnings p { margin: 4px 0; font-size: .85rem; overflow-wrap: anywhere; }
+
+@media (max-width: 720px) {
+  .topbar { align-items: start; flex-direction: column; }
+  .summary { grid-template-columns: 1fr; }
+  .workspace { grid-template-columns: 1fr; }
+  .sidebar { position: static; max-height: none; }
+  main { min-height: 420px; padding: 22px 16px; }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .requirement, .metric { transition: border-color .15s, transform .15s; }
+  .metric:hover { transform: translateY(-2px); }
+}

scripts/requirements_browser.html

@@ -0,0 +1,55 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>OpenSpec requirements</title>
+  <link rel="stylesheet" href="/app.css">
+  <script src="/app.js" defer></script>
+</head>
+<body>
+  <header class="topbar">
+    <div>
+      <p class="eyebrow">LOCAL REQUIREMENTS</p>
+      <h1>OpenSpec atlas</h1>
+      <p id="rootPath" class="root-path"></p>
+    </div>
+    <button id="refresh" class="refresh" type="button">Refresh files</button>
+  </header>
+
+  <section id="summary" class="summary" aria-label="Project summary"></section>
+
+  <div class="workspace">
+    <aside class="sidebar" aria-label="Requirements navigation">
+      <label class="search-label" for="search">Search requirements</label>
+      <input id="search" type="search" placeholder="Capability, requirement, scenario…" autocomplete="off">
+      <p id="searchStatus" class="search-status" aria-live="polite"></p>
+
+      <section aria-labelledby="specHeading">
+        <div class="section-title">
+          <h2 id="specHeading">Specifications</h2>
+          <span id="specCount" class="count"></span>
+        </div>
+        <nav id="specNav" class="nav-list" aria-label="Specifications"></nav>
+      </section>
+
+      <section aria-labelledby="changeHeading">
+        <div class="section-title">
+          <h2 id="changeHeading">Active changes</h2>
+          <span id="changeCount" class="count"></span>
+        </div>
+        <nav id="changeNav" class="nav-list" aria-label="Active changes"></nav>
+      </section>
+    </aside>
+
+    <main id="content" tabindex="-1">
+      <div class="empty-state">
+        <span aria-hidden="true">◇</span>
+        <p>Loading OpenSpec…</p>
+      </div>
+    </main>
+  </div>
+
+  <aside id="warnings" class="warnings" aria-live="polite" hidden></aside>
+</body>
+</html>

scripts/requirements_browser.js

@@ -0,0 +1,167 @@
+"use strict";
+
+const $ = id => document.getElementById(id);
+const state = {data: null, selection: null, artifact: 0, query: ""};
+
+function node(tag, text, className) {
+  const el = document.createElement(tag);
+  if (text !== undefined && text !== null) el.textContent = String(text);
+  if (className) el.className = className;
+  return el;
+}
+
+function matches(value) {
+  return !state.query || JSON.stringify(value).toLocaleLowerCase().includes(state.query);
+}
+
+function metric(value, label) {
+  const box = node("div", null, "metric");
+  box.append(node("strong", value), node("span", label));
+  return box;
+}
+
+function navButton(kind, item, detail) {
+  const button = node("button", null, "nav-button");
+  button.type = "button";
+  button.append(node("strong", item.title || item.id), node("small", detail));
+  button.setAttribute("aria-current", state.selection?.kind === kind && state.selection.id === item.id ? "page" : "false");
+  button.onclick = () => {
+    state.selection = {kind, id: item.id};
+    state.artifact = 0;
+    render();
+    $("content").focus();
+  };
+  return button;
+}
+
+function scenarioLines(raw) {
+  return String(raw || "").split("\n").map(line => line.replace(/^-\s+/, "").replace(/\*\*/g, "").trim()).filter(Boolean);
+}
+
+function renderSpec(spec) {
+  const main = $("content");
+  const head = node("header", null, "document-head");
+  head.append(node("span", "Durable specification", "type"), node("h2", spec.title || spec.id));
+  if (spec.purpose) head.append(node("p", spec.purpose));
+  main.append(head);
+  const requirements = spec.requirements.filter(matches);
+  if (!requirements.length) main.append(node("p", "No requirements match this search.", "no-results"));
+  for (const requirement of requirements) {
+    const details = node("details", null, "requirement");
+    if (state.query) details.open = true;
+    details.append(node("summary", requirement.name));
+    const body = node("div", null, "requirement-body");
+    body.append(node("p", requirement.text));
+    for (const item of requirement.scenarios || []) {
+      if (!matches(item) && state.query) continue;
+      const scenario = node("section", null, "scenario");
+      scenario.append(node("h4", item.name));
+      for (const line of scenarioLines(item.rawText)) scenario.append(node("p", line));
+      body.append(scenario);
+    }
+    details.append(body);
+    main.append(details);
+  }
+}
+
+function renderBlock(block, target) {
+  if (block.type === "heading") target.append(node(`h${Math.min(6, Math.max(2, block.level || 2))}`, block.text));
+  else if (block.type === "list") {
+    const list = target.lastElementChild?.tagName === "UL" ? target.lastElementChild : node("ul");
+    if (!list.isConnected) target.append(list);
+    list.append(node("li", block.text));
+  } else if (block.type === "task") target.append(node("p", block.text, `task${block.done ? " done" : ""}`));
+  else if (block.type === "code-boundary") target.append(node("p", block.text || "code", "code-boundary"));
+  else target.append(node("p", block.text));
+}
+
+function renderChange(change) {
+  const main = $("content");
+  const head = node("header", null, "document-head");
+  head.append(node("span", `Active change · ${change.schema || "OpenSpec"}`, "type"), node("h2", change.id),
+              node("p", `${change.completedTasks}/${change.totalTasks} implementation tasks complete`));
+  main.append(head);
+  if (!change.artifacts.length) {
+    main.append(node("p", "No readable planning artifacts are available.", "no-results"));
+    return;
+  }
+  state.artifact = Math.min(state.artifact, change.artifacts.length - 1);
+  const tabs = node("div", null, "artifact-tabs");
+  change.artifacts.forEach((artifact, index) => {
+    const button = node("button", artifact.id);
+    button.type = "button";
+    button.setAttribute("aria-pressed", index === state.artifact ? "true" : "false");
+    button.onclick = () => { state.artifact = index; render(); };
+    tabs.append(button);
+  });
+  main.append(tabs);
+  const artifact = change.artifacts[state.artifact];
+  const article = node("article", null, "artifact");
+  article.setAttribute("aria-label", artifact.path);
+  const blocks = state.query ? artifact.blocks.filter(matches) : artifact.blocks;
+  if (!blocks.length) article.append(node("p", "No artifact content matches this search.", "no-results"));
+  for (const block of blocks) renderBlock(block, article);
+  main.append(article);
+}
+
+function renderWarnings() {
+  const box = $("warnings"), warnings = state.data.warnings || [];
+  box.replaceChildren();
+  box.hidden = !warnings.length;
+  if (!warnings.length) return;
+  box.append(node("h2", `${warnings.length} file warning${warnings.length === 1 ? "" : "s"}`));
+  for (const warning of warnings) box.append(node("p", `${warning.file}: ${warning.message}`));
+}
+
+function render() {
+  if (!state.data) return;
+  const specs = state.data.specs.filter(matches), changes = state.data.changes.filter(matches);
+  $("summary").replaceChildren(metric(state.data.summary.specifications, "Specifications"),
+                                  metric(state.data.summary.requirements, "Requirements"),
+                                  metric(state.data.summary.changes, "Active changes"));
+  $("rootPath").textContent = state.data.root;
+  $("specCount").textContent = specs.length;
+  $("changeCount").textContent = changes.length;
+  $("specNav").replaceChildren(...specs.map(item => navButton("spec", item, `${item.requirementCount} requirements`)));
+  $("changeNav").replaceChildren(...changes.map(item => navButton("change", item, `${item.completedTasks}/${item.totalTasks} tasks`)));
+  const found = specs.length + changes.length;
+  $("searchStatus").textContent = state.query ? `${found} document${found === 1 ? "" : "s"} match` : "";
+  const main = $("content");
+  main.replaceChildren();
+  let selected = state.selection?.kind === "spec" ? state.data.specs.find(item => item.id === state.selection.id)
+               : state.selection?.kind === "change" ? state.data.changes.find(item => item.id === state.selection.id) : null;
+  if (!selected || (state.query && !matches(selected))) {
+    selected = specs[0] || changes[0];
+    state.selection = selected ? {kind: specs.includes(selected) ? "spec" : "change", id: selected.id} : null;
+  }
+  if (!selected) main.append(node("p", "No specifications or changes match this search.", "no-results"));
+  else if (state.selection.kind === "spec") renderSpec(selected);
+  else renderChange(selected);
+  renderWarnings();
+}
+
+async function load() {
+  const refresh = $("refresh");
+  refresh.disabled = true;
+  refresh.textContent = "Refreshing…";
+  try {
+    const response = await fetch("/api/state", {cache: "no-store"});
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || `HTTP ${response.status}`);
+    state.data = data;
+    render();
+  } catch (error) {
+    const main = $("content");
+    main.replaceChildren(node("h2", "Could not load OpenSpec"), node("p", error.message));
+  } finally {
+    refresh.disabled = false;
+    refresh.textContent = "Refresh files";
+  }
+}
+
+$("refresh").onclick = load;
+$("search").addEventListener("input", event => {
+  state.query = event.target.value.trim().toLocaleLowerCase();
+  render();
+});
+load();

scripts/requirements_browser.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Local, read-only browser for this repository's OpenSpec requirements."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Callable
+from urllib.parse import urlsplit
+
+
+HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+PAGE = Path(__file__).with_name("requirements_browser.html")
+STYLES = Path(__file__).with_name("requirements_browser.css")
+SCRIPT = Path(__file__).with_name("requirements_browser.js")
+Executor = Callable[[list[str], Path], subprocess.CompletedProcess[str]]
+
+
+class BrowserError(RuntimeError):
+    """An actionable setup or OpenSpec discovery error."""
+
+
+def _execute(argv: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, cwd=cwd, text=True, capture_output=True, check=False)
+
+
+class OpenSpecClient:
+    def __init__(self, cwd: Path, executor: Executor = _execute):
+        self.cwd = cwd.resolve()
+        self.executor = executor
+
+    def json(self, *arguments: str) -> dict:
+        argv = ["openspec", *arguments]
+        try:
+            result = self.executor(argv, self.cwd)
+        except FileNotFoundError as exc:
+            raise BrowserError("OpenSpec is not installed or is not on PATH. Run `openspec --version` first.") from exc
+        if result.returncode:
+            detail = (result.stderr or result.stdout).strip()
+            raise BrowserError(f"`{' '.join(argv)}` failed: {detail or f'exit {result.returncode}'}")
+        try:
+            value = json.loads(result.stdout)
+        except json.JSONDecodeError as exc:
+            raise BrowserError(f"`{' '.join(argv)}` returned invalid JSON: {exc.msg}") from exc
+        if not isinstance(value, dict):
+            raise BrowserError(f"`{' '.join(argv)}` returned JSON that is not an object")
+        return value
+
+    def root(self) -> Path:
+        data = self.json("context", "--json")
+        raw = data.get("root")
+        path = raw.get("path") if isinstance(raw, dict) else None
+        if not isinstance(path, str) or not path:
+            raise BrowserError(
+                "No OpenSpec root was found. Run this command inside an initialized project or run `openspec init`."
+            )
+        root = Path(path).resolve()
+        if not (root / "openspec").is_dir():
+            raise BrowserError(f"OpenSpec reported a root without an openspec directory: {root}")
+        return root
+
+
+def _inside(root: Path, candidate: Path) -> bool:
+    try:
+        return os.path.commonpath((str(root.resolve()), str(candidate.resolve()))) == str(root.resolve())
+    except (OSError, ValueError):
+        return False
+
+
+def safe_read(root: Path, filename: str) -> str:
+    path = Path(filename)
+    if not path.is_absolute():
+        path = root / path
+    if not _inside(root, path):
+        raise BrowserError(f"Refused artifact outside the OpenSpec root: {filename}")
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise BrowserError(f"Could not read {path.relative_to(root)}: {exc}") from exc
+
+
+TASK = re.compile(r"^- \[([ xX])\]\s+(.*)$")
+HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
+
+
+def parse_markdown(text: str) -> list[dict]:
+    """Extract readable structure without interpreting or trusting embedded HTML."""
+    blocks: list[dict] = []
+    paragraph: list[str] = []
+
+    def flush() -> None:
+        if paragraph:
+            blocks.append({"type": "paragraph", "text": " ".join(paragraph).strip()})
+            paragraph.clear()
+
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if not line:
+            flush()
+            continue
+        if match := HEADING.match(line):
+            flush()
+            blocks.append({"type": "heading", "level": len(match.group(1)), "text": match.group(2).strip()})
+        elif match := TASK.match(line):
+            flush()
+            blocks.append({"type": "task", "done": match.group(1).lower() == "x", "text": match.group(2).strip()})
+        elif line.startswith(('- ', '* ')):
+            flush()
+            blocks.append({"type": "list", "text": line[2:].strip()})
+        elif line.startswith("```"):
+            flush()
+            blocks.append({"type": "code-boundary", "text": line[3:].strip()})
+        else:
+            paragraph.append(line.strip())
+    flush()
+    return blocks
+
+
+def _artifact_files(status: dict) -> list[tuple[str, str]]:
+    found: list[tuple[str, str]] = []
+    paths = status.get("artifactPaths")
+    if not isinstance(paths, dict):
+        return found
+    for artifact_id, details in paths.items():
+        if not isinstance(details, dict):
+            continue
+        existing = details.get("existingOutputPaths", [])
+        if isinstance(existing, list):
+            found.extend((str(artifact_id), item) for item in existing if isinstance(item, str))
+    return found
+
+
+def build_snapshot(client: OpenSpecClient, root: Path | None = None) -> dict:
+    root = (root or client.root()).resolve()
+    warnings: list[dict] = []
+    specs: list[dict] = []
+    changes: list[dict] = []
+
+    inventory = client.json("list", "--specs", "--json")
+    for item in inventory.get("specs", []):
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            warnings.append({"file": "spec inventory", "message": "Ignored a malformed specification entry"})
+            continue
+        spec_id = item["id"]
+        try:
+            detail = client.json("show", spec_id, "--type", "spec", "--json")
+            requirements = detail.get("requirements") if isinstance(detail.get("requirements"), list) else []
+            specs.append({
+                "id": spec_id,
+                "title": detail.get("title") or spec_id,
+                "purpose": detail.get("overview") or "",
+                "requirementCount": len(requirements),
+                "requirements": requirements,
+            })
+        except BrowserError as exc:
+            warnings.append({"file": f"spec:{spec_id}", "message": str(exc)})
+
+    change_inventory = client.json("list", "--json")
+    for item in change_inventory.get("changes", []):
+        if not isinstance(item, dict) or not isinstance(item.get("name"), str):
+            warnings.append({"file": "change inventory", "message": "Ignored a malformed change entry"})
+            continue
+        name = item["name"]
+        change = {"id": name, "completedTasks": item.get("completedTasks", 0),
+                  "totalTasks": item.get("totalTasks", 0), "artifacts": []}
+        try:
+            status = client.json("status", "--change", name, "--json")
+            change["schema"] = status.get("schemaName") or ""
+            for artifact_id, filename in _artifact_files(status):
+                try:
+                    change["artifacts"].append({"id": artifact_id, "path": str(Path(filename).relative_to(root)),
+                                                "blocks": parse_markdown(safe_read(root, filename))})
+                except (BrowserError, ValueError) as exc:
+                    warnings.append({"file": filename, "message": str(exc)})
+        except BrowserError as exc:
+            warnings.append({"file": f"change:{name}", "message": str(exc)})
+        changes.append(change)
+
+    return {
+        "root": str(root),
+        "summary": {"specifications": len(specs),
+                    "requirements": sum(spec["requirementCount"] for spec in specs),
+                    "changes": len(changes)},
+        "specs": specs,
+        "changes": changes,
+        "warnings": warnings,
+    }
+
+
+def handler_for(snapshot: Callable[[], dict], page: Path = PAGE) -> type[BaseHTTPRequestHandler]:
+    assets = {"/": (page, "text/html; charset=utf-8"),
+              "/app.css": (STYLES, "text/css; charset=utf-8"),
+              "/app.js": (SCRIPT, "text/javascript; charset=utf-8")}
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "OpenSpecRequirements/1"
+
+        def _send(self, status: int, body: bytes, content_type: str) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:
+            route = urlsplit(self.path).path
+            if route in assets:
+                filename, content_type = assets[route]
+                try:
+                    body = filename.read_bytes()
+                except OSError as exc:
+                    self._send(HTTPStatus.INTERNAL_SERVER_ERROR,
+                               json.dumps({"error": f"Could not load browser UI: {exc}"}).encode(),
+                               "application/json; charset=utf-8")
+                    return
+                self._send(HTTPStatus.OK, body, content_type)
+            elif route == "/api/state":
+                try:
+                    body = json.dumps(snapshot(), ensure_ascii=False).encode("utf-8")
+                    self._send(HTTPStatus.OK, body, "application/json; charset=utf-8")
+                except BrowserError as exc:
+                    body = json.dumps({"error": str(exc)}, ensure_ascii=False).encode("utf-8")
+                    self._send(HTTPStatus.INTERNAL_SERVER_ERROR, body, "application/json; charset=utf-8")
+            else:
+                self._send(HTTPStatus.NOT_FOUND, b'{"error":"not found"}', "application/json; charset=utf-8")
+
+        def do_POST(self) -> None:
+            self._send(HTTPStatus.METHOD_NOT_ALLOWED, b'{"error":"read only"}', "application/json; charset=utf-8")
+
+        def log_message(self, format: str, *args: object) -> None:
+            sys.stderr.write(f"requirements-browser: {format % args}\n")
+
+    return Handler
+
+
+def create_server(snapshot: Callable[[], dict], port: int, page: Path = PAGE) -> ThreadingHTTPServer:
+    if not 0 <= port <= 65535:
+        raise BrowserError("Port must be between 0 and 65535.")
+    try:
+        return ThreadingHTTPServer((HOST, port), handler_for(snapshot, page))
+    except OSError as exc:
+        raise BrowserError(f"Could not bind {HOST}:{port}: {exc}. Choose another port with `--port PORT`.") from exc
+
+
+def parser() -> argparse.ArgumentParser:
+    out = argparse.ArgumentParser(description="Browse this project's OpenSpec requirements locally")
+    out.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"loopback port (default: {DEFAULT_PORT})")
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    client = OpenSpecClient(Path.cwd())
+    try:
+        root = client.root()
+        server = create_server(lambda: build_snapshot(client, root), args.port)
+    except BrowserError as exc:
+        print(f"requirements-browser: {exc}", file=sys.stderr)
+        return 2
+    print(f"OpenSpec requirements: http://localhost:{server.server_port}")
+    print(f"Reading: {root / 'openspec'}")
+    print("Press Ctrl+C to stop.")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_requirements_browser.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import socket
+import subprocess
+import threading
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+from scripts.requirements_browser import (BrowserError, OpenSpecClient, build_snapshot, create_server,
+                                          parse_markdown, safe_read)
+
+
+def completed(value, returncode=0, stderr=""):
+    stdout = value if isinstance(value, str) else json.dumps(value)
+    return subprocess.CompletedProcess([], returncode, stdout, stderr)
+
+
+def fixture_root(tmp_path: Path) -> Path:
+    (tmp_path / "openspec" / "changes" / "demo").mkdir(parents=True)
+    (tmp_path / "openspec" / "config.yaml").write_text("schema: spec-driven\n", encoding="utf-8")
+    (tmp_path / "openspec" / "changes" / "demo" / "proposal.md").write_text(
+        "# Proposal\n\n## Why\n\nInspect <script>alert(1)</script>.\n\n- [ ] pending\n", encoding="utf-8")
+    return tmp_path
+
+
+def fake_executor(root: Path, broken_spec: bool = False):
+    def execute(argv: list[str], cwd: Path):
+        args = tuple(argv[1:])
+        values = {
+            ("context", "--json"): {"root": {"path": str(root)}},
+            ("list", "--specs", "--json"): {"specs": [{"id": "alpha", "requirementCount": 1}]},
+            ("show", "alpha", "--type", "spec", "--json"): {
+                "title": "Alpha", "overview": "First capability", "requirements": [{
+                    "name": "Visible", "text": "The tool SHALL show it.",
+                    "scenarios": [{"name": "Open", "rawText": "- **WHEN** opened\n- **THEN** shown"}],
+                }],
+            },
+            ("list", "--json"): {"changes": [{"name": "demo", "completedTasks": 0, "totalTasks": 1}]},
+            ("status", "--change", "demo", "--json"): {
+                "schemaName": "spec-driven", "artifactPaths": {"proposal": {
+                    "existingOutputPaths": [str(root / "openspec" / "changes" / "demo" / "proposal.md")]
+                }}
+            },
+        }
+        if broken_spec and args[:2] == ("show", "alpha"):
+            return completed("not json")
+        return completed(values[args])
+    return execute
+
+
+def test_client_resolves_root_and_reports_missing_cli(tmp_path):
+    root = fixture_root(tmp_path)
+    assert OpenSpecClient(root, fake_executor(root)).root() == root
+
+    def missing(argv, cwd):
+        raise FileNotFoundError
+
+    with pytest.raises(BrowserError, match="not installed or is not on PATH"):
+        OpenSpecClient(root, missing).root()
+
+
+def test_client_reports_missing_root(tmp_path):
+    def no_root(argv, cwd):
+        return completed({"root": None})
+
+    with pytest.raises(BrowserError, match="No OpenSpec root"):
+        OpenSpecClient(tmp_path, no_root).root()
+
+
+def test_snapshot_contains_specs_changes_tasks_and_inert_text(tmp_path):
+    root = fixture_root(tmp_path)
+    snapshot = build_snapshot(OpenSpecClient(root, fake_executor(root)))
+    assert snapshot["summary"] == {"specifications": 1, "requirements": 1, "changes": 1}
+    assert snapshot["specs"][0]["requirements"][0]["scenarios"][0]["name"] == "Open"
+    blocks = snapshot["changes"][0]["artifacts"][0]["blocks"]
+    assert any(block["type"] == "task" and not block["done"] for block in blocks)
+    assert any("<script>alert(1)</script>" in block.get("text", "") for block in blocks)
+
+
+def test_snapshot_keeps_other_content_when_one_spec_is_malformed(tmp_path):
+    root = fixture_root(tmp_path)
+    snapshot = build_snapshot(OpenSpecClient(root, fake_executor(root, broken_spec=True)))
+    assert snapshot["changes"][0]["id"] == "demo"
+    assert snapshot["specs"] == []
+    assert "invalid JSON" in snapshot["warnings"][0]["message"]
+
+
+def test_snapshot_keeps_specs_when_one_artifact_is_unreadable(tmp_path):
+    root = fixture_root(tmp_path)
+    (root / "openspec" / "changes" / "demo" / "proposal.md").unlink()
+    snapshot = build_snapshot(OpenSpecClient(root, fake_executor(root)))
+    assert snapshot["specs"][0]["id"] == "alpha"
+    assert snapshot["changes"][0]["artifacts"] == []
+    assert "Could not read" in snapshot["warnings"][0]["message"]
+
+
+def test_safe_read_refuses_paths_and_symlinks_outside_root(tmp_path):
+    root = fixture_root(tmp_path / "project")
+    outside = tmp_path / "secret.md"
+    outside.write_text("secret", encoding="utf-8")
+    with pytest.raises(BrowserError, match="outside"):
+        safe_read(root, str(outside))
+    link = root / "openspec" / "linked.md"
+    link.symlink_to(outside)
+    with pytest.raises(BrowserError, match="outside"):
+        safe_read(root, str(link))
+
+
+def test_parser_extracts_headings_lists_and_tasks():
+    assert parse_markdown("# A\n\nText\n\n- item\n- [x] done") == [
+        {"type": "heading", "level": 1, "text": "A"},
+        {"type": "paragraph", "text": "Text"},
+        {"type": "list", "text": "item"},
+        {"type": "task", "done": True, "text": "done"},
+    ]
+
+
+def test_browser_client_uses_safe_dom_rendering():
+    script = Path("scripts/requirements_browser.js").read_text(encoding="utf-8")
+    assert "textContent" in script
+    assert "innerHTML" not in script
+    html = Path("scripts/requirements_browser.html").read_text(encoding="utf-8")
+    assert 'id="specNav"' in html
+    assert 'id="changeNav"' in html
+    assert 'id="search"' in html
+
+
+def running_server(tmp_path: Path):
+    page = tmp_path / "page.html"
+    page.write_text("<!doctype html><title>Requirements</title>", encoding="utf-8")
+    server = create_server(lambda: {"summary": {"specifications": 1}}, 0, page)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server, thread
+
+
+def test_http_serves_page_snapshot_and_rejects_writes_or_paths(tmp_path):
+    server, thread = running_server(tmp_path)
+    base = f"http://127.0.0.1:{server.server_port}"
+    try:
+        with urllib.request.urlopen(base + "/") as response:
+            assert response.status == 200
+            assert b"Requirements" in response.read()
+        with urllib.request.urlopen(base + "/app.css") as response:
+            assert response.headers.get_content_type() == "text/css"
+            assert b":focus-visible" in response.read()
+        with urllib.request.urlopen(base + "/app.js") as response:
+            assert response.headers.get_content_type() == "text/javascript"
+            assert b"textContent" in response.read()
+        with urllib.request.urlopen(base + "/api/state") as response:
+            assert json.load(response)["summary"]["specifications"] == 1
+        for path in ("/etc/passwd", "/api/state?path=/etc/passwd"):
+            request = urllib.request.Request(base + path, method="POST" if path.startswith("/api") else "GET")
+            with pytest.raises(urllib.error.HTTPError) as error:
+                urllib.request.urlopen(request)
+            assert error.value.code in (404, 405)
+    finally:
+        server.shutdown()
+        thread.join()
+        server.server_close()
+
+
+def test_busy_port_has_actionable_error(tmp_path):
+    server, thread = running_server(tmp_path)
+    try:
+        with pytest.raises(BrowserError, match="--port PORT"):
+            create_server(lambda: {}, server.server_port, tmp_path / "page.html")
+    finally:
+        server.shutdown()
+        thread.join()
+        server.server_close()