chore: add mechanical doc gardening checks

Author: juancarlosrodicio

opencode/docs/ai/evolution/evolution_history.md

@@ -62,3 +62,22 @@ Evidence:
 - Temporary positive and negative lifecycle fixtures passed/fail as expected.
 - `change_evaluation.json` records `keep` for the approved scope and documents
   the remaining transcript replay limitation for `/evolve`.
+
+## Iteration 013 - Doc Gardening Mechanical Checks
+
+Status: `keep`.
+
+Changes:
+
+- `scripts/check-harness.mjs` validates that `AGENTS.md` stays a short index.
+- The checker requires documentation coverage for visible agents and commands.
+- The checker validates local paths referenced by manifests and evaluations.
+- `docs/ai/harness/checks.md` documents these rules as mechanical doc gardening.
+
+Evidence:
+
+- `node --check scripts/check-harness.mjs` passed.
+- `node scripts/check-harness.mjs` passed.
+- A temporary negative control confirmed the expected failure when a command is
+  not documented.
+- `./scripts/check.sh` passed from the public repository root.

opencode/docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/analysis/overview.md

@@ -0,0 +1,27 @@
+# Iteration 013 Analysis
+
+## Evidence reviewed
+
+- `scripts/check-harness.mjs`
+- `docs/ai/harness/checks.md`
+- `docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/evaluation.md`
+
+## Root cause
+
+The harness already documented doc gardening as a practice, but several cheap
+rules were still manual: keeping `AGENTS.md` short, documenting all visible
+agents and commands, and avoiding broken local evidence paths in AHE JSON.
+
+## Chosen component
+
+The narrowest fix is tooling plus docs:
+
+- `scripts/check-harness.mjs` enforces the rules locally.
+- `docs/ai/harness/checks.md` declares the rules as mechanical doc gardening.
+
+No agent contract, command flow, provider, model, or permission change is needed.
+
+## Attribution expectation
+
+Future harness edits should fail earlier when they add agents, commands, or AHE
+evidence without updating the local knowledge map.

opencode/docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/change_evaluation.json

@@ -0,0 +1,32 @@
+{
+  "iteration": 13,
+  "evaluates_iteration": 13,
+  "results": [
+    {
+      "change_id": "chg-1-mechanical-doc-gardening-checks",
+      "predicted_fixes_confirmed": [
+        "The packaged checker now validates AGENTS.md as a short index with references to docs/ai/harness/ and docs/ai/evolution/.",
+        "The packaged checker now validates coverage for agents/*.md in docs/ai/harness/agents.md.",
+        "The packaged checker now validates coverage for commands/*.md in docs/ai/harness/commands.md.",
+        "The packaged checker now validates files and evidence paths in AHE JSON without treating arbitrary prose as a path."
+      ],
+      "predicted_fixes_not_confirmed": [],
+      "risk_tasks_regressed": [],
+      "risk_tasks_not_regressed": [
+        "No workflow phase was added for normal feature work.",
+        "No routing, permission, model, provider, or agent behavior changed.",
+        "The path parser is limited to files and evidence fields so prose is not treated as a path."
+      ],
+      "unpredicted_regressions": [],
+      "decision": "keep",
+      "evidence": [
+        "docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/evaluation.md",
+        "docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/analysis/overview.md",
+        "docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/change_manifest.json",
+        "scripts/check-harness.mjs",
+        "docs/ai/harness/checks.md"
+      ],
+      "notes": "This is a static-contract/tooling iteration. Transcript replay is intentionally not required because the change does not modify routing or runtime agent behavior."
+    }
+  ]
+}

opencode/docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/change_manifest.json

@@ -0,0 +1,49 @@
+{
+  "iteration": 13,
+  "changes": [
+    {
+      "id": "chg-1-mechanical-doc-gardening-checks",
+      "type": "improvement",
+      "description": "Extend the packaged harness checker so cheap doc-gardening rules are enforced mechanically instead of staying only as manual review guidance.",
+      "files": [
+        "scripts/check-harness.mjs",
+        "docs/ai/harness/checks.md"
+      ],
+      "failure_pattern": "Harness documentation can drift when AGENTS.md stops acting as a short index, new agents or commands are not reflected in docs, or AHE JSON references local artifacts that no longer exist.",
+      "evidence": [
+        "docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/evaluation.md",
+        "docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/analysis/overview.md",
+        "docs/ai/harness/checks.md",
+        "scripts/check-harness.mjs"
+      ],
+      "root_cause": "Doc gardening was documented as a lightweight practice, but the checker only validated a subset of the rules, leaving avoidable drift to manual review.",
+      "component_touched": "tooling",
+      "predicted_fixes": [
+        "The checker fails when AGENTS.md no longer references the harness and evolution docs or grows beyond the short-index threshold.",
+        "The checker fails when an agent markdown file is not documented in docs/ai/harness/agents.md.",
+        "The checker fails when a command markdown file is not documented in docs/ai/harness/commands.md.",
+        "The checker fails when files or evidence fields in AHE JSON reference missing local repo paths."
+      ],
+      "risk_tasks": [
+        "Do not add new mandatory workflow phases for normal feature work.",
+        "Do not change routing, permissions, models, providers, or agent behavior.",
+        "Avoid an over-broad path parser that treats prose as a missing local path.",
+        "Keep error messages specific enough for agent remediation."
+      ],
+      "constraint_level": "tool",
+      "why_this_component": "The failure pattern is repository drift in local docs and AHE artifacts, so a local checker is the smallest enforceable boundary. Agent prompts would be weaker and runtime replays are unnecessary because no routing behavior changes.",
+      "post_change_validation": [
+        "Run `node --check scripts/check-harness.mjs`.",
+        "Run `node scripts/check-harness.mjs` and require `Harness check passed.`",
+        "Run a temporary negative control that removes one command documentation marker and require a missing documented command failure.",
+        "Run `./scripts/check.sh` from the public repository root.",
+        "Run `git diff --check`."
+      ],
+      "decision_criteria": {
+        "keep": "All static checks pass and the negative control fails with a clear doc coverage message.",
+        "improve": "The main check passes but the negative control message is unclear or too broad.",
+        "rollback+pivot": "The checker rejects valid historical artifacts or requires behavioral/routing changes to pass."
+      }
+    }
+  ]
+}

opencode/docs/ai/evolution/runs/iteration-013-doc-gardening-mechanical-checks/evaluation.md

@@ -0,0 +1,92 @@
+# Iteration 013 - Doc Gardening Mechanical Checks
+
+## Objective evaluated
+
+Convert cheap doc-gardening rules into local mechanical checks without changing
+agent routing, permissions, models, providers, or workflow behavior.
+
+## Scenarios executed
+
+### Scenario 1 - Script syntax
+
+- Evidence type: `static_contract`
+- Command:
+
+```bash
+node --check scripts/check-harness.mjs
+```
+
+- Expected: syntax check exits successfully.
+- Result: pass.
+
+### Scenario 2 - Harness contract check
+
+- Evidence type: `static_contract`
+- Command:
+
+```bash
+node scripts/check-harness.mjs
+```
+
+- Expected: checker accepts the packaged harness and reports
+  `Harness check passed.`
+- Result: pass.
+
+### Scenario 3 - Negative doc coverage control
+
+- Evidence type: `static_contract`
+- Command:
+
+```bash
+tmpdir="$(mktemp -d)"
+cp -R . "$tmpdir/opencode"
+python3 - "$tmpdir/opencode/docs/ai/harness/commands.md" <<'PY'
+from pathlib import Path
+path = Path(__import__("sys").argv[1])
+text = path.read_text()
+path.write_text(text.replace("### `/test`", "### `test`", 1))
+PY
+(cd "$tmpdir/opencode" && node scripts/check-harness.mjs)
+```
+
+- Expected: checker fails with a clear missing documented command message.
+- Result: pass.
+
+### Scenario 4 - Public repository check
+
+- Evidence type: `static_contract`
+- Command from repository root:
+
+```bash
+./scripts/check.sh
+```
+
+- Expected: required files, packaged harness checks, and private-data scan pass.
+- Result: pass.
+
+### Scenario 5 - Whitespace safety
+
+- Evidence type: `static_contract`
+- Command from repository root:
+
+```bash
+git diff --check
+```
+
+- Expected: no whitespace errors.
+- Result: pass.
+
+## Results summary
+
+| Scenario | Type | Status |
+| --- | --- | --- |
+| Script syntax | static_contract | pass |
+| Harness contract check | static_contract | pass |
+| Negative doc coverage control | static_contract | pass |
+| Public repository check | static_contract | pass |
+| Whitespace safety | static_contract | pass |
+
+## Residual risk
+
+This iteration proves the checker catches local documentation drift. It does not
+prove any runtime routing change, and none was intended.

opencode/docs/ai/harness/checks.md

@@ -18,13 +18,21 @@ The harness check validates:
 
 - `opencode.json`;
 - `default_agent: lead`;
+- `AGENTS.md` as a short index pointing to `docs/ai/harness/` and
+  `docs/ai/evolution/`;
 - minimum frontmatter in `agents/*.md` and `commands/*.md`;
+- documentation coverage for every `agents/*.md` file in
+  `docs/ai/harness/agents.md`;
+- documentation coverage for every `commands/*.md` file in
+  `docs/ai/harness/commands.md`;
 - local `/feature` contract;
 - local `/plan` contract;
 - main docs in `docs/ai/harness/`;
 - benchmark references to replay and evidence taxonomy;
 - AHE run lifecycle under `docs/ai/evolution/runs/`;
 - AHE manifests when present.
+- local paths referenced by `change_manifest.json` and
+  `change_evaluation.json`.
 
 ## AHE Run Lifecycle
 
@@ -45,4 +53,12 @@ Before closing an AHE iteration:
 - verify every manifest has predicted fixes, risk tasks, and component level;
 - add `change_evaluation.json` when evaluating a previous change.
 
+## Mechanical Doc Gardening
+
+The local check turns the cheapest maintenance rules into mechanical checks:
+
+- `AGENTS.md` must stay a short map, not a long manual;
+- new agents and commands must appear in the harness docs;
+- manifests and evaluations must not point to missing local artifacts.
+
 Do not make doc gardening mandatory for normal features.

opencode/docs/ai/harness/commands.md

@@ -68,6 +68,17 @@ Criteria:
 - `debugger` enters only for traces, results, or concrete previous evidence.
 - Output is scoped specs, atomic tasks, and validation.
 
+## `/mvp-spec`
+
+Contract: `scoper -> researcher -> scoper synthesis -> specifier`.
+
+Criteria:
+
+- Same no-implementation boundary as `/scope`.
+- Produces a strict MVP spec with small 1-2 hour tasks.
+- Makes out of scope explicit.
+- Stops if research is not ready for spec.
+
 ## Visible Auxiliary/Subtask Commands
 
 These commands are visible slash commands, but they do not add mandatory phases