12 Commits

Author	SHA1	Message	Date
Bo	f4f991bbda	docs: fix broken intra-repo links in docs/ (ag-28dp #docs-link-rot) (#781) ... ## What Fix 44 broken intra-repo links across 7 files under `docs/`, surfaced by a `docs/` markdown link audit. `mkdocs.yml` has `strict: false`, so the broken links slipped past CI — but they break GitHub-raw viewing and agent file-reading (the repo treats pointer rot in base docs as a defect). ## Two pointer-rot classes 1. **41× `](skills/<name>.md)` → `](../skills/<name>/SKILL.md)`** — skills live at `skills/<name>/SKILL.md`, never `skills/<name>.md`, and `docs/` is one level deep so the target needs `../`. Several links already had the **correct link text** (e.g. `[skills/pre-mortem/SKILL.md](skills/pre-mortem.md)`) — only the href was wrong, confirming intent. Special case: `skills/catalog.md` → `SKILLS.md` (`docs/SKILLS.md` = the complete 82-skill reference). 2. **3× `](cli/commands.md)` → `](../cli/docs/COMMANDS.md)`** — the generated CLI command doc. Files: `GLOSSARY.md`, `index.md`, `context-lifecycle.md`, `behavioral-discipline.md`, `create-your-first-skill.md`, `context-packet.md`, `software-factory.md`. **Not touched:** the intentional placeholder links in `docs/standards/markdown-style-guide.md` (syntax demos: `url`, `image.png`, `./other-doc.md`, etc.). ## Verification - `docs/` broken-link scan: **44 → 0** outside the style-guide placeholders. - `markdownlint-cli2` on all 7 files: **0 errors**. - Pure link-href changes (44 insertions / 44 deletions); no prose or behavior change. Closes-scenario: ag-28dp#docs-link-rot Bounded-context: BC1-Corpus Evidence: ag-28dp	2026-06-06 10:17:39 -04:00
Bo	78fc0e64f5	docs: de-hook the 6 big operator/architecture docs (ag-t1ca #big-files) (#711) ... ## What Completes the hooks-runtime decoupling (ag-t1ca) — the 6 large files, each de-hooked by a dedicated verify-first pass (no `hooks/` dir, no `hooks.json`, `ao hooks` absent, hook `.sh` files absent; CI = the authoritative gate). | File | Reframe | |---|---| | ARCHITECTURE.md | hooks-as-enforcement / `hooks/ # 12 hook scripts` dir / "Session Hooks" → CI gates + `ao` commands + "Session Lifecycle"; 82-skill breakdown intact | | agentops-system-map.md | "52 Skills/121 CLI/13 hook entries" → "82/76/hookless (CI-gated)"; hook-enforcement section → hookless mapping | | context-lifecycle.md | hook-file citations → real mechanisms (CI gate + `/pre-mortem`,`/validate`,`/post-mortem` + `ao constraint`/`ao findings`) | | leverage-points.md | "3 active hooks"/push-gate/pre-mortem-gate → CI gates + skill steps; resolved the doc's own active-vs-guardrail contradiction | | troubleshooting.md | "Hooks aren't running" / "push gate hook" / `ao hooks test` → hookless guidance; **ROADMAP.md link kept** (audit's "broken link" was a false positive) | | INCIDENT-RUNBOOK.md | Scenario C "Hook Scripts Fail" + Per-Hook Kill Switches → 3.0 "Skills Not Loading / CI Gate Failing"; `AGENTOPS_HOOKS_DISABLED` kept only as user-authored-hooks opt-out | | agentops-brief.md | "73 shared skills/12 Hook Events"/"Startup hooks" → 82 skills, hookless lifecycle | ## Verification (aggregate, by me — not just subagent self-reports) - `markdownlint -c .markdownlint.json` (all docs) → **0 errors** - `tests/docs/validate-links.sh` → **0 broken** (2902 checked) - `scripts/sync-skill-counts.sh --check` → clean (ARCHITECTURE.md gate target intact) - residual hooks-as-live-runtime grep across all 7 → only correct negation/opt-in framing remains - net −41 lines (reframe, not gutting) Closes-scenario: ag-t1ca#big-files Bounded-context: BC1-Corpus Evidence: docs/ARCHITECTURE.md	2026-06-03 22:05:09 -04:00
Bo	cca8fc6731	Drain open next-work.jsonl: 6 PRs in one branch (epic soc-xlw8) (#266) ... * docs(mkdocs): fix 5 anchor mismatches + 1 unresolvable relative link (soc-2yx9) mkdocs slugify collapses em-dash spacing in headings to a single hyphen, so '## A — B' produces id="a-b", not 'a--b'. Five doc cross-references encoded the visual double-dash and were silently flagged INFO by `mkdocs build --strict`. Fixes (slugs verified against built site/ HTML): - docs/GLOSSARY.md → how-it-works.md#ralph-wiggum-pattern-fresh-context-every-wave - docs/cdlc.md (×2) → the-science.md#part-6-the-convergence-cdlc-as-the-unifying-spine - docs/context-lifecycle.md (×2) → #the-knowledge-ledger-session-to-session-flow - docs/releases/2026-03-21-v2.28.0-notes.md → ../CHANGELOG.md#2280-2026-03-21 Plus one structural fix: - docs/documentation-index.md → ../evals/workbench/ replaced with the github.com URL pattern used by every other extra-docs link in this file. evals/ lives outside docs_dir so mkdocs cannot resolve relative links there. Acceptance: zero INFO/WARN/ERROR mentioning these 5 files in `mkdocs build --strict`. Pre-existing INFO lines on templates/ and L*-*/ README directory links are out of scope (research §U4 / pre-mortem L3). Closes soc-2yx9 from epic soc-xlw8. * fix(goals): anchor cwd to GOALS.md repo root for `ao goals measure` (soc-crzz) Reproduction: from /tmp, `ao goals measure --file <abs>/GOALS.md` returned 21/22 fails with "bash: scripts/check-*.sh: No such file or directory". Goal Check strings are relative paths; bash inherited the caller's cwd. Fix: at RunMeasure entry, derive the repo root from the absolute GoalsFile path and chdir to it for the duration of the measurement; restore the prior cwd via deferred no-op-safe restorer (`withGoalFileCwd`). When GoalsFile is not inside a git repo, the helper returns a no-op so today's behavior is preserved outside repos. Also expose `Paths.RepoRoot` from cli/internal/paths so future callers can detect the resolved repo top without re-shelling git. The field is empty when the resolver was given a directory not inside a repo, mirroring `git rev-parse --show-toplevel` semantics. Smoke (post-fix): `cd /tmp && ao goals measure --file <abs>/GOALS.md --json` returns 22/22 pass, zero "No such file" errors. Tests: - TestRunMeasure_RelativeScripts_FromExternalCwd exercises the bug path end-to-end (fake git repo + relative-script goal + chdir to outside). - TestWithGoalFileCwd_NoRepoFallback verifies the no-repo no-op. - TestWithGoalFileCwd_EmptyPath verifies the empty-input no-op. Per pre-mortem H1 (.agents/council/2026-05-07-pre-mortem-drain-open-next-work-items.md). Closes soc-crzz from epic soc-xlw8. * feat(eval): add stdout_contains_auto_detect ratchet for live test counts (soc-bvhn) Two eval pins drifted silently when tests were added: - evals/agentops-core/hook-lifecycle-behavior.json "Total: 226" - evals/agentops-core/pre-push-gate-governance.json "1..51" The 226-pin only counted tests/hooks/test-hooks.sh and missed the 86-test test-hooks.bats suite entirely; the 1..51-pin was a manually-bumped plan line (commit bd104270 was 50→51 after PR #263 added a test). Replace both with a new expectation type stdout_contains_auto_detect that: 1. Re-executes a source-of-truth command (e.g. `bash tests/hooks/test-hooks.sh`) 2. Captures a regex group from its combined stdout+stderr 3. Verifies the case stdout contains the FULL match (drift = fail loud) 4. Honors tolerance_pct (default 0; strict-by-default) 5. Pre-checks the command's binary on PATH so missing `bats` etc. fails with an explicit "not found on PATH" message instead of regex miss 6. Inherits the case's cwd / suite-dir + timeout policy Drift surfaces a `BUMP the pinned value to "Total: N"` one-liner so the operator can react in one edit. Migrated both pins to use the new type. Pre-mortem M3 (.agents/council/2026-05-07-pre-mortem-drain-open-next-work-items.md) patch is enforced indirectly: validExpectationType registers the new kind, and the parser rejects empty command/pattern at load time. Tests: 8 new in expectations_auto_detect_test.go covering pass-on-match, fail-loud-on-drift, missing-binary-fails-loud, pattern-no-match, the bats `1..N` plan-line shape, missing-command rejection, tolerance allowing numeric drift, and registry membership. Closes soc-bvhn from epic soc-xlw8. * feat(reconcile): observation-log aggregator unblocks Wave 1E (soc-ejq2) Wave 1E (soc-f42z9) of the Reconciliation Engine epic cannot promote the factory-claim-ledger validator from advisory to blocking until ≥20 advisory runs are aggregated to .agents/reconcile/observation-log.jsonl. The CI job (`factory-claim-ledger-strict (advisory)` at validate.yml:450-565) already emits per-run observation JSON as a workflow artifact; nothing aggregated them. This builds the missing pull-mode aggregator. scripts/aggregate-observation-log.sh: 1. `gh run list --workflow validate.yml ...` for recent runs 2. `gh run download <run-id> -n factory-claim-ledger-observation` per run (silently skips runs that predate the advisory job) 3. Schema-validates EVERY observation BEFORE dedup (pre-mortem M3 patch: `jq unique_by(.run_id)` silently collapses null-key entries — we reject malformed observations up front with `jq -e all(.run_id and ...)`) 4. Dedups on run_id, atomic write to .agents/reconcile/observation-log.jsonl 5. Backfills merged_anyway and ledger_updated: - pr_number=null (push-to-main): both false. Push-to-main observations satisfy the no-silent-merge criterion by definition. - else: `gh pr view` for state + `git log` for ledger-touch detection Empty-output case (no runs yet): produces valid empty JSONL, exits 0. Idempotent: re-running does not duplicate; verified by L2 test. Skeleton .agents/reconcile/promotion-decision.md (gitignored, not in repo) seeded by the script for operator to fill in false-positive baseline. L1+L2 fixture-driven tests (9/9 pass): empty-input, dedup, schema rejection of null run_id, push-to-main backfill semantics, --dry-run no-write, idempotent byte-identical re-runs. Adds `reconcile` to docs/contracts/agents-write-surfaces.md (prose table and BEGIN/END allowlist) — required for `check-agents-write-surfaces.sh` to pass after the new write surface lands. NOT in scope (deferred to follow-up issues): - Scheduled .github/workflows/aggregate-observations.yml workflow - Operator-filled promotion-decision.md baseline - Wave 1E gate flip itself (soc-f42z9) Per pre-mortem M3 (.agents/council/2026-05-07-pre-mortem-drain-open-next-work-items.md). Closes soc-ejq2 from epic soc-xlw8. * feat(crank): wire CI-policy parity gate into wave acceptance (soc-il9k) Prevents recurrence of c587b361-style manual fixes. Wave 1C of soc-e4ulx added factory-claim-ledger-strict (advisory) to .github/workflows/validate.yml without updating AGENTS.md or `summary.needs:`. Codex-team caught and fixed the drift manually. This PR formalizes that recovery as a conditional crank wave-acceptance gate, so the next wave that touches workflow YAML fails loud at acceptance instead of slipping through. Insertion (canonical and codex-mirrored): - skills/crank/SKILL.md Step 5.5: new "CI-Policy Parity Gate (conditional)" sub-section pointing to the worked example. - skills/crank/references/wave-patterns.md: appended worked example with drift→fix transcript referencing commit c587b361. - skills/swarm/references/local-mode.md (worker prompt template): added section 4 to CONDITIONAL PREFLIGHT CHECKS so workers run the gate proactively, not only at acceptance. - skills-codex/* parity copies + regenerated codex hashes. Trigger (narrow grep — yaml workflow files only): if git diff --name-only HEAD~1 -- | grep -qE '^\.github/workflows/.*\.ya?ml$'; then bash scripts/validate-ci-policy-parity.sh || exit 1 fi CODEOWNERS-only or markdown-only changes do not trip the gate. The validator (scripts/validate-ci-policy-parity.sh, 186 LOC, unchanged) is a read-only dependency. Golden fixture tests/integration/test-ci-policy-parity-wave-gate.sh (9/9 pass): SKILL doc presence, trigger-pattern shape, worked-example linkage, worker-template wiring, codex parity, validator presence, drifted-fixture exits 1, aligned-fixture exits 0, live-repo PASS. Per planning rule finding-2026-05-07-ci-parity-as-wave-acceptance — this PR IS the formalization of that rule (self-referential by design). Closes soc-il9k from epic soc-xlw8. * feat(reconcile): thesis-stability gate + Wave 0 snapshot (soc-mt50) Gates the Reconciliation Engine arc transition from Wave 1 to Wave 2 (soc-r3y8b) by diffing current README/PRODUCT/GOALS hero sections against the snapshot frozen at Wave 0 close (commit ab479e26 — "docs(positioning): wiki-framing sweep across all surface docs (soc-9xn0)"). scripts/check-thesis-stability.sh: Hero extractor anchored to '^## ' (with trailing space) per pre-mortem M2 patch — code-fence-safe, excludes the H2 boundary line itself: awk 'NR==1, /^## / {if (!/^## /) print}' <file> Per-file diff against the snapshot's fenced ```...``` block. Operator decides accept/re-brainstorm/incidental on FAIL. Exit codes: 0 = no drift, 1 = drift (operator decision required), 2 = precondition error (snapshot missing, source files missing, or snapshot carries a literal `^<!-- WAVE_0_TODO -->$` line — anchored regex prevents prose mentions of the marker from triggering the precondition gate, per pre-mortem L6). --json mode emits {verdict, drifted, decision_template} for tooling. Snapshot artifact (.agents/reconcile/wave-0-thesis-snapshot.md): Frozen verbatim hero blocks for README.md / PRODUCT.md / GOALS.md at closure SHA ab479e26. Header documents extraction contract + regen path. Decision template (.agents/reconcile/thesis-stability-decision.md): Operator-fillable record. Three explicit options (accept / re-brainstorm / incidental). Re-validation matrix for Waves 2-4 acceptance criteria on accept-drift path. .gitignore: Adds the snapshot + decision-template paths to the .agents/ allowlist alongside existing exceptions (rpi/next-work.jsonl, nightly/, evolve/, goals/, findings/registry.jsonl). observation-log.jsonl and promotion-decision.md remain runtime state (generated by aggregator and operator fill-in respectively) and stay ignored. Smoke (run during implementation): - bash scripts/check-thesis-stability.sh → exit 0 (no drift today) - bash scripts/check-thesis-stability.sh --help → usage emitted, exit 0 - inject SMOKE-DRIFT into README hero, re-run → exit 1 with diff - revert, re-run → exit 0 Per pre-mortem M2 + L6 (.agents/council/2026-05-07-pre-mortem-drain-open-next-work-items.md). Closes soc-mt50 from epic soc-xlw8. * ci(reconcile): allowlist thesis-stability snapshot + decision artifacts (soc-mt50 follow-up) PR-E (06f416e1) added two static contract artifacts under .agents/reconcile/ that need to be tracked: wave-0-thesis-snapshot.md (frozen at Wave 0 SHA ab479e26) and thesis-stability-decision.md (operator-fillable template). The .gitignore exception alone is not sufficient — scripts/check-no-tracked-agents.sh maintains a narrow audit-truth allowlist of paths under .agents/ that may be tracked. Without an allowlist update, the pre-push-gate's "tracked .agents state" check fails on these two new files. Extends ALLOWED_PATHS_REGEX and ALLOWED_REINCLUDES_REGEX to include the two reconcile paths. observation-log.jsonl + promotion-decision.md intentionally remain runtime state (generated by the aggregator and operator fill-in respectively) and are NOT added to the allowlist. Updates the file's header comment to document the new reconcile entry in the audit-truth allowlist surface. Acceptance: - bash scripts/check-no-tracked-agents.sh → "no disallowed tracked repo-root .agents state" - bash scripts/pre-push-gate.sh --fast → exit 0 (46 skipped, 0 failed) Per CLAUDE.md "All exceptions require a coordinated update of .gitignore + this allowlist + CLAUDE.md/PROGRAM.md guidance." (Reconciliation Engine arc context covered in PR-E commit message.) * chore(rpi): mark soc-9xn0 + soc-e4ulx next-work entries consumed (soc-ot2m) Closes the housekeeping tail of epic soc-xlw8. Both unconsumed entries in .agents/rpi/next-work.jsonl flip to consumed=true, claim_status=consumed, consumed_by=soc-xlw8, consumed_at=2026-05-08T09:30:00-04:00. Mapping (10 raw items → 7 work units → 6 PRs; U1 already resolved by Wave 1A pre-session, no PR needed): U2 BATS count audit gap → PR-C f75201f5 (soc-bvhn) U3 ao goals measure cwd → PR-B 04e585e8 (soc-crzz) U4 mkdocs link rot + anchors → PR-A cf584671 (soc-2yx9) U5 observation-log aggregator → PR-D af681e9c (soc-ejq2) U6 thesis-stability gate → PR-E 06f416e1 (+93e4cf05) U7 CI-policy parity in crank → PR-F a2fb6a2f (soc-il9k) Closure note (gitignored, local provenance): .agents/rpi/closure-2026-05-07-next-work-items.md Also adds .agents/findings/registry.jsonl with three reusable findings generated during this session (the file was untracked due to .agents/ gitignore precedence; the audit-truth allowlist already permits it): - finding-2026-05-07-mkdocs-slug-observed-not-asserted - finding-2026-05-07-sed-range-includes-boundary-line - finding-2026-05-07-jq-unique-by-collapses-null-keys Acceptance: - bash scripts/validate-next-work-contract-parity.sh → exit 0 - jq -c . < .agents/rpi/next-work.jsonl → valid JSONL, 2 entries - bash scripts/check-no-tracked-agents.sh → no disallowed paths - bash scripts/pre-push-gate.sh --fast → exit 0 (46 skipped) Per pre-mortem L5 (.agents/council/2026-05-07-pre-mortem-drain-open-next-work-items.md): the validator was already passing pre-PR (the phase-2-summary's claim of broken parity was stale). Acceptance is steady-state ("validator continues to exit 0 after marking entries consumed"), not transition. Closes soc-ot2m and epic soc-xlw8. * chore(reconcile): record Wave 1E promotion-decision baseline (Option B defer) Filled .agents/reconcile/promotion-decision.md from skeleton with computed baseline from observation-log.jsonl: 3 obs / 0 fail / 2 PRs / vacuous FP rate. Sample 3 < 20 threshold and PRs 2 < 3 threshold do not justify promotion to blocking; first-day post-aggregator data is also clustered within ~4h. Selected Option B (defer/extend sampling) with explicit re-evaluation trigger documented (>=20 runs, >=3 PRs, >=1 fail). validate.yml gate stays advisory (continue-on-error: true intact). No behavior change to CI. Re-evaluation tracked under bd soc-nsuq, which blocks Wave 1E parent soc-f42z9. Audit-truth allowlist extended in both .gitignore and scripts/check-no-tracked-agents.sh to track the decision artifact, mirroring the thesis-stability-decision.md allowlist pattern from 93e4cf05. The promotion-decision is committed input to the Wave 1E gate-flip workflow, not runtime state. Refs: soc-xlw8 (RPI follow-up), soc-f42z9 (Wave 1E parent), soc-nsuq (re-evaluation), soc-ejq2 (aggregator that produced the baseline).	2026-05-08 14:08:40 -04:00
Boden Fuller	cc6750c4e8	feat(docs,skills): rebuild Pages site with MkDocs Material + harden RPI orchestrator delegation contract ... ## Docs site — boshu2.github.io/agentops - Replace Jekyll minima with MkDocs Material (slate dark palette default) - Landing hero scoped to .landing-hero (no gradient bleed on inner pages) - Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes - Generate skill catalog + per-skill pages from skills/*/SKILL.md at build - Generate CLI reference from cli/docs/ at build (fails build on missing source) - Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py) - Wire mkdocs build --strict into pre-push gate (Check 25a) - Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages) - README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp - tests/docs/validate-links.sh patched to understand mkdocs-generated paths ## RPI orchestrator strict-delegation contract - Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on. - Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror) - Forged learning with detection phrases + corrective actions (ao-inject-ready) - Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0 - Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer - Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized - CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred ## fix(hooks): go-test-precommit skips when no Go files staged - Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version - Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged - Applied to both hooks/ (source) and cli/embedded/hooks/ (synced) Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-19 10:37:58 -04:00
Boden Fuller	8adb8b7773	docs: align README-linked docs with current framing	2026-04-09 23:03:30 -04:00
Boden Fuller	672beddb98	docs: unify operational-layer positioning	2026-04-09 16:30:38 -04:00
Boden Fuller	3eb679c6f6	feat(knowledge): rename athena → compile + add Karpathy-style knowledge compiler ... Rename the athena skill to compile — a descriptive name that communicates what it actually does. Extend with Karpathy's LLM Knowledge Bases architecture: - New compile phase: LLM reads raw .agents/ artifacts and produces interlinked markdown wiki at .agents/compiled/ with index.md, log.md, backlinks - New lint phase: detects contradictions, orphan pages, stale claims, coverage gaps - Pluggable compute backend via AGENTOPS_COMPILE_RUNTIME (ollama|claude|openai) - Hash-based incremental compilation (only recompile changed sources) - compile.sh engine with security fixes (no shell injection, path traversal guard) - Full rename across 93 files: skills, docs, CLI, tests, hooks, scripts, codex Existing Mine → Grow → Defrag cycle preserved as phases within the larger compile workflow. No vector DB — compiled wiki IS the retrieval layer.	2026-04-05 17:57:40 -04:00
Boshu2	029f3ecb08	docs: fix broken links and orphaned docs from README restructure ... - GLOSSARY: fix broken anchor #knowledge-flywheel → #pillar-4-knowledge-flywheel - GLOSSARY: update #the-rpi-workflow → #the-phased-lifecycle - ARCHITECTURE: rename "The RPI Workflow" → "The Phased Lifecycle" - INDEX: add evolve-setup.md, ENV-VARS.md, SKILL-ROUTER.md, and 5 other orphaned docs - context-lifecycle: fix source column to self-reference instead of README	2026-03-11 17:47:54 -04:00
Boshu2	ec061db60d	docs(readme): extract reference material into dedicated docs (679→472 lines) ... Move config env vars, Knowledge Ledger lifecycle, parallel RPI diagram, evolve setup, recovery/hygiene, and vibe checks out of README into their natural doc homes. Deep Dive section collapsed to summary + link table. Phase details and Built On attribution preserved. New: docs/evolve-setup.md Appended: docs/how-it-works.md (phased/parallel RPI) Appended: docs/context-lifecycle.md (knowledge ledger flow)	2026-03-11 17:12:53 -04:00
Boshu2	0e62657856	docs(flywheel): close prevention-ratchet validation loop	2026-03-10 07:44:59 -04:00
Test	899c0eaea5	feat: add finding registry prevention ratchet	2026-03-09 16:44:54 -04:00
Test	e0d4a8a55d	feat: add headless Claude team backend	2026-03-09 13:34:36 -04:00