chore: remove stale root files and consolidate docs/

.claude/agents/requirements_reviewer.md

@@ -16,13 +16,13 @@ You are a requirements traceability reviewer. Your job is to verify the three-wa
 
 ## Project Conventions
 
-This project uses formal requirements documents with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY, etc.) located in the `specs/` directory. Specs are organized into domain subdirectories:
+This project uses formal requirements documents with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY, etc.) located in the `doc/specs/` directory. Specs are organized into domain subdirectories:
 
-- `specs/deepwork/` — root DeepWork specs (DW-REQ-prefixed)
-- `specs/deepwork/jobs/` — job-related specs (JOBS-REQ-prefixed)
-- `specs/deepwork/review/` — review-related specs (REVIEW-REQ-prefixed)
-- `specs/deepwork/cli_plugins/` — CLI plugin specs (PLUG-REQ-prefixed)
-- `specs/learning-agents/` — learning agent specs (LA-REQ-prefixed)
+- `doc/specs/deepwork/` — root DeepWork specs (DW-REQ-prefixed)
+- `doc/specs/deepwork/jobs/` — job-related specs (JOBS-REQ-prefixed)
+- `doc/specs/deepwork/review/` — review-related specs (REVIEW-REQ-prefixed)
+- `doc/specs/deepwork/cli_plugins/` — CLI plugin specs (PLUG-REQ-prefixed)
+- `doc/specs/learning-agents/` — learning agent specs (LA-REQ-prefixed)
 
 Each file follows the naming pattern `{PREFIX}-REQ-NNN-<topic>.md`, where the prefix identifies the domain:
 
@@ -75,7 +75,7 @@ When asked to review, perform these checks:
 ### 1. Requirements Coverage
 
 For every piece of new or changed end-user functionality in the diff (end-user functionality means behavior observable through public APIs, CLI commands, MCP tools, or documented outputs — internal refactoring that doesn't change observable behavior does not require new requirements):
-- Verify there is a corresponding requirement in `specs/**/*-REQ-*.md`
+- Verify there is a corresponding requirement in `doc/specs/**/*-REQ-*.md`
 - If functionality is new, check that a new requirement was added
 - If functionality changed, check that the relevant requirement was updated
 - Flag any functional code changes that lack a matching requirement

.deepreview

@@ -118,7 +118,7 @@ requirements_traceability:
     instructions: |
       Review the changed files for requirements traceability.
 
-      This project keeps formal requirements in `specs/` organized by domain.
+      This project keeps formal requirements in `doc/specs/` organized by domain.
       Each file follows the naming pattern `{PREFIX}-REQ-NNN-<topic>.md` where
       PREFIX is one of: DW-REQ, JOBS-REQ, REVIEW-REQ, LA-REQ, PLUG-REQ.
       Requirements are individually numbered (e.g. JOBS-REQ-004.1). Requirements
@@ -192,12 +192,12 @@ requirements_traceability:
       `assert "--platform" in args` can verify exactly. If the requirement
       specifies a concrete value, path, or structure, use a test.
 
-      See specs/validating_requirements_with_rules.md for more information.
+      See doc/specs/validating_requirements_with_rules.md for more information.
 
       ## Review checklist
 
       1. Check that any new or changed end-user functionality has a
-         corresponding requirement in `specs/`.
+         corresponding requirement in `doc/specs/`.
       2. Check that every requirement touched by this change has at least
          one automated test OR at least one `.deepreview` rule validating
          it. **Verify the mechanism matches the requirement type** — flag

.deepwork/requirements_traceability_info.sh

@@ -13,7 +13,7 @@ REPO_ROOT="$(git rev-parse --show-toplevel)"
 cd "$REPO_ROOT"
 
 # Configurable directories
-SPEC_DIR="specs"
+SPEC_DIR="doc/specs"
 TEST_DIR="tests"
 
 TMPDIR_TRACE=$(mktemp -d)

CHANGELOG.md

@@ -13,6 +13,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Deprecated the `steps/` folder pattern for job definitions — step instructions are now inlined in `job.yml`; moved supplemental reference files from `steps/` to job root directories
 - Repair workflow now instructs agents to `git rm` step instruction files after inlining
+- Moved `specs/` to `doc/specs/` and consolidated `docs/` into `doc/` to reduce root directory clutter
+
+### Removed
+
+- `coverage_report.md` (stale snapshot)
+- `job_refactor.md` (superseded planning notes)
+- `CLAUDE_PLUGINS_README.md` (redundant with README.md)
 
 ### Fixed
 

README.md

@@ -297,7 +297,7 @@ requirements_traceability:
   review:
     strategy: all_changed_files
     instructions: |
-      This project keeps formal requirements in specs/.
+      This project keeps formal requirements in doc/specs/.
       Verify that every requirement has a corresponding
       automated test or review rule that enforces it.
       Flag any requirement missing traceability.

README_REVIEWS.md

@@ -10,7 +10,7 @@ DeepWork Reviews lets you define automated code review policies using `.deeprevi
 - **"Gotcha" regression checkers** — Watch a specific file or module for a known class of mistake that has regressed before, with instructions describing exactly what to look for
 - **Cross-file consistency reviews** — Group a logical set of interrelated files (e.g., API schema + client code + tests) so the reviewer can verify that any individual change makes sense in the wider context
 - **Tone and style reviews for human-facing content** — Review copy, docs, blog posts, or marketing pages for consistent voice, reading level, and style guidelines
-- **Requirements validation** — Verify that code, config, and instruction files satisfy formal requirements that need judgment to evaluate (see [Validating Requirements with Review Rules](specs/validating_requirements_with_rules.md))
+- **Requirements validation** — Verify that code, config, and instruction files satisfy formal requirements that need judgment to evaluate (see [Validating Requirements with Review Rules](doc/specs/validating_requirements_with_rules.md))
 
 ## How It Works
 

tests/unit/plugins/test_claude_plugin.py

@@ -1,7 +1,7 @@
 """Tests for the Claude Code plugin — validates PLUG-REQ-001.
 
 Each test class maps to a numbered requirement section in
-specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md.
+doc/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md.
 
 Requirements that need judgment to evaluate (e.g., "skill MUST instruct the
 agent to do X") are validated by review rules in .deepreview, not by tests.

tests/unit/test_learning_agents_file_structure.py

@@ -9,7 +9,7 @@
 LA-REQ-005.12, LA-REQ-005.13.
 
 Each test class maps to a numbered requirement section in the corresponding
-spec under specs/learning-agents/.
+spec under doc/specs/learning-agents/.
 
 Only deterministic, boolean-verifiable requirements have tests here.
 Judgment-based requirements are covered by DeepSchemas on the relevant skill files.

tests/unit/test_learning_agents_plugin.py

@@ -4,7 +4,7 @@
 LA-REQ-001.4, LA-REQ-001.5, LA-REQ-001.6, LA-REQ-001.7, LA-REQ-001.8.
 
 Each test class maps to a numbered requirement section in
-specs/learning-agents/LA-REQ-001-plugin-structure.md.
+doc/specs/learning-agents/LA-REQ-001-plugin-structure.md.
 
 Only deterministic, boolean-verifiable requirements have tests here.
 """

tests/unit/test_learning_agents_session_tracking.py

@@ -6,7 +6,7 @@
 LA-REQ-004.15, LA-REQ-004.16, LA-REQ-004.17, LA-REQ-004.18.
 
 Each test maps to a numbered requirement in
-specs/learning-agents/LA-REQ-004-session-tracking.md.
+doc/specs/learning-agents/LA-REQ-004-session-tracking.md.
 
 Tests validate hook script content (jq commands, file paths, variable handling)
 and behavioral logic (script execution with controlled inputs).

tests/unit/test_learning_agents_skills.py

@@ -5,7 +5,7 @@
 LA-REQ-011.10, LA-REQ-011.11, LA-REQ-011.12, LA-REQ-011.13.
 
 Each test class maps to a numbered requirement section in
-specs/learning-agents/LA-REQ-011-skill-routing.md.
+doc/specs/learning-agents/LA-REQ-011-skill-routing.md.
 
 Only deterministic, boolean-verifiable requirements have tests here.
 These tests inspect the SKILL.md files directly for correct routing