docs(tidy): T-3 — audit + plan + minimal .well-known/{ai,humans}.txt

[hyperpolymath]

Summary

Audit + plan for the repo-wide doc-tidy, plus the two minimal RSR-compliance additions that don't warrant their own PR.

docs/TIDY-PLAN.adoc is the master plan. It catalogues every file in scope, assigns each a disposition, and enumerates the remaining work as 22 thematic T-4..T-24 PRs with recommended merge order. Acknowledges T-1 (#359), T-2 (#360), and the CLAUDE.md refresh (#363) which already landed — does not re-propose their work.

.well-known/ai.txt (new) and .well-known/humans.txt (moved from docs/humans.txt) close two RSR-compliance gaps; both are small enough to ride along with the plan.

Why a plan PR first

The cleanup blast-radius is real (e.g., docs/CAPABILITY-MATRIX.adoc is cited 27x; moving it to docs/status/ in T-8 requires updating every cite). Per the owner's "sequence of thematic PRs" instruction and the standing DOC-DEDUP rule, surfacing the plan in a tracked document lets each subsequent T-N PR cite it for scope, and lets reviewers verify nothing escapes the plan or duplicates earlier work.

Audit sources

• RSR template: hyperpolymath/rsr-template-repo (fetched via WebFetch — taxonomy + naming conventions captured)
• Per-file disposition: Explore-agent audit of top-level + docs/ + subdir READMEs + .machine_readable/ A2ML files + CLAUDE.md
• Open issues/PRs: GitHub MCP enumeration (21 open issues, 1 other open PR Phase 2c: Extend walker to all six anti-patterns, make it default #357)

Both audits dated 2026-05-25.

Headline RSR-template gaps remaining

Gap	Action
Justfile + validate-rsr recipe	T-4
flake.nix (or guix.scm)	T-5
.editorconfig + .gitattributes	T-6
docs/specs/SETTLED-DECISIONS.adoc → per-ADR in docs/decisions/	T-7
docs/{CAPABILITY-MATRIX,TECH-DEBT}.adoc → docs/status/	T-8 (27 xrefs)
docs/ECOSYSTEM.adoc → docs/architecture/	T-9
docs/{guides,tutorial}/ → docs/{onboarding,developer}/	T-11
docs/academic/ → docs/{theory,whitepapers}/	T-12
docs/history/ → docs/archive/	T-13
Root governance dups → one-line stubs	T-17
Delete superseded root capability docs	T-18
10 missing subdir READMEs	T-20
.machine_readable/6a2/ A2ML hygiene	T-21
Wiki sync	T-22
Issue triage labels + #177 status comment	T-23
CLAUDE.md slim-down (extract LANGUAGE-EXEMPTIONS + BOT-POLICIES)	T-24

(Full table with risk and rationale in docs/TIDY-PLAN.adoc.)

Diff

• + docs/TIDY-PLAN.adoc — the plan (~430 lines, AsciiDoc)
• + .well-known/ai.txt — minimal AI-usage discovery file, points to root 0-AI-MANIFEST.a2ml
• R docs/humans.txt → .well-known/humans.txt — content unchanged; no incoming references to update

Test plan

• .well-known/ai.txt resolves and contains the policy summary
• .well-known/humans.txt resolves and matches prior docs/humans.txt content
• No broken cross-references introduced — nothing in the prior tree referenced docs/humans.txt
• No CI behaviour change — the plan and the two .well-known/ additions don't intersect with any code path

Refs the doc-tidy mandate from the 2026-05-25 conversation. Sequel to T-1 (#359), T-2 (#360).

---

Generated by Claude Code

[ghost]

🔍 Hypatia Security Scan

Findings: 103 issues detected

Severity	Count
🔴 Critical	15
🟠 High	42
🟡 Medium	46

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Action actions/checkout@v6 needs attention",
    "type": "unpinned_action",
    "file": "publish-jsr.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action denoland/setup-deno@v2 needs attention",
    "type": "unpinned_action",
    "file": "publish-jsr.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/example/smoke_driver.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/cli.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/lib/compile.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/lib/runner.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/affinescript-deno-test/lib/discover.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/affinescript/affinescript/packages/affine-js/types.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

[hyperpolymath]

Session log — 2026-05-24..26

Tying together the work this PR caps off, for human discoverability. Machine-readable state is already current in .machine_readable/6a2/STATE.a2ml, docs/CAPABILITY-MATRIX.adoc, and docs/TECH-DEBT.adoc.

CORE-01 Phase 3 — borrow-checker

Slice	Description	Outcome
A — NLL last-use expiry	compute_last_use_index pre-pass; check_block expires in-block ref-bindings once their binder is dead. Unblocks let r = &x; print(*r); x = 2 and the &mut equivalent.	✅ Merged #335
B — flow-sensitive escape via outer = &y	StmtAssign pre-releases the held borrow and re-binds the (binder → new_borrow) ref-graph entry to the freshly-created borrow. NLL/return-escape now see the current referent.	✅ Effectively merged via #354 / #355 / #356 (after #351 was procedurally closed for merge-conflict mechanics)
C-light — CFG-join for ExprHandle + ExprTry catch arms	Snapshot-restore-merge mirroring ExprMatch's pattern; factored merge_arm_results helper. Catch arms / handler arms no longer pollute each other.	✅ Merged #358
C-full — Polonius origin variables on TyRef/TyMut	Architectural type-system change.	◻ Deferred, ADR-gated
C′ — loop soundness (2-iter check)	Coupled to a StmtAssign clear-on-rewrite fix.	◻ Deferred
D — quantity-checker tightening for captured linears	Re-examine ExprLambda capture borrows post-NLL.	◻ Deferred
Ref-to-ref binding	r = some_other_ref_var (RHS not a direct &place) leaves the ref-binding stale.	◻ Deferred — symmetric let/assign limitation

Repo-tidy

Phase	Description	Outcome
T-1	Adopt 0-AI-MANIFEST.a2ml; restore docs/TECH-DEBT.adoc; retire AI.a2ml + AI.djot	✅ Merged #359
T-2	Delete out-of-scope submarine-game root docs (2,182 lines)	✅ Merged #360
(sibling)	CLAUDE.md language-policy refresh for 2026-05-25 estate policy	✅ Merged #363
T-3 (this PR)	Audit + 22-step plan + minimal .well-known/{ai,humans}.txt	⏳ In review
T-4..T-24	Thematic implementation PRs per docs/TIDY-PLAN.adoc	◻ Pending T-3 merge

CI signal (for future agents)

These checks fail on every PR for baseline reasons (not anything in any individual PR's diff). Documented in .claude/CLAUDE.md § "Known-failing baseline checks":

• vscode-smoke — npm 404 on unpublished @hyperpolymath/affine-vscode
• migration-assistant — pre-ci(migration-assistant): fix smoke-parse for tree-sitter-cli 0.25 #342 base branches fail; recent ones pass
• governance / Language / package anti-pattern policy — flags documented TypeScript exemptions
• Hypatia 100+ findings — almost entirely the same pre-existing exemption hits + unpinned shared-workflow refs

A real new finding shows as a delta in the count; otherwise treat as baseline. T-24 plans to extract the exemption tables into docs/governance/LANGUAGE-EXEMPTIONS.adoc so the shared governance scanner has somewhere documented to consult.

What lives where

• lib/borrow.ml — full implementation; trailing docstring narrates pt1 → pt2 → Slice A → Slice B → Slice C, with deferred residuals enumerated.
• test/test_e2e.ml § "E2E Borrow Graph" — 14 hermetic tests across Slices A/B/C.
• test/e2e/fixtures/borrow_*.affine + slice_b_*.affine + slice_c_*.affine — the per-slice positive + anti-regression fixtures.
• docs/CAPABILITY-MATRIX.adoc — authoritative readiness; borrow-checker row pinned to Slices A+B+C-light.
• docs/TECH-DEBT.adoc — coordination ledger; CORE-01 row records every part/slice; residual narrowed to C-full / C′ / D + ref-to-ref binding.
• .machine_readable/6a2/STATE.a2ml line 74 — borrow-checker mirror, current.
• docs/TIDY-PLAN.adoc (this PR) — full T-4..T-24 plan with risk/order.

Safe-to-close conditions

This PR's merge or close auto-unsubscribes the session. The borrow-checker work is fully merged; the doc-tidy continues from T-4 onward with the plan as the single source of truth — any subsequent agent or human session can pick it up cold.

---

Generated by Claude Code