Make `scripts/docs-build.sh --check` a MEANINGFUL signal instead of advisory
noise (was 82 strict-mode warnings, always ignored).
Root cause: mkdocs --strict fails on 82 links that leave docs/ (the knowledge
graph deliberately links out to skills/, scripts/, schemas/, evals/, and canonical
repo-root docs). All 82 were verified to resolve to REAL repo files on disk — zero
accidental breaks — so they are intentional cross-references, not bugs.
Fixes (category A + B, INFO-level drift, verified against built HTML anchors):
- Anchors: GLOSSARY SKILLS.md#beads->#beads-br; INCIDENT-RUNBOOK scenario-C
double->single hyphen (x2); pawls.md directive-precedence / diversity-mode /
escalation double->single (referrers in ADR-0007, autonomy-ladder, pawls self);
catch-derived-fuel membrane update anchor (single + date suffix).
- Suffixes: levels L1-L4 README next-level links + workflows meta-observer ->
explicit README.md targets.
Dispositions (category C + D): the 82 intentional external cross-refs are enumerated
in tests/docs/mkdocs-strict-allowlist.txt and explained per-class in
docs/docs-build-dispositions.md. `docs-build.sh --check` now runs mkdocs --strict
end-to-end (nothing weakened, no --no-strict) and fails on any warning NOT on the
allowlist — proven: a fresh broken link still fails the check; the 82 pass.
Result: `docs-build.sh --check` is CLEAN-or-dispositioned (exit 0). Wired doc into
nav + CONTRIBUTING pointer.
Fold 5 substrate skills into their survivors (ao skills retire --into), after
re-litigating each keep-rationale:
- vibing-with-ntm -> ntm (operator layer over the same NTM tools)
- agy-headless-evidence -> agy-native (consumes agy-native; evidence is a
listed capability; mirrors agy-mcp/rules/sidecar folds)
- codex-approval -> codex-exec (codex-runtime driving-adapter; mirrors the
codex-* consolidation)
- dual-pane-atm -> using-atm (a specialization of the ATM substrate)
- orchestrate -> using-atm (route/preflight/verify instrument; the ao
orchestrate CLI survives, only the skill doc folds)
using-atm is the surviving out-of-session-substrate consolidator. Manual cleanups
ao skills retire does NOT reach: git rm .agy-plugin/skills/vibing-with-ntm +
drop it from validate-agy-plugin.sh core_skills; drop the dual-pane-atm/orchestrate
lines from scripts/.scenario-linkage-allow; drop vibing-with-ntm from
scripts/lint/codex-cross-runtime-skills.txt; repoint 26 broken cross-ref links to
survivors + fix frozen-twin generated_hash. scenario-linkage / skill-redirects
(47 resolve) / doc-skill-refs / manifests all green.
NOTE: validate-agy-plugin.sh has a PRE-EXISTING 9-bundle drift at HEAD (agent-mail,
beads-*, cass, cc-hooks, dcg, ntm, rch — stale hand-committed .agy-plugin bundle,
no sync tooling, not a routed gate); untouched here, flagged for a follow-up.
Restore the cut reverse-engineer-rpi skill (was cut in 94db74318), rename it
(drop the rpi suffix across 16 files + both trees), and upgrade it from a pure
teardown tool into teardown -> steal-map (have/gap/steal/park/reject) -> route
one-way doors to /discovery's mixed-model duel. Folds this session's discipline:
validated cross-family not self-report, park substrate we delegate (ADR-0009),
steal the pattern not the platform, probe real state not stale. 308->125 lines,
codex twin mirrored (slim frontmatter + hashes), disposition keep row added.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Extract the behavior-first-planning discipline (intent → frozen Gherkin
behaviors → EXECUTED-red acceptance tests → derived spec → acceptance-gated
bead DAG) into skills/behavior-first-planning/SKILL.md, so the capability
survives independent of the bdd-foundry workflow. The rule it enforces: no
runnable acceptance test, no bead — closing the spec-first "beads ship with no
done-criteria" hole (the 3/10 problem) before W3 thins the workflow.
Covers the four bdd-foundry phases + the closing independent-review gate
(validate before tracker write). Codex twin mirrored (manual) + hashes regen;
dispositions ledger row (BC3 Loop, domain, planning, parity required); registry
+ skill-domain-map + SKILL-TIERS + count-propagation regenerated (73→74).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Completes the staleness epic. 42 P2/P3 files converged to current truth
(bd→br, gascity/gt-sling/mayor→NTM+Agent Mail, daemon→substrate, hooks→hookless,
CI-authoritative→push-to-main local Go gate); GLOSSARY's 18 dead skills/* links
repaired to ../skills/<name>/SKILL.md (19 links, 0 broken); contracts/runbooks
that freeze retired-system nouns bannered RETIRED/HISTORICAL rather than rewritten.
Adds the Arc-7 ratchet — scripts/check-docs-no-retired-tech.sh — which scans all
live docs (260) for retired-subsystem commands/phrases and fails on regression.
A doc opts out by carrying a RETIRED/HISTORICAL/SUPERSEDED banner (or being an
ADR / migration / upgrade / index doc), and lines that describe a removal are not
flagged. Running it caught 12 stale refs the deep-read sweep missed — a
"CI is the authoritative gate" cluster (agentops-brief, primitive-chains,
INCIDENT-RUNBOOK, knowledge-flywheel, philosophy, software-factory), stale
hook-smoke in release-e2e-checklist, and GasCity descriptors in
contracts/index + SCHEMAS + strategic-direction — now fixed. Gate: PASS.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Salvaged the uncommitted work from wt-ag-ez7y6 and completed the 4->2 beads
skill consolidation the salvaged test asserts:
- Fold the "Issue-Lifecycle Discipline" doctrine (live-reads-authoritative,
scoped-closure-proof, parent-reconciliation, narrow-the-umbrella-issue,
normalize-stale-queue) from the retired `beads` umbrella into beads-br.
- Retire skills/beads --into beads-br via `ao skills retire` (trees removed,
ledger row moved to historical: merged-into beads-br).
- Re-target every retired-skill reference: crank/implement/plan/post-mortem/
refactor frontmatter+deps, SKILL-TIERS rows, docs/SKILLS.md, GLOSSARY link,
sku_catalog LOOP_MOVES[2], image manifests (counts adjusted).
- Codex twin: mirror the doctrine into skills-codex/beads-br, prune `beads` from
the codex catalog/manifest, regen hashes (parity gate age-yxl).
- Add cli/cmd/ao/beads_consolidation_test.go (L2 structural invariants). Uses a
leak-proof repo-root finder (skills/+docs/contracts/) because the shared
findRepoRoot keys on .agents/, which the cmd/ao suite leaks into the pkg dir.
Fixed an ao-skills-retire bug surfaced here: the historical row was appended at
the end of the `workflows:` section (between historical: and dispositions:)
instead of inside historical:. Corrected manually; full fix tracked separately.
Bounded-context: BC3-Loop
Evidence: cli/cmd/ao/beads_consolidation_test.go
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
skills/converge/SKILL.md is a thin (<=120 line) lazily-loaded memo that points
at the Go 'ao converge' command — NOT a reimplementation (it's a Go CLI, not a
skill). References 'ao converge', carries the two-leg cross-family dispatch table
+ the LAW-0 rule, no shell-loop reimplementation. Disposition row added; full
make regen-all propagated the new skill into registry.json + the generated docs
(SKILLS/GLOSSARY/ARCHITECTURE/context-map/domain-map + 71->72 counts).
Closes-scenario: ag-slice4-skill-thin-memo-1wi5y#S4.1
Bounded-context: BC5-Runtime
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Freeze a mechanical claim, dispatch a stake-free Fable refuter + a codex exec
read-only refuter in parallel with the full gate, fix findings forward, re-verify
pins on the landed tree. Self-audit: WARN (acceptable v1). Factory tax paid:
codex twin+prompt, manifest/catalog/dispositions/tiers rows, counts 67, regen green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Squash merge image consolidation after CI repair.\n\nValidated by GitHub Actions: changes, lint, codex-parity, skills-integrity, skill-gates, contracts-sync, correctness on Ubuntu and Windows, security, eval, skill-eval, doctrine-proof, process-hygiene, and summary. Cursor Bugbot was pending/advisory; main has no branch protection/rules requiring it.
## What
Google is deprecating the **gemini CLI** in favor of **Antigravity
(AGY)**. This migrates the vendor lane: retire the 4 legacy `gemini-*`
skills (built for gemini-cli affordances) and build out the real **AGY
lane**.
## Skills
- **Retired:** `gemini-native`, `gemini-mcp-hooks`,
`gemini-headless-evidence`, `gemini-skills-extensions` (both `skills/`
and `skills-codex/`).
- **AGY lane (4, dual-form):** `agy-native` + `agy-rules-workflows`
(enhanced — folded in the still-relevant intent, added
`/goal`+`/schedule`), `agy-mcp-plugins` + `agy-headless-evidence` (new).
Targeted at AGY's real affordances (Antigravity plugins/MCP/hooks,
agentapi headless, scoped worktrees) — **not** a 1:1 rename of
gemini-cli surface.
## Derived surfaces
Regenerated registry (171 skills), codex catalog/manifest,
skill-domain-map, SKILL-TIERS, context-map, narrative docs. `~/.gemini`
*paths* preserved (AGY's real config root).
## Validation
- Door-9 (no `claude -p`) PASS across all skills.
- `scripts/regen-all.sh --check` → ALL GATES GREEN.
- 0 references to dead `gemini-*` skill names. JSON valid.
## Not in this PR (follow-up: fork-and-own)
Binary-tool AGY support — `caam` (add `agy` tool) and `ntm` (add `--agy`
pane). Auth is already shared via `~/.gemini`; these are launch/spawn
wiring gaps tracked separately.
## 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
## What
Verified-clean subset of the second-wave counts/misc bead (ag-j4tw).
- **GLOSSARY.md:170** "ships 66 shared skills" → 82, and **extended
`sync-skill-counts.sh`** to cover the call-site so it self-heals and CI
catches future drift (same gate pattern as ag-bcl4).
- **test-architecture-debt-analysis.md:3** hardcoded Mac path
`/Users/fullerbt/…/cli/cmd/ao/` → repo-relative `cli/cmd/ao/`.
## Verify-first dropped FALSE POSITIVES
Applying the session's recurring lesson (audit agents over-flag):
- ENV-VARS `COUNCIL_EXPLORER_MODEL/TIMEOUT`, `COUNCIL_R2_TIMEOUT` are
**live** (consumed by `skills/council/`, not `cli/` — the audit only
grepped cli/).
- `MEMRL_MODE` exists (3 files); `rg-optimized.md:70` is blank; ROADMAP
"hookless S2–S5" is a real follow-on; `ao inject` is live.
## Still open (ag-j4tw stays open)
- agentops-brief.md / agentops-system-map.md counts are entangled in
**hook-diagram lines** → handle with ag-t1ca.
- TESTING.md `tests/hooks/` (hooks) + testing-skills.md
`tests/_quarantine/claude-code` → `tests/claude-code` (larger path
rework).
## Verification
- `scripts/sync-skill-counts.sh --check` → clean (GLOSSARY now covered)
Closes-scenario: ag-j4tw#counts-glossary
Bounded-context: BC2-Validation
Evidence: docs/GLOSSARY.md
* 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).
Replace "bookkeeping, validation, primitives, and flows" with the three
product layers (Context Compiler, Validation Gates, Knowledge Flywheel) in
core docs, README skills table, and comparison docs. Adds three-layer
comparison tables to all 5 vs-*.md files and a navigation section to
documentation-index.md.
Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.
Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
Replace with the canonical github URL so both mkdocs and raw-GitHub
readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
router so evaluators, installers, contributors, and upgraders don't
have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
orphaned) and add an "Install verification" block pointing at ao doctor.
New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
install/uninstall, customization env vars, and common failure modes,
pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
--no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
swarm-evidence schema enforcement, and pre-mortem gate tightening.
Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
Compile, Context Window, Discovery, Dream/Overnight Run alias,
Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
an easily-missed sentence to a bold callout with CI-failure rationale.
mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.
Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
single remaining preexisting warning about index.md is out of scope).
## 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>
Wave 3 of ag-lhb: Remove deleted skill entries from SKILL-TIERS.md,
sync counts to 49 total (40 user-facing, 9 internal), fix broken
GLOSSARY.md link to deleted extract skill, fix heal.sh dead xrefs.
boshu