mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
ao-pre-reduction@5b334a13f
98 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Bo
|
6d5d111faf |
feat(skills): land four-vendor skill corpus (#803)
## Summary - Lands the AgentOps skill corpus across source and Codex wrappers, including Gemini image targets. - Integrates the skill branch onto current origin/main and refreshes generated manifests/catalogs. - Normalizes local next-work queue enum drift and fixes shellcheck in alias-collision validation. ## Validation - bash scripts/regen-all.sh --check - bash scripts/validate-skill-schema.sh - bash tests/skills/test-token-budgets.sh - bash tests/skills/run-all.sh - bash scripts/audit-codex-parity.sh && bash scripts/validate-codex-override-coverage.sh && bash scripts/validate-codex-generated-artifacts.sh --scope worktree && bash scripts/validate-codex-api-conformance.sh && bash scripts/validate-codex-runtime-sections.sh && bash scripts/lint-codex-native.sh - bash skills/heal-skill/scripts/heal.sh --strict - PRE_PUSH_SKIP_MKDOCS=1 bash scripts/pre-push-gate.sh --fast MkDocs strict remains skipped locally via the documented PRE_PUSH_SKIP_MKDOCS=1 override because the repo currently emits repo-wide strict-link warnings unrelated to this landing; CI remains authoritative. |
||
|
Bo
|
419bda7532 |
feat(memory): classify bd remember notes (ag-u1zi) (#745)
## Summary Implements ag-u1zi W4.1: a deterministic classifier for migrating `bd remember` notes into the memory architecture without promoting bead-local operational chatter into pull-learning memory. Changes: - adds `scripts/classify-bd-remember.py` with JSON/markdown output, `--input`, `--expected-count`, and `--generated-at` options - adds fixture and Bats coverage for classification coverage, lineage preservation, markdown manifest, and expected-count mismatch - adds `docs/contracts/bd-remember-migration-manifest.md` plus documentation-index entry Classification policy: - `bead`: bead-linked, session-local, one-off, or tracker-operational notes - `pull-learning`: reusable project learning candidates, emitted as `reach=pull`, `maturity=provisional`, `source=migrated-bd-remember` - `discard`: empty/stale/deprecated/obsolete notes Dolt/bd caveat: `bd update ag-u1zi --claim` and `bd ready` are failing via the known Dolt/MySQL write/read path (`context canceled` / invalid connection), so claim/provenance is recorded in Agent Mail rather than bd state. ## Validation Focused: - `bats tests/scripts/bd-remember-classifier.bats` PASS - `python3 -m py_compile scripts/classify-bd-remember.py` PASS - `bash scripts/check-contracts-structural-floor.sh` PASS after indexing the new contract doc - `git diff --check` PASS Required push path: - `bash scripts/regen-all.sh` ran; failed only known CMDAO surface parity red, timestamp-only `registry.json` drift reverted - `PRE_PUSH_FAIL_FAST=false bash scripts/pre-push-gate.sh` completed with the known red set: 4 failures (`test-fixture parity`, canonical-root worktree disposition, corpus freshness, contract canary pre-push-governance); no observed diff-caused failure ## Review Request Requesting cross-model ACK before merge. Do not merge unless PR checks reach CLEAN and quorum is satisfied. Closes-scenario: ag-u1zi Bounded-context: BC1-Corpus Validation-evidence: classifier script + Bats coverage; see Validation section above. |
||
|
Bo
|
b8731a4378 |
docs(audit): remediate stale root + key docs — hookless refs, skill counts, retired CI jobs (ag-lk80 #staleness-fixes) (#705)
## What Remediates verified staleness from the 2026-06-03 doc audit of root governance/product docs + the key `docs/` cluster. Two systemic rot patterns drove almost every finding: **skill-count drift** (73/78/~80 vs truth 82) and **hooks references that survived the 3.0 hookless teardown**. All fixes independently verified against `cli/**`, `scripts/**`, `.github/workflows/validate.yml`, and `skills/**`. ## Changes (by bead) | Bead | Sev | Fix | |---|---|---| | ag-swi1 | CRIT | `newcomer-guide.md`: removed hooks-as-runtime-layer framing (3.0 ships zero hooks); 5→4 layers; fixed dead `scripts/install-dev-hooks.sh` ref; reframed hooks as opt-in via `hooks-authoring` skill | | ag-99xv | CRIT | `index.md`: skill count 73→82. **The "broken catalog link" was a false positive** — `docs/skills/catalog.md` is generated at build by `gen_skill_pages.py`; link left unchanged | | ag-xa2b | CRIT | `cli-skills-map.md`: removed 5 phantom skills (`pr-plan`, `pr-retro`, `update`, `readme`, `oss-docs`) an agent could mis-invoke. Deep hooks-decoupling of this file (title, "Hook Callers" column, "Hooks → Commands" section) **decomposed to a follow-up** — half-editing leaves it internally inconsistent | | ag-w4t8 | CRIT | `AGENTS-CI.md`: dropped retired advisory rows `practice-citations` (RETIRED 2026-05-19) and `factory-claim-ledger-strict` (no such job; references nonexistent file) | | ag-bcl4 | HIGH | `index.md` + `documentation-index.md`: counts → 82, **and extended `sync-skill-counts.sh`** to cover both call-sites so the count self-heals and CI (`validate-doc-release.sh` → `sync --check`) catches future drift — the durable fix, not just retyping the number | | ag-p7zg | HIGH | `CLAUDE.md`: aligned Ship-phase pre-push command to `scripts/pre-push-gate.sh --fast`, matching `AGENTS-WORKFLOW.md` | | ag-y5ii | MED | `documentation-index.md`: dropped stale "hooks" from the how-it-works description | ## Deferred (filed as follow-up beads, not in this PR) - PRODUCT.md "April 2026 Claude Code source analysis" reframe — product positioning, operator's call - Full hooks-decoupling of `cli-skills-map.md` — structural rework, needs its own verification - `bd worktree create --branch` syntax is wrong in CLAUDE.md/AGENTS-WORKFLOW.md (needs a positional name) — discovered this session - `validate-bd-closeout-contract.sh` requires `bd dolt push` conditional wording in AGENTS.md that the AGENTS split dropped (pre-existing main red, local-only gate) - Second-wave sweep of the remaining ~80 `docs/` files (ag-bz8n) ## Verification - `scripts/sync-skill-counts.sh --check` → clean (both new call-sites covered) - `scripts/validate-cli-skills-map.sh` → PASS - `tests/docs/validate-doc-release.sh` → PASS - No residual `hooks/` / `hooks.json` runtime refs in `newcomer-guide.md` - All referenced paths exist (`skills/hooks-authoring/`, `scripts/pre-push-gate.sh`) Closes-scenario: ag-lk80#staleness-fixes Bounded-context: BC1-Corpus Evidence: docs/index.md |
||
|
Bo
|
37c86dc282 |
docs(doctrine): re-narrate out-of-session substrate Gas City → NTM+MCP+managed-agents (ag-vg40 #substrate-renarration) (#676)
## What The **doctrine slice** of the ACFS-prune (operator-authorized 2026-06-02). Re-narrates AgentOps's out-of-session story. **Kept (the sovereignty floor — unchanged):** AgentOps = the in-session loop + compounding context; ships no daemon/scheduler/overnight-runner; delegates out-of-session execution to a *swappable substrate*. The in-session/out-of-session boundary and the "substrate owns when/where/who-supervises/coordination" split stay. **Changed (the reference substrate):** Gas City → the adopted ACFS trio — **NTM** (local tmux swarm) + **MCP** (`ao mcp serve`, shipped) + **managed-agents** (`ao agent`). "AgentOps IS a Gas City reference config" → "AgentOps adopts NTM+MCP+managed-agents; it still owns no core, it just doesn't own or reference Gas City." This is the deep-dive's "adopt the substrate, don't own it." ## Changes (7 files, +25 / −120) - `docs/3.0.md` — substrate table row; replaced the "Gas City reference City" section with "Running the loop out of session" (the three substrate options); Olympus comparison rows; sovereignty-floor line - `docs/architecture/canonical-loop-model.md` — Factory-driver framing, ASCII diagram, boundary table, dispatch paragraph - `docs/cdlc.md`, `docs/architecture/fungibility-charter.md` — substrate one-liners - **deleted** `docs/architecture/gc-posture.md` + reconciled its 4 inbound links (both index files, documentation-index, fungibility-charter) ## Scope boundaries - **ADR-0009 left historical** — decision records are immutable; it records the *then*-rationale. - **`thesis-stability` not tripped** — that gate guards the product thesis (README/PRODUCT/GOALS), not the substrate detail. (Its current FAIL is pre-existing README/PRODUCT/GOALS tagline drift, unrelated to this PR.) - **Follow-up `ag-124p`** (separate PR): the code/config strip — `packs/agentops` + `city.toml` + `skills/using-gc` + `cli/hooks/claude.json` gc-wiring. ## Note This is outward-facing doctrine — opened for your review rather than auto-merged. PR #5 this session; you authorized continuing past the scope ceiling for the prune. Closes-scenario: ag-vg40#substrate-renarration Bounded-context: BC1-Corpus Evidence: docs/3.0.md |
||
|
Bo
|
efb7fd66e9 |
feat(ci): repo-wide path-filter/gate-target coverage audit + gap fixes (ag-g9ex #pathfilter-audit) (#666)
## What Repo-wide audit of every file-reading CI gate in `.github/workflows/validate.yml` against the invariant the #634/#638 trunk-heal proved: **a gate that READS a file must be TRIGGERED by a path-filter covering that file.** A docs-thinning commit (`bbfd278e`) silently disabled the security redteam canary because the `contracts` filter didn't cover `AGENTS.md`, and it surfaced only on a later unrelated PR. Closes **ag-g9ex** (Slice5[GOVERNANCE]). Derived from `.agents/retro/2026-05-31-bead-crank-postmortem.md` §4(#2) + §7(#5). ## Audit `docs/contracts/ci-pathfilter-coverage-audit.md` enumerates every gate that reads specific files, the files it reads, the filter(s) that trigger it, and a COVERED/GAP verdict. 13 gates audited + verified non-findings. ## Gaps found and fixed (2) 1. **AGENTS tiered-split siblings uncovered (direct #634 class).** `scripts/validate-agents-split.sh` validates `AGENTS.md` + `AGENTS-{WORKFLOW,CI,CODEX,RUNTIME}.md`, but the gate triggered on `docs/ci/shell` and the four siblings were covered by **no** consumed filter. A sibling-only edit would skip the split gate. **Fix:** added the siblings to the `contracts` filter + `contracts` to the gate trigger (mirrors #638). 2. **wiring-closure not re-triggered by GOALS.md de-wire.** `scripts/check-wiring-closure.sh` greps `GOALS.md`/`GOALS.yaml` to confirm every `check-*.sh` is referenced, but triggered on `go/hooks/shell/ci` — not `goals`. A GOALS.md-only de-wire would skip it. **Fix:** added `goals` to the gate trigger. ## Governance (--admin self-merge, §7 #4) Documented as policy in the audit doc rather than shipped as a half-working CI gate (GitHub Actions cannot observe `--admin` from inside a `pull_request` workflow; building a fake gate would be over-engineering against the bead's explicit guidance). Mechanical enforcement filed as a follow-up. ## Guard test Extended `tests/scripts/test-pathfilter-gate-coverage.bats` (the #638 guard) with 3 new assertions: AGENTS-split targets ⊂ `contracts`, split gate triggers on `contracts`, wiring-closure triggers on `goals`. All 10 tests pass. ## Gates run (local) - `python3 yaml.safe_load(validate.yml)` → VALID - `bats test-pathfilter-gate-coverage.bats` → 10/10 ok - `scripts/check-contracts-structural-floor.sh` → PASS (46 contracts) - `scripts/validate-ci-policy-parity.sh` → PASS (11 rows) - `git diff origin/main --stat` → scope-only (4 files) Closes-scenario: ag-g9ex#pathfilter-audit Bounded-context: BC2-Validation Evidence: docs/contracts/ci-pathfilter-coverage-audit.md |
||
|
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 |
||
|
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 |
||
|
Bo
|
cfaeb356a9 |
docs(spike): characterize Dreaming/memory writers + Anthropic export shape (ag-cj8mk #dreaming-characterization) (#643)
Spike **ag-cj8mk**: characterizes the three foreign Dreaming/memory
writers and the Anthropic Dreaming export shape, to unblock the
Dreaming→corpus converter family (ag-5vozd / ag-5lllu / ag-8lyx5 /
ag-onf37).
Deliverable: a tracked contract/decision doc (`.agents/` is gitignored
in this repo, so spikes that unblock later work persist under
`docs/contracts/`).
## What it characterizes
- **Anthropic Dreaming (Managed Agents):** `POST /v1/dreams` (`drm_...`)
async job → output **memory store**; notes read via Memory Stores REST
(`memories.list`/`retrieve`) as `{path, content (freeform markdown),
content_sha256}` + immutable `memver_...` versions. **Go/no-go verdict:
GO — stable REST pull**, not opportunistic SSE capture (`content_sha256`
is the dedup/high-water key). SSE is an optional live-progress view
only.
- **OpenClaw memory-wiki indexer (bushido):** chunk+embedding SQLite
(`main.sqlite`) over source `~/wiki`/memory markdown; cron is empty
post-retirement. Does not touch `.agents/`.
- **Local gc-dream / T3 synthesis (bushido, retired):** dream-draft
front-matter markdown + scored T3 verdict JSON. Does not touch
`.agents/`.
- **Normalized target:** `.agents/learnings/*.md` (Lesson Format) via
`ao corpus capture` — current flag surface + the `--source` delta
(ag-onf37).
## Load-bearing constraint
**Managed Agents are NOT ZDR.** Dream/session transcripts + memory
versions are retained server-side, so holdout/eval ground-truth and PII
must NEVER reach the cloud feeders. The converter + leak guard (ag-5vozd
/ ag-onf37) enforce refuse-to-persist on the `ao corpus capture` write
path; nightly CI is the backstop. The doc characterizes SHAPES only — no
holdout/eval/PII content.
## Verification
- `scripts/check-contracts-structural-floor.sh` → PASS (45 contracts)
- `git diff origin/main --stat` → scope-only (new contract + 1 index
line)
Closes-scenario: ag-cj8mk#dreaming-characterization
Bounded-context: BC1-Corpus
Evidence: docs/contracts/dreaming-writers-characterization.md
|
||
|
Bo
|
49562ffc0b |
docs(agent-native): decision doc mapping Managed Agents + Agent SDK to the hookless waist (ag-uphk9 #agent-native-mechanism) (#631)
## What Spike output for **ag-uphk9** — a committed decision doc, `docs/contracts/agent-native-mechanism.md`, that nails the mechanism by which an out-of-session Claude/Codex loop stays under AgentOps guardrails **without hooks**. Documents the **as-built** mechanism (the `/agent-native` skill #616, `ao agent bundle` #618, `ao mcp serve` #619/#621, `agent-output-validate.yml` #617), not design-ahead. ## Deliverables (per the bead) - **Hook-intent → hookless mapping table** — orientation / standards / scope-guard / commit-review / holdout-isolation, each → a skill + an `ao` subcommand + a CI job. Two columns throughout: **Claude** (Managed Agents / SDK / MCP-`ao`) and **Codex/NTM** (shell-`ao` / tmux / `ssh bushido`). Confirms **zero hooks required**. - **Managed-Agents Agent shape** (`model` / `instructions` / `tools` / `skills`) + **self-hosted bushido sandbox** declaration reaching the in-boundary `ao` over MCP + Dolt over tailnet (`100.109.17.108:3306`). - **Agent SDK hooks** (PreToolUse/PostToolUse/Stop/SessionStart) scoped strictly as the **OPTIONAL adapter** (wiring in `skills/agent-native/references/sdk-hook-adapter.md`) + a one-paragraph "why CI is the default gate, not these hooks". - **Explicit non-goals**: no marketplace-hook port; eval substrate (`~/.agents/evals/SCHEMA.md`) untouched; holdout/eval corpus excluded from hosted bundles (Managed Agents are **not** ZDR). ## Why this is bounded + safe One new contract doc + one index link. No CLI/skill/Go surfaces touched → no regen/build needed. No holdout payload, no out-of-repo contract dependency. Unblocks the heavier (operator/ops-gated) managed-dispatch + grader slices by fixing the mechanism first. ## Validation - `check-contracts-structural-floor`: **PASS (44 contracts)** — the new contract recognized + linked. - Catalogued in `docs/documentation-index.md` (contract-catalogue gate). - All relative links verified to resolve (`/agent-native` skill, sdk-hook-adapter ref, sibling contracts, `agent.go`/`mcp_serve.go`, `agent-output-validate.yml`). - Scope: 2 files, +102 insertions, zero deletions. Closes-scenario: ag-uphk9#agent-native-mechanism Bounded-context: BC5-Runtime Evidence: docs/contracts/agent-native-mechanism.md |
||
|
Boden Fuller
|
bbfd278e32 | docs(agents): thin root context into lean routers + on-demand workflow reference | ||
|
Bo
|
0f16a574bc |
feat(eval): outcomes-rubric projection contract + schema (ag-hguuf #outcomes-rubric) (#624)
## What
Defines the machine-checkable contract for projecting the **locked eval
substrate** into an **Outcomes-style grading payload** (Anthropic
Managed Agents Outcomes analog) — holdout-safe by construction *and* by
schema.
The schema validates the **actual** output of `ao eval outcomes compile`
(`evalsubstrate.Rubric`), not the bead's pre-implementation prose sketch
(which imagined `suite_id`/`metric`/`decision_rule`/`split`). Per
source-of-truth precedence (executable > narrative), the shipped
projection deliberately emits *fewer* fields — a smaller cloud boundary
is a smaller leak surface. The "deliberately NOT projected" rationale is
documented in the contract.
## The load-bearing invariant
**Managed Agents are not ZDR** — a rubric crossing the cloud boundary
must never carry a ground-truth answer / holdout value / `target` /
`expected_output`. Enforced three ways:
1. **By construction** — `ProjectRubric` can't copy ground truth
(existing).
2. **By re-scan** — `Rubric.ContainsAny` guard (existing).
3. **By schema (this PR)** — `additionalProperties:false` at **every
nesting level** → a malformed compiler emission that smuggles a leak
field **fails schema validation**, not merely a code check.
## Files
- `schemas/outcomes-rubric.v1.schema.json` — the contract schema
-
`tests/fixtures/outcomes-rubric/{valid-dev,valid-holdout-criteria-only,invalid-contains-target}.json`
- `scripts/validate-outcomes-rubric.sh` — standalone validator (python
`jsonschema`, mirrors `validate-next-work.sh`); `--selftest` asserts
pass/pass/fail
- `tests/scripts/validate-outcomes-rubric.bats` — 9 acceptance tests
- `cli/internal/evalsubstrate/rubric_schema_test.go` — Go schema↔struct
drift guard (reflection)
- `docs/contracts/outcomes-rubric-projection.md` —
SCHEMA-field→Outcomes-field mapping; catalogued in doc index;
cross-linked from `eval-verdict-pipeline.md`
The contract **references** the LOCKED `~/.agents/evals/SCHEMA.md`
§rc2/§4 — it never edits it. Substrate EXTENDED, never relitigated.
## Evidence
- `scripts/validate-outcomes-rubric.sh --selftest` → PASS/PASS/FAIL
(exit 0)
- `bats tests/scripts/validate-outcomes-rubric.bats` → 9/9 ok
- `go test ./internal/evalsubstrate/` → 82 passed; `go vet` clean; `go
build ./...` success
- `check-contract-compatibility.sh` → contract catalogued + schema
reference OK
- `shellcheck scripts/validate-outcomes-rubric.sh` → clean
Closes-scenario: ag-hguuf#outcomes-rubric-projection-contract
Bounded-context: BC4-Evaluation
Evidence: schemas/outcomes-rubric.v1.schema.json
|
||
|
Bo
|
fe731d12b9 |
feat(skills): skill-flow connectivity gate + closed consumes vocabulary (#597)
## Do all skills flow together? **No — not until this PR.** Investigating the question surfaced a structural gap: skill dependencies are declared across **three overlapping frontmatter fields that drifted apart and were never reconciled**, and nothing enforced connectivity or constrained the `consumes` vocabulary. | Field | Meaning | Read by context-map? | |-------|---------|----------------------| | `consumes` | upstream inputs | yes (data-flow table) | | `context_rel` | DDD relationship | yes (mermaid) | | `metadata.dependencies` | upstream skill slugs | **no** | Findings (76 skills): - **33 skills** where `consumes` (skills) ≠ `metadata.dependencies` — the two skill-slug fields disagree. - The generated `context-map.md` **ignored `metadata.dependencies` entirely** (34 skills, the richest layer). - Counting all three layers, **16 true orphans** (incl. core skills like `push`, `session-bootstrap`) with zero skill-to-skill edges — silently. - `consumes` was an **open free-text field**: no check that a token resolves to anything. `scripts/audit-skill-metadata.sh` already flagged the `consumes`-vocabulary and connectivity checks as *"discovered follow-ups, not enforced."* This is that follow-up. ## What this PR does **1. Connectivity gate** — `scripts/validate-skill-flow.sh` (+ `validate-skill-flow` CI job): - **Closed `consumes` vocabulary**: every token must resolve to a skill slug, a whitelisted external input (`repo-context`, `external-api`, `bd`, `github-pr`, `onboard`), or an artifact some skill produces. Catches typos/undeclared deps. - **`metadata.dependencies` resolution**: every entry must name a real skill. - **Orphan detection** across all three edge layers; un-allowlisted orphans fail. - Reports (non-fatal): cross-layer disagreement + dead-end artifacts, so they can be reconciled later. **2. Wire the genuine-gap edges** — added `context_rel` for 6 disconnected skills and regenerated `context-map.md`: - `deps` → `vibe`, `red-team` → `vibe` (mirrors `security`/`security-suite`) - `provenance` ↔ `trace` - `scenario` → `validation` - `release` → `ship-loop` **3. Close the vocabulary** — the closed `consumes` namespace is enforced by the gate and documented in `docs/contracts/skill-flow.md` (linked in `documentation-index.md`). 14 intentionally-standalone leaves are allowlisted in `scripts/skill-flow-standalone.txt` with a rationale per entry. ## Verification ``` $ bash scripts/validate-skill-flow.sh validate-skill-flow: 76 skill(s), 121 skill-to-skill edge(s) orphans: 14 (allowlisted standalone: 14) OK: skill flow is connected and the consumes vocabulary is closed. ``` - `validate-skill-flow.sh`: exit 0 ✅ - `validate-context-map-drift.sh`: exit 0 ✅ - `check-contracts-structural-floor.sh`: PASS (contract cataloged) ✅ - 11 acceptance tests in `tests/scripts/validate-skill-flow.bats` (bats not installed locally; exercised via manual smoke + will run in CI `bats-tests`). Bounded-context: BC1-Corpus Evidence: OK: skill flow is connected and the consumes vocabulary is closed. --- _Generated by [Claude Code](https://claude.ai/code/session_01WLdHEva31cixBjxo8z9TXK)_ Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Bo
|
e4e32a3374 |
feat(orchestration): dual-runtime OrchestrationPort foundation (ag-nk67 #orchestration-foundation) (#598)
## What
The **dual-runtime OrchestrationPort foundation** — the seam that gates
the
`[EPIC] AgentOps × Claude Managed Agents integration (dual-runtime)`
application epics.
Implements the 3-category model (Claude Workflow / NTM swarm / plain
skill) behind a
single `OrchestrationPort` with safe degradation **NTM → Claude-native →
beads floor**
and a global `AGENTOPS_ORCHESTRATION=off` opt-out.
Derived from a live 3-legged spike (`~/dev/agentops-3cat-spike/`): safe
degradation is
solvable at the selection layer; parallel buys quality/independence not
wall-clock at
small N; NTM is a multi-vendor control plane that runs Claude/Codex as
panes.
## What's in it (10 slices, agent-team driven)
- **Port + adapters** — `cli/internal/ports/orchestration.go` (idiomatic
to existing ports pattern) + new `cli/internal/orchestration/` pkg:
`Selector`, `ntm_probe` (capability detection via `ntm
--robot-capabilities`, not `command -v`), `beads_floor` +
`OrchestrationResult` parity type, degradation-conformance test.
- **Live CLI** — `ao orchestrate select` (`--pin`/`--opt-out`/`--json`);
COMMANDS.md regenerated.
- **Contracts** — `schemas/orchestration-{backend,result}.v1` + paired
`docs/contracts/` docs (structural-floor gated: 41 contracts).
- **Prose** — swarm/shared/crank rewritten NTM>native>beads; **gc
demoted** (soc-2rtm0); `rpi_phased_stream.go` doc-comment fixed.
- **Skills** — `automation-shape-routing` (the 3-category router) +
`workflow-builder` + meta-skill authoring chain wired (`context_rel`);
skill counts synced.
- `lib/orchestrate-select.sh` selector seam.
## Verification (local)
`go build ./...` clean · `go vet` clean · **56 Go tests pass**
(orchestration 31, ports 10, cmd/ao orchestrate 15) · structural-floor
PASS (41) · `lib/orchestrate-select.sh --self-test` 6/6 · live command:
`--json`→claude (NTM absent), `--opt-out`→beads, `--pin claude`→claude.
## Notes
- Bundles the foundation + the routing/authoring skills as one coherent
dual-runtime arc.
- NTM/Claude executors are stubs (the parity contract is real); concrete
executors land in the application epics this gates.
- Two-ladders distinction preserved (spawn-backend ladder A vs CLI
phase-executor ladder B) — see `docs/contracts/orchestration-ports.md`.
Closes-scenario: ag-nk67#orchestration-foundation
Bounded-context: BC5-Runtime
Evidence: cli/internal/orchestration/conformance_test.go
|
||
|
Bo
|
9e9caccb49 |
docs(architecture): GC is an adapter behind AgentOps ports (soc-7blko #gc-posture) (#574)
## Summary Adds the canonical **GC posture / boundary doc** — the page a one-liner like "Gas City is the reference substrate" points at. - `docs/architecture/gc-posture.md` (new): states GC is **one opt-in, swappable adapter behind AgentOps's ports** (not the runtime AgentOps runs inside); the hexagon points the right way — AgentOps core owns the ports, GC satisfies the out-of-session Factory-driver role. - **Guardrail (hard limit):** never register AgentOps state (corpus, bd/Dolt, ratchet) as a **GC-managed-city resource**; rationale = the Olympus ~**1,478**-flap incident (attributed as the stated Olympus rationale, not an AgentOps-measured in-repo metric). - **Sovereignty:** GC is local/self-hostable; AgentOps-on-GC preserves **"no cloud required."** - Registered in `docs/documentation-index.md` and the `docs/architecture/index.md` grid. Built as a non-nav architecture page like its siblings `canonical-loop-model.md` / `operating-loop.md` (mkdocs `--strict` green). ## Scope Docs-only, single coherent arc (`docs/**` + `tests/**`). No `cli/**`, no skill changes, no release edits. Single squash-revert rollback. ## Test plan - [x] `bats tests/scripts/test-gc-posture-doc.bats` — written first (failed for the right reason: doc absent), now green (6/6). Asserts adapter-behind-ports, opt-in + swappable, the managed-city guardrail + `1,478`, the `no cloud required` + self-hostable/local sovereignty line, and the documentation-index link. - [x] `mkdocs build --strict` — passed. - [x] `ao autodev validate --file ../PROGRAM.md --json` — `valid: true`. Closes-scenario: soc-7blko#gc-posture Bounded-context: BC2-doctrine Evidence: tests/scripts/test-gc-posture-doc.bats |
||
|
Bo
|
8af560f678 |
fix(ci): reconcile hookless gates and flywheel snapshot
Squash merge PR #546. Local evidence: doc-release, smoke, snapshot gate, pre-push Bats, snapshot Bats, structural gates, and pre-push --fast passed. PR GitHub Actions were blocked in runner setup by GitHub codeload/action download failures before repository code executed. Snapshot records current corpus as DECAYING rather than preserving stale compounding evidence. |
||
|
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 |
||
|
Bo
|
e90d6d79f9 |
feat(registry): SKU capability catalog (schema v2) — generated skill×command×BC join (ag-cbm) (#525)
## What Extends `registry.json` into a **generated SKU capability catalog** (schema_version 2) — the flagship 3.0 inventory feature. It is a 4th DERIVED projection (alongside DDD-vocab / Hex-frontmatter / Gherkin-acceptance), a JOIN of existing sources — **never hand-authored** (repo bans hand-edited inventory maps). Oracle-validated design: `.agents/discovery/2026-05-24-capability-inventory-and-gaps.md`. ## Catalog 214 SKU entries: **81 skills + 66 cli-commands + 64 gates + 3 reference-impls**. Each entry: `sku` (stable id), `name`, `type`, `bounded_context`, `hex_role`, `tier`, `purpose`, `status` (active | deprecated | planned | alias-of:<sku>), `disposition`, `consumes`, `produces`, `drives_commands`, `driven_by_skills`. `registry.json` schema v2 is a strict **superset** of v1 — existing `summary`/`surfaces`/`cadence_recommendations` consumers (the Go `ao registry` command) keep working; new `capabilities`/`capability_summary`/`cli_top_level_commands` blocks are added. ## The join key — `drives_commands` Derived from each skill **BODY** (SKILL.md + `references/*`), resolved against the live cobra tree (`scripts/lib/sku_extract.py`). Stale refs that resolve to nothing (e.g. the removed `ao schedule`) never become edges. `driven_by_skills` is the cmd→skill reverse. This closes oracle gap #1 (no skill↔command linkage anywhere). ## New gate — `validate-sku-catalog-drift` Three required checks: **(a) drift** (regenerate + diff), **(b) linkage integrity** (every `drives_commands` edge resolves to a real `ao` command — closes gaps #1/#2/#3), **(c) coverage** (every BC + every operating-loop move has an active skill; every BC has a cli-command). Wired into `validate.yml` + the verdict aggregator. ## Stale refs fixed `ao schedule` in `skills/crank` + `skills/rpi` best-practices and `agentopsd` in `skills/swarm` shared-checkout-discipline → reframed to the hookless / out-of-session (cron-driven `ao rpi`/`ao evolve` via Gas City) model. Disjoint from PR #524 (which fixed the hooks/inject refs); rebased on it — `validate-skill-cli-snippets.sh` is now 0. ## Retired The bogus "163 cli_commands" count (Go-file count, oracle gap #6) → **66 real top-level cobra nodes** from the live tree. ## Gates (all green locally) registry-check · validate-sku-catalog-drift (3/3) · validate-context-map-drift · skill-domain-map-golden · bounded-contexts-drift · codex-parity-drift · regen-codex-hashes --check · contract-compatibility (sku-catalog.md catalogued) · doc-release · validate-skill-cli-snippets (0) · skill-frontmatter · heal --strict · markdownlint (0) · shellcheck (0 errors) · mkdocs --strict · `go test ./cmd/ao` (9207) · new bats suite (5/5). Closes-scenario: ag-cbm#sku-catalog Bounded-context: BC1-Corpus Evidence: .agents/discovery/2026-05-24-capability-inventory-and-gaps.md |
||
|
Bo
|
ad69fec1d7 |
feat(skills): using-gc agent guide + complete tool-dependency declaration (ag-p4p) (#523)
## What
Builds the GC on-ramp for AgentOps 3.0: a `using-gc` skill that guides
agents on the `gc` (Gas City) CLI exactly like the `bd` protocol guides
them, plus a complete, accurate tool-dependency declaration. **Additive
— no existing behavior changed.**
THE MODEL (operator): "use gc like we use bd" — skills GUIDE agents on
the gc workflow; `ao` does NOT wrap gc. gc is a guided out-of-session
dependency, same as bd.
## Changes
1. **New skill `skills/using-gc/`** — agent-facing guide to running
AgentOps on Gas City, mirroring the bd-protocol style. Covers the gc
primitives (City/`city.toml`, Rig, Pack, Agent, Order, Formula, mayor +
refinery), the end-to-end workflow (`gc start` → `gc rig add` → the
mayor-driven dispatch loop: `bd ready` → `gc sling <rig>/refinery
<bead>` → worker runs `ao rpi <bead>`), cron `exec` Orders for
maintenance (`ao compile`/`ao maturity`), and is HONEST about the
order-auto-dispatch gap (no per-fire var-binding → dispatch is
mayor-driven today; order-auto-dispatch is an upstream-GC item,
soc-5jwah). References the real pack at `packs/agentops/` and
`docs/3.0.md`. Two reference docs + a `.feature` (linked +
`@covered-by:` a new bats test).
2. **Complete dependency declaration** — derived from `ao doctor` tool
checks (`ao`, `awk`, `bash`, `bd`, `cass`, `gc`, `git`, `tmux`) +
`scripts/install*.sh` + the shared fallback table. Classified REQUIRED
(ao, git, runtime), TRACKING (bd + Dolt), ORCHESTRATION (gc,
out-of-session), PR/CI (gh), BUILD-FROM-SOURCE (go), UTILITIES (jq, rg,
curl, openssl, sha256sum, tmux, cass). Landed in: `docs/dependencies.md`
(canonical detail, catalogued in documentation-index), a README
"Requirements" section (summary), and the expanded
`skills/shared/SKILL.md` fallback table (now includes gc, gh, go, jq,
rg).
3. **Fixed stale `using-agentops/SKILL.md:212`** — the runtime-mode `gc`
row described the DELETED `runtime=gc` auto-executor ("ao rpi
auto-selects gc executor", "gc event bus"). Reframed to the mayor-driven
reference City: gc dispatches whole `ao rpi`/`ao evolve` loops; there is
no in-CLI `runtime=gc` mode.
4. **Brief gc pointer** in repo `CLAUDE.md` + `AGENTS.md` near the bd
section, pointing to the using-gc skill (no skill content duplicated).
## Gates (all green locally)
- `sync-skill-counts.sh`: 80→81 total, 9→10 internal — PASS, verified
consistent.
- `validate-context-map-drift`: regenerated
docs/contracts/context-map.md — matches.
- Codex twin `skills-codex/using-gc/` created (`$skill` notation, no
Claude primitives); registered across the 4 catalog surfaces;
`regen-codex-hashes.sh` clean; `audit-codex-parity` PASS; 81 codex
artifacts.
- `generate-registry.sh` (81 skills) — up to date.
- skill-domain-map disposition added (BC5 Runtime) + regenerated golden
— matches; registry-drift narrative counts fixed (80→81).
- plugin-load-test (no symlinks — references copied), skill-schema
(81/81), skill-frontmatter (81/81), skill-dependency-check, heal.sh
--strict (clean), scenario-test-linkage (PASS, new .feature linked via
bats), markdownlint (0 errors), doc-release-gate (PASS).
- New bats test `tests/scripts/using-gc-skill.bats` (5/5).
- Codex description aggregate budget bumped 2700→2800 (catalog grew to
81; same precedent as the 2600→2700 bump when expert-council landed).
- `cd cli && go build && go vet && go test ./cmd/ao/` green (embedded
using-agentops copy synced via `make sync-hooks`).
Closes-scenario: ag-p4p#gc-onramp
Bounded-context: BC5-Runtime
Evidence: skills/using-gc/SKILL.md
|
||
|
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
|
||
|
Bo
|
52930e05ff |
docs(3.0): honest doctrine — AgentOps is in-session, GC/Olympus own out-of-session (#3.0-honest-doctrine) (#518)
Lands the honest AgentOps 3.0 doctrine so the repo's narrative matches the shipped code: the daemon is **deleted**, AgentOps is the **in-session** agent operating loop + context compiler, and out-of-session orchestration is delegated to a substrate (the reference **Gas City City** or **Olympus**). ## What landed - **`docs/3.0.md`** (north star, rewritten): in-session-only identity; honest GC reference-City section — dispatch is **mayor-driven** today, order-auto-dispatch is a labeled **GC-upstream maturity gap** (`soc-5jwah`), not turnkey; two reference implementations table (AgentOps-on-GC has **no** daemon; Olympus **kept** its daemon because it is a sovereign product); e2e-proof evidence cited. - **`docs/architecture/canonical-loop-model.md`** (new): one loop body, two drivers, one inner tick, one config. Evolve (in-session, AgentOps-shipped) vs Factory (out-of-session, substrate-owned); crank/swarm placed as in-session steps. - **`docs/adr/ADR-0009-daemon-deletion-in-session-only.md`** (new, Accepted): the daemon-deletion decision — DELETE-not-deprecate rationale (AgentOps has no core to protect; Olympus kept its daemon because it's sovereign), the rejected *deprecate-keep-standalone* alternative, the sovereignty tradeoff (always-on requires GC), the e2e GC dispatch gap. References `soc-j7a5q`. - **`skills/domain/references/`**: loop-family vocabulary (loop, evolve, factory, rpi, autodev, context-compiler) as 6 entries + INDEX rows + SKILL.md links. - **README**: "Two ways to use it" reframed to **in-session vs out-of-session**; deleted-command prose (`ao daemon` / `ao schedule` / `ao overnight`) reframed to in-session + GC reference. - **`packs/agentops`**: dispatch relabeled mayor-driven; order-auto-dispatch GC-upstream gap (`soc-5jwah`) called out in `bead-dispatch.toml`, `rpi-dispatch.toml`, and `FINALIZE-NOTES.md`. `gc config show --validate` still exits 0. - Reconciled stale `agentopsd` prose in `skills/scope` + `skills/session-bootstrap`. ## Gates - `heal.sh --strict`: clean - doc-release gate: succeeded (link validation PASS, 0 broken) - `gc config show --validate --city .`: exit 0 - markdownlint: 0 errors - `generate-registry.sh --check`: up to date - codex parity (domain): passed - `go build ./...`: success **Do not merge** — the operator reviews `docs/3.0.md` before tagging. Closes-scenario: soc-j7a5q#3.0-honest-doctrine Bounded-context: BC1-Corpus Evidence: .agents/discovery/2026-05-24-gvkj6-e2e-proof.md |
||
|
Bo
|
ee748d580d |
feat(rip)!: retire factory command + contract corpus (soc-2rtm0 #cascade-rip) (#512)
**Wave 1 of the orchestration-substrate cascade rip** (soc-2rtm0). The
full cascade (daemon + dream/overnight + schedule/plans/watch + gc-glue
+ factory) is ~50K LOC across deeply-entangled packages — far past one
reviewable PR. Per the bead's slice directive and the recon map's
serial-by-wave verdict, this ships as sequential PRs by wave. **This is
the factory wave** (the only cleanly-disjoint slice — no KEEP-feature
entanglement).
## What this retires (operator-confirmed FULL factory retire)
**Go command surface** (no external non-test caller — clean delete):
- `cmd/ao/factory.go`, `factory_admit.go`, `factory_pilot.go`,
`factory_admission_adapter.go` (+ all tests)
- `internal/ports/factory_admission.go` +
`inmemory_factory_admission.go` (+ test) — the port was only wired to
the daemon by the deleted production adapter
- severed factory flag save/restore + command-tree assertions from
`cobra_commands_test.go` / `testutil_test.go`
**Contract corpus** (scripts, schemas, contract docs, runbooks,
fixtures, tests):
- `scripts/check-factory-{admission,claim-ledger,yield-ledger}.sh`
- `schemas/factory-{admission,work-order,yield}.v1.schema.json`
- `docs/contracts/factory-{admission,claim-ledger,yield-ledger}.*`
-
`docs/runbooks/{factory-manual-merge,daemon-factory-admission,cloud-frontier-pilot}.md`
- `tests/e2e/factory-operator-canary.sh`,
`tests/integration/test-factory-claim-ledger-ci-job.sh`,
`tests/scripts/test-factory-admission-contracts.py`,
`tests/fixtures/factory-*`
- orphaned `aggregate-observation-log` subsystem (script + integration
test + fixtures) — its only data source was the deleted
`factory-claim-ledger-strict` CI job
**CI / generated reconciliation:**
- removed 3 factory jobs from `validate.yml` (+ both `needs:` arrays +
verdict echoes); removed entries from `ci-jobs.yaml`; regenerated
`AGENTS-CI.md` (63 jobs)
- removed factory gate-ids from `GOALS.md`; trimmed
`contracts-structural-floor` factory references
- regenerated `registry.json` (177→174 CLI commands), `COMMANDS.md` (−70
lines), `cli-skills-map.md` (73→72 headings)
- updated `cli-command-surface-matrix` canary spec + fixture counts
(`top=72 sub=194 all=266`); scrubbed deleted-file links from
`documentation-index.md`, `SCHEMAS.md`, `contracts/index.md`,
`agentopsd-control-plane.md`, `insert-schema-practices.py`
## Deliberately left for the daemon-carve wave
Daemon-owned factory job types (`factory.admission`,
`factory.local-pilot`) and the `agentopsd` routing-policy schema remain
— they belong to `internal/daemon/` and retire when the daemon does.
## Gates verified green locally
`gofmt`/`go build`/`go vet`, full Go test (**11830 pass**),
`validate-ci-policy-parity`, `contract-compatibility`,
`contracts-structural-floor`, `registry --check`, `doc-release` (0
broken links), `smoke-test`, `json-flag-consistency` (0 errors),
**`contract-canaries` (failures=0)**, codex-hashes, `pre-push-gate.bats`
(55).
Diff: 66 files changed, ~16 insertions / ~5680 deletions.
Closes-scenario: soc-2rtm0#cascade-rip
Bounded-context: BC5-Runtime
Evidence: .agents/discovery/2026-05-24-rip-caller-map.md
|
||
|
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 |
||
|
Bo
|
c012b6c1ee |
feat(bdd): scenario→test linkage runner + CI gate (soc-63xfx #scenario-test-runner) (#503)
## What Mechanizes the scenario→test linkage gap. 71 `.feature` files existed under `skills/*/references/` but only a handful had an executing test; the rest were unverified documentation. This adds a linkage **convention + checker + blocking CI gate** — a linkage check, not a full Gherkin step-interpreter (that scope was deliberately avoided per the bead's pragmatic-scope guidance). ## Convention `@covered-by:<test-path>[::<Name>]` Gherkin tag placed directly above a `Scenario:` (or above `Feature:` for file-wide coverage). Lightest convention that resolves "scenario X is covered by test Y" without maintaining a separate registry. The `::<Name>` form additionally asserts a named test (Go func / bats `@test` / bash func) exists in the file. ## Deliverables - **`scripts/check-scenario-test-linkage.sh`** — parses every `.feature` scenario, resolves `@covered-by` targets, and FAILS on: unlinked-and-unallowlisted scenarios, dangling links (missing path or named test), allowlist/tag conflicts, and stale allowlist entries. Flags: `--warn-only`, `--json`, `--help`. Exit 0/1/2. - **`scripts/.scenario-linkage-allow`** — 68 doc-only feature files, a *draining backlog* (drain as skills gain executing tests). The gate is real: a scenario not here and not tagged fails CI. - **Starter set** — `rpi`, `goals`, `scenario` features fully linked (11 scenarios) to their `tests/e2e/*` tests, proving the mechanism end to end. - **`validate.yml`** — `validate-scenario-test-linkage` T1 blocking job + summary `needs` + summary echo; manifest entry in `docs/contracts/ci-jobs.yaml` + regenerated `AGENTS-CI.md` table (parity gate green). - **`docs/contracts/scenario-test-linkage.md`** + `documentation-index.md` catalog entry. - **`tests/scripts/check-scenario-test-linkage.bats`** — 13 regression tests (pass/fail/warn/json/file-level-tag/misuse). Sibling to `executable-spec-link-integrity` (directive→scenario). Together they close the GOALS-directive → scenario → test evidence chain. ## Verification (all green) - `shellcheck scripts/check-scenario-test-linkage.sh` — clean - gate run locally — PASS (256 scenarios, 71 files; 11 linked, 245 allowlisted) - 5 failure paths manually exercised → exit 1; `--warn-only` → exit 0; misuse → exit 2 - `bats tests/scripts/check-scenario-test-linkage.bats` — 13/13 ok - `check-contracts-structural-floor.sh` — PASS (new contract catalogued) - `validate-ci-policy-parity.sh` — PASS (manifest + AGENTS table synced) - `validate.yml` + `ci-jobs.yaml` YAML parse OK - diff stat: +639/−2, all-additions, no collateral data loss Closes-scenario: soc-63xfx#scenario-test-runner Bounded-context: BC4-Evidence Evidence: scripts/check-scenario-test-linkage.sh |
||
|
Bo
|
c1a46cee26 |
chore: scrub all jsm references — external ref only, patterns kept (soc-wnic7 #scrub-jsm) (#501)
## What Operator directive (soc-wnic7): scrub ALL references to "jsm" from AgentOps. jsm was only an external reference corpus we learned patterns from. The absorbed **patterns stay** (skill-quality rubric, SELF-TEST shape, system-tuning methodology, bug-hunt patterns, attribution patterns, marketplace-export profile) — only the jsm **name**, jsm-dedicated docs, and jsm export tooling are removed. ## Deleted (8 files) - `docs/reference/jsm-agentops-gap-audit.md` - `docs/reference/jsm-clean-room-extraction-policy.md` - `docs/reference/jsm-cli-capability-map.md` - `docs/reference/jsm-pilot-upgrade-backlog.md` - `docs/reference/jsm-skill-absorption.md` - `docs/reference/jsm-skill-standards.md` - `scripts/check-jsm-export.sh` - `scripts/inventory-jsm-skills.sh` ## Renamed (kept methodology, stripped jsm) `skills/standards/references/jsm-attribution.md` → `external-source-attribution.md` (+ skills-codex + cli/embedded mirrors). The attribution methodology (Pattern A/B, choice rule, mkdocs constraint, clean-room hygiene) is a kept pattern — renamed and de-named rather than deleted, so the standards skill keeps a repoint target. ## Edited - De-catalogued the 6 deleted docs from `docs/documentation-index.md` and `docs/reference/index.md`; de-named the kept skill-quality-rubric entries. - Genericized every footer/credit per the scope rule: - `Adapted from jsm / \`x\`` → `Adapted from an external skill corpus / \`x\`` - `(jsm/ACFS skill corpus)` → `(ACFS skill corpus)` — **ACFS/gstack credits left intact** - jsm-only credits (system-tuning, hooks-authoring) → "external skill corpus", keeping the methodology-only/no-verbatim hygiene clause - Genericized: "JSM-Style/Marketplace Export Profile", hexagonal-map adapter node, domain-evolution BDD/plan gherkin steps, CHANGELOG entries, skill-auditor validation-terms tuple. - Removed dead `check-jsm-export` blocks from 4 SELF-TEST.md files. ## Regen + gates (all green) `make sync-hooks` · `regen-codex-hashes.sh` · `generate-registry.sh` re-run. Verified: `grep -ri jsm` empty (per exclusions); `regen-codex-hashes --check` OK; `generate-registry --check` OK; `validate-embedded-sync` in sync; `validate-context-map-drift` OK; `check-docs-learning-references` PASS; `heal.sh --strict` clean; `audit-codex-parity` PASS; `go build ./...` OK; no dangling punctuation; no broken links to deleted files. Closes-scenario: soc-wnic7#scrub-jsm Bounded-context: BC1-Corpus Evidence: docs/documentation-index.md |
||
|
Bo
|
3ac00e5337 |
docs(3.0): mark none-a-noise-injector met — 7 noise hooks deleted (soc-cul67 #hookless-docs) (#496)
## What Flips the docs/3.0.md **"Hooks audited for noise"** acceptance box from `[ ]` to `[x]`. The 7 noise-injector hooks were **deleted outright** across `soc-e2ju0` S1–S3 (they were value-negative: A/B Δ=0) — not flipped to opt-in. 46 hooks remain, all gates or bounded adapters, none a noise-injector. ## Changes - **docs/3.0.md** — acceptance box `[ ]` → `[x]`; note now states the 7 noise-injectors were deleted (S1–S3), 46 hooks remain. The "Every AgentOps bead worked or closed" box intentionally left `[ ]`. The doctrine "default install works with zero hooks" line and the S2–S5 follow-on note are untouched (S4 default-install is not done yet). - **docs/architecture/hook-noise-audit.md** — summary reframed: original 53-hook audit (14 gate / 25 bounded-adapter / 14 noise) → current 46-hook reality (20 gate / 26 bounded-adapter / **0 noise**). The 14 "noise" entries split into 7 true noise-injectors (deleted) + 7 conditional injectors (reclassified as gates). Noise-injector table → all 7 deleted with their stage; gates list 14→20 (`go-vet-post-edit` removed — it was deleted, not a surviving gate); bounded-adapters 25→26; resolution note replaces the pending follow-on. - **docs/3.0-readiness.md** — hooks box `[ ]` → `[x]`; net 4/6 → 5/6 boxes met; W3 row and remaining-work refreshed. - **docs/documentation-index.md** — audit one-liner refreshed (no longer implies noise-injectors exist). - **skills/hooks-authoring/SKILL.md** — added a hookless-first guardrail: hooks are gates/bounded-adapters, never noise-injectors. Codex artifact + manifest source_hash regenerated for this skill only. ## Gates (all green) - `validate-hooks-doc-parity.sh` — PASS - `validate-codex-generated-artifacts.sh` — PASS (was failing on the SKILL.md edit; fixed via scoped hash regen) - `check-codex-parity-drift.sh` — PASS; `audit-codex-parity.sh --skill hooks-authoring` — PASS - `markdownlint` on all 6 touched md — PASS - `heal.sh --strict skills/hooks-authoring` — clean - Deleted-hook grep on docs/3.0.md + docs/HOOKS.md — empty (only historical mentions remain in the audit doc) Closes-scenario: soc-cul67#hookless-docs Bounded-context: BC1-Corpus Evidence: docs/3.0.md |
||
|
Bo
|
ab1329137d |
docs(architecture): hexagon port-realness audit (soc-upwor #port-audit) (#485)
## What
Empirical ground-truth inventory of the AgentOps runtime hexagonal seam
(`cli/internal/ports` + adapters), taken 2026-05-23 against `main`.
Read-only analysis bead — adds one doc + one catalog line, NO code
changes.
Grounds the adapter backlog for epic **soc-zvhsl** so the
adapter-building beads (soc-rg5z0 WorkspacePort, soc-ebgjk TrackerPort,
soc-21mrg loop-state, soc-vzyhn corpus) execute against a precise plan.
Every claim cites a real `file:line`.
## Headline counts
- **26** declared port interfaces
- **18** have a real (non-in-memory) adapter
- **8** have no conforming adapter (in-memory-only or
signature-mismatched)
- **git: 35** direct `exec.Command("git", ...)` callsites; **bd: 10** —
reached without a port
## Key corrections to the prior survey
- The epic survey's "21 ports, only `storage_fs` is real" is **stale**:
26 interfaces, 18 real adapters (16 `production*` in `cmd/ao` from
compile-cycles 112/113, plus 3 in `cli/internal/wiki/`, plus
`storage_fs`).
- Required-7 (`check-hook-port-replacements.sh`): **3 real**
(EventBus/GateRunner/Harness), **4 in-memory-only**
(Closeout/ContextCompiler/SafetyPolicy/Workspace).
- `.agentops/loop-state.json` (cited in soc-21mrg) **does not exist** —
the real loop-state gap is the *frozen* RPI supervisor lane
(`rpi_loop_supervisor.go:1007-1139`); the evolve lane is already behind
the port.
- Corpus adapters are real but the **flywheel core**
(compile/mine/grow/defrag) bypasses them.
## Recommended adapter build order
1. WorkspacePort → `workspace_git` (soc-rg5z0, P1) — 35 git callsites,
port not even constructed
2. IssueTracker → bd adapter (soc-ebgjk, P1) — zero impls today; widen
to read paths
3. Corpus reader/writer adoption in flywheel core (soc-vzyhn, P2) —
migration not greenfield
4. Loop-state atomic adapter for the *live* lane (soc-21mrg, P2) —
resolve lane question first
Closes-scenario: soc-upwor#port-audit
Bounded-context: BC5-Runtime
Evidence: docs/architecture/hexagon-port-realness-audit.md
|
||
|
Bo
|
eacf6415d3 |
docs(3.0): 3.0-readiness level-set + update acceptance boxes (soc-hplds #w4-levelset) (#481)
W4 (final wave) of the 3.0 reconciliation. Honest level-set against docs/3.0.md after W0-W3. - **docs/3.0-readiness.md (NEW)** — wave-by-wave outcomes, box-by-box status, `ao goals measure` snapshot (**85.7%, 26/31**; both fails non-blocking: 1 infra-flake, 1 warn-only), named remaining work. - **docs/3.0.md** — acceptance boxes updated to true status: **4 of 6 met** (north-star-single-source, docs-match-reality, hexagon-complete, loop-executable); 2 open with tracking beads (hooks-none-noise → `soc-e2ju0`; every-bead → coherence/ledger beads remain). - documentation-index.md cataloged. The reconciliation met its mandate: **docs match reality, hexagon complete, hooks audited.** The 2 open boxes have named beads, not unknowns. NOTE: claude-review infra-red (weekly limit, resets May 25) — operator-authorized bypass when sole red. Closes-scenario: soc-hplds#w4-levelset Bounded-context: BC1-Corpus Evidence: docs/3.0-readiness.md |
||
|
Bo
|
5b4bad166a |
docs(architecture): hook-noise audit — classify all 53 hooks vs the 3.0 no-noise criterion (soc-6zihw #hook-noise-audit) (#480)
W3 of the 3.0 reconciliation. Classifies every hook against docs/3.0.md's *'hooks must not inject random noise'* criterion. **docs/architecture/hook-noise-audit.md (NEW):** 53 hooks → **14 GATE · 25 BOUNDED-ADAPTER · 14 NOISE-INJECTOR**. 39/53 (74%) already meet the 3.0 criterion. **Key finding:** the 14 noise-injectors push `additionalContext` into the prompt on every matching event regardless of relevance (standards-injector; commit-review-gate — misnamed, never blocks; edit-knowledge-surface; research/context nudges; …). All already honor per-hook disable flags but are on-by-default. Top-4 verdicts verified directly (grep: no deny/exit-2 + unconditional additionalContext), not just from the audit swarm. **Scope:** this PR is the **audit** (analysis). The behavior change — flipping the 14 to opt-in-default so the default experience is quiet — is **soc-e2ju0** (operator-confirmed audit-only here). W4 marks the docs/3.0.md acceptance box accordingly. NOTE: claude-review infra-red (weekly limit, resets May 25) — operator-authorized bypass when sole red. Closes-scenario: soc-6zihw#hook-noise-audit Bounded-context: BC5-Runtime Evidence: docs/architecture/hook-noise-audit.md |
||
|
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 |
||
|
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 |
||
|
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 |
||
|
Bo
|
5968234af9 |
feat(evolve): port mt-olympus guardrail substrate — mechanical pre-cycle halt gate + doctrine ADRs (soc-sfjx #substrate) (#399)
## Why `soc-g2qd` built six `/evolve` CLI primitives the skill never called; an unsupervised session then drifted for ~10h on green CI alone. Research (`.agents/research/2026-05-21-mt-olympus-evolve-loop.md`) showed mt-olympus runs the **same** `/evolve` skill non-stop (~245 cycles) because its guardrails are **mechanical** — a `halt-check.sh` that *runs before every cycle* — not prose the agent can skip. This ports that property to agentops. ## What changed | Surface | Change | |---|---| | `scripts/evolve/halt-check.sh` (NEW) | Mechanical pre-cycle gate: operator markers (KILL/STOP/DORMANT/HANDOFF) with soc-5qit non-sticky + TTL semantics, goal-regression (cycle-history `goals_passing` drop), prior-cycle-FAIL restorative signal. `--json` + human modes. shellcheck-clean. | | `skills/evolve/SKILL.md` Step 1 | **Wired**: replaces the 40-line inline marker block with `bash scripts/evolve/halt-check.sh` (graceful inline fallback for repos lacking it). Step 0 now reads `docs/adr`/`docs/decisions` doctrine each cycle. | | `docs/adr/ADR-0007`, `ADR-0008` (NEW) | Deterministic-no-self-stop + intelligent-agile operating-model doctrine, adapted to agentops conventions (numbered `docs/adr/`) from mt-olympus's `docs/decisions/` ADRs. | | `docs/documentation-index.md` | Catalogue ADR-0007/0008. | | `tests/scripts/evolve-halt-check.bats` (NEW) | L2: gate behavior (markers/TTL/regression/fail/auto-clear) **AND** proves SKILL.md actually invokes the gate. | ## Lessons from soc-g2qd applied (so this isn't a repeat) - **Adapt, not blind-copy:** halt-check reads agentops's existing `cycle-history.jsonl` schema (not mt-olympus's `cycle-*-report.json`); ADRs follow the `docs/adr/ADR-NNNN` convention (not `docs/decisions/`). Dropped `emit-cycle-report.sh` + `validate-cycle-closeout.sh` mid-build — agentops already has `scripts/evolve-log-cycle.sh`; parallel writers would duplicate infra. - **Wire + test the consumer:** bats test 1 fails if SKILL.md stops calling the gate — the orphaned-primitive regression guard the prior epic lacked. ## How tested - `shellcheck scripts/evolve/halt-check.sh` — clean - `bats tests/scripts/evolve-halt-check.bats` — 11/11 (incl. consumer-wiring proof) - `test-token-budgets.sh` — skills/evolve 9966 < 10000 (the Step 1 rewrite netted negative) - `markdownlint` ADR-0007/0008 — 0 errors Sibling pattern: mirrors mt-olympus `scripts/evolve/halt-check.sh` (priority-ordered marker/regression checks, `--json` contract), adapted to agentops markers. Fitness: evolve guardrails 0 mechanical → 1 enforced pre-cycle; tests 0 → 11 passing; skill budget 9989 → 9966. Closes-scenario: soc-sfjx#substrate Bounded-context: BC5-Runtime Evidence: scripts/evolve/halt-check.sh |
||
|
Bo
|
f7cc505a7a |
fix(agentopsd): harden AI smell surfaces (soc-0l5z #ai-smell-hardening) (#389)
## Summary - Replace the plans manifest shape-only stub with projection-backed daemon state. - Gate llmwiki placeholder outputs behind explicit opt-in and make fake daemon execution test/demo-only. - Refresh stale Olympus-ported docs and tune README/PRODUCT claims to default-safe runtime behavior. - Repair strict docs-site and hook-lease inventory drift surfaced by the merge gate. ## Validation - `scripts/pre-push-gate.sh --fast` - `go test ./internal/daemon ./internal/llmwiki ./cmd/ao` - `bash tests/docs/validate-doc-release.sh` - `scripts/docs-build.sh --check` - `bash scripts/validate-sovereignty-proof-citations.sh` - `bash scripts/check-hook-lease-inventory.sh` Closes-scenario: soc-0l5z#ai-smell-hardening Bounded-context: BC5-Runtime Evidence: validate-sovereignty-proof-citations: scanned 3 pages, 16 citations |
||
|
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 |
||
|
Bo
|
2c263b424c |
feat(scripts): PMF evidence gate + .agents-to-docs promoter (soc-m6v5.8 #pmf-evidence-gate) (#381)
## Why The dogfood plan for 3.0 (`.agents/plans/2026-05-20-ultimate-dogfood-3.0.md`) ran a `/pre-mortem` that surfaced HIGH-1: `.agents/` is gitignored, so any public claim (PRODUCT.md, README, launch posts) citing only `.agents/<path>` is unreachable for readers. D5 of the plan addresses this by introducing the **evidence promotion** path + a CI gate. ## What Three artifacts implementing the contract at `docs/contracts/pmf-evidence.md`: 1. **`scripts/export-evidence.sh <bead-id> <src> [<dest-name>]`** — copies a `.agents/` artifact to `docs/evidence/<bead-id>/<dest-name>` and appends a provenance footer (source path, SHA-256, UTC promotion date, bead-id). Idempotent (no-op if hashes match), refuses to overwrite drift (exit 1 with `DRIFT` message). 2. **`scripts/check-pmf-evidence.sh [<target>...]`** — gate that scans PRODUCT.md / README.md / `docs/launch/*.md` for lines naming `.agents/` paths. Refuses (exit 1) any file that cites `.agents/` without also referencing a `docs/evidence/` promotion. Opt-out per-line with `<!-- internal -->` for commentary about the rule itself. `--json` flag for CI consumption. 3. **`docs/contracts/pmf-evidence.md`** — the contract doc + round-trip example + acceptance criteria block + non-goals. Catalogued in `docs/documentation-index.md` per CLAUDE.md "Contracts must be catalogued" rule. ## How it dogfoods The 3.0 release plan's D6 (ablation experiment, soc-vuu6.33) is the first real consumer — its output lives at `.agents/research/.../ablation.md` and D8 (PRODUCT.md rewrite, soc-m6v5.9.4) needs to cite it. Without this PR, D5 vs D6 was a direct contradiction noted in the pre-mortem. ## Test 21 bats tests, all passing: - `tests/scripts/export-evidence.bats` (10): promotion, custom dest-name, idempotency, DRIFT detection, invalid-bead rejection, missing-source error, arg-count errors, SHA-256 matches content, nested bead-id (`soc-m6v5.9.4.1`) accepted. - `tests/scripts/check-pmf-evidence.bats` (11): clean / violation / promotion-present / `<!-- internal -->` opt-out / line-number reporting / multi-violation count / `--json` shape / missing-target exit 3 / unknown flag / default PRODUCT.md scan / tolerates missing default targets. Two parser bugs were caught + regression-tested during dev: - `printf '\n---\n'` interprets `---` as a flag (fixed via `printf '%s' '---'`). - In-function counter doesn't always survive `set -euo pipefail` across function boundaries (fixed by counting `wc -l` of the appended-to file). Closes-scenario: soc-m6v5.8#pmf-evidence-gate Bounded-context: BC1-Corpus Evidence: scripts/export-evidence.sh Evidence: scripts/check-pmf-evidence.sh Evidence: docs/contracts/pmf-evidence.md Evidence: tests/scripts/export-evidence.bats Evidence: tests/scripts/check-pmf-evidence.bats Co-authored-by: Codex <codex@example.invalid> |
||
|
Bo
|
7ba899f76e |
docs(contracts): registry-as-derived design contract (soc-jbea #design-contract) (#371)
## Why Council 2026-05-20-pr-cleanup-220-240 (Judge B + C, both adversarial) identified **registry.json sibling-coupling** as the largest unaddressed waste in the 2026-05-20 PR-cleanup session — an estimated 40-50% of session wall-clock cost. Every parallel skill-ref PR conflicts with siblings on the generated `registry.json`; one merge invalidates all N-1 others. Defense-in-depth has helped (verified_rebase, smart-skill-md-merge.sh) but addresses symptoms. This contract addresses the root cause. ## What this PR is — and what it is NOT This PR adds a **design contract**, not implementation. - **NEW:** `docs/contracts/registry-as-derived.md` (status: design) - **EDIT:** `docs/documentation-index.md` (one-line catalog entry, per CLAUDE.md "Contracts must be catalogued") - **NO CODE CHANGES.** The contract weighs three options: | Option | Summary | Verdict | |---|---|---| | A | registry.json as build artifact, gitignored, CI regenerates | **Recommended** | | B | Registry-owner workflow pattern, no code change | Stopgap | | C | Per-skill manifest + aggregator stub | Over-engineered | Acceptance criteria + child beads (soc-jbea.1 through soc-jbea.7) are defined inline. Same pattern proposed for `skills-codex/.agentops-manifest.json` + `skills-codex/*/.agentops-generated.json` (treated as parallel sub-epic). ## Why scout-mode soc-jbea was filed as P1 with two architectural options. Implementing either touches: `.github/workflows/validate.yml`, `scripts/generate-registry.sh`, `.gitignore`, multiple CI gate jobs, onboarding docs, downstream consumers. Not a coherent-arc PR. The right shape is: design contract first (this PR), child beads for each migration step, separate session for implementation. ## Session-scope note This is PR #12 of this session, past the second soc-n75z checkpoint (count=10 council verdict was WARN with explicit "file beads first, then teardown, do NOT iterate"). Operator explicitly overrode with "do all top 3 now" directive. Recording the override here for the next post-mortem. Closes-scenario: soc-jbea#design-contract Bounded-context: BC4-Shipyard Evidence: docs/contracts/registry-as-derived.md --------- Co-authored-by: Codex <codex@example.invalid> |
||
|
Bo
|
7d81893137 |
docs(contracts): drop local pre-push-gate — CI is sole source-of-truth (soc-g2r9) (#357)
## Summary
ADR locking in the decision from `soc-g2r9`: **retire
`scripts/pre-push-gate.sh` as the local mirror of CI; treat
`.github/workflows/validate.yml` + `claude-code-review` as the sole
authoritative push gate.**
The local mirror has drifted three observable times in the 2026-05-19
session alone, each costing a self-correction PR. Per the bead's
three-option matrix (`{accept-drift, drop-local-gate,
mirror-CI-via-act}`), `drop-local-gate` removes the *category* of drift
instead of paying ongoing alignment cost.
Closes: soc-g2r9
## Fitness delta
- Source-of-truth surfaces for push validation: **2 → 1** (CI only)
- Local self-correction PRs from drift this session: **3 → 0** (cannot
drift if no local mirror)
- AP#7 mechanical-enforcement gap: **0 → ~1 day**, closed by Wave 3
(`soc-eqjd`)
- Follow-up beads filed: **0 → 4** (soc-bbvw, soc-uo0c, soc-eqjd,
soc-liyr)
## Tradeoff matrix considered
| Option | Effort | Drift cost | Verdict |
|---|---|---|---|
| `accept-drift` | 30min (1 ADR) | unchanged | rejected — legitimizes
the cost we filed the bead to remove |
| `drop-local-gate` (**chosen**) | ~2-3h across waves | impossible (no
local) | removes the *category* |
| `mirror-CI-via-act` | 1-2 days, +30s/push, +2GB Docker | impossible
(Docker GH-Actions runtime) | rejected — heaviest, CI feedback loop
already acceptable |
## What this PR does
Decision-locking only — deletion churn is sliced into 4 follow-up arcs
to keep each PR a single rollback semantic.
| File | Change |
|---|---|
| `docs/contracts/local-pre-push-gate-retirement.md` | New ADR (116
lines, mirrors `agentops-daemon.md` shape) |
| `docs/documentation-index.md` | +1 line — ADR linked |
| `.githooks/pre-push` | Removes the gate invocation block (10 lines);
keeps `bd hooks run pre-push`; drops unused `REPO_ROOT` local |
## Follow-up beads (discovered-from soc-g2r9)
| Bead | P | Wave |
|---|---|---|
| `soc-bbvw` | 1 | Wave 1 — delete `scripts/pre-push-gate.sh` + retire
~12 gate-only helpers |
| `soc-uo0c` | 2 | Wave 2 — retire gate-only bats (KEEP
`verify-gate-claim.bats`) |
| `soc-eqjd` | 1 | Wave 3 — migrate AP#7 from pre-push check #39 to
validate.yml |
| `soc-liyr` | 2 | Wave 4 — doctrine sweep |
Wave 3 (`soc-eqjd`) is the priority — closes the ~1-day mechanical AP#7
gap this PR opens.
## Reversibility
Fully reversible by reverting. Orphaned files stay on disk by design.
## Dogfood note
This is the first PR shipped under the new regime — `git push` did NOT
run `scripts/pre-push-gate.sh` because this very PR removes that
invocation. If the new hook shape breaks, this push surfaces it first.
It pushed cleanly.
Bounded-context: BC0-foundations (gate architecture decision)
Evidence: shellcheck .githooks/pre-push — clean
Co-authored-by: Codex <codex@example.invalid>
|
||
|
Bo
|
00de9efe01 |
feat(scripts): generate AGENTS CI table from yaml manifest + workflow (soc-3oij) (#322)
## What Closes `soc-3oij` — the AGENTS CI Jobs registries-drift surface. Pairs with PR #315 (add-validate-job scaffolder) which atomically wires NEW jobs across 5 touch-points; this PR makes the EXISTING AGENTS table mechanical. ## Source-of-truth shift **Before:** AGENTS.md `### CI Jobs and What They Check` was hand-edited (65 rows). `validate-ci-policy-parity.sh` used awk to spot-check job-name parity but couldn't catch reason/failure drift or ordering drift. **After:** - `docs/contracts/ci-jobs.yaml` is the canonical reason+failure manifest. - `scripts/generate-ci-jobs-table.sh` renders the AGENTS table from yaml + workflow `summary.needs` order + `continue-on-error: true` annotations. - `scripts/validate-ci-policy-parity.sh` is now a 30-line wrapper around `generate-ci-jobs-table.sh --check` (golden-file diff). ## Changes | File | Change | |---|---| | `docs/contracts/ci-jobs.yaml` | **NEW.** 65 jobs, name/reason/failure per entry. Bootstrap-extracted from current AGENTS.md (regex handles escaped pipes in cells). | | `scripts/generate-ci-jobs-table.sh` | **NEW.** Modes: render (default), --check (diff vs AGENTS), --write (rewrite section). Python-embedded for yaml parsing. Enforces every workflow needs-job has a manifest entry; every COE job renders `(non-blocking)`. | | `scripts/validate-ci-policy-parity.sh` | Rewritten as wrapper. Old 190-line awk parity now subsumed by generator. | | `AGENTS.md` | Regenerated section in workflow.summary.needs order (was alphabetical). | | `.github/workflows/validate.yml` | Parity job now triggers on `contracts` and `docs` path-filter changes too. Installs `pyyaml`. | | `docs/documentation-index.md` | Catalog entry for `ci-jobs.yaml` (required by `contract-compatibility-gate`). | | `tests/scripts/generate-ci-jobs-table.bats` | **NEW.** 11 bats tests covering all modes (render/check/write), drift detection, COE annotation, missing-file behavior, section preservation. | ## Discovered + fixed inline `docs/contracts/claude-bot-delegation.md` had a broken `../../AGENTS.md` link from PR #306 (`soc-22wa`) — mkdocs strict build was failing on it (pre-existing, but it blocks any docs-touching PR from passing pre-push). Repointed to GitHub URL per the convention used by other contract entries. ## Validation - ✅ `bats tests/scripts/generate-ci-jobs-table.bats`: **11/11 pass** - ✅ `scripts/generate-ci-jobs-table.sh --check`: PASS (67 rows = 2 header + 65 jobs) - ✅ `scripts/validate-ci-policy-parity.sh`: PASS - ✅ `scripts/pre-push-gate.sh --fast`: passed (1 pre-existing warn on scenarios/trace executable-spec link integrity) - ✅ Non-blocking parity: 6 jobs in manifest tagged `(non-blocking)` = 6 jobs in workflow with `continue-on-error: true` (`check-test-staleness`, `doctor-check`, `executable-spec-link-integrity`, `factory-claim-ledger-strict`, `practice-citations`, `swarm-evidence`) - ✅ Workflow ↔ manifest job set: 65 = 65, zero drift ## Closes registries-drift arc Three-PR sequence: 1. `soc-zxia` (PR #308 + #317): DDD docs layer (registry drift detector, generated skill-domain-map) 2. `soc-3oij` scaffolder (PR #315): CI integration layer (atomic new-job wiring) 3. `soc-3oij` generator (this PR): AGENTS CI table layer (generated from manifest) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Codex <codex@example.invalid> |
||
|
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>
|
||
|
Bo
|
ff8dd0febf |
chore(scripts): Phase 3/3 — generate skill-domain-map from canonical yaml (soc-zxia.3 v2) (#317)
**Replacement for #313** after Phases 0+1+2 squash-merged into main as #308. ## What Replaces hand-edited table sections of `docs/reference/agentops-skill-domain-map.md` with generated output from canonical yaml sources. Adds a golden-file CI gate that **forbids drift**. ## Why #308 (Phase 0+1+2) just landed: - Phase 0 — drift detector - Phase 1 — schema-gate frontmatter (hexagonal_role + practices required) - Phase 2 — BC1-BC5 in `bounded-contexts.yaml` Phase 3 (this PR) completes the epic: the Full Skill Map table becomes generated, not hand-edited. Drift is structurally impossible. ## Implementation ### New files - `docs/contracts/skill-dispositions.yaml` — 78 canonical entries (skill / domain / hexagonal_role / disposition / rationale) - `scripts/generate-skill-domain-map.sh` — generator + golden-file checker (`--check` mode) ### Modified - `docs/reference/agentops-skill-domain-map.md` — keeps hand prose; 3 table sections wrapped in `<!-- BEGIN:* -->` / `<!-- END:* -->` markers that the generator replaces - AGENTS.md CI table — new `validate-skill-domain-map-golden` row - documentation-index.md — `skill-dispositions.yaml` link - pre-push-gate.sh + validate.yml — wired into both ### Generator invariants - Every `skills/<name>/` must have a dispositions row - Every dispositions row's `hexagonal_role` must match SKILL.md frontmatter - Output deterministic (sorted alphabetically; no timestamps) ## Verification ```text $ bash scripts/generate-skill-domain-map.sh --check PASS — skill-domain-map.md matches generator output. $ bash scripts/check-registry-drift.sh PASS — no drift. $ bash scripts/check-bounded-contexts-drift.sh PASS — registry docs match yaml canonical. ``` All 3 drift gates green. ## Domain-tightening epic complete after this lands End-state: `registries-drift` lesson is **structurally encoded**. Graduates from `practice: unassigned` → `practice: accepted`. Closes: soc-zxia.3, soc-zxia Supersedes: #313 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Bo
|
8ae55664dc |
docs(contracts): add @claude bot delegation runbook (soc-22wa) (#306)
## What Adds `docs/contracts/claude-bot-delegation.md` — operational runbook for the `@claude` GitHub App. ## Why Session 2026-05-17 (the PR-discipline cascade) uncovered four gotchas with `@claude` that lived in scattered learning-store entries but had no single canonical contract: | # | Gotcha | Evidence this session | |---|---|---| | 1 | Default install ships read-only perms | PR #301 upgraded `contents/pull-requests/issues` to `write` | | 2 | Bot has no `workflows: write` — workflow-file edits fail | PR #270 revert: *"undo claude.yml forward-port (requires workflows permission)"* | | 3 | `skipped` conclusion is anti-loop, not failure | All bot runs at 09:27:41–45 on its own follow-up comments | | 4 | Auto-merge needs green required checks on current head | #295/#291 sat MERGEABLE/BEHIND with failed `go-build` until `update-branch` re-ran CI | The runbook captures all four with table-based decoding (status, can/can't, when-to-delegate) and cross-references the existing lessons (`claude-app-default-readonly`, `dogfood-install-pr`). ## Acceptance - [x] `docs/contracts/claude-bot-delegation.md` exists with sections: install, permissions, triggers, can/can't, status decoding, four gotchas, when-to-use, how-to-delegate-well, operating contract - [x] Linked from `docs/documentation-index.md` per "Contracts must be catalogued" - [x] Cross-references existing lessons + `AGENTS.md` - [x] Lands via PR (governed by branch protection — dogfoods the discipline this repo just installed) Closes-scenario: bot-runbook-encoded Bounded-context: docs/contracts Evidence: docs/contracts/claude-bot-delegation.md, docs/documentation-index.md Closes: soc-22wa 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Bo
|
f55cbb3dcd |
chore(scripts): add registry drift detector for DDD/hex registry docs (soc-ry4a) (#308)
## What Adds \`scripts/check-registry-drift.sh\` — a drift detector for the hand-maintained DDD/hex registry docs. Detects three classes of drift: 1. **Count drift** — narrative + audit-table + Gherkin scenario counts vs actual \`skills/\` directory count 2. **Membership drift** — every skill listed in the Full Skill Map exists in \`skills/\` and vice versa 3. **Role drift** — \`hexagonal_role\` column in the map matches each \`SKILL.md\` frontmatter ## Why Encodes the \`registries-drift\` lesson from session 2026-05-17: > Hand-maintained inventory docs drift silently. Three axis owners (DDD vocab, Hex frontmatter, Gherkin features) must be generated or schema-gated; never hand-edited maps. Pre-PR state (detected by the new script): | Doc | Declared | Actual | |---|---|---| | \`agentops-skill-domain-map.md\` narrative | 77 skills | 78 | | \`agentops-skill-domain-map.md\` audit table | 78 | 78 ✓ | | \`agentops-domain-evolution-bdd.md\` Gherkin | 77 skills | 78 | | \`skills/expert-council/SKILL.md\` | no \`hexagonal_role\` | declared \`domain\` in map | All four reconciled in this PR; final check is PASS. ## Implementation ### \`scripts/check-registry-drift.sh\` - Modes: \`--check\` (default), \`--fix-counts\` (auto-update inline narrative counts), \`--json\` (machine-readable report) - Returns exit 1 on FAIL, 0 on PASS/WARN - Runtime: < 1s - Dep: PyYAML (already required for context-map generator) ### Wired into: - \`scripts/pre-push-gate.sh\` — always-runs section (drift can be introduced by any skill add/rename/remove) - \`.github/workflows/validate.yml\` — new \`validate-registry-drift\` job + added to \`summary\` job's \`needs\` (so it gates merges) ### Reconciliation - 77 → 78 in 2 doc locations (via \`--fix-counts\`) - \`hexagonal_role: domain\` added to expert-council frontmatter (consistent with council, which it aliases to) - documentation-index.md count updated + annotation added ### Codex parity \`skills-codex/expert-council/.agentops-generated.json\` source_hash auto-updated. \`generated_hash\` unchanged → codex artifact is byte-identical, no regen required. \`bash scripts/check-codex-parity-drift.sh\` returns PASS. ## Acceptance - [x] \`scripts/check-registry-drift.sh\` exists, runs in < 1s - [x] Detects count/membership/role drift; current state PASSES after reconciliation - [x] Wired into pre-push-gate.sh — confirmed gate runs (\`registry drift: ok\`) - [x] Wired into validate.yml summary needs list - [x] Linked from documentation-index.md - [x] Lands via PR (governed by branch protection — dogfoods discipline) Closes-scenario: drift-detector-encoded Bounded-context: scripts/ + CI gates Evidence: scripts/check-registry-drift.sh, validate-registry-drift job, PASS verdict Closes: soc-ry4a 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Bo
|
ec22c23bac |
feat(scripts): add-validate-job scaffolder atomically wires new CI jobs (soc-3oij) (#315)
## What Adds `scripts/add-validate-job.sh` — atomically scaffolds a new `validate-*` CI job across all 5 touch-points in one command. ## Why Adding a new validate-* job currently requires hand-edits to **5+ files in lockstep**: | Surface | What needs editing | |---|---| | `.github/workflows/validate.yml` | new job block | | `.github/workflows/validate.yml` | summary.needs list entry | | `.github/workflows/validate.yml` | summary echo line | | `scripts/pre-push-gate.sh` | new always-runs section | | `tests/scripts/pre-push-gate.bats` | make_stub for helper script | | `AGENTS.md` | CI Jobs table row | Missing any one triggers cascading CI failures across multiple gates. I hit this exact failure **twice this session** while shipping the soc-zxia (registries-drift remediation) epic — missing AGENTS rows broke `validate-ci-policy-parity`; missing bats stubs broke `bats-tests` + `agentops-contract-canaries`. This PR is the **meta-fix**: the same registries-drift pattern that soc-zxia closed for the DDD docs layer, applied to the CI integration layer. ## Usage ```bash scripts/add-validate-job.sh validate-my-thing \ --script scripts/check-my-thing.sh \ --reason "What this validates (AGENTS table column)" \ --failure "Common failure mode (AGENTS table column)" \ [--python] # if the helper needs pip install pyyaml [--dry-run] # show patches without applying ``` ## Properties - **Idempotent**: re-running with same args is a no-op (conflict detection on job-name uniqueness) - **Input validation**: job-name format (`validate-<kebab>`), helper-script existence, all required surface files present, missing required flags - **Dry-run mode**: preview all 6 patches before applying - **Single command**: no chance to miss a touch-point ## Anchors The scaffolder inserts before known anchors in each surface: | Surface | Insertion anchor | |---|---| | workflow job block | before `validate-flywheel-proof:` | | summary.needs | before `validate-flywheel-proof,` | | summary echo | before flywheel-proof echo line | | pre-push gate | before `# --- 22d. Flywheel-proof` | | bats stubs | after make_stub for `proof-run.sh` | | AGENTS table | before validate-flywheel-proof row | ## Verification (dry-run) Tested against a hypothetical `validate-example` job — scaffolder produces correct, well-formed patches for all 6 touch-points. Wet-run validates on the next real validate-* job addition. ## Acceptance - [x] `scripts/add-validate-job.sh` exists, executable, has `--help` - [x] Validates inputs (job name format, script existence, conflict detection) - [x] Dry-run shows correct patches for all 6 touch-points - [x] Linked from `docs/documentation-index.md` - [x] Lands via PR (dogfoods the discipline) ## Related - Filed-from: soc-zxia (Domain-tightening epic that exposed this need) - Closes: soc-3oij - Companion follow-ups (future beads): - soc-m6tp — generate AGENTS.md CI table from validate.yml (reduces from 6 surfaces to 5) - soc-xban — auto-discover bats helper stubs (reduces from 5 to 4) - soc-hwgm — fix TestRunInit* global state flake under -shuffle 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Bo
|
9ea0665522 |
docs(contracts): add lesson-format contract for .agents/learnings/ (soc-4mc2 #lesson-format-spec) (#304)
## What Adds **`docs/contracts/lesson-format.md`** — the canonical format for `.agents/learnings/` entries. Captured from the format weaknesses observed in the **2026-05-17 cascade session's consolidated retrospective**: monolithic file, no schema, no trigger/falsification clauses, no graduation path. The user reviewed the output and asked "is this a good format? should we improve it?" — this PR is the structural answer. ## The spec defines - **File layout**: `.agents/learnings/<date>-<id>.md`, one lesson per file - **9 required frontmatter fields**: `id`, `date`, `severity` (critical/high/medium/low), `trigger`, `verifiable`, `rule`, `falsified_by`, `practice`, `related` - **3 required body sections**: Context, Why this matters, How to apply - **4-state graduation path**: `unassigned` → `proposed` → `accepted` → `encoded` (mechanical enforcement in CI/hook/standards) - **Paired `bd remember` discipline**: key === filename id === frontmatter id; body === `rule:` field verbatim - **A canonical example** (the `landed-means-pushed` lesson from this session, in full) - **7 banned anti-patterns** - **A future lint plan** (filed as a follow-up bead) ## Scope of this PR Only the spec + its index entry. Today's 11 lessons get refactored into the new format **locally** (`.agents/` is gitignored), and the 11 `bd remember` entries get rewritten — but those local changes don't go through git, so they're not in this PR. ## Acceptance - `docs/contracts/lesson-format.md` exists ✅ - Linked in `docs/documentation-index.md` (per the contracts-must-be-catalogued rule) ✅ - Spec embeds a worked example (`landed-means-pushed`) so future lessons have a literal template to copy - A linter is filed as a follow-up bead (the lint isn't shipped here; the contract is) ## Why one PR Per the discipline: every PR cites a bead, scenarios slice the PR. soc-4mc2 has 3 scenarios; this PR closes the only gitable one (`lesson-format-spec`). The other two are local-only refactor work; not PR-bound. Co-authored-by: Codex <codex@example.invalid> |
||
|
Bo
|
1f0e545a51 |
Executable spec layer (epic soc-58nt, F2–F5): GOALS as BDD acceptance criteria (#292)
* feat(goals): F2.0 scenario-result artifact contract + producer/writer
bead: soc-58nt.2.6
* docs(goals): F4.0 trace link convention ADR-0005
bead: soc-58nt.4.8
* docs(goals): F3.0 domain-slice manifest contract + ADR-0004
bead: soc-58nt.3.8
- schemas/domain-slice-manifest.v1.schema.json: JSON Schema (draft/2020-12,
additionalProperties:false) for domain-slice manifests. All required fields:
domain, version, bounded_context, directive_ids (d-<slug> pattern), scenario_ids,
context_roots, allowed_read_globs, denied_read_globs, validation_commands, owner.
- docs/adr/ADR-0004-domain-slice-manifest-contract.md: records four decisions:
(A) command shape is ao rpi phased --domain <name>; (B) manifest is durable
tracked artifact at docs/domains/<name>/manifest.yaml; (C) reconciles with the
domain skill (vocabulary), context-map.md (architecture view), and skill
frontmatter — no overlap; (D) Go model named domainSliceManifest, explicitly
distinct from rpi_phased_manifest.go's phaseManifest. Cross-references ADR-0003.
- docs/domains/README.md: explains the directory, field table, relationship to
the three pre-existing domain surfaces, and how to add a new slice.
- docs/domains/example/manifest.yaml: fully populated example; validated against
the schema via jsonschema (PASSED).
* feat(goals): F2.1 scenario-result aggregation reader
bead: soc-58nt.2.1
* feat(rpi): F3.1 domainSliceManifest model + loader
Implements the domainSliceManifest Go model and loader in
cli/internal/domainslice/ per the F3.0 contract (ADR-0004, Decision D).
Uses gopkg.in/yaml.v3 with KnownFields(true) to reject unknown fields,
mirrors the schema's additionalProperties:false. Validates all required
fields, directive_id pattern (^d-[a-z0-9][a-z0-9-]*$), context_roots
minItems:1, and validation_commands sub-fields with field-named errors.
Explicitly distinct from phaseManifest (rpi_phased_manifest.go).
28 tests pass (L1 unit + L2 fixture round-trip via docs/domains/example/manifest.yaml).
bead: soc-58nt.3.1
* feat(goals): F4.1 read-only executable-spec trace graph walker
bead: soc-58nt.4.1
* feat(goals): F2.2 per-directive scenario_satisfaction + threshold verdict
bead: soc-58nt.2.2
* feat(rpi): F3.2 ao rpi phased --domain scoping
bead: soc-58nt.3.2
* feat(goals): F4.2/F4.3 ao goals trace --from / --orphans
beads: soc-58nt.4.2 soc-58nt.4.3
* feat(goals): F4.4 ao goals render — GOALS.md to Gherkin
bead: soc-58nt.4.4
* feat(rpi): F3.3a domain-scope audit evidence
bead: soc-58nt.3.3
* feat(goals): F2.3 scenario_satisfaction JSON field + --scenarios-only
Per-directive scenario satisfaction added to ao goals measure: 0 -> 8
new JSON fields and a --scenarios-only mode that skips gate execution.
bead: soc-58nt.2.3
* feat(rpi): F3.4 ao rpi phased --scaffold-domain
bead: soc-58nt.3.4
* test(goals): commit missing goals-trace scenario-results fixture
The F4.1/F4.2 walker tests reference a scenario-results.json fixture under
a gitignored .agents/ subpath; it was never force-added and a clean
checkout (and CI) lacks it, failing 5 scenario_result tests. Force-add it.
bead: soc-58nt.4.1
* fix(goals): F4.1 tighten goalstrace scenario-claim heuristic
bead: soc-58nt.4.9
- Tighten scenarioTokenRe: auto- tokens now require at least two
hyphen-separated slug segments (auto-X-Y…), so single-word English
compounds like auto-merge and auto-update are no longer matched.
- Downgrade broken_bead_scenario_claim from error to warning when the
claim comes from a heuristic (ConfidenceLow) free-text match; per
ADR-0005 §4.1 only an explicit Scenarios: line constitutes a broken
explicit link and may produce an error.
- Add beads_test.go with table-driven tests covering: English auto-*
false-positive rejection, real multi-segment auto-* ID detection,
explicit missing scenario → error, heuristic missing → warning only,
resolvable scenario → no defect, end-to-end Walk with auto-merge bead
produces no error-severity finding.
* test(goals): F2.T1 regression-coverage audit + gap fill
bead: soc-58nt.2.4
* ci(goals): F1.6 wire executable-spec link lint + trace-orphans (warn-first)
bead: soc-58nt.1.9
* feat(rpi): F3.3b runtime hook enforcement of domain scope
bead: soc-58nt.3.9
* test(goals): F2.T2 e2e script for scenario-satisfaction gate
bead: soc-58nt.2.5
* docs(goals): F5.0 re-steer policy + mutation-safety contract (ADR-0006)
bead: soc-58nt.5.9
* docs(goals): fix streak-reset prose in ADR-0006 (cleanup)
bead: soc-58nt.5.9
[no-sibling] prose fixup only, no structural change
0 → 0 schema fields changed
* test(goals): F4.T1 regression-coverage audit + gap fill
bead: soc-58nt.4.6
* feat(wiki): land wiki bounded context waves 1-4 (epic soc-behj)
Phased strangler consolidating ao's .agents/-touching logic into one
cli/internal/wiki bounded context. Each wave gated by the 102 cmd/ao
integration tests staying green; legacy command surface untouched.
- W1 soc-1lju FrontmatterCodec — all 5 frontmatter parsers delegate
- W2 soc-36lw CorpusLocator — agentsDirIn moved, 17 call sites migrated
- W2 soc-f4tr Artifact + Claim domain types with subtype invariants
- W3 soc-vot0 persistent WikiIndex — JSONL, incremental by content-hash
- W3 soc-r08p FreshnessPolicy — claim-level evidence-driven freshness
- W4 soc-ijp8 WikiPipeline — subsumes llmwiki loop, 3 stages wired
- W4 soc-q50a port conformance suite
Also anchors .gitignore's bare wiki/ pattern with a !cli/internal/wiki/
negation — the new package was being silently ignored.
Wave 5 (ao wiki command group) is not included in this commit.
* test(goals): F4.T2 e2e script for trace chain
bead: soc-58nt.4.7
* test(rpi): F3.T1 regression-coverage audit + gap fill
bead: soc-58nt.3.6
* test(rpi): F3.T2 e2e script for domain-scoped RPI
bead: soc-58nt.3.7
* feat(goals): F5.1 verdict ledger schema + writer
bead: soc-58nt.5.1
* feat(goals): F5.2 re-steer policy engine + verdict-ledger producer hookup
bead: soc-58nt.5.2
* feat(goals): F5.4 feedback-to-learning compiler
Adds cli/internal/feedbackcompiler — scans the verdict ledger for
fail->pass directive transitions and drafts a learning entry in
docs/learnings/ for each transition found. Drafts carry status: draft
and directive_id frontmatter (ADR-0005 §2.6). Never auto-promotes.
Idempotent: skips existing drafts on re-run.
Also documents the auto-draft workflow in
skills/forge/references/feedback-compiler-drafts.md with a compact
reference-link in skills/forge/SKILL.md (under 248-line limit).
Synced to skills-codex/forge/ and regenerated codex hashes.
bead: soc-58nt.5.4
* docs(goals): F5.5 compound-engineering retro in /post-mortem
Extend the /post-mortem skill with a Compound-Engineering Retro section
that compares iteration N vs N-1 for a domain slice using the F5.1 verdict
ledger (.agents/goals/verdict-ledger.json). The mode emits a comparative
delta — directives that improved (fail→pass, satisfaction up), regressed
(pass→fail, satisfaction down), or held stable — plus learning yield since
N-1, written as a status:draft learning to .agents/learnings/.
Detailed step-by-step procedure (CE.0–CE.5) lives in
references/compound-engineering-retro.md; SKILL.md carries a compact
trigger/commands summary and links to it. Both files synced to
skills-codex/post-mortem/ with updated codex hashes.
bead: soc-58nt.5.5
* feat(goals): F5.3 ao goals steer --auto with human-gated confirmation
bead: soc-58nt.5.3
* test(goals): F5.T1 regression-coverage audit + gap fill
bead: soc-58nt.5.7
* test(goals): F5.T2 e2e script for auto re-steer
bead: soc-58nt.5.8
* docs(goals): F2.4 docs regen for scenario-satisfaction gate + epic CLI artifacts
Regenerate cli/docs/COMMANDS.md and registry.json from a clean worktree at
HEAD so the soc-58nt command surface is documented without leaking unrelated
peer WIP into the generated docs.
F2 (soc-58nt.2.7): document scenario_satisfaction JSON shape, --scenarios-only,
result-artifact resolution, and exit codes in skills/goals/SKILL.md +
references/executable-spec-chain.md; cross-ref ao goals measure/trace from
skills/scenario/SKILL.md.
Epic-wide artifacts also landed here because they regenerate atomically across
F2-F5: COMMANDS.md/registry.json (all new ao goals/rpi surface), cli-skills-map
heading count, skills-codex hashes, ADR-0004/0005/0006 documentation-index
links, and the F2-F5 e2e CI lanes in validate.yml.
ao capabilities and ao robot-docs need no manual edits — both build their
command/flag surface from the live cobra tree, so new commands register
automatically (Global Rule G5 satisfied by construction).
bead: soc-58nt.2.7
* docs(domain): F3.5 domain-as-loop docs for domain-scoped RPI
Document the domain-slice runtime in skills/domain/SKILL.md (a "Domain as a
scoped RPI loop" section connecting the Slice primitive to ao rpi phased
--domain / --scaffold-domain / --force) and add the Domain-Slice row to the
modes table in skills/scaffold/SKILL.md, mirroring the existing Project/
Component/CI mode-row shape. The scaffold skill's Domain-Slice Mode section
already covered the workflow; this lands the missing modes-table entry so the
mode count is 3 -> 4.
The COMMANDS.md/registry/CI-lane regen for F3 landed in soc-58nt.2.7.
skills-codex hashes for the two changed skills refreshed via
scripts/regen-codex-hashes.sh; codex-parity audit clean.
bead: soc-58nt.3.5
* docs(goals): F5.6 re-steer loop docs in /post-mortem
Cross-reference the auto re-steer loop from the Compound-Engineering Retro
section of skills/post-mortem/SKILL.md: when the compound retro names a
chronically regressing directive, ao goals steer recommend prints
policy-driven directive mutations from the same verdict ledger and ao goals
steer apply writes the mutation to GOALS.md, human-gated via the non-lossy
patcher (ADR-0006). Mirrors the existing "closing the loop" cross-ref shape
used elsewhere in the skill's See Also prose.
The ao goals steer recommend/apply COMMANDS.md surface, the F5 e2e CI lane,
and the ADR-0006 documentation-index link landed atomically in soc-58nt.2.7's
epic-wide regen; the re-steer contract detail lives in
skills/goals/references/executable-spec-chain.md (also in 2.7).
skills-codex/post-mortem hash refreshed; codex-parity audit clean.
bead: soc-58nt.5.6
* docs(goals): F4.5 docs regen for goals trace + render (epic-subsumed)
F4's docs deliverables — the `ao goals trace` and `ao goals render` entries in
cli/docs/COMMANDS.md, the F4 trace-chain e2e CI lane in validate.yml, the
ADR-0005 documentation-index link, and the Trace/Render mode sections plus the
trace contract in skills/goals/SKILL.md + references/executable-spec-chain.md —
all co-landed atomically in soc-58nt.2.7's epic-wide CLI-reference regen
(commit
|
||
|
Bo
|
a984b742d9 | feat(skills): productize skill factory workflow (#290) | ||
|
Boden Fuller
|
5208da954d |
feat(goals): non-lossy GOALS.md directive-block patcher + stable IDs
Foundation for epic soc-58nt (executable spec layer). - ADR-0003: executable-spec artifact durability — promoted spec scenarios live in tracked spec/scenarios/, ad hoc evaluation scenarios stay in their existing local dir, domain manifests in docs/domains/ (soc-58nt.6). - cli/internal/goals/patcher.go: GoalsPatcher edits a single directive block in place, preserving the Three-Gap section, Gates Tags column, prose, and HTML comments that RenderGoalsMD/WriteMDGoals drop. Stable directive IDs are title slugs, independent of display number, so they survive 'ao goals steer prioritize' renumbering (soc-58nt.1.8). Recovered from codex preserve-WIP branches after a working-tree clean. Closes soc-58nt.6, soc-58nt.1.8. |
||
|
Boden Fuller
|
b8c5a3761b |
feat(agentops): make 3.0 hookless-first
Add DDD skill-domain contracts, hook lease inventory, replacement ports, artifact-first RPI skill boundaries, and release exact-SHA validation. Demote ao inject to a compatibility adapter and remove prompt-only default hooks. |
||
|
Boden Fuller
|
ee763750ba |
docs: rename PRACTICE.md to PRACTICE-REGISTRY.md + add CDLC narrow-waist doctrine
Rescope PRACTICE.md into PRACTICE-REGISTRY.md: it now owns only the practice-slug lineage registry, not product positioning or CDLC doctrine. Update all references (schema, validate-practice-citations.sh, bats test, architecture-terms.md, documentation-index.md, aggregate.go comment). Introduce the Context Density Rule as a canonical domain concept: every high-value context token carries intent, boundary, evidence, decision, constraint, or next action. New domain entry context-density-rule.md (+ codex mirror). Thread the BDD/Gherkin + DDD + Hexagonal + TDD narrow waist through cdlc.md, README.md, PRODUCT.md, GOALS.md, and the rpi/domain/ post-mortem skills. Sync codex artifacts. |
||
|
Boden Fuller
|
b85eee22c4 |
Merge branch 'main' into crank/ddd-hexagonal-2026-05-12
Main advanced 127 commits while this DDD/hexagonal+doctrine branch was in
flight (v2.41.0 + v2.41.1 shipped on main). Resolved 4 conflicts:
- skills/validation/SKILL.md: kept --ours (full DAG extraction to
references/dag.md). Supersedes main's
|