skills/boshu2__agentops
1
0
Fork 0
mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00
Code Issues Packages Projects Releases Wiki Activity
3,158 Commits 103 Branches 178 Tags
ao-pre-reduction@5b334a13f
Commit Graph

19 Commits

Author SHA1 Message Date
Bo efc2609682 docs(architecture): formalize the L0-L4 autonomy ladder (ag-wrom #autonomy-ladder) (#787) 
## What

Closes the partial in Google-SRE convergence **point #8** (`ag-wrom`):
AgentOps already ran work at several autonomy levels (human-in-loop
in-session → substrate dispatch → bounded `autodev`) but the progression
was *implicit* — nothing named the rungs, stated what each may mutate,
or defined the evidence that earns a promotion. Implicit autonomy is how
a probabilistic agent quietly acquires more authority than its track
record justifies.

Adds `docs/architecture/autonomy-ladder.md`:

- **The invariant every rung obeys** — non-deterministic reasoning core
wrapped by a deterministic enforcement boundary (CI gates +
ports-and-adapters + ratchet) the agent can't bypass. The ladder moves
the *leash*, never relaxes the *boundary*. L4 code passes the same CI as
L0 code.
- **L0–L4 rungs** mapped to AgentOps' real dispatch vocabulary, with
human posture / acts-before-review / may-merge per rung.
- **Promotion gates** — per-lane, revocable, gated on
statistically-significant success vs Golden data at the
Bronze/Silver/Gold tier.
- **Demotion** — auto-downgrade on risk (the L3→L2 analog of Google's
de-escalation) + the unconditional Red Button.
- **Hard ceilings** — no rung confers authority over
external/secrets/schema/deletion/strategic-fork/merge-beyond-contract;
those stay draft-and-queue at every level.
- Honest divergence stated: AgentOps autonomy is **build-time** (code +
`.agents/` corpus), not run-time production ops — which is why L4 is
delegated to a substrate, not shipped (ADR-0009).

Wires it into the architecture index card grid + `mkdocs.yml` nav, and
flips convergence point #8 from ⚠️ partial to ✅ encoded (tally 9/1/1).

## Evidence
Closes-scenario: ag-wrom#autonomy-ladder
Bounded-context: BC1-Corpus
Evidence: markdownlint-cli2 PASS on all 3 changed docs; all cross-links
verified to resolve (operating-loop, canonical-loop-model,
fungibility-charter, google-sre, ADR-0009 in-docs relative; CLAUDE.md +
skills/autodev as GitHub URLs per repo convention for out-of-docs
targets); new page registered in mkdocs nav for `mkdocs build --strict`.
 2026-06-06 12:18:20 +00:00
Bo cfee2b078a docs(convergence): first-class Convergence section — The Reading + Ledger + Google SRE map (ag-4hf7 #google-sre-convergence) (#650) 
## What

Establishes a first-class **`docs/convergence/`** section: the record of
the industry independently arriving at the structure AgentOps already
runs — kept distinct from the competitor map. Three surfaces:

1. **`the-reading.md`** — the *living thesis*. The argument (with
mechanism, firm-vs-forming consensus table, honest moat-risk, and a "how
to read a new signal" rubric) that the industry is converging and
**why**.
2. **`ledger.md`** — the dated *receipts* table (who/when/which
invariant). Seeded with Google SRE 2026.
3. **`google-sre.md`** — the per-party *encoding map*: 11 convergence
points → real AgentOps loci (8 encoded · 2 partial · 1 gap).
4. **`index.md`** — section hub framing the three.

## Why first-class, not under comparisons/

A vindication record is the *inverse* of a competitor grid — wrong to
parent it under "vs the competition." Radar = competitors in our lane;
Convergence = independents arriving from outside it. Promoted to its own
top-level nav section (`git mv`, history preserved; permalinks updated;
cross-links rewired both ways).

## Gaps surfaced (filed as beads)

| Bead | Point | Work |
|---|---|---|
| `ag-fjbu` | #3 | Adopt Bronze/Silver/Gold eval-tiering +
True-vs-Observed-Precision naming |
| `ag-wrom` | #8 | Formalize an L0–L4-style autonomy ladder for AgentOps
dispatch |
| `ag-7278` | #11 | Council: does coherent-arc need a fix-forward escape
hatch? (Google is ahead) |

## Verification

- All relative links across the convergence section + comparisons
pointers resolve.
- mkdocs nav + documentation-index updated; renames preserve history.

Closes-scenario: ag-4hf7#google-sre-convergence
Bounded-context: BC1-Corpus
Evidence: docs/convergence/the-reading.md
 2026-05-31 18:48:45 +00:00
Bo f4a91f97a6 docs(fungibility): AgentOps 3.0 Fungibility Charter — 6 commitments (soc-vuu6.29 #fungibility-charter) (#644) 
Codifies the AgentOps 3.0 fungibility doctrine — implicit in the
primitives but contradicted by 2.x surfaces — into a single charter at
`docs/architecture/fungibility-charter.md`.

## The six commitments
1. **Default RPI mode is single-model** — the session's model runs every
phase; multi-model is opt-in.
2. **Any agent can claim any bead** — no role gating; `bd
ready`/`--claim` already enforce this.
3. **Stateless agent assumption** — agents are interchangeable consumers
of the `.agents/` corpus; no agent owns a domain or carries
irreplaceable state.
4. **Universal init prompt is standard** — every spawn runs `ao session
bootstrap` (shipped, vuu6.25).
5. **Death is normal; recovery is automatic** — `ao beads stale-claims`
+ `ao beads resume` (shipped) make dead-agent recovery operational.
6. **Specialization is opt-in** —
`--mixed`/`--pool=N`/`--diverse`/`--codex` exist but are never the
default.

Each commitment names the shipped primitive that implements it, so the
doctrine is honest (the risk-gate from the bead: do not land doctrine
ahead of primitives — vuu6.25 closed, the stale-claims primitive lives
in `cli/cmd/ao/beads_stale.go`/`beads_resume.go` on main).

## Cross-references / discoverability
- `docs/architecture/operating-loop.md` — See also (acceptance: charter
referenced from the spine)
- `docs/architecture/index.md` — card
- `docs/documentation-index.md` — catalogue line
- `mkdocs.yml` — added to nav under Architecture

Docs-only, no code, scope-only diff (5 files, +105 / -0).
README/PRODUCT.md positioning rewrite is out of scope here (separate
slice soc-vuu6.30 + the CI citation gate); this PR lands the charter
artifact itself.

Closes-scenario: soc-vuu6.29#fungibility-charter
Bounded-context: BC5-Runtime
Evidence: docs/architecture/fungibility-charter.md
 2026-05-31 12:46:48 -04:00
Bo dde214825b docs(3.0): ag-p7j W1 — delete daemon contracts, regen generated docs, reframe skills (ag-p7j) (#529) 
W1 (structural) of the 3-way ag-p7j doc-sweep. Owns
shared/generated/structural artifacts + skills + contracts. Disjoint
from W2 (#527, core narrative) and W3 (#528, peripheral docs), both
already merged; this branch is rebased on top of them.

## Deleted (deleted-surface docs)
-
`docs/contracts/{agentops-daemon,ao-watch,daemon-idempotency,dream-run-contract,agent-worker,ao-outcomes,openclaw-consumer-api,gascity-integration}.md`
- `docs/code-map/agentopsd-codebase-map.md`
- `gascity-integration.md` deleted because it described the OLD
daemon↔GasCity adapter (`ao daemon run --executor-policy=gascity`,
daemon ledger, OpenClaw consumer endpoints). The current GC story is the
using-gc skill + the reference City.
- Removed every deleted doc's row from `docs/documentation-index.md`,
`docs/contracts/index.md`, and `mkdocs.yml` nav.

## Regenerated (generators, not hand-edited)
- `docs/cli-surface.{md,json}` via `check-cmdao-surface-parity.sh
--write-surface` — daemon/schedule/overnight/plans/watch/factory rows
gone (live `ao` binary no longer registers them; the docs were stale).
- `registry.json`, `skills/catalog.json`, SKU catalog, codex
`.agentops-generated.json` hashes + manifest.
- Skill counts verified in sync (81 skills).

## Reframed to in-session / GC / hookless
- Skills: `dream` (+codex twin, neutralized literal `agentopsd`/`ao
schedule`/`ao overnight`/`ao watch`/`ao plans` while keeping the
retirement message), `compile` (+codex), `scaffold/recommended-reading`
(+codex), `discovery/best-practices`, `validation/best-practices`.
- Generated narrative: `docs/SKILLS.md` /dream block,
`docs/ARCHITECTURE.md` dream paragraph, `skills/SKILL-TIERS.md` dream
row.
- Contracts prose: `docs/contracts/ubiquitous-language.md`,
`docs/contracts/agents-write-surfaces.md` (kept catalog rows for
surviving load-bearing-lane subdirs; dropped deleted-command references
in descriptions).

## 3.0.md:150
Restored the strong claim: "...gone from the CLI **and from live doc
prose** (only historical surfaces — ADRs, the CHANGELOG, release notes,
and the 3.0 migration record — still name them, by design)"; kept the
`validate-sku-catalog-drift` linkage-gate mention.

## Collateral (minimal dead-link repairs to my deleted targets)
- `docs/daemon-migration.md` (gascity-integration link →
dependencies.md), `cli/README.md` (dropped dream-run-contract link). The
comparisons-file dead link was resolved by W3's merge.

## Gates (all green locally)
doc-release (2765 links, 0 broken) · contract-compatibility (0 failures)
· structural-floor · agents-write-surfaces · registry --check ·
validate-sku-catalog-drift · validate-ci-policy-parity ·
validate-skill-cli-snippets · validate-codex-runtime-sections · codex
parity (5 skills) + regen-codex-hashes --check · skill-catalog drift ·
cli-skills-map · markdownlint (changed files) · mkdocs --strict · `cd
cli && go build ./...`

Closes-scenario: ag-p7j#w1-structural
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
 2026-05-24 21:55:17 -04:00
Bo 46ed7fee5a docs(3.0): sweep remaining daemon/schedule/hook prose + MIGRATION-3.0 (ag-qbw) (#520) 
## What

Wave 2 of the AgentOps 3.0 honest-docs sweep (post-#518 audit, bead
ag-qbw). Makes the `docs/` prose match the shipped code: the daemon,
scheduler, factory, and all hooks were **DELETED** (not deprecated).
AgentOps is the in-session loop + context compiler; out-of-session
orchestration is delegated to a substrate (Gas City reference City /
Olympus). Mirrors the already-correct `docs/3.0.md`.

This makes `docs/3.0.md:150` ("the standalone
daemon/scheduler/overnight-runner surfaces are gone from ... live doc
prose") true for the enumerated wave-2 surfaces.

## Deleted (whole docs about deleted commands)

- `docs/scheduling.md` — entire `ao schedule` + `ao daemon` guide
-
`docs/contracts/{agentopsd-control-plane,agentopsd-schedule,routing-policy}.md`
- `docs/contracts/jobspec-openapi-v0.yaml`
- `docs/templates/dark-factory-schedule.yaml.example`
- `docs/design/olympus-v4-specs/*.md` — v4-port reference for the dead
Olympus → agentopsd extraction

## Reframed (prose → in-session + Gas City)

- Daemon/schedule/overnight: `agentops-3-youtube-starter-series.md`,
`agentops-3-pmf-evidence-loop.md`, `wiki-for-agents.md`,
`activation-profiles.md` (+ `profiles/README.md` profile rename),
`CI-CD.md` (overnight lane)
- Hooks → hookless + CI-as-authoritative-gate (hooks removed #511):
`knowledge-flywheel.md`, `troubleshooting.md`, `reference.md`,
`CI-CD.md`, `release-e2e-checklist.md`, `seed-definition.md`

## Catalog + cross-link cleanup (no broken links)

- `documentation-index.md` — removed deleted-doc rows + the v4 section
- `contracts/index.md` — removed deleted-contract cards
- `rfcs/0002-jobspec-openapi-v0.md` marked superseded; `SCHEMAS.md`,
`templates/README.md` cross-links fixed

## Created

- `docs/MIGRATION-3.0.md` (from the approved draft) + catalog row +
mkdocs nav entry

## Gates (green for this PR's surfaces)

- Link check: **2723 links, 0 broken**
- Contracts structural floor: **PASS (45 contracts)**
- Contract compatibility (orphans): **PASS**
- markdownlint (all changed/new files): **clean**
- `heal.sh --strict`: **All clean**
- mkdocs-strict: my new doc + nav entry build cleanly. The strict build
is **red on main for pre-existing reasons outside this scope** —
`docs/_hooks/gen_cli_reference.py` FATALs on missing `cli/docs/HOOKS.md`
(hooks removed #511, generator not updated; release-mechanics domain)
and `docs/3.0.md:172` links `../PRODUCT.md`/`../GOALS.md` (root files
outside the docs tree). Both confirmed present on `origin/main`; filed
for wave 3.

## Scope notes

- Did **not** touch `CHANGELOG.md`, `cli/`, or version files (parallel
worker owns release mechanics).
- The audit grep still matches ~40 more out-of-scope `docs/` files
(contracts/*, code-map, comparisons, narrative pages, runbooks). Filed
as **wave 3 (ag-p7j)**.

Closes-scenario: ag-qbw#doc-sweep-2
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
 2026-05-24 18:27:24 -04:00
Bo e431339c40 feat(hookless)!: remove all hooks — skills + CLI only (soc-57b7f #remove-all-hooks) (#511) 
## What

AgentOps 3.0 goes **fully hookless**. This removes the entire hook
product surface — the product is now skills + the `ao` CLI with **zero
hooks**. CI is the authoritative gate.

## Deleted

- `hooks/` — 46 hook scripts + `hooks.json` + examples (whole directory)
- `cli/embedded/hooks/` + embedded `hooks.json` +
`embedded/lib/hook-helpers.sh`
- `lib/hook-helpers.sh`
- `ao hooks` CLI command: `cli/cmd/ao/hooks.go`, `hooks_run.go` + 5 hook
test files; `cli/internal/bridge/hooks.go`;
`cli/internal/doctor/fix_hooks.go` + test
- Codex hook manifest (`hooks/codex-hooks.json`) + handler/audit scripts
(`scripts/audit-codex-hooks.sh`, `install-dev-hooks.sh`,
`test-hooks-output.sh`, `test-codex-hookless-lifecycle.sh`,
`test-hookless-rpi-phased.sh`)
- Hook lease surface: `docs/contracts/hook-lease-*`,
`schemas/hook-lease.v1.schema.json`,
`scripts/check-hook-lease-inventory.sh`,
`check-hook-port-replacements.sh`, `generate-hook-lease-inventory.py`
- Hook docs: `docs/HOOKS.md`, `cli/docs/HOOKS.md`,
`docs/architecture/hook-noise-audit.md`,
`docs/contracts/hook-runtime-contract.md`
- `tests/hooks/` (whole dir) + hook test scripts; 5 hook eval suites +
fixtures

## CI gates removed

`hook-preflight`, `validate-hooks-doc-parity`, `hook-output-schema-lint`
(+ scripts/bats), the hook eval suites, the `test-runtime-codex-smoke` /
`test-codex-native-install` / `test-codex-plugin-install` hook-handler
assertions, the cli-integration hook-lifecycle steps, the bats
`tests/hooks/*` glob + orphan-hooks audit, and the `--with-hooks`
install path. `embedded-sync` now validates only lib/skills. Both
summary `needs:` lists + the summary echo +
`docs/contracts/ci-jobs.yaml` updated; `validate-ci-policy-parity`
passes (66 rows). `.codex-plugin/plugin.json` drops the "Hooks"
capability.

## Load-bearing PRESERVED (reported, not forced)

- **`cli/cmd/ao/codex_runtime.go`** — the codex runtime *lifecycle
profile* (`HookCapable`/`HookConfigured` detection) is a
runtime-capability abstraction used by 6 `validate-codex-*` CI gates,
distinct from the hook product. Deleting it is a separate refactor.
- **`hooks-authoring` skill** + `schemas/hooks-manifest.v1.schema.json`
— reframed as an opt-in "author your own hooks" guide. Deleting the
skill cascades into catalog/domain-map/dispositions/context-map golden
files (skill-count sync), out of scope for the hook-product removal.
- **`scripts/pre-push-gate.sh`** — retired local gate (not in CI);
self-skips deleted hook scripts via `[[ -x ]]` guards; its 55 bats tests
still pass.
- Domain-enforcement audit keeps the `enforced`-mode schema for
backward-compatible JSON readers, but the hookless resolver only returns
`audited`/`unavailable`.

## Verification

`go build` / `go vet` clean; `go test ./...` = **11849 passed, 0
failed** (68 pkgs). gofmt clean on all touched files. Green: registry
`--check` (0 hooks), `regen-codex-hashes --check`,
`validate-ci-policy-parity`, `check-wiring-closure`,
`validate-embedded-sync`, `validate-manifests`, `validate-agents-split`,
`doc-release` (0 broken links), `generate-cli-reference --check`,
`heal.sh --strict`, codex/claude/plugin smoke tests, baseline-audit (0
stale). Diff: 231 files, +354 / −39803.

Closes-scenario: soc-57b7f#remove-all-hooks
Bounded-context: BC5-Runtime
Evidence: .github/workflows/validate.yml
 2026-05-24 11:19:37 -04:00
Bo b8aa715fa8 docs(roadmap): move aspirational claims into docs/ROADMAP.md (soc-icvff #w1b-roadmap) (#470) 
W1b of the 3.0 reconciliation (match reality). Designed-but-unbuilt
features were scattered through live docs; consolidated into one roadmap
so live docs describe only what exists.

- **docs/ROADMAP.md (NEW)**: gt convoy / bd mol / bd cook, curation
later stages, hookless default-install (ADR-0002 S2–S5), legacy-RPI
removal (soc-1gbpz) — non-committed framing
- troubleshooting.md / brownian-ratchet.md / curation-pipeline.md:
removed inline unbuilt-command examples → ROADMAP pointers
- documentation-index.md + mkdocs nav: cataloged

No code. grep confirms no unbuilt-as-available language left in live
docs.

NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.

Closes-scenario: soc-icvff#w1b-roadmap
Bounded-context: BC1-Corpus
Evidence: docs/ROADMAP.md
 2026-05-23 10:08:13 -04:00
Bo 4dd53dffa3 docs(3.0): canonical 3.0 north star + weave into sources of truth (soc-25sgs #3.0-north-star) (#468) 
W0 of the 3.0 reconciliation (operator-ratified). Grounds the repo
before reconciliation work.

- **docs/3.0.md (NEW)** — single source of truth: the SDLC↔CDLC loop
(BDD/Gherkin planning → tests → bounded build through ports → both-ends
behavior+contract validation → feedback → ratchet), the
BDD/DDD/Hexagonal/TDD waist, context density, and a precise
hookless-first explanation (hooks = quiet adapters, not
noise-injectors). + 3.0-ready acceptance + non-goals.
- Woven into README, PRODUCT.md, GOALS.md, CLAUDE.md,
docs/documentation-index.md, mkdocs.yml nav.

Pure grounding: no code, no bead closes, no features. Links verified;
additions-only.

NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.

Closes-scenario: soc-25sgs#3.0-north-star
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
 2026-05-23 09:27:56 -04:00
Bo 9a92652d4d docs(architecture): behavior-shaping-environment doctrine — the ABC spine (soc-loqc #behavior-shaping-doctrine) (#414) 
Operator product thesis (2026-05-22): AgentOps is the environment that
arranges antecedents + reinforcement so agents reliably perform
agreed-upon behaviors. This names the operant-conditioning model
(Antecedent → Behavior → Consequence) AgentOps already embodies — the
*why* beneath the loop.

- docs/architecture/behavior-shaping-environment.md (NEW): ABC model +
surface→mechanism mapping (antecedent=context arrangement,
behavior=.feature, consequence=gates/ratchet reward + hooks/STOP/reverts
stop), why-it-works, 5 governing principles, propagation map
- catalogued in documentation-index + architecture/index; added to
mkdocs nav

Anchor for epic **soc-tk1d**. The other 3 surfaces (domain vocab,
positioning, GOALS contract) cite this doc.

Sibling pattern: mirrors docs/architecture/operating-loop.md doctrine
shape. Fitness: behavior-science surfaces 0/4 → 1/4.

NOTE: claude-review will be infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.

Closes-scenario: soc-loqc#behavior-shaping-doctrine
Bounded-context: BC1-Corpus
Evidence: docs/architecture/behavior-shaping-environment.md
 2026-05-22 15:25:35 -04:00
Bo 81fe2d5ae8 feat(docs): sovereignty-proof page — F6/F7 + RPI-leanness case studies (soc-vuu6.32 #sovereignty-proof) (#386) 
## Summary

New \`docs/sovereignty-proof/\` surface with two committed case studies
showing where independent-vendor review caught what same-vendor review
missed:

- **2026-05-15 RPI-leanness council** — Codex (gpt-5.5) independently
reframed "RPI is waterfall" to "plan.md is an artifact-boundary bug",
turning a multi-week methodology rewrite into a single-port surgical
change (PR #275 was already in-flight implementing this).
- **2026-05-16 CDLC research council** — Two Codex judges independently
flagged the F6 session-misjoin bug in
\`cli/cmd/ao/flywheel_citation_feedback.go\` and the F7
\`hooks/citation-tracker.sh\` wiring gap. No Claude judge surfaced
either.

## Why

Council non-negotiable #2
(.agents/council/2026-05-18-validate-agentops-3.0-doctrine.md).
Mixed-model capability must be visible as load-bearing proof of the
sovereignty thesis, not buried as opt-in obscurity. The page is what
makes the sovereignty claim falsifiable + linkable from the README hero
(unblocks soc-vuu6.30).

## Mechanical guarantees

- \`scripts/validate-sovereignty-proof-citations.sh\` scans every
\`.md\` under \`docs/sovereignty-proof/\` for \`file:line\` citations
(\`path/to/file:NN\` or \`path/to/file:NN-MM\`) and verifies each
resolves at HEAD. Currently 16 citations across 3 pages.
- New CI job \`validate-sovereignty-proof-citations\` (required) wires
the script into \`validate.yml\` with broad triggers so any
referenced-surface change re-runs the gate. Added to merge-gate
\`needs:\` arrays + summary echo.
- 8-case bats regression suite at
\`tests/scripts/validate-sovereignty-proof-citations.bats\` (pass /
file-missing / line-overflow / fenced-code-block / backtick / multi-page
/ no-dir / no-markdown).
- mkdocs nav entry under Concepts → Sovereignty Proof.
- \`docs/documentation-index.md\` Concepts entry.

## Acceptance (BDD)

Given a visitor wants to verify the sovereignty claim is real, When they
click "Sovereignty proof" from README hero (slice 1, blocked on this),
Then they land on \`docs/sovereignty-proof/index.md\` showing real
\`/council --mixed\` output from the 2026-05-15 reframe AND 2026-05-16
F6+F7 findings with \`file:line\` citations and verdict file links.

## Verification

\`\`\`bash
bash scripts/validate-sovereignty-proof-citations.sh
# validate-sovereignty-proof-citations: scanned 3 pages, 16 citations
# PASS — all citations resolve.

bats tests/scripts/validate-sovereignty-proof-citations.bats
# 1..8 (all pass)
\`\`\`

Closes-scenario: soc-vuu6.32#sovereignty-proof
Bounded-context: BC1-Corpus
Evidence: docs/sovereignty-proof/index.md
Evidence: scripts/validate-sovereignty-proof-citations.sh
Evidence: tests/scripts/validate-sovereignty-proof-citations.bats
Evidence: .github/workflows/validate.yml
 2026-05-21 00:48:38 +00:00
Bo d69f9f0c13 feat(architecture): intent-to-loop hexagon doc + BDD skill scaffolding (soc-4d0r) (#321) 
## What

Foundation slice for the **soc-qk4b** epic ('TDD-crank all skills into
intent-to-loop hexagons'). The epic description listed these artifacts
as 'What already exists' — but they were never committed to main.
Without them, the 6 sub-issues (`soc-qk4b.1` through `.6`) cannot start.

## New

`docs/architecture/intent-to-loop-hexagon.md` — process-level hexagon
connecting [Ports and
Adapters](../blob/main/docs/architecture/ports-and-adapters.md)
(structure) to [Operating
Loop](../blob/main/docs/architecture/operating-loop.md) (execution).
Defines the 8-port chain with driving/driven/guard adapters and
done-state rules:

```
Intent
  -> shape_intent      -> AcceptanceExample
  -> persist_intent    -> WorkItem / Bead
  -> plan_slices       -> Slice
  -> execute_slice     -> implementation
  -> execute_wave      -> wave packet
  -> validate_acceptance -> CriterionVerdict
  -> record_evidence   -> Evidence
  -> steer_goal        -> LearningDisposition
```

## Skill changes

Source-of-truth in `skills/`, mirrored to `skills-codex/` (re-hashed via
`scripts/regen-codex-hashes.sh`):

| Skill | Change |
|---|---|
| `plan` | Require Gherkin block or upstream-scenario link for
feature/bug/product-facing behavior issues; `hexagon:` boundary block
for non-trivial plans and beads. |
| `discovery`, `rpi`, `validate`, `validation`, `beads`,
`shared/validation-contract` | Reference the intent-to-loop hexagon as
the boundary contract. |

## Doc plumbing

- `docs/architecture/{index,operating-loop,ports-and-adapters}.md` +
`docs/contracts/skill-ports-and-adapters.md`: cross-link to new hexagon.
- `docs/templates/{intent-issue,slice-validation}.md`: carry hexagon
block into intent issues and slice validation plans.
- `mkdocs.yml`, `docs/documentation-index.md`: register new doc in nav.

## AGENTS.md

- bd integration block regenerated (`v:1 profile:full hash:f65d5d33`).
- Session Completion section added with **conditional** `bd dolt push`
wording — passes `scripts/validate-bd-closeout-contract.sh`.

## Validation

- ✅ `scripts/pre-push-gate.sh --fast`: passed (1 pre-existing warn on
`scenarios/trace` executable-spec link integrity, unrelated)
- ✅ `scripts/validate-bd-closeout-contract.sh`: passes
- ✅ `scripts/regen-codex-hashes.sh`: 7 manifest hashes updated for
parity
- ✅ All 8 codex JSON files: syntactically valid
- ✅ Self-review per pre-commit hook: no removed error handling, no
changed defaults, no silent data loss

## Origin

Discovered during analysis of merged branch
`refactor/council-mode-taxonomy-soc-ml4l` (PR #293) on 2026-05-18 — the
BDD/hexagon scaffolding sat uncommitted in the worktree after #293
merged. Filed as `soc-4d0r` with `discovered-from: soc-qk4b`. This PR
lands the work cleanly off fresh `main`.

## Unblocks

- soc-qk4b (epic)
- soc-qk4b.1 — Control ledger for 77-skill hexagon crank
- soc-qk4b.2 — Loop priority skills (hexagon/TDD crank)
- soc-qk4b.3 — Factory priority skills
- soc-qk4b.4 — Corpus priority skills
- soc-qk4b.5 — Validation priority skills
- soc-qk4b.6 — Runtime priority skills

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Codex <codex@example.invalid>
 2026-05-18 16:48:14 -04:00
Bo a427dcce6d docs(positioning): assurance profile + goals as reconcile setpoints (soc-sx99) (#257) 
* docs(positioning): add assurance profile for agent factory rigor

* docs(positioning): frame goals as reconcile setpoints

* chore(scripts): suppress SC2034 on bd_out — set by run_capture via name-ref

Drive-by fix needed to push crank/soc-sx99 — pre-push shellcheck flagged
bd_out as unused in test-rpi-surface-smoke.sh, but it is set indirectly by
run_capture's name-ref pattern. Adds a targeted shellcheck disable comment.
 2026-05-07 17:50:17 -04:00
Boden Fuller d535db3e29 docs(cdlc): add Context Development Life Cycle concept page 
Map the DevOps SDLC to CDLC — seven phases (Generate, Compile, Test,
Distribute, Deliver, Observe, Adapt) with AgentOps implementation for
each. Added to Concepts nav between The Science and Brownian Ratchet.
Also updates mkdocs site_description to context-compiler framing.

Ref: Debois CDLC talk (AI Engineer 2026), soc-hsef
 2026-05-04 13:07:46 -04:00
Boden Fuller d54eba7aaa docs: add local compute routing policy draft 2026-05-03 15:03:42 -04:00
Boden Fuller 6e7ed526a9 feat(daemon): ship AgentOps daemon runtime 2026-04-28 23:54:11 -04:00
Claude c4166a5c51 docs: fix broken CLI links, add HOOKS/SCHEMAS/UPGRADING pages, expand GLOSSARY 
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).
 2026-04-22 05:01:02 +00:00
Boden Fuller 1e073d8363 chore: purge archived AO↔Olympus bridge integration + prefer local Go in precommit hook 
Olympus (ol) was the power-user daemon predecessor to AgentOps, archived
in strategic-direction.md. The bridge contracts (SPEC_ONLY, never
enforced), MemRL policy surface, OL quarantine constraints collector, and
supporting scripts/tests all referenced a now-dead integration. Purging
them removes ~2400 lines of stale surface area.

## Deleted files
- docs/ol-bridge-contracts.md
- docs/architecture/ao-olympus-ownership-matrix.md
- docs/plans/2026-02-13-ao-olympus-bridge-next-steps.md
- docs/contracts/memrl-policy-integration.md
- docs/contracts/memrl-policy.schema.json
- docs/contracts/memrl-policy.profile.example.json
- cli/cmd/ao/inject_ol_test.go
- skills/vibe/scripts/ol-validate.sh + codex mirror
- skills-codex/swarm/scripts/ol-ratchet.sh, ol-wave-loader.sh
- tests/ol-integration/ (entire directory)

## CLI code stripped
- internal/search/types.go: OLConstraint struct + InjectedKnowledge.OLConstraints field
- internal/search/inject_run.go: CollectOLConstraints, WriteConstraintsSection, quarantineRelPath const, all related trim/render logic
- cmd/ao/inject.go: gatherOLConstraints, collectOLConstraints wrapper, olConstraint type alias, init-time call site
- Package comments in provenance/storage/types/formatter updated "olympus" → "agentops"
- formatter/markdown.go: session tag "olympus" → "agentops" (+ test update)
- Tests: deleted TestCollectOLConstraints + TestInject_collectOLConstraints, stripped OL subtests from TestFormatKnowledgeMarkdown and TestInject_*, renamed "olympus" literal test data to "other-repo"
- rpi_phased_context.go: stripped "matches Olympus DefaultTimeout" and "Modeled on Olympus internal/git/worktree.go" comments

## Docs + skills stripped
- mkdocs.yml nav: 3 entries removed (AO-Olympus Matrix, MemRL Policy, OL-AO Bridge)
- docs/INDEX.md, contracts/index.md, architecture/index.md, index.md: cross-refs removed
- strategic-direction.md: retirement rationale compressed to one paragraph
- docs/context-packet.md, positioning/devops-for-vibe-coding.md, plans/README.md: OL-specific content removed
- skills/vibe/SKILL.md + codex mirror, swarm/SKILL.md: OL script refs removed
- skills/vibe/references/deep-checks.md, plan/references/planning-rules.md (+ codex), pre-mortem/references/council-fail-patterns.md (+ codex): OL rule/pattern entries removed
- skills-codex hashes regenerated (plan, pre-mortem, swarm, vibe)

## Precommit hook fix
- hooks/go-test-precommit.sh: prefer ~/.local/go/bin/go when present. Hooks
  don't inherit interactive-shell PATH, so apt-provided go-1.22 would
  otherwise override a user-local 1.26 install. Mirrors the zshrc pattern.

## Retained (historical / useful)
- strategic-direction.md: 1-paragraph archival note
- Historical release notes (docs/releases/*.md) — immutable past-release record
- cli/testdata/transcripts/real-2.4mb.jsonl — captured test fixture
- docs/brownian-ratchet.md ol-rg3p bead-ID refs — internal bead prefix, not Olympus

## Verification
- go build ./... && go vet ./... clean
- go test ./... clean except pre-existing TestGCBridgeVersion_Live panic
- scripts/docs-build.sh --check (mkdocs strict) clean
- scripts/check-contract-compatibility.sh passes
- scripts/regen-codex-hashes.sh run — 4 skills updated
 2026-04-19 14:33:00 -04:00
Boden Fuller 57527e3fd2 docs(theme): match agentops-showcase palette — warm terracotta on near-black 
Source of truth: boshu2/agentops-showcase (12factoragentops.com).
Tokens copied from its tailwind.config.ts + globals.css.

## Palette
- Primary: #d97757 (hsl(15 55% 60%)) — warm clay / terracotta
- Accent: #fbcfb2 — soft peach
- Background: #0a0a0a (neutral-950, warm matte)
- Card bg: #111110 / #171512 (warm-tinted ladder)
- Foreground: #dea78c / #c79073 (warm tan on dark)
- Selection: rgba(217,119,87,0.3) with peach text

## Fonts
- Code: Space Mono (replaces JetBrains Mono) to match showcase
- Text: Inter (unchanged)

## Updated
- mkdocs.yml palette: primary/accent → "custom" so the theme defers to
  our CSS variables
- docs/assets/stylesheets/extra.css: full rewrite — header gradient,
  announce bar, buttons, grid cards, code blocks, tables, admonitions,
  nav, search, scrollbars, selection all retuned to the warm palette
- docs/assets/logo.svg + favicon.svg: gradient swapped from indigo→pink
  to terracotta→peach to match
- Hero landing H1 gradient: now clay→peach→amber
- Preserved the .landing-hero scoping so inner-page H1s stay solid,
  not gradient

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-19 12:14:58 -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