ohjonathan · ohjonathan · Feb 13, 2026 · Feb 12, 2026 · Feb 13, 2026 · Feb 13, 2026
diff --git a/.ontos-internal/logs/2026-02-12_init.md b/.ontos-internal/logs/2026-02-12_init.md
@@ -0,0 +1,21 @@
+---
+id: log_20260212_init
+type: log
+status: active
+event_type: chore
+source: cli
+branch: main
+created: 2026-02-12
+---
+
+# init
+
+## Summary
+
+<!-- Brief description of what was done -->
+
+## Changes Made
+
+<!-- List of changes -->
+
+## Testing
diff --git a/.ontos-internal/reference/decision_history.md b/.ontos-internal/reference/decision_history.md
@@ -2,8 +2,8 @@
 GENERATED FILE - DO NOT EDIT MANUALLY
 Regenerated by: ontos_generate_context_map.py
 Source: /Users/jonathanoh/Dev/Ontos-dev/.ontos-internal/logs, /Users/jonathanoh/Dev/Ontos-dev/.ontos-internal/archive/logs
-Last generated: 2026-02-11T23:52:40
-Log count: 16 active, 77 archived, 0 skipped
+Last generated: 2026-02-12T19:20:06
+Log count: 17 active, 77 archived, 0 skipped
 -->
 
 ---
@@ -19,6 +19,13 @@ This file is auto-generated from session logs. Do not edit directly.
 
 To regenerate: `python3 .ontos/scripts/ontos_generate_context_map.py`
 
+## 2026-02-12
+
+### [chore] 20260212 Init
+- **Log:** `log_20260212_init`
+
+> <!-- Brief description of what was done -->
+
 ## 2026-02-11
 
 ### [chore] 20260211 Init

diff --git a/.ontos-internal/strategy/proposals/v3.3.1/plan.md b/.ontos-internal/strategy/proposals/v3.3.1/plan.md
@@ -0,0 +1,203 @@
+# v3.3.1 — External Review Remediation Plan
+
+**PR:** [#76](https://github.com/ohjonathan/Project-Ontos/pull/76)
+**Branch:** `fix/v3.3.1-external-review-remediation`
+**Date:** 2026-02-12
+
+---
+
+## Origin
+
+An external LLM adversarial review of Ontos v3.3.0 raised 9 numbered issues plus "quick wins." This plan documents the point-by-point triage — each issue received a **Yes**, **No**, or **Partial yes** verdict with evidence from the actual codebase — followed by the implementation.
+
+---
+
+## Preamble
+
+The reviewer clearly ran the tool, read the code, and checked public-facing artifacts. Several claims were verified against the live codebase (e.g., running `ontos link-check`, reading every file mentioned). Below is the point-by-point assessment.
+
+---
+
+## Issue 1: link-check is shipping 408 false positives
+
+**Verdict: Yes — accept. This is the v3.3.1 priority.**
+
+Running `ontos link-check` against the repo produced:
+
+```
+broken_references: 408
+```
+
+The top offenders:
+- **Bare numbers:** `1` (50 hits), `2` (46), `3` (36), `4` (19), `5` (10), `6` (7), `0` (6)
+- **Version strings:** `v3.0` (18), `v3.2` (10), `v3.2.3` (7), `v3.2.1` (7), `v3.3` (6), `v2.x` (6)
+- **Field names in prose:** `depends_on` (7), `pending_curation` (5)
+- **Filenames:** `AGENTS.md` (5)
+- **Track codes:** `A1` (6), `A3` (4)
+
+**Root cause:** `_looks_like_doc_id()` in `ontos/core/body_refs.py` (line ~647) accepts ANY token containing a digit, dot, or underscore. In generic scan mode (no `known_ids` provided), every such token that doesn't match an existing doc ID is classified as "broken." This means bare list numbers, version strings, YAML field names, and filenames all get flagged.
+
+The zone-aware tokenizer correctly skips code fences and inline code, but has no heuristic filtering for version patterns, bare numbers, known field names, or filename patterns.
+
+The two-tier boundary model from the v3.3.0 adversarial review solved false *negatives* (missing punctuation-adjacent IDs); this is a separate false *positive* problem in the `_looks_like_doc_id` heuristic.
+
+**Fix implemented:** Added 4 pre-classification filters in `_looks_like_doc_id()`:
+
+| Filter | Pattern | Rejects |
+|--------|---------|---------|
+| Bare numbers | `^\d{1,3}$` | `1`, `42`, `100` (but not 4+ digit numbers) |
+| Version strings | `^v?\d+(\.\d+)+$` | `v3.2`, `3.2.1`, `v3.3.0` |
+| Known field names | Frozenset of 14 entries | `depends_on`, `status`, `pending_curation`, etc. |
+| File extensions | 20 common extensions | `AGENTS.md`, `config.toml`, `body_refs.py` |
+
+**Result:** 408 → 92 broken references. Remaining 92 are genuinely ambiguous tokens (track codes like `A1`, variable-like names like `logs_dir`).
+
+---
+
+## Issue 2: Three generated files are stale and contradictory
+
+**Verdict: Yes — accept with correction. Two of three are stale.**
+
+| File | Claim | Actual |
+|------|-------|--------|
+| `.cursorrules` | v3.2.0, doc count 91 | **Confirmed.** Generated by v3.2.0 on 2026-02-09. Shows "Doc Count: 91" vs actual 43. Severely stale. |
+| `AGENTS.md` | v3.2.3, doc count 42 | **Outdated claim.** AGENTS.md was regenerated today (2026-02-12) by v3.3.0 and now shows 43 docs. The reviewer likely saw an earlier state. |
+| `Ontos_Manual.md` | Title says "v3.2" | **Confirmed.** Header reads `# Ontos Manual v3.2` despite v3.3.0 being released. Manual doesn't document `link-check` or `rename`. |
+
+**Deeper issue:** `ontos map --sync-agents` regenerates AGENTS.md but does NOT regenerate `.cursorrules`. The `ontos agents --all` command generates both. Design gap — standard activation flow would leave .cursorrules stale.
+
+**Fix implemented:**
+- Ran `ontos agents --all --force` to sync both files
+- Bumped manual title to v3.3
+- Added link-check and rename to Section 10 command reference (subsections 10.2 and 10.3)
+
+---
+
+## Issue 3: SECURITY.md is from a different era
+
+**Verdict: Yes — accept. Severely outdated.**
+
+The file referenced:
+- **Supported version:** `0.4.x` — the current version is `3.3.0`
+- **Security scope scripts:** `.ontos/scripts/ontos_generate_context_map.py`, `.ontos/scripts/ontos_migrate_frontmatter.py`, `.ontos/scripts/ontos_end_session.py` — all legacy paths
+- No mention of the `ontos` Python package, CLI entry point, or any post-v3.0 architecture
+
+**Fix implemented:** Rewrote SECURITY.md to reference v3.x, the `ontos` package as the security-relevant surface, updated supported versions (3.3.x, 3.2.x), and scope (references `ontos/io/yaml.py`, `ontos/io/scan.py`, `ontos/cli.py`).
+
+---
+
+## Issue 4: README roadmap is outdated
+
+**Verdict: Yes — accept.**
+
+The roadmap table listed v3.2.0 as "Current" and v3.3 as "Next" with aspirational features ("Decision capture, typed dependencies, import capability") that were NOT shipped. v3.3.0 actually shipped as "Full Spectrum Hardening."
+
+**Fix implemented:**
+- v3.3.0 is now "Current" with accurate highlights
+- v3.4 defined as "Next"
+- Added summary paragraph for v3.3
+
+---
+
+## Issue 5: The minimal example is empty
+
+**Verdict: Yes — accept.**
+
+`examples/minimal/` contained only a `README.md` with inline code blocks. The 3 referenced files (`docs/kernel/mission.md`, `docs/strategy/audience.md`, `docs/atom/data_model.md`) did not exist on disk. Running `ontos map` would find nothing.
+
+**Fix implemented:** Created the 3 actual doc files with proper Ontos frontmatter so the example is runnable.
+
+---
+
+## Issue 6: Legacy scripts are still in the repo and still running
+
+**Verdict: Partial yes — the coupling concern is valid; the "FutureWarning" claim was not verified.**
+
+Confirmed:
+- `.ontos/scripts/` contains 22 Python scripts from the pre-v3.0 era
+- `pyproject.toml` included `.ontos/scripts/tests/` in `testpaths`, so legacy tests ran in every CI pass
+- 6 test files with ~150 test functions under `.ontos/scripts/tests/`
+
+Not confirmed:
+- The claim that "the test suite emits a FutureWarning about `ontos_config.py`" specifically — the conftest.py configures warning filters, but no test emits this warning. Reviewer may have seen warnings on a different Python version.
+
+**Fix implemented:** Isolated, not removed:
+- Removed `.ontos/scripts/tests/` from default `testpaths` in `pyproject.toml`
+- Added `legacy` pytest marker via conftest `pytest_collection_modifyitems` auto-marking
+- Legacy tests still runnable explicitly: `pytest .ontos/scripts/tests/` (152 pass)
+- Kept tests because they catch regressions in the compatibility layer
+
+---
+
+## Issue 7: Two CHANGELOGs is confusing
+
+**Verdict: Yes — accept the observation, but the fix is a note, not consolidation.**
+
+The split is intentional:
+- `CHANGELOG.md` — user-facing, starts at v3.0.2, clean markdown
+- `Ontos_CHANGELOG.md` — tooling-internal, full history from v0.1.0, has Ontos frontmatter
+
+**Fix implemented:** Added a one-line cross-reference at the top of `CHANGELOG.md`:
+> For the full historical changelog with Ontos frontmatter (from v0.1.0), see `Ontos_CHANGELOG.md`.
+
+Lightest possible fix. Consolidating would either lose the frontmatter/metadata value of `Ontos_CHANGELOG.md` or force tooling metadata into the user-facing file.
+
+---
+
+## Issue 8: ontos doctor shows git hooks warning but hooks aren't critical
+
+**Verdict: No — decline.**
+
+Running `ontos doctor` produces:
+```
+OK: git_hooks: pre-push, pre-commit installed
+```
+
+The only warning is about AGENTS.md staleness, not hooks. The reviewer likely tested in a clean environment where hooks weren't installed via `ontos hook --install`. The behavior is correct:
+- Hooks not installed → WARN (actionable: run `ontos hook --install`)
+- Hooks installed → OK
+
+This is standard diagnostic behavior. Could be revisited if adoption feedback confirms it's noisy for most users.
+
+---
+
+## Issue 9: "Development Status :: 3 - Alpha" classifier
+
+**Verdict: Yes — accept. Bump to Beta.**
+
+`pyproject.toml` line 17: `"Development Status :: 3 - Alpha"`
+
+With 19 public commands, 888+ tests, CI across Python 3.9–3.12, 13 tagged releases, multiple adversarial reviews, and structured release processes, Alpha is underselling it.
+
+**Fix implemented:** Changed to `"Development Status :: 4 - Beta"` — signals "feature-complete for the core use case, API may still evolve."
+
+---
+
+## Implementation Summary
+
+### Phase 1: Quick Wins
+1. `ontos agents --all --force` → fixed .cursorrules and AGENTS.md
+2. Rewrote `SECURITY.md` → v3.x scope
+3. Updated `README.md` → v3.3.0 roadmap
+4. Bumped `pyproject.toml` → Alpha to Beta
+5. Added cross-reference note in `CHANGELOG.md`
+6. Updated `docs/reference/Ontos_Manual.md` → v3.3 title, link-check/rename in Section 10
+
+### Phase 2: v3.3.1 Hotfix
+7. Fixed `ontos/core/body_refs.py` `_looks_like_doc_id()` — 4 false positive filters
+8. Added 43 tests in `tests/core/test_body_refs.py`
+
+### Phase 3: Lower Priority
+9. Populated `examples/minimal/docs/` with 3 runnable doc files
+10. Isolated `.ontos/scripts/tests/` from default pytest (legacy marker)
+
+### Verification
+
+| Check | Result |
+|-------|--------|
+| `pytest tests/` | 888 passed, 2 skipped, 0 failures |
+| `pytest tests/core/test_body_refs.py` | 61 passed (43 new) |
+| `pytest .ontos/scripts/tests/` | 152 passed (legacy, isolated) |
+| `ontos link-check` | 92 broken refs (down from 408) |
+| `ontos doctor` | 8 passed, 0 failed, 1 warning |
+| `ontos map --quiet` | Clean generation, exit 0 |
diff --git a/Ontos_Context_Map.md b/Ontos_Context_Map.md
@@ -4,13 +4,13 @@ type: reference
 status: generated
 ontos_map_version: 2
 generated_by: ontos map
-generated_at: 2026-02-12 11:19:50
+generated_at: 2026-02-12 19:23:23
 ---
 
 # Ontos-dev Tiered Context Map
 
 > Auto-generated by Ontos 3.0
-> Last updated: 2026-02-12 11:19:50
+> Last updated: 2026-02-12 19:23:23
 
 This document provides a tiered index of the knowledge graph for AI orientation.
 - **Tier 1: Essential Context**: (~2k tokens) Project summary, recent work, and architecture.
@@ -21,16 +21,16 @@ This document provides a tiered index of the knowledge graph for AI orientation.
 
 ### Project Summary
 - **Name:** Ontos-dev
-- **Doc Count:** 43
-- **Last Updated:** 2026-02-12 16:19:50 UTC
+- **Doc Count:** 46
+- **Last Updated:** 2026-02-13 00:23:23 UTC
 
 ### Recent Activity
 | Log | Status | Summary |
 |-----|--------|---------|
 | v330 | active | No summary |
 | v300 | scaffold | No summary |
-| log_20260211_v3-3b-track-b-complete | active | No summary |
-| ... and 26 more logs | | |
+| log_20260212_v3-3-1-external-review-remediation-complete-merged | active | No summary |
+| ... and 29 more logs | | |
 
 ### Key Documents
 - `ontos_manual` (2 dependents) — docs/reference/Ontos_Manual.md
@@ -78,6 +78,9 @@ This document provides a tiered index of the knowledge graph for AI orientation.
 | docs/logs/2026-02-11_v3-3a-v3-3b-folder-split-and-track-b-kickoff.md | `log_20260211_v3-3a-v3-3b-folder-split-and-track-b-kickoff` | log | active |
 | docs/logs/2026-02-11_v3-3b-pr2-ready-to-merge.md | `log_20260211_v3-3b-pr2-ready-to-merge` | log | active |
 | docs/logs/2026-02-11_v3-3b-track-b-complete.md | `log_20260211_v3-3b-track-b-complete` | log | active |
+| docs/logs/2026-02-12_add-3-new-link-check-fp-filters-short-labels-al.md | `log_20260212_add-3-new-link-check-fp-filters-short-labels-al` | log | active |
+| docs/logs/2026-02-12_external-review-remediation-implemented-9-point-v3.md | `log_20260212_external-review-remediation-implemented-9-point-v3` | log | active |
+| docs/logs/2026-02-12_v3-3-1-external-review-remediation-complete-merged.md | `log_20260212_v3-3-1-external-review-remediation-complete-merged` | log | active |
 | docs/reference/Migration_v2_to_v3.md | `migration_v2_to_v3` | reference | active |
 | docs/reference/Ontos_Agent_Instructions.md | `ontos_agent_instructions` | kernel | active |
 | docs/reference/Ontos_Manual.md | `ontos_manual` | kernel | active |
@@ -158,6 +161,12 @@ This document provides a tiered index of the knowledge graph for AI orientation.
     Add this document to another document's depends_on
 - ⚠️ **log_20260211_v3-3b-track-b-complete**: Document has no incoming dependencies
     Add this document to another document's depends_on
+- ⚠️ **log_20260212_add-3-new-link-check-fp-filters-short-labels-al**: Document has no incoming dependencies
+    Add this document to another document's depends_on
+- ⚠️ **log_20260212_external-review-remediation-implemented-9-point-v3**: Document has no incoming dependencies
+    Add this document to another document's depends_on
+- ⚠️ **log_20260212_v3-3-1-external-review-remediation-complete-merged**: Document has no incoming dependencies
+    Add this document to another document's depends_on
 - ⚠️ **migration_v2_to_v3**: Document has no incoming dependencies
     Add this document to another document's depends_on
 - ⚠️ **ontos_agent_instructions**: Document has no incoming dependencies
@@ -248,6 +257,12 @@ This document provides a tiered index of the knowledge graph for AI orientation.
     Add a concepts: list to the frontmatter
 - ⚠️ **log_20260211_v3-3b-track-b-complete**: Log document missing 'concepts' field (required at L2)
     Add a concepts: list to the frontmatter
+- ⚠️ **log_20260212_add-3-new-link-check-fp-filters-short-labels-al**: Log document missing 'concepts' field (required at L2)
+    Add a concepts: list to the frontmatter
+- ⚠️ **log_20260212_external-review-remediation-implemented-9-point-v3**: Log document missing 'concepts' field (required at L2)
+    Add a concepts: list to the frontmatter
+- ⚠️ **log_20260212_v3-3-1-external-review-remediation-complete-merged**: Log document missing 'concepts' field (required at L2)
+    Add a concepts: list to the frontmatter
 - ⚠️ **v300**: Log document missing 'concepts' field (required at L2)
     Add a concepts: list to the frontmatter
 - ⚠️ **v330**: Unknown concept: 'v3.3'
@@ -280,11 +295,11 @@ This document provides a tiered index of the knowledge graph for AI orientation.
 
 - `v330`
 - `v300`
+- `log_20260212_v3-3-1-external-review-remediation-complete-merged`
+- `log_20260212_external-review-remediation-implemented-9-point-v3`
+- `log_20260212_add-3-new-link-check-fp-filters-short-labels-al`
 - `log_20260211_v3-3b-track-b-complete`
 - `log_20260211_v3-3b-pr2-ready-to-merge`
 - `log_20260211_v3-3a-v3-3b-folder-split-and-track-b-kickoff`
 - `log_20260211_v3-3a-merge-cleanup-and-v3-3b-setup-wrap`
-- `log_20260211_v3-3-track-a4-docs-tests-dead-code-cleanup-and-def`
-- `log_20260211_v3-3-track-a3-merge-closeout`
-- `log_20260211_v3-3-track-a2-command-safety-hardening-closure`
-- `log_20260211_v3-3-a1-hardening-tail-cherry-picked-into-main`
+- `log_20260211_v3-3-track-a4-docs-tests-dead-code-cleanup-and-def`
diff --git a/docs/logs/2026-02-12_add-3-new-link-check-fp-filters-short-labels-al.md b/docs/logs/2026-02-12_add-3-new-link-check-fp-filters-short-labels-al.md
@@ -0,0 +1,21 @@
+---
+id: log_20260212_add-3-new-link-check-fp-filters-short-labels-al
+type: log
+status: active
+event_type: chore
+source: cli
+branch: fix/link-check-fp-reduction-round2
+created: 2026-02-12
+---
+
+# add 3 new link-check FP filters — short labels, AL
+
+## Summary
+
+<!-- Brief description of what was done -->
+
+## Changes Made
+
+<!-- List of changes -->
+
+## Testing
diff --git a/docs/logs/2026-02-12_add-integration-tests-documenting-filtered-pattern.md b/docs/logs/2026-02-12_add-integration-tests-documenting-filtered-pattern.md
@@ -0,0 +1,21 @@
+---
+id: log_20260212_add-integration-tests-documenting-filtered-pattern
+type: log
+status: active
+event_type: chore
+source: cli
+branch: fix/link-check-fp-reduction-round2
+created: 2026-02-12
+---
+
+# add integration tests documenting filtered-pattern
+
+## Summary
+
+<!-- Brief description of what was done -->
+
+## Changes Made
+
+<!-- List of changes -->
+
+## Testing