Add DOX validation, templates, and evidence docs

.github/AGENTS.md

@@ -0,0 +1,28 @@
+# GitHub automation DOX
+
+## Purpose
+
+Owns GitHub-native automation for this repository.
+
+## Ownership
+
+- `workflows/dox-lint.yml` runs the optional DOX structural validator in GitHub Actions.
+
+## Local Contracts
+
+- Workflows must use repository-local scripts where possible.
+- CI must not require secrets for documentation validation.
+- Workflow names should describe the check they run.
+
+## Work Guidance
+
+- Keep workflow permissions minimal.
+- Prefer standard GitHub-hosted runners and stock actions for portability.
+
+## Verification
+
+- Run `python3 scripts/dox_lint.py .` locally before relying on the workflow.
+
+## Child DOX Index
+
+No child DOX files yet.

.github/workflows/dox-lint.yml

@@ -0,0 +1,23 @@
+name: DOX lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  dox-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Run DOX structural validator
+        run: python3 scripts/dox_lint.py .
+
+      - name: Run linter regression tests
+        run: python3 -m unittest discover -s tests

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+node_modules/
+dist/
+build/
+coverage/
+.DS_Store

AGENTS.md

@@ -1,7 +1,9 @@
+<!-- DOX-CORE-START: do not edit or remove this protected framework block -->
 # DOX framework
 
-- DOX is highly performant AGENTS.md hierarchy installed here
-- Agent must follow DOX instructions across any edits
+- DOX is a highly portable AGENTS.md hierarchy installed here
+- Agents must follow DOX instructions across any edits
+- The protected framework block between `DOX-CORE-START` and `DOX-CORE-END` is the root contract and must not be weakened, removed, or rewritten by agents
 
 ## Core Contract
 
@@ -76,8 +78,25 @@ Default section order:
 
 ## User Preferences
 
-When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md
+When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md.
+<!-- DOX-CORE-END: protected framework block ends here -->
+
+## Project Guidance
+
+- This repository distributes DOX as Markdown-first guidance plus optional helper conventions.
+- Keep the core install path copy-pasteable: users can still copy `AGENTS.md` without installing anything.
+- Optional tooling must remain additive. Scripts and specs may validate DOX trees, but they must not make the Markdown framework dependent on a package or service.
+- Distinguish reported evidence from verified guarantees. Do not present third-party metrics as proof unless the methodology is independently audited.
+
+## Verification
+
+- Run `python3 scripts/dox_lint.py .` after changing AGENTS.md structure, docs conventions, or child indexes.
+- For docs-only prose changes that do not affect the DOX tree, review the rendered Markdown or changed diff.
 
 ## Child DOX Index
 
-This project is not yet indexed. Before continuing you must scan the project, build the DOX tree and replace this message with the actual index. Go deep and scan files recursively to properly evaluate complexity and create nested DOX files where needed.
+- `.github/AGENTS.md` — GitHub Actions automation for DOX validation.
+- `agents/AGENTS.md` — templates for orchestrator/documenter agent workflows that maintain DOX trees.
+- `docs/AGENTS.md` — DOX specification, validation convention, and evidence/caveat documentation.
+- `scripts/AGENTS.md` — optional local tooling for validating DOX structure.
+- `tests/AGENTS.md` — regression tests for optional DOX tooling.

README.md

@@ -29,6 +29,47 @@ No AGENTS.md yet? Copy the file into your project root. The agent will see these
 
 For an existing project, you can tell your agent: `Initialize DOX tree for this project now.` It will create all the child AGENTS.md files and indexes.
 
+## Usage examples
+
+### Basic setup
+
+1. Create or open a project repository.
+2. Copy [AGENTS.md](./AGENTS.md?plain=1) to the project root.
+3. Ask your coding agent: `Initialize DOX tree for this project now.`
+4. Review the generated child indexes before accepting the changes.
+
+### After changing code
+
+1. The agent reads the root `AGENTS.md` and every applicable child `AGENTS.md` before editing.
+2. The agent makes the requested code or documentation change.
+3. The agent performs a DOX pass before closeout.
+4. If the change affects durable structure, ownership, contracts, workflows, verification, or child indexes, the nearest owning `AGENTS.md` is updated.
+5. If the change is local and does not affect durable rules, the agent reports that docs were intentionally left unchanged.
+
+### Optional validation
+
+DOX is Markdown-first, but this fork includes an optional convention and linter:
+
+```bash
+python3 scripts/dox_lint.py .
+```
+
+The linter checks that child indexes point to real `AGENTS.md` files, child docs keep the standard section shape, and the protected root DOX framework block is present. This fork also includes a GitHub Actions workflow that runs the same check on pushes to `main` and pull requests.
+
+## Optional agent templates
+
+See [agents/](./agents/) for portable orchestrator and documenter templates. They describe a two-agent maintenance pattern:
+
+- an orchestrator scans the repository and assigns candidate paths
+- documenter agents inspect one path at a time and update the nearest owning `AGENTS.md` when DOX requires it
+
+The templates are examples, not a required runtime. Adapt their tool names to your agent harness.
+
+## Specification and evidence
+
+- [docs/spec.md](./docs/spec.md) defines the optional machine-checkable DOX convention.
+- [docs/evidence.md](./docs/evidence.md) records reported third-party session metrics and the caveats around interpreting them.
+
 ## Credits
 
 <p align="center">

agents/AGENTS.md

@@ -0,0 +1,29 @@
+# Agent templates DOX
+
+## Purpose
+
+Owns reusable agent prompt templates for maintaining DOX trees.
+
+## Ownership
+
+- `orchestrator.md` describes the coordination role for scanning candidate files and delegating documentation work.
+- `documenter.md` describes the focused role for inspecting one path and updating the nearest owning `AGENTS.md` when required.
+
+## Local Contracts
+
+- Templates must remain harness-portable. Name common capabilities instead of hard-coding one tool stack unless a section is explicitly adapter-specific.
+- Templates must not require DOX users to install a runtime.
+- Documenter guidance may edit `AGENTS.md` files only; source-file edits belong to the caller's coding agent.
+
+## Work Guidance
+
+- Keep outputs concise and deterministic so orchestrators can parse them.
+- Include adapter notes for Codex, Claude Code, OpenCode, and Hermes-style subagents only as examples.
+
+## Verification
+
+- Run `python3 scripts/dox_lint.py .` after changing this folder or its child index.
+
+## Child DOX Index
+
+No child DOX files yet.

agents/documenter.md

@@ -0,0 +1,65 @@
+# DOX documenter agent template
+
+## Purpose
+
+Inspect one target path and update the nearest owning `AGENTS.md` only when DOX requires a durable documentation change.
+
+## Inputs
+
+- Repository root path.
+- One target file or directory path.
+- Optional changed-file diff or summary from the caller.
+
+## Workflow
+
+1. Read the root `AGENTS.md`.
+2. Walk from the repository root to the target path.
+3. Read every `AGENTS.md` on that route.
+4. Use the nearest `AGENTS.md` as the local contract and parent docs for broader rules.
+5. Inspect the target path enough to understand whether it changes:
+   - purpose, scope, ownership, or responsibilities
+   - durable structure, contracts, workflows, or operating rules
+   - required inputs, outputs, permissions, constraints, side effects, or artifacts
+   - verification or quality expectations
+   - child `AGENTS.md` index contents
+6. If the target creates a durable boundary, create a child `AGENTS.md` with the standard section shape.
+7. If the nearest owning doc is stale, update it concisely.
+8. If no durable contract changed, leave docs untouched.
+9. Return exactly one result line:
+
+```text
+PATH <path> | ACTION <updated|created|skipped|error> | DOX <path|none> | DETAIL <brief reason>
+```
+
+## Constraints
+
+- Edit only `AGENTS.md` files.
+- Do not edit source files, README prose, specs, or scripts unless the caller explicitly assigned that documentation file as the target.
+- Do not weaken or remove the protected root DOX framework block.
+- Do not duplicate broad parent rules in child docs.
+- Delete stale contradictions instead of preserving historical notes.
+- Keep `DETAIL` under 100 characters.
+
+## Decision guide
+
+Update docs when the answer is yes:
+
+- Would a future agent need to know this to edit safely?
+- Did ownership, workflow, verification, side effects, or durable structure change?
+- Did a parent child-index become wrong?
+- Did a new folder become a stable boundary?
+
+Skip docs when the answer is yes:
+
+- Is this a one-off content edit with no durable process impact?
+- Is the target generated, cached, vendored, or temporary?
+- Is the existing `AGENTS.md` already accurate?
+
+## Example results
+
+```text
+PATH src/api/server.py | ACTION updated | DOX src/api/AGENTS.md | DETAIL added streaming endpoint contract
+PATH docs/spec.md | ACTION skipped | DOX docs/AGENTS.md | DETAIL existing docs contract already covers spec prose
+PATH src/payments | ACTION created | DOX src/payments/AGENTS.md | DETAIL new durable payment boundary
+PATH missing.py | ACTION error | DOX none | DETAIL target path not found
+```

agents/orchestrator.md

@@ -0,0 +1,57 @@
+# DOX orchestrator agent template
+
+## Purpose
+
+Coordinate DOX maintenance across a repository without letting one agent mutate the whole tree blindly.
+
+The orchestrator scans candidate paths, selects the paths that may affect durable documentation, delegates one path at a time to a documenter agent, collects compact results, and reports the final DOX maintenance summary.
+
+## Inputs
+
+- Repository root path.
+- Changed paths, selected paths, or a user request such as `Initialize DOX tree for this project now.`
+- Access to a documenter subagent or an equivalent isolated worker.
+
+## Workflow
+
+1. Read root `AGENTS.md`.
+2. Build a concise repository map, excluding generated/vendor/cache folders such as `.git/`, `node_modules/`, `.venv/`, `dist/`, `build/`, and coverage outputs.
+3. Identify candidate files or directories that may affect durable project structure, ownership, contracts, workflows, verification, or child indexes.
+4. For each candidate path, launch a documenter worker with:
+   - repository root
+   - absolute or root-relative target path
+   - the current DOX chain that applies to that path, if already known
+5. Require the documenter to return one result line:
+
+```text
+PATH <path> | ACTION <updated|created|skipped|error> | DOX <path|none> | DETAIL <brief reason>
+```
+
+6. Continue after errors, but include them in the final report.
+7. After all workers finish, run the available DOX validation command if one exists.
+8. Report:
+   - total paths processed
+   - updated/created/skipped/error counts
+   - `AGENTS.md` files touched
+   - validation result
+
+## Constraints
+
+- Do not edit source files. The orchestrator coordinates documentation only.
+- Prefer changed paths over a full repository scan when the caller provides a diff.
+- Do not create child `AGENTS.md` files for temporary or generated folders.
+- Do not weaken the protected root DOX framework block.
+- Keep final output short enough for a caller to act on.
+
+## Adapter notes
+
+Different agent harnesses expose different tool names:
+
+| Capability | Examples |
+|---|---|
+| Spawn worker | `task`, `delegate_task`, subagent, child process |
+| Ask user | `question`, `clarify`, chat prompt |
+| Read file | `read`, `read_file`, filesystem tool |
+| Run command | `bash`, `terminal`, shell tool |
+
+Use the capability, not the literal tool name, unless you are writing for one specific harness.

docs/AGENTS.md

@@ -0,0 +1,30 @@
+# Docs DOX
+
+## Purpose
+
+Owns human-readable DOX specifications, validation conventions, and evidence notes.
+
+## Ownership
+
+- `spec.md` defines the optional machine-checkable convention for DOX trees.
+- `evidence.md` records claims, caveats, and interpretation boundaries for reported DOX outcomes.
+
+## Local Contracts
+
+- Keep DOX Markdown-first. Specs may define optional validation, but must not imply users need a package or service to use DOX.
+- Separate normative requirements from recommendations and examples.
+- Evidence notes must distinguish reported third-party observations from verified guarantees.
+
+## Work Guidance
+
+- Prefer short, operational sections over broad essays.
+- Use RFC-style words only when useful: required, recommended, optional.
+- Do not overclaim empirical impact without methodology, raw data, or reproducible analysis.
+
+## Verification
+
+- Run `python3 scripts/dox_lint.py .` from the repository root after changing docs structure or child indexes.
+
+## Child DOX Index
+
+No child DOX files yet.

docs/evidence.md

@@ -0,0 +1,40 @@
+# DOX evidence notes
+
+This page records reported evidence and caveats. It is not a benchmark certificate.
+
+## Reported external observation
+
+GitHub issue #3 reported an analysis of 9,911 Claude Code session logs comparing sessions with custom agent rulesets such as `AGENTS.md`/DOX against sessions without them.
+
+Reported figures:
+
+| Metric | With DOX / AGENTS.md | Without DOX / AGENTS.md | Reported difference |
+|---|---:|---:|---:|
+| Average human turns per session | 4.87 | 1.66 | +193% |
+| Average prompt input tokens | 73,097.8 | 16,537.6 | Larger context navigation |
+| Average tool errors per session | 0.68 | 0.37 | Higher, not automatically better |
+| Average API cost per session | $10.48 | $2.09 | Higher, not automatically better |
+
+## Interpretation boundaries
+
+The data suggests that structured agent instructions may correlate with longer, deeper agent sessions. It does not, by itself, prove that DOX causes better outcomes.
+
+Important caveats:
+
+- Longer sessions can mean harder tasks, better persistence, or inefficient loops.
+- Higher token use and cost can mean deeper work, or waste.
+- Higher tool errors are not inherently positive.
+- Public issue text does not provide raw data, sampling rules, or reproducible analysis.
+- `AGENTS.md` usage may correlate with more sophisticated users or larger repositories.
+
+## Responsible claim
+
+Safe wording:
+
+> DOX gives agents a durable local context structure. Third-party users have reported longer and deeper agent sessions with AGENTS.md-style rulesets, but those reports should be treated as observational rather than causal proof.
+
+Avoid wording like:
+
+> DOX proves agents are 193% better.
+
+That claim is not supported by the available public evidence.