Skip to content

AGENTS.md

Latest commit

 

History

History
78 lines (55 loc) · 3.51 KB

AGENTS.md

File metadata and controls

78 lines (55 loc) · 3.51 KB
Raw

AGENTS.md

What This Project Is

GithubRepoAuditor is the workbook-first portfolio operating system for repo truth and weekly review. It generates the canonical local portfolio truth snapshot consumed by downstream dashboards, reports, command-center surfaces, and planning lanes.

Current State

The current machine-readable truth surface is output/portfolio-truth-latest.json. Compatibility Markdown, workbooks, dashboards, and reports are derived surfaces; do not treat them as canonical inputs unless a task is specifically about that artifact.

Stack

  • Python
  • uv
  • pytest
  • ruff
  • Local JSON, Markdown, HTML, workbook, and control-center outputs

How To Run

Refresh and verify the local portfolio truth snapshot:

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:

uv run ruff check .
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 opt-in:

uv run operator-os-seam-linter --identity-resolution --identity-since 2026-07-03T13:02:06Z --truth output/portfolio-truth-latest.json --json

Use --identity-since for regression-gate checks after producer fixes. It filters timestamped local stores only: bridge-db activity, session-costs, and notification-hub durable events. Untimestamped Notion snapshot rows are skipped in since-window mode.

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.
  • Do not let generated reports, old dashboards, or historical registry files override the latest portfolio truth snapshot.
  • Do not read or emit secrets, .env values, keychains, OAuth stores, raw private transcripts, raw logs, browser profiles, or credential-bearing configs while auditing repos.

Review guidelines

Focus Codex review on portfolio truth correctness, attention-state and maturity contract drift, generated-vs-canonical source confusion, identity-resolution fallbacks, since-window filters, seam-linter coverage, and misleading reports or dashboards. Treat changes that make archived, parked, experiment, or active-product status look healthier or more current than the source evidence as merge-relevant.

Treat exact output contracts and mutation boundaries as first-class review surfaces. CLI JSON keys, workbook columns, Markdown provenance markers, operator queue fields, writeback targets, dry-run behavior, and GitHub/Notion mutation paths must not drift silently. Any change that turns a read-only/dry-run path into an external write, or reports stale/generated state as current canonical truth, is merge-relevant.

For docs-only PRs, comment only when a doc claims current portfolio state, published readiness, generated report truth, or operator guidance that is not backed by the latest canonical truth path or reviewed commands.

Next Recommended Move

When repairing portfolio context, keep the attention contract tight: improve default-attention repos only when the work supports a real publish, park, archive, security, release, dirty-worktree, owner, active-product, bridge/Notion/sync, or cost decision.