From 61408044e60e2ff5e991878a97f3457d0af23391 Mon Sep 17 00:00:00 2001 From: saagpatel Date: Fri, 3 Jul 2026 05:32:14 -0700 Subject: [PATCH] Document operator OS seam-linter verification --- AGENTS.md | 8 +++++++- README.md | 11 ++++++++++- pyproject.toml | 1 + 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e35be3c6..81e435db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,10 +18,12 @@ The current machine-readable truth surface is `output/portfolio-truth-latest.jso ## How To Run -Refresh the local portfolio truth snapshot: +Refresh and verify the local portfolio truth snapshot: ```sh uv run python -m src.cli report saagpatel --portfolio-truth +jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json +uv run operator-os-seam-linter --truth output/portfolio-truth-latest.json --json ``` Useful checks for repo changes: @@ -33,6 +35,10 @@ uv run pytest -q Use narrower tests when the change is scoped and the full suite would be disproportionate. +The seam-linter checks truth freshness, schema pinning, and generated Markdown +provenance markers. Its identity-resolution check is intentionally deferred until +the dialect census produces the alias map. + ## Known Risks - `output/portfolio-truth-latest.json` is generated state, but it is also the current truth surface for other local workflows. Regenerate it deliberately after catalog or context changes. diff --git a/README.md b/README.md index 90be77c2..04a84d2b 100644 --- a/README.md +++ b/README.md @@ -348,12 +348,21 @@ For day-to-day operations, `--control-center` is now the clean read-only entrypo The portfolio truth layer now has its own dedicated generation path. `--portfolio-truth` scans the configured local projects workspace, produces `output/portfolio-truth-latest.json` plus dated historical truth snapshots, and regenerates the configured project-registry and portfolio-audit Markdown compatibility outputs from that same truth contract instead of treating either markdown file as canonical. -For current live portfolio counts, query the canonical snapshot instead of copying numbers into handoff or demo docs: +After regenerating portfolio truth, verify the canonical snapshot instead of copying numbers into handoff or demo docs: ```bash +uv run python -m src.cli report saagpatel --portfolio-truth jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json +uv run operator-os-seam-linter --truth output/portfolio-truth-latest.json --json ``` +The Operator-OS seam-linter is the small conformance check for that truth layer. +It verifies the latest truth artifact freshness, schema pin, and generated +Markdown provenance markers. + +Identity-resolution enforcement remains a named v0.1 extension point and should +not be enabled until the dialect census and alias map exist. + Phase 104 added a second standalone workspace mode: `--portfolio-context-recovery`. That mode freezes the active/recent weak-context cohort from the live truth snapshot, writes dry-run recovery plan artifacts into `output/`, skips dirty or temporary repos automatically, and can apply bounded minimum-context upgrades plus repo-level catalog seeds before regenerating the truth snapshot and compatibility outputs. Watch mode now uses that same baseline contract in live execution. Each cycle records the requested watch strategy, the chosen mode, and the reason a full refresh was required or an incremental rerun remained safe. diff --git a/pyproject.toml b/pyproject.toml index f02ef246..a78f96a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -79,6 +79,7 @@ Documentation = "https://github.com/saagpatel/GithubRepoAuditor#readme" [project.scripts] audit = "src.cli:main" +operator-os-seam-linter = "src.operator_os_seam_linter:main" [tool.setuptools.packages.find] where = ["."]