devrites 3.0.3 → 3.0.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.0.4](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.3...v3.0.4) (2026-07-20)
+
+### Fixed
+
+* **ci:** harden supply chain checks ([d902574](https://github.com/ViktorsBaikers/DevRites/commit/d902574a7d30168fcef94aa4a3dae7707191fe8d))
+* **devrites:** normalize canonical workspace files ([e70221f](https://github.com/ViktorsBaikers/DevRites/commit/e70221f5dd9fbda0f3a73c500a493497bc023a91))
+
 ## [3.0.3](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.2...v3.0.3) (2026-07-20)
 
 ### Fixed

package/README.md

@@ -115,7 +115,7 @@ Full diagram set (lifecycle, polish orchestrator, review fan-out, debug loop,
 rules carrier, workspace state, namespace map) →
 [`docs/flow.md`](docs/flow.md).
 
-**Status:** [`v3.0.3`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.0.3) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.0.4`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.0.4) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Contents
 

package/docs/adr/0001-go-engine-as-control-plane.md

@@ -0,0 +1,43 @@
+# ADR-0001: Go engine as deterministic control plane
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled; decision predates the ADR log)
+
+> Network scope was narrowed by [ADR-0008](0008-sanctioned-engine-network-boundary.md):
+> deterministic workspace operations remain network-free, while explicit
+> updater/source-cache I/O is isolated in `internal/iohooks`.
+
+## Context
+
+DevRites orchestrates an LLM through a spec-driven lifecycle. Two kinds of work
+are entangled: **judgment** (is this spec good? is this code right?) which only
+a model can do, and **bookkeeping** (which phase are we in? are the required
+sections present? what's the next question id?) which must be exact, fast, and
+identical every run. Letting the model do the bookkeeping makes the process
+non-reproducible and burns context on arithmetic.
+
+## Decision
+
+Ship a single statically-linked Go binary (`CGO_ENABLED=0`, stdlib-only, zero
+third-party deps in the hot path) as the **control plane**: it owns all
+deterministic state transitions, gates, and derivations over `.devrites/`. It
+makes **no** model or network calls. The filesystem is the data plane; the LLM
+supplies judgment. Commands are a hand-rolled `switch` dispatch, not a CLI
+framework.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Bookkeeping inside the agent prompt | Non-deterministic, context-hungry, unauditable — the exact failure this system exists to remove. |
+| Node/TS engine (like the reference system GSD Core) | Drags a package tree + supply-chain surface; the pure-Go single binary has none and cross-compiles to every target from one runner. |
+| Cobra / urfave CLI framework | A dependency and a config surface for a switch statement the stdlib already handles. |
+
+## Consequences
+
+- Reproducible process: same state in, same verdict out, no wall-clock or
+  network variance (the one remaining wall-clock read is now seamed — ADR-0006).
+- Zero-dependency binary: trivial supply chain, `go install`-able, no runtime.
+- Cost: the engine can express only what's deterministic. Anything needing
+  judgment must round-trip to the model — by design.
+- The engine is the trust root, so it carries the strictest CI gates (ADR-0006).

package/docs/adr/0002-dual-host-harness.md

@@ -0,0 +1,34 @@
+# ADR-0002: Dual-host harness (Claude + Codex)
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled)
+
+## Context
+
+Each AI coding host (Claude Code, Codex, and — in adjacent tools — Cursor,
+Cline, Copilot) speaks its own hook dialect: different stdin shapes, exit-code
+conventions, and settings surfaces. The lifecycle logic (orient, gate, hook
+decisions) is host-independent; only the edge translation differs.
+
+## Decision
+
+Support exactly **two** hosts today — `claude` and `codex` — behind a thin
+`internal/harness` adapter that translates each host's hook stdin/exit
+conventions into the shared `orient` + `gate` core. Host support is
+enumerated in code, not open-ended. `harness-matrix --check` keeps
+`docs/harness-compliance.md` in sync with the adapters (drift is a CI failure).
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| A generic declarative capability/adapter registry now (the GSD Core model) | Real ceiling-raiser for N hosts, but a large refactor unjustified at N=2. Recorded as a Proposed follow-up, not built. See the adoption study in `docs/research/gsd-core-adoption.md` §3.1. |
+| Claude-only | Codex users are already real; single-host would strand them. |
+| Per-host forks of the logic | Duplicates the lifecycle core across edges — the thing the adapter exists to prevent. |
+
+## Consequences
+
+- Adding a host today means editing `harness.go` — acceptable friction at N=2,
+  the calcification risk rises with N (hence the Proposed registry follow-up).
+- The shared core is tested once; only edge translation is host-specific.
+- `harness-matrix --check` makes host-support drift visible in CI.

package/docs/adr/0003-gate-model-hitl-pause.md

@@ -0,0 +1,38 @@
+# ADR-0003: Gates block as a HITL pause, never a crash
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled)
+
+## Context
+
+A gate is a deterministic completeness check — e.g. "does this feature have the
+sections required to leave the current phase?" When a gate is not satisfied the
+engine must stop the agent, but *how* it stops matters. A crash (non-zero,
+stderr stack) reads as a tool failure and invites the agent to retry blindly or
+route around it. The intended meaning is the opposite: **the work is
+incomplete, pause and involve the human.**
+
+## Decision
+
+A blocked gate is a structured **human-in-the-loop pause**: a specific
+"missing X" message on stdout and a distinct, reserved **exit code 3** — never a
+crash, never a generic non-zero. Gates are **transition-fired** (they run only
+when explicitly invoked at a phase boundary, not on every tool call). Two
+kinds: `Readiness` (sections needed to leave the current phase) and `Seal` (the
+full seal set). `StopGate` enforces the rest-point invariant: a feature claiming
+completion with empty proof, or with `.red` set, cannot end the turn.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Exit 1 / crash on an unmet gate | Indistinguishable from a real error; agents retry or route around it instead of pausing for the human. |
+| Run gates on every tool call | Turns a transition check into per-action overhead and noise; gates are boundary events. |
+| Auto-advance past a soft-missing section | Defeats the completeness guarantee the gate exists to provide. |
+
+## Consequences
+
+- Exit 3 is a reserved, load-bearing contract — the harness and hooks branch on
+  it. Its guard test (`tests/adr_0003_gate_exit_code_test.go`) locks it.
+- Blocks are legible: the agent (and human) see exactly which section is missing.
+- Gate authors must classify a stop as "incomplete" (exit 3) vs a true error.

package/docs/adr/0004-state-schema-phases-sections.md

@@ -3,6 +3,10 @@
 - **Status:** Accepted
 - **Date:** 2026-07-08 (backfilled)
 
+> Artifact filename direction was amended by
+> [ADR-0007](0007-canonical-live-workspace-filenames.md). Phase-relative section
+> completeness remains unchanged.
+
 ## Context
 
 A feature's working state must be legible to both humans and the engine, and
@@ -13,9 +17,8 @@ that don't exist yet (there's no proof during framing).
 
 ## Decision
 
-Model feature state as **six single-concern section files** — `spec`, `plan`,
-`decisions`, `tasks`, `proof`, `status` (with transitional aliases
-`evidence→proof`, `state→status` that `migrate` normalizes). Drive the lifecycle
+Model feature state as **six single-concern sections** — `spec`, `plan`,
+`decisions`, `tasks`, `proof`, `status`. Drive the lifecycle
 through the ordered rite-\* arc:
 `frame → spec → temper → define → plan → vet → build → converge → prove → polish → review → seal → ship → done`.
 Completeness is **phase-relative and additive**: the typed phase registry maps

package/docs/adr/0005-hooks-as-engine-subcommands.md

@@ -0,0 +1,39 @@
+# ADR-0005: Hooks are engine subcommands, not shell scripts
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled; see commits porting `reviewer-readonly`,
+  `subagent-orient`, and the guard hooks into the Go engine)
+
+## Context
+
+Lifecycle hooks (orient on session start, readonly-guard for reviewers,
+stop-gate, statusline, redwatch, …) began as standalone `pack/.claude/hooks/*.sh`
+scripts. Shell hooks drift from the engine's own state logic, are hard to test
+in isolation, behave differently across the two hosts, and duplicate parsing the
+engine already does.
+
+## Decision
+
+Hooks are **subcommands of the one Go binary**: `devrites-engine hook <id>`.
+The pack ships only `hooks.json` wiring plus host settings; every hook's logic
+lives in the engine, sharing the `orient`/`gate`/`state` core. A control plane
+selects which hooks fire: `DEVRITES_HOOK_PROFILE` (minimal / standard / strict)
+and `DEVRITES_DISABLED_HOOKS`. Each hook has a golden parity test
+(`tests/parity_*_test.go`) pinning its stdout + exit across both hosts.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Keep hooks as `.sh` scripts | Drift from engine state logic, per-host divergence, poor testability, duplicated parsing. |
+| One monolithic hook entry point | Loses per-hook enable/disable and per-hook golden tests. |
+| Node hook runtime | Reintroduces a runtime dependency ADR-0001 deliberately avoids. |
+
+## Consequences
+
+- Hooks are unit-testable Go with golden parity snapshots, not shell fixtures.
+- One implementation serves both hosts; the harness (ADR-0002) handles edge
+  translation.
+- Profiles make the hook surface tunable without editing wiring.
+- The pack's `hooks/*.sh` files are removed; `hooks.json` is the only pack-side
+  hook artifact.

package/docs/adr/0006-clock-seam-and-engine-ci-gates.md

@@ -0,0 +1,50 @@
+# ADR-0006: Clock seam + Go static-analysis CI gates
+
+- **Status:** Accepted
+- **Date:** 2026-07-08
+
+## Context
+
+Two gaps surfaced while studying a more mature peer system (GSD Core; see
+`docs/research/gsd-core-adoption.md`):
+
+1. **Unwired static analysis.** `engine/Makefile` defined `staticcheck` and
+   `govulncheck` targets, but CI ran only `gofmt` + `go vet`. No `-race`, no
+   custom analysis on the trust-root binary.
+2. **A wall-clock leak.** `resolve next-qid` derived today's date from a raw
+   `time.Now()` with no seam, so its golden snapshot was pinned to the date it
+   was recorded and failed **every other day** — a latent red the peer system's
+   clock-seam lint would have caught at author time.
+
+## Decision
+
+- **Clock seam.** Wall-clock reads in the resolve command flow through one
+  overridable point, `clockNow()`, honoring `DEVRITES_NOW` (RFC-3339 or bare
+  `YYYY-MM-DD`). Date-derived output is deterministic under test; goldens pin the
+  clock instead of tracking the real date.
+- **Engine CI gates.** The `engine` CI job installs pinned `staticcheck`
+  (2025.1.1) + `govulncheck` and runs both as **blocking** steps, and runs the
+  suite with `-race`. `make quality` mirrors this so a green local gate means a
+  green pipeline.
+- **Coverage** is measured (`make cover`) but **not** yet a hard floor: the
+  number is understated because most behaviour is exercised through CLI-level
+  integration tests in `tests/` that don't attribute to per-package coverage.
+  A ratchet-only floor is a follow-up once attribution is meaningful.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Regenerate the date golden and move on | Fixes it for one day; the test rots again at the next date boundary. The seam fixes the class. |
+| Introduce `golangci-lint` | New dependency + config surface; `staticcheck` + `govulncheck` were already defined in the Makefile — wire what exists. |
+| Inject a full `Clock` interface everywhere | Heavier than the one failing path needs; the env seam is the minimal correct fix. A shared clock package is a Proposed generalization. |
+| Hard coverage floor now | Misleading at ~23% aggregate due to integration-test attribution; a floor here would gate on noise. |
+
+## Consequences
+
+- The engine suite is deterministic across dates and race-checked; static
+  analysis and CVE scanning block on the trust-root binary.
+- `DEVRITES_NOW` is a supported test seam; other date-deriving commands
+  (`learnings`, `conventions`, `footprint`, `stuck`) still read `time.Now()`
+  directly and can adopt the same seam when they need deterministic output.
+- Guard test `tests/adr_0006_clock_seam_test.go` locks the seam behaviour.

package/docs/adr/0007-canonical-live-workspace-filenames.md

@@ -0,0 +1,36 @@
+# ADR-0007: Canonical live workspace filenames
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+
+## Context
+
+ADR-0004 established phase-relative `proof` and `status` sections while the
+live workspace later standardized its human-facing artifacts on `README.md`,
+`state.md`, and `evidence.md`. Shipped skills, validators, the typed workflow
+registry, and user documentation already write those names, but migration and
+some engine comments still normalized in the opposite direction.
+
+## Decision
+
+Use `README.md`, `state.md`, and `evidence.md` as the canonical live workspace
+map, cursor, and proof log. Continue reading `feature.md`/`index.md`, `status.md`,
+and `proof.md` as compatibility aliases. `devrites-engine migrate` adds missing
+canonical files from aliases without deleting or overwriting either form.
+Internal `proof` and `status` section identifiers remain conceptual completeness
+names, not canonical filename declarations.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Restore `feature.md`, `status.md`, and `proof.md` as canonical | Would reverse the shipped workspace contract and require coordinated changes across skills, validators, docs, fixtures, and generated hosts. |
+| Treat both directions as equally canonical | Makes migration non-idempotent and leaves writers without one preferred target. |
+| Delete aliases after migration | Risks data loss and breaks existing workspaces and older installed packs. |
+
+## Consequences
+
+- Migration direction matches the files produced and required by the live pack.
+- Existing aliases remain losslessly readable and are preserved on disk.
+- Schema version remains `1`; this is an additive filename normalization, not a
+  content-schema break.

package/docs/adr/0008-sanctioned-engine-network-boundary.md

@@ -0,0 +1,33 @@
+# ADR-0008: Sanctioned engine network boundary
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+
+## Context
+
+ADR-0001 described the Go control plane as network-free. The binary now also
+owns explicit installation/update and source-cache operations that require HTTP,
+while deterministic workspace bookkeeping still must not depend on network or
+model responses. The implemented boundary already isolates HTTP in one package.
+
+## Decision
+
+Keep deterministic workspace state, gate, hook, migration, and derivation logic
+network- and model-free. Permit network access only in `internal/iohooks` for
+explicit updater and source-cache operations. No other first-party package may
+import network clients, and no engine package may call a model API.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Forbid all network access in the binary | Would remove the verified updater and source-cache refresh behavior users already rely on. |
+| Allow each consumer its own HTTP client | Expands the audit surface and weakens the executable package boundary. |
+| Ship a second updater binary | Adds packaging, release, and cross-platform complexity without improving the existing package isolation. |
+
+## Consequences
+
+- Workspace verdicts remain deterministic and offline-capable.
+- Network behavior has one auditable package and one guard test.
+- The binary as a whole is not network-free; documentation must distinguish the
+  control-plane core from explicit I/O commands.

package/docs/adr/README.md

@@ -0,0 +1,58 @@
+# Architecture Decision Records
+
+An ADR captures **one** load-bearing decision: the context that forced it, the
+decision itself, the alternatives that were rejected and *why*, and the
+consequences accepted. The rejected-alternatives table is the point — it keeps
+the "why not X" from being re-litigated every quarter.
+
+`CLAUDE.md` points every agent here (`CONTEXT.md` + `docs/adr/` are the
+single-context domain record). Keep this directory the source of truth for
+architecture; per-feature `decisions.md` files stay scoped to that feature.
+
+## Convention
+
+- Filename: `NNNN-kebab-title.md`, zero-padded, monotonic.
+- Frontmatter fields: **Status** (Proposed / Accepted / Superseded by NNNN),
+  **Date** (YYYY-MM-DD), **Deciders** (optional).
+- Sections: **Context** → **Decision** → **Alternatives considered** (a table:
+  option · why rejected) → **Consequences**.
+- **Guard test:** an accepted ADR that asserts a runtime invariant SHOULD have a
+  named regression test — `engine/tests/adr_NNNN_*_test.go` — so the decision
+  has an executable proof it still holds. Reference the ADR number in the test's
+  doc comment.
+
+## Template
+
+```markdown
+# ADR-NNNN: <title>
+
+- **Status:** Accepted
+- **Date:** YYYY-MM-DD
+
+## Context
+<the forces: what problem, what constraints, what was true at the time>
+
+## Decision
+<what we chose, stated as a present-tense rule>
+
+## Alternatives considered
+| Option | Why not |
+|--------|---------|
+| ... | ... |
+
+## Consequences
+<what this makes easy, what it costs, what follow-up it implies>
+```
+
+## Index
+
+| ADR | Title | Status | Guard test |
+|-----|-------|--------|-----------|
+| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | — |
+| [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `tests/parity_*_test.go` |
+| [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `tests/adr_0003_gate_exit_code_test.go` |
+| [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `tests/adr_0004_required_by_phase_test.go` |
+| [0005](0005-hooks-as-engine-subcommands.md) | Hooks are engine subcommands, not shell scripts | Accepted | `tests/parity_*_test.go` |
+| [0006](0006-clock-seam-and-engine-ci-gates.md) | Clock seam + Go static-analysis CI gates | Accepted | `tests/adr_0006_clock_seam_test.go` |
+| [0007](0007-canonical-live-workspace-filenames.md) | Canonical live workspace filenames | Accepted | `internal/migrate/migrate_test.go`, `tests/migrate_cli_test.go` |
+| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted | `tests/meta_test.go` |

package/docs/engine/state-schema.md

@@ -54,9 +54,10 @@ Backward compatibility: `.devrites/features/<slug>/` remains readable as a legac
 workspace location. `feature.md` / `index.md` may stand in for `README.md`, and
 `proof.md` may stand in for `evidence.md`.
 
-### `feature.md`
+### Workspace maps
 
-The per-feature index. Its YAML frontmatter carries:
+The canonical per-feature index is `README.md`; `feature.md` and `index.md` are
+readable aliases. A map may carry YAML frontmatter with:
 
 | field           | meaning                                        |
 | --------------- | ---------------------------------------------- |
@@ -65,9 +66,9 @@ The per-feature index. Its YAML frontmatter carries:
 | `phase`         | current workflow phase (see below)             |
 | `schemaVersion` | schema version the file was written against    |
 
-A feature exists when it has either a live `state.md` ledger or the transitional
-`feature.md` manifest. The mutable `state.md` cursor is authoritative when both
-declare a phase; an unknown declared phase is an error.
+A feature exists when it has either a live `state.md` ledger or a workspace map.
+The mutable `state.md` cursor is authoritative when both declare a phase; an
+unknown declared phase is an error.
 
 ## Sections
 

package/engine/internal/migrate/migrate.go

@@ -90,11 +90,11 @@ func featureDirsNeedingNormalization(root string) ([]normalizationTarget, error)
 }
 
 func needsNormalizeFeature(dir string) bool {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		return true
 	}
-	return regularFileExists(filepath.Join(dir, "evidence.md")) && !regularFileExists(filepath.Join(dir, "proof.md")) ||
-		regularFileExists(filepath.Join(dir, state.LedgerFile)) && !regularFileExists(filepath.Join(dir, "status.md"))
+	return regularFileExists(filepath.Join(dir, "proof.md")) && !regularFileExists(filepath.Join(dir, state.EvidenceFile)) ||
+		regularFileExists(filepath.Join(dir, "status.md")) && !regularFileExists(filepath.Join(dir, state.LedgerFile))
 }
 
 func regularFileExists(path string) bool {
@@ -103,16 +103,21 @@ func regularFileExists(path string) bool {
 }
 
 func normalizeFeatureDir(dir, slug string) error {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	for _, alias := range state.WorkspaceMapFiles()[1:] {
+		if err := copyAliasFile(dir, alias, state.WorkspaceMapFile); err != nil {
+			return fmt.Errorf("copy %s to %s: %w", alias, state.WorkspaceMapFile, err)
+		}
+	}
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		phase := derivePhase(filepath.Join(dir, state.LedgerFile))
-		if err := state.AtomicWrite(filepath.Join(dir, "feature.md"), []byte(featureIndex(slug, phase)), 0o644); err != nil {
-			return fmt.Errorf("write feature index: %w", err)
+		if err := state.AtomicWrite(filepath.Join(dir, state.WorkspaceMapFile), []byte(workspaceIndex(slug, phase)), 0o644); err != nil {
+			return fmt.Errorf("write workspace index: %w", err)
 		}
 	}
-	if err := copyAliasFile(dir, "evidence.md", "proof.md"); err != nil {
-		return fmt.Errorf("copy evidence.md to proof.md: %w", err)
+	if err := copyAliasFile(dir, "proof.md", state.EvidenceFile); err != nil {
+		return fmt.Errorf("copy proof.md to evidence.md: %w", err)
 	}
-	return copyAliasFile(dir, state.LedgerFile, "status.md")
+	return copyAliasFile(dir, "status.md", state.LedgerFile)
 }
 
 func copyAliasFile(dir, alias, canonical string) error {
@@ -128,8 +133,8 @@ func copyAliasFile(dir, alias, canonical string) error {
 	return state.AtomicWrite(dst, data, 0o644)
 }
 
-// featureIndex renders the manifest added to a normalized workspace.
-func featureIndex(slug string, phase state.Phase) string {
+// workspaceIndex renders the compact map added to a normalized workspace.
+func workspaceIndex(slug string, phase state.Phase) string {
 	return fmt.Sprintf(`---
 slug: %s
 title: %s

package/engine/internal/migrate/migrate_test.go

@@ -1,6 +1,7 @@
 package migrate
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -33,8 +34,11 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 	}
 
 	assertFile(t, root, "work/alpha/spec.md", "spec\n")
-	assertFile(t, root, "work/alpha/proof.md", "proof\n")
-	assertFile(t, root, "work/alpha/status.md", "status: done - shipped\n")
+	assertFile(t, root, "work/alpha/evidence.md", "proof\n")
+	assertFile(t, root, "work/alpha/state.md", "status: done - shipped\n")
+	assertFileContains(t, root, "work/alpha/README.md", "phase: done")
+	assertMissing(t, root, "work/alpha/proof.md")
+	assertMissing(t, root, "work/alpha/status.md")
 	assertFile(t, root, "work/alpha/review.md", "review\n")
 
 	f, err := state.LoadFeature(root, "alpha")
@@ -57,8 +61,9 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 
 func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	root := t.TempDir()
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/state.md"), "- Phase: prove\n")
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/evidence.md"), "evidence\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/feature.md"), "# Beta\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/status.md"), "- Phase: prove\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/proof.md"), "evidence\n")
 
 	res, err := Run(root)
 	if err != nil {
@@ -67,6 +72,9 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	if got := strings.Join(res.Migrated, ","); got != "beta" {
 		t.Fatalf("Run normalized=%q, want beta", got)
 	}
+	assertFile(t, root, "features/beta/README.md", "# Beta\n")
+	assertFile(t, root, "features/beta/state.md", "- Phase: prove\n")
+	assertFile(t, root, "features/beta/evidence.md", "evidence\n")
 	assertFile(t, root, "features/beta/status.md", "- Phase: prove\n")
 	assertFile(t, root, "features/beta/proof.md", "evidence\n")
 
@@ -111,3 +119,17 @@ func assertFile(t *testing.T, root, rel, want string) {
 		t.Fatalf("%s=%q, want %q", rel, got, want)
 	}
 }
+
+func assertFileContains(t *testing.T, root, rel, want string) {
+	t.Helper()
+	if got := testutil.ReadFile(t, filepath.Join(root, rel)); !strings.Contains(got, want) {
+		t.Fatalf("%s=%q, want it to contain %q", rel, got, want)
+	}
+}
+
+func assertMissing(t *testing.T, root, rel string) {
+	t.Helper()
+	if _, err := os.Stat(filepath.Join(root, rel)); !os.IsNotExist(err) {
+		t.Fatalf("%s exists or stat failed with %v, want missing", rel, err)
+	}
+}

package/engine/internal/state/feature.go

@@ -66,8 +66,8 @@ func featureDir(root, slug string) string {
 
 // ListFeatures returns the slugs of every feature under root — directories under
 // canonical work/ plus compatibility features/ recognized as a feature — sorted.
-// A directory is a feature if it has a manifest (feature.md) OR the working-state
-// ledger (state.md), so a live workspace the pack created without a manifest
+// A directory is a feature if it has a workspace map OR the working-state
+// ledger (state.md), so a live workspace the pack created without a map
 // still lists. Missing layout directories yield an empty list, not an error.
 func ListFeatures(root string) ([]string, error) {
 	seen := map[string]bool{}
@@ -96,11 +96,18 @@ func ListFeatures(root string) ([]string, error) {
 	return slugs, nil
 }
 
-// isFeatureDir reports whether dir is a recognized feature: it carries a manifest
-// or the working-state ledger. Either is a sufficient phase source for LoadFeature.
+// isFeatureDir reports whether dir carries a workspace map or the working-state
+// ledger. Either is a sufficient phase source for LoadFeature.
 func isFeatureDir(dir string) bool {
-	return regularFileExists(filepath.Join(dir, "feature.md")) ||
-		regularFileExists(filepath.Join(dir, LedgerFile))
+	if regularFileExists(filepath.Join(dir, LedgerFile)) {
+		return true
+	}
+	for _, name := range workspaceMapFiles {
+		if regularFileExists(filepath.Join(dir, name)) {
+			return true
+		}
+	}
+	return false
 }
 
 func regularFileExists(path string) bool {
@@ -109,18 +116,25 @@ func regularFileExists(path string) bool {
 }
 
 // LoadFeature reads feature <slug> under root. The phase comes from the live
-// working-state ledger when it declares one, otherwise from feature.md
-// frontmatter. A feature with neither a manifest nor a ledger does not exist.
-// Section content is read from the canonical section files or their transitional
+// working-state ledger when it declares one, otherwise from workspace-map
+// frontmatter. A feature with neither a map nor a ledger does not exist.
+// Section content is read from the canonical section files or their
 // aliases (see sectionFiles).
 func LoadFeature(root, slug string) (*Feature, error) {
 	dir := featureDir(root, slug)
 
-	manifest, mErr := os.ReadFile(filepath.Join(dir, "feature.md"))
-	if mErr != nil && !errors.Is(mErr, os.ErrNotExist) {
-		return nil, fmt.Errorf("feature %q: %w", slug, mErr)
+	var manifest []byte
+	for _, name := range workspaceMapFiles {
+		data, err := os.ReadFile(filepath.Join(dir, name))
+		if err == nil {
+			manifest = data
+			break
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("feature %q: read %s: %w", slug, name, err)
+		}
 	}
-	hasManifest := mErr == nil
+	hasManifest := manifest != nil
 	hasLedger := regularFileExists(filepath.Join(dir, LedgerFile))
 	if !hasManifest && !hasLedger {
 		return nil, fmt.Errorf("feature %q not found", slug)
@@ -150,7 +164,7 @@ func LoadFeature(root, slug string) (*Feature, error) {
 		phase = manifestPhase
 	}
 	if phase == "" {
-		return nil, fmt.Errorf("feature %q: no phase in feature.md frontmatter or %s ledger", slug, LedgerFile)
+		return nil, fmt.Errorf("feature %q: no phase in workspace-map frontmatter or %s ledger", slug, LedgerFile)
 	}
 	if !KnownPhase(phase) {
 		return nil, fmt.Errorf("feature %q: unknown phase %q", slug, phase)

package/engine/internal/state/schema.go

@@ -3,11 +3,23 @@ package state
 //go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
 
 // SchemaVersion is the .devrites state-schema version this engine understands.
-// A feature.md may declare its own schemaVersion in frontmatter; the engine
+// A workspace map may declare its own schemaVersion in frontmatter; the engine
 // refuses a version newer than this (see LoadFeature) and otherwise reads the
 // files, which evolve additively.
 const SchemaVersion = 1
 
+const (
+	WorkspaceMapFile = "README.md"
+	EvidenceFile     = "evidence.md"
+)
+
+var workspaceMapFiles = []string{WorkspaceMapFile, "feature.md", "index.md"}
+
+// WorkspaceMapFiles returns the canonical workspace map followed by readable aliases.
+func WorkspaceMapFiles() []string {
+	return append([]string(nil), workspaceMapFiles...)
+}
+
 // Section is one single-concern completeness file within a feature directory.
 // Splitting a feature into small files (rather than one long document) keeps
 // each file context-cheap and makes completeness self-evident.
@@ -33,23 +45,23 @@ var Sections = []Section{
 }
 
 // sectionFiles lists the filenames that can satisfy each section, canonical name
-// first, then the transitional aliases the live pack still writes — the same
-// mapping `devrites-engine migrate` normalizes (evidence→proof, state→status). A section
+// first, then supported aliases — the same mapping `devrites-engine migrate`
+// normalizes (proof→evidence, status→state). A section
 // counts as present if ANY of its files has real content, so the engine reads a
-// live workspace before the pack sweep converges the filenames. The manifest
-// (feature.md) is not a section; it is handled separately in LoadFeature.
+// live workspace before the pack sweep converges the filenames. The workspace
+// map is not a section; it is handled separately in LoadFeature.
 var sectionFiles = map[Section][]string{
 	SectionSpec:      {"spec.md"},
 	SectionPlan:      {"plan.md"},
 	SectionDecisions: {"decisions.md"},
 	SectionTasks:     {"tasks.md"},
-	SectionProof:     {"proof.md", "evidence.md"},
-	SectionStatus:    {"status.md", "state.md"},
+	SectionProof:     {EvidenceFile, "proof.md"},
+	SectionStatus:    {"state.md", "status.md"},
 }
 
 // LedgerFile is the working-state ledger the live pack writes. It carries the
 // phase in its canonical cursor table (legacy "- Phase: <p>" remains readable)
-// when no feature.md manifest declares one, and it satisfies the status section.
+// when no workspace map declares one, and it satisfies the status section.
 const LedgerFile = "state.md"
 
 // Phase is a workflow state. The order mirrors the rite-* arc.

package/engine/internal/state/state_test.go

@@ -138,9 +138,9 @@ func writeWorkSection(t *testing.T, root, slug, name, body string) {
 	}
 }
 
-// A live workspace the pack creates has no feature.md manifest: the phase lives in
-// the state.md ledger and the proof/status sections are satisfied by their aliases
-// (evidence.md / state.md). The engine must load, list, and report it anyway.
+// A live workspace map need not carry frontmatter: the phase lives in
+// the canonical state.md ledger and the proof/status concepts are satisfied by
+// evidence.md/state.md. The engine must load, list, and report it anyway.
 func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 	root := filepath.Join(t.TempDir(), ".devrites")
 	writeSection(t, root, "live", "state.md", "- Phase: prove\n- Status: running\n")
@@ -148,7 +148,7 @@ func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 	writeSection(t, root, "live", "plan.md", "# Plan\n\nApproach.\n")
 	writeSection(t, root, "live", "decisions.md", "# Decisions\n\nChose X.\n")
 	writeSection(t, root, "live", "tasks.md", "# Tasks\n\n- [x] slice 1\n")
-	writeSection(t, root, "live", "evidence.md", "# Evidence\n\nTests pass.\n") // alias for proof
+	writeSection(t, root, "live", "evidence.md", "# Evidence\n\nTests pass.\n")
 
 	rep, err := Status(root, "live")
 	if err != nil {
@@ -158,10 +158,10 @@ func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 		t.Errorf("phase = %q, want prove (from the state.md ledger)", rep.Phase)
 	}
 	if !rep.Present[SectionProof] {
-		t.Error("proof section should be present via its evidence.md alias")
+		t.Error("proof section should be present via canonical evidence.md")
 	}
 	if !rep.Present[SectionStatus] {
-		t.Error("status section should be present via its state.md alias")
+		t.Error("status section should be present via canonical state.md")
 	}
 	if !rep.Complete() {
 		t.Errorf("prove-phase feature should be complete, missing: %v", rep.Missing)

package/engine/tests/budget_test.go

@@ -7,8 +7,8 @@ import (
 
 // TestStatusLiveWorkspace is the P2 acceptance check: `devrites-engine status <slug>`
 // must report a canonical work/<slug> feature the live pack created without a
-// feature.md manifest — phase from the state.md ledger, proof/status via their
-// evidence.md/state.md aliases. Before the schema unification this returned
+// workspace-map frontmatter — phase from the canonical state.md ledger and proof/status
+// completeness from canonical evidence.md/state.md files. Before schema unification this returned
 // "feature not found".
 func TestStatusLiveWorkspace(t *testing.T) {
 	work := t.TempDir()

package/engine/tests/meta_test.go

@@ -1,7 +1,7 @@
 package main_test
 
-// Cross-cutting assertions the spec calls out explicitly: the engine makes zero
-// network calls, and the inline fail-open guard no-ops when the binary is absent.
+// Cross-cutting assertions: network I/O stays inside the one sanctioned package,
+// and the inline fail-open guard no-ops when the binary is absent.
 
 import (
 	"bytes"
@@ -11,7 +11,7 @@ import (
 )
 
 // TestFirstPartyMakesNoNetworkCalls asserts that no first-party package imports a
-// network client EXCEPT internal/iohooks — the ONE sanctioned network surface,
+// network client EXCEPT internal/iohooks — the one sanctioned network surface,
 // where the source-citation cache does conditional-HEAD revalidation. Confining
 // network to that single, auditable package keeps the rest of the engine a
 // network-free control plane that makes zero model calls (PRD: "zero API"). The

package/engine/tests/migrate_cli_test.go

@@ -58,25 +58,26 @@ func TestMigrateNormalizesCanonicalWorkSchema(t *testing.T) {
 	}
 
 	feat := filepath.Join(root, "work", slug)
-	// evidence.md → proof.md, state.md → status.md, plus a generated feature.md.
-	for _, want := range []string{"feature.md", "spec.md", "plan.md", "decisions.md", "tasks.md", "proof.md", "status.md"} {
+	// Current canonical files stay canonical; migration adds only the missing map.
+	for _, want := range []string{"README.md", "state.md", "spec.md", "plan.md", "decisions.md", "tasks.md", "evidence.md"} {
 		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
 			t.Errorf("missing new-schema file %s: %v", want, err)
 		}
 	}
-	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	readme, err := os.ReadFile(filepath.Join(feat, "README.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(fm), "phase: temper") {
-		t.Errorf("feature.md phase not derived from state.md\n%s", fm)
+	if !strings.Contains(string(readme), "phase: temper") {
+		t.Errorf("README.md phase not derived from state.md\n%s", readme)
 	}
-	if !strings.Contains(string(fm), "schemaVersion: 1") {
-		t.Errorf("feature.md missing schemaVersion\n%s", fm)
+	if !strings.Contains(string(readme), "schemaVersion: 1") {
+		t.Errorf("README.md missing schemaVersion\n%s", readme)
 	}
-	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
-	if !strings.Contains(string(proof), "Tests green") {
-		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	for _, unwanted := range []string{"feature.md", "proof.md", "status.md"} {
+		if _, err := os.Stat(filepath.Join(feat, unwanted)); !os.IsNotExist(err) {
+			t.Errorf("migration created legacy alias %s: %v", unwanted, err)
+		}
 	}
 
 	// A backup of the pre-migration state must exist.
@@ -127,11 +128,12 @@ func TestMigrateNormalizesLiveFeatureInPlace(t *testing.T) {
 		t.Fatal(err)
 	}
 	files := map[string]string{
-		"state.md":     "# State\n\n- Phase: prove\n- Status: running\n",
+		"feature.md":   "# Legacy feature map\n",
+		"status.md":    "# State\n\n- Phase: prove\n- Status: running\n",
 		"spec.md":      "# Spec\n\nRotate tokens.\n",
 		"plan.md":      "# Plan\n\nStep 1, step 2.\n",
 		"tasks.md":     "# Tasks\n\n- [x] one\n",
-		"evidence.md":  "# Evidence\n\nTests green.\n",
+		"proof.md":     "# Evidence\n\nTests green.\n",
 		"decisions.md": "# Decisions\n\nUse HMAC.\n",
 	}
 	for name, body := range files {
@@ -147,25 +149,25 @@ func TestMigrateNormalizesLiveFeatureInPlace(t *testing.T) {
 	if !strings.Contains(out, "migrated 1 feature(s)") {
 		t.Errorf("unexpected migrate output\n%s", out)
 	}
-	for _, want := range []string{"feature.md", "proof.md", "status.md", "state.md", "evidence.md"} {
+	for _, want := range []string{"README.md", "feature.md", "proof.md", "status.md", "state.md", "evidence.md"} {
 		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
 			t.Errorf("missing normalized file %s: %v", want, err)
 		}
 	}
-	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	readme, err := os.ReadFile(filepath.Join(feat, "README.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(fm), "phase: prove") {
-		t.Errorf("feature.md phase not derived from ledger\n%s", fm)
+	if !strings.Contains(string(readme), "Legacy feature map") {
+		t.Errorf("README.md did not carry feature.md content\n%s", readme)
 	}
-	status, _ := os.ReadFile(filepath.Join(feat, "status.md"))
-	if !strings.Contains(string(status), "running") {
-		t.Errorf("status.md did not carry state.md content\n%s", status)
+	stateFile, _ := os.ReadFile(filepath.Join(feat, "state.md"))
+	if !strings.Contains(string(stateFile), "running") {
+		t.Errorf("state.md did not carry status.md content\n%s", stateFile)
 	}
-	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
-	if !strings.Contains(string(proof), "Tests green") {
-		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	evidence, _ := os.ReadFile(filepath.Join(feat, "evidence.md"))
+	if !strings.Contains(string(evidence), "Tests green") {
+		t.Errorf("evidence.md did not carry proof.md content\n%s", evidence)
 	}
 	if got := backupDirs(t, root); len(got) != 1 {
 		t.Errorf("want exactly one backup dir, got %v", got)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",
@@ -54,6 +54,7 @@
     "test:fast": "node scripts/run-tests.mjs --fast",
     "test:parallel": "node scripts/run-tests.mjs",
     "test:serial": "node scripts/run-tests.mjs --serial",
+    "audit": "npm audit --audit-level=moderate",
     "size:baseline": "node scripts/check-instruction-size-baseline.mjs --write",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run --no-ci"

package/scripts/validate-workflow-security.py

@@ -4,9 +4,8 @@
 DevRites' publish (release.yml) and auto-merge paths are high-value targets, so this
 gate fails CI when a workflow:
 
-  - uses a THIRD-PARTY action not pinned to a full 40-char commit SHA — a moving tag
-    like `@v2` lets a compromised upstream inject code into the pipeline (GitHub-owned
-    `actions/*` and `github/*` tags are tolerated);
+  - uses any non-local action not pinned to a full 40-char commit SHA — a moving
+    tag like `@v2` lets a compromised upstream inject code into the pipeline;
   - declares no `permissions:` scope anywhere — the default token is broad;
   - uses `permissions: write-all` (over-broad);
   - uses `pull_request_target`, except for a Dependabot-only workflow that never
@@ -19,7 +18,6 @@ import os
 import re
 import sys
 
-FIRST_PARTY = {"actions", "github"}   # GitHub-owned; major-tag refs tolerated
 SHA_RE = re.compile(r"^[0-9a-f]{40}$")
 USES_RE = re.compile(r"^\s*-?\s*uses:\s*([^\s#]+)")
 DEPENDABOT_ONLY_RE = re.compile(
@@ -61,13 +59,10 @@ def scan_text(path, text):
         ref = m.group(1)
         if ref.startswith("./") or ref.startswith("."):
             continue  # local action
-        owner = ref.split("/", 1)[0]
-        if owner in FIRST_PARTY:
-            continue
         at = ref.rsplit("@", 1)
         pin = at[1] if len(at) == 2 else ""
         if not SHA_RE.match(pin):
-            findings.append("%s:%d: third-party action '%s' not pinned to a full commit "
+            findings.append("%s:%d: action '%s' not pinned to a full commit "
                             "SHA — pin it (a moving tag is a supply-chain risk)"
                             % (path, i, ref))
     return findings