docs: propose v5 remediation release plan

[ohjonathan]

Summary

• add the current audit revalidation review that establishes the issue and custody baseline
• add a detailed 31-section proposal covering the valid open issues and their release sequencing
• add a framework manifest and tracker for a terminal Pre-A split into independently reviewed child deliverables
• refresh generated Ontos context and agent metadata

Why

The existing roadmap left uncertainty about whether the complete workspace-vocabulary model should wait for v6. This proposal establishes an additive v5 path:

• v5.0.3: root-file dependency correctness, log-path alignment, safe aliasing, and compatibility delegation
• v5.1.0: complete content-addressed activation receipts and workspace vocabularies
• v5.2.0: semantic references, stable findings/baselines, and same-device Git-aware coordination
• v6.0.0: removal of exactly the eleven compatibility names promised through v5

The parent remains planning-only. Its requested Template 16 disposition is Split into multiple proposals; every implementation train must receive its own scope, review evidence, and release decision.

Impact

This is documentation and governance only. It changes no Ontos runtime behavior or public API and does not mutate any GitHub issue, label, milestone, or release state.

Validation

• Ontos activation: 231 documents loaded, 0 load errors, 0 validation errors
• full and frontmatter-only Ontos link checks: clean
• llm-dev manifest conformance: 4/4 checks passed
• changed-path scope: 6/6 files within the documentation-only manifest
• exact branch-identity gate: passed
• post-commit scoped cleanliness: passed
• cardinality guards: 4 release targets, 9 audited issues, 11 v6 removals
• commit hooks: Ontos document graph and auto-consolidation passed

[ohjonathan]

Falsification Review — PR #179 (v5 Remediation Release Plan)

Method

Treat each concrete claim as falsifiable and actively seek disconfirming evidence in: baseline source (7d07556), the v2 deprecation test, live issue/PR/release state, archive inventory, and PR-internal cross-references.

Outcome: No load-bearing claim falsified

Every falsifiable factual claim I tested held up against the source of truth.

#	Claim (location)	Falsification attempt	Result
1	"exactly eleven compatibility names" (§18.1) + "No Ontos production path calls them" (§2 fact 7)	grep production usage in ontos/ excl. paths.py	Confirmed. Only hits are re-exports in ontos/__init__.py and ontos/core/__init__.py; zero callers. tests/core/test_paths_v2_deprecation.py pins len(...) == 11.
2	v6.0.0 deprecation warnings exist (§18.1)	grep paths.py for "v6.0.0"	Confirmed. paths.py:34 emits removed in v6.0.0; test asserts match=...removed in v6\.0.0. (Note: an unrelated working-tree branch regressed this — irrelevant to the PR baseline.)
3	#176 _looks_like_path defect (§11.2)	read graph.py:40	Confirmed verbatim.
4	#177 issue body is imprecise; targets resolve source-relative first (§15.1)	read _resolve_markdown_target	Confirmed. Docstring: "source-relative first ... then workspace-relative"; candidates=[source_parent/..., root_resolved/...].
5	"77 archived logs / 383 non-log / 25 .project-internal files" (§18.2)	count git tree at baseline	Confirmed exactly (77 / 383 / 25). .project-internal is a real dir, not a typo.
6	consolidation hard-codes .ontos-internal; ontos log honors config (§2 fact 8, §11.3)	read consolidate.py:230-235	Confirmed. Hard-codes .ontos-internal/logs, archive/logs, reference/decision_history.md.
7	lock is worktree-scoped <worktree>/.ontos.lock (§2 fact 6)	read context.py:309	Confirmed. lock_path = self.repo_root / ".ontos.lock" — no Git-common-dir coordination.
8	MCP freshness = mtime+size; AGENTS = mtime (§2 fact 2)	read cache.py:53,298, doctor.py:758	Confirmed. freshness_mode="file-mtime-fingerprint"; return stat.st_mtime_ns, stat.st_size.
9	Cardinality gates: 4 releases / 9 issues / 11 removals	ran the manifest's exact gate commands on the PR file	All pass (4 / 9 / 11).
10	baseline 7d07556 = v5.0.2; "patch-safe work shipped through v5.0.2"; "PR #170 merged/released"	gh PR/release lookup	Confirmed. #170 MERGED 2026-07-14; v5.0.2 released 2026-07-14.
11	"live open-issue inventory" = 9 issues	gh issue list --state open	Confirmed. Exactly those 9 are open; no in-scope issue omitted.
12	"231 documents"; "all 100 IDs" (#165)	228→231 (+3 new docs); 91 Fable+9 R2=100	Confirmed.
13	Internal §-references resolve; tracker/manifest/branch consistency	enumerate all 31 sections + refs	Confirmed. All cross-refs resolve; branch matches headRefName; -A.proposal claude-opus reviewer matches.

Non-blocking findings (tensions, not falsifications)

• A. "link checks: clean" vs shipped warnings. The PR's generated Ontos_Context_Map.md carries 8 Unknown concept warnings from the new docs' concepts: tags (release-planning, compatibility, validation, etc.). Under project convention (AGENTS.md) these are non-blocking warnings, distinct from hard errors — so "0 validation errors" is defensible, but "clean" is loose wording. Resolves at v5.1 ([Feature] Workspace-defined document vocabularies and governed enum-repair mappings #178).
• B. [P1-containing] v5.0.1 patch-safe sweep + v6.0.0 path compatibility removal #149 priority label diverges within the PR. The revalidation doc (2026-07-10) records [P1-containing] v5.0.1 patch-safe sweep + v6.0.0 path compatibility removal #149 as P1-containing; §23.1 proposes retitling to [P2]. These are two temporal snapshots (P1 patch work shipped in v5.0.2), not a contradiction — the proposal explicitly bridges them. Worth a one-line clarifying note to prevent a careless misread.
• C. Live [P1-containing] v5.0.1 patch-safe sweep + v6.0.0 path compatibility removal #149 body is stale (still calls fix: close v5.0.1 config and provenance audit tail #170 a "draft PR ... merge pending"; fix: close v5.0.1 config and provenance audit tail #170 is merged). The proposal correctly proposes to fix this in §23.1 — it is not itself misrepresenting fix: close v5.0.1 config and provenance audit tail #170's status. This is a board-hygiene gap the PR addresses.
• D. Revalidation doc's working-tree counts ("40 implemented-uncommitted", "1447 passed", "354/268/90") describe a transient 2026-07-10 tree state that is no longer reproducible. The doc itself disclaims these as non-authoritative provenance, and the proposal does not load-bearing depend on them. Low risk.
• E. The §2.1 "388 passed in 9.88s" characterization count was not re-run here, but every listed test file (incl. test_paths_v2_deprecation.py) exists at baseline, and the claim is honestly scoped to "characterizes current behavior; does not prove any proposed feature."

Verdict

This is an unusually well-grounded proposal. I could not falsify any of its load-bearing claims against code, releases, or board state; the scope exactly matches the live open-issue set with nothing omitted, the v6 "eleven names" deletion-safety argument is mechanically verified, and internal references are consistent. The only items a reviewer should note are documentation-hygiene nuances (A–C) — most of which the proposal itself proposes to remedy — and non-reproducible provenance counts (D) that the doc already disclaims. No gate in the manifest is falsely claimed to pass (the G-verdict-1/G-blocker-1 verdict gates are honestly left pending, matching the "Split into multiple proposals" review that this PR is submitting for).

---

Review generated by an automated falsification pass against baseline 7d07556, live GitHub state, and PR-internal consistency. Non-author review; not a lifecycle verdict.