modify agents.md to follow parent in root

docs/AGENTS.md

@@ -1,32 +1,7 @@
-# Documentation rules for this repository
+# Sensor design documentation
 
-The workspace writing standard is authoritative for every document here. It is at
+Follow [AUTHORING](../../docs/AUTHORING.md) and [AGENTS](../../AGENTS.md).
-`D:\orisys_ws\docs\AUTHORING.md` on disk, not in this repository.
 
-This file exists because that standard is not auto-discovered from inside a repository: the
+Keep Blender/export contracts and measured probe results in repository docs.
-workspace skill root is `D:\orisys_ws\.agents\skills\`, and an agent whose working directory is
+Distinguish nominal design, simulated response and hardware measurements in every parameter table.
-`D:\orisys_ws\orisys-sensor-design` resolves its project root to this repository's `.git`. Read
+Use tools/lint_gate.py with the design environment; see AUTHORING for required workspace tooling.
-the standard at the path above.
-
-## Where this repository's documents belong
-
-| Document | Home |
-|---|---|
-| The exported unwarp map and nominal geometry contract | `docs/design-parameters.md` |
-| How to re-run the probe and how to read its output | `docs/probe-method.md`, `docs/probe-pipeline.md` |
-| Measured probe results | `docs/probe-findings.md` |
-| Blender authoring decisions and rejected alternatives | a decision record under `docs/` |
-| Throwaway: rendered frames, per-run job files, sweep logs | `build/` (already gitignored) |
-
-The last row matters most here: this repository generates ~90 MB of derived probe output per
-run. That is regenerated output, not design input, and it must not be promoted into `docs/`.
-
-## Check your documents before finishing
-
-```powershell
-python D:\orisys_ws\scripts\doc_lint.py          # changed Markdown — must pass
-python D:\orisys_ws\scripts\doc_lint.py --all    # audit the whole corpus
-```
-
-`tools/lint_gate.py` runs this alongside Ruff. Oversized documents already present are recorded
-in `D:\orisys_ws\docs\inventory.json` with a written reason, so only new growth fails.

tools/lint_gate.py

@@ -131,16 +131,24 @@ def run_doc_gate(force_all: bool) -> dict:
     """
     script = REPO.parent / "scripts" / "doc_lint.py"
     if not script.is_file():
-        return {"status": "unavailable", "findings": [], "baselined": []}
+        print(f"lint_gate: required documentation checker missing: {script}", file=sys.stderr)
+        return {"status": "error", "findings": [], "baselined": []}
     cmd = [sys.executable, str(script), "--json"]
     if force_all:
         cmd.append("--all")
     result = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", check=False)
+    if result.returncode not in (0, 1):
+        print(f"lint_gate: documentation checker failed ({result.returncode}): {result.stderr.strip()}", file=sys.stderr)
+        return {"status": "error", "findings": [], "baselined": []}
     if not result.stdout.strip():
         print(f"lint_gate: doc gate produced no output: {result.stderr.strip()[:200]}", file=sys.stderr)
         return {"status": "error", "findings": [], "baselined": []}
     try:
-        return json.loads(result.stdout)
+        payload = json.loads(result.stdout)
+        expected = "clean" if result.returncode == 0 else "findings"
+        if not isinstance(payload, dict) or payload.get("status") != expected:
+            return {"status": "error", "findings": [], "baselined": []}
+        return payload
     except json.JSONDecodeError:
         print("lint_gate: could not parse doc gate output", file=sys.stderr)
         return {"status": "error", "findings": [], "baselined": []}
@@ -161,6 +169,10 @@ def main(argv: list[str] | None = None) -> int:
     docs: dict = {"status": "skipped", "findings": [], "baselined": []}
     if not args.no_docs and args.files is None:
         docs = run_doc_gate(force_all=args.all)
+        if docs.get("status") not in ("clean", "findings"):
+            if args.json:
+                print(json.dumps({"status": "error", "docs": docs, "findings": []}))
+            return 2
 
     # Report the documentation verdict even when Ruff is unavailable: a missing linter must not
     # hide the docs result, and the exit code still signals the environment problem.