fbba8af5ac
feat: land audit hardening and goal-design workflow
2026-07-09 12:20:53 -04:00
3fe37b1867
docs: repair strict docs-build link/anchor warnings + disposition the rest (age-y0ww)
...
Make `scripts/docs-build.sh --check` a MEANINGFUL signal instead of advisory
noise (was 82 strict-mode warnings, always ignored).
Root cause: mkdocs --strict fails on 82 links that leave docs/ (the knowledge
graph deliberately links out to skills/, scripts/, schemas/, evals/, and canonical
repo-root docs). All 82 were verified to resolve to REAL repo files on disk — zero
accidental breaks — so they are intentional cross-references, not bugs.
Fixes (category A + B, INFO-level drift, verified against built HTML anchors):
- Anchors: GLOSSARY SKILLS.md#beads->#beads-br; INCIDENT-RUNBOOK scenario-C
double->single hyphen (x2); pawls.md directive-precedence / diversity-mode /
escalation double->single (referrers in ADR-0007, autonomy-ladder, pawls self);
catch-derived-fuel membrane update anchor (single + date suffix).
- Suffixes: levels L1-L4 README next-level links + workflows meta-observer ->
explicit README.md targets.
Dispositions (category C + D): the 82 intentional external cross-refs are enumerated
in tests/docs/mkdocs-strict-allowlist.txt and explained per-class in
docs/docs-build-dispositions.md. `docs-build.sh --check` now runs mkdocs --strict
end-to-end (nothing weakened, no --no-strict) and fails on any warning NOT on the
allowlist — proven: a fresh broken link still fails the check; the 82 pass.
Result: `docs-build.sh --check` is CLEAN-or-dispositioned (exit 0). Wired doc into
nav + CONTRIBUTING pointer.
2026-07-08 23:29:25 -04:00
e29568e196
fix(docs): doc-lifecycle sweep — delete byte-dup, duplicates gate, BC6 label, career-leak excision, hookless reconcile (age-gate-the-ungated-egwt.12)
2026-07-01 19:23:34 -04:00
4a7c6a0701
feat(gates): docs.skill-refs --all-docs — widen the 6-file skill-ref gate to live docs + SKILL-ROUTER sync (age-gate-the-ungated-egwt.5)
...
Add an --all-docs mode to check-doc-skill-refs.sh that scans the union of the
pinned doctrine files PLUS the full LIVE docs/** set (scripts/lib/docs-scope.sh),
ratcheted by a new filename-pinned shrink baseline
(scripts/.docs-skill-refs-baseline). Two-way ratchet: a non-baselined live doc
with a dead `/skill` ref FAILS; a baselined file that no longer offends FAILS
demanding a prune. Detection stays slash-syntax + headings only (never bare
skill names). Default (no-flag) behavior is byte-identical.
docs/SKILL-ROUTER.md (the curated router) is covered by --all-docs (a live
docs/** file, never baselined) so a dead ref there FAILS strict, without
perturbing the byte-identical default doc count.
seed.go docs.skill-refs row: Match widened to docs/** + the baseline + the lib;
Args set to [--all-docs --strict]. Burn-down (long-tail only): repointed retired
`/retro`->/post-mortem, `/vibe`->/validate, `/ratchet`->/flywheel,
`/research-multi`->/research, `/implement-wave`->/crank, and reworded the
retired `/dream` across 13 docs/levels + docs/workflows + docs/philosophy
pages, then pruned them from the baseline (91 -> 78 offenders). Owner-locked
pages (comparisons/getting-started/positioning) stay baselined.
Bats twin tests/scripts/check-doc-skill-refs-all-docs.bats covers all the modes.
2026-07-01 18:12:53 -04:00
b7503b4519
feat(gates): docs.cli-snippets gate — resolve ao commands in live docs against the cobra tree (age-gate-the-ungated-egwt.4)
2026-07-01 18:07:41 -04:00
23769dff5f
fix(beads): resolve canonical ledger from worktrees (age-worktree-beads-ledger-guard-c1u1)
2026-06-19 22:34:07 -04:00
7e447c02b5
docs(destale): wave 2 + ratchet — all live docs off retired tech (age-docs-staleness-remediation-cko)
...
Completes the staleness epic. 42 P2/P3 files converged to current truth
(bd→br, gascity/gt-sling/mayor→NTM+Agent Mail, daemon→substrate, hooks→hookless,
CI-authoritative→push-to-main local Go gate); GLOSSARY's 18 dead skills/* links
repaired to ../skills/<name>/SKILL.md (19 links, 0 broken); contracts/runbooks
that freeze retired-system nouns bannered RETIRED/HISTORICAL rather than rewritten.
Adds the Arc-7 ratchet — scripts/check-docs-no-retired-tech.sh — which scans all
live docs (260) for retired-subsystem commands/phrases and fails on regression.
A doc opts out by carrying a RETIRED/HISTORICAL/SUPERSEDED banner (or being an
ADR / migration / upgrade / index doc), and lines that describe a removal are not
flagged. Running it caught 12 stale refs the deep-read sweep missed — a
"CI is the authoritative gate" cluster (agentops-brief, primitive-chains,
INCIDENT-RUNBOOK, knowledge-flywheel, philosophy, software-factory), stale
hook-smoke in release-e2e-checklist, and GasCity descriptors in
contracts/index + SCHEMAS + strategic-direction — now fixed. Gate: PASS.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com >
2026-06-17 10:29:17 -04:00
b84dcf3ca2
docs(hookless): close cold-start orientation drift (soc-qh2g1 #cold-start-orientation-coherence) ( #795 )
...
## Summary
Close the hookless cold-start orientation gap for `soc-qh2g1` by making
the live startup docs and skills point at explicit `ao session
bootstrap` plus pulled context (`ao inject` / `ao lookup`) instead of
hidden SessionStart behavior.
## Changes
- Reframes live docs that still implied automatic startup/handoff
injection to the hookless explicit-command path.
- Updates source and Codex skill mirrors for `quickstart`, `inject`,
`using-agentops`, `recover`, `bug-hunt`, and `session-bootstrap`.
- Expands the cold-start and docs drift gates so `SessionStart hook`,
`startup hooks`, and `auto-inject ... hook` promises fail unless
explicitly hedged as opt-in, removed, or historical.
- Refreshes scoped Codex skill hashes for the touched mirrors.
## Test plan
- [x] `bash scripts/check-hookless-cold-start.sh`
- [x] `bash scripts/check-doc-hooks-drift.sh`
- [x] `bats tests/scripts/check-hookless-cold-start.bats
tests/scripts/check-doc-hooks-drift.bats`
- [x] `shellcheck scripts/check-hookless-cold-start.sh
scripts/check-doc-hooks-drift.sh`
- [x] `bash scripts/regen-codex-hashes.sh --check --only
session-bootstrap,quickstart,inject,using-agentops,recover,bug-hunt`
- [x] `bash scripts/validate-codex-generated-artifacts.sh`
- [x] `bash scripts/validate-codex-lifecycle-guards.sh`
- [x] `bash scripts/validate-agents-split.sh`
- [x] `git diff --check`
- [x] `bash scripts/validate-skill-runtime-parity.sh`
- [x] `bash scripts/lint-codex-native.sh`
Closes-scenario: soc-qh2g1#cold-start-orientation-coherence
Bounded-context: BC1-Corpus
Evidence: scripts/check-hookless-cold-start.sh
2026-06-06 11:23:56 -04:00
e74d8899fd
feat(ci): gate live-hooks reintroduction in docs/ (ag-rryf #doc-hooks-drift-gate) ( #713 )
...
## What
Adds `scripts/check-doc-hooks-drift.sh` — a CI regression guard that
fails when a **live-facing** doc reintroduces a live hooks runtime after
the 3.0 hookless teardown:
- `hooks/hooks.json` (retired manifest), a `hooks/<name>.sh` runtime
path,
- `ao hooks` (not a registered command — verified absent from
`cli/cmd/ao/`),
- a bare `session-{start,end,autostart}*.sh` hook-file ref
…unless the **same line** hedges it as hookless / opt-in / historical /
removed / a git-hook. Companion to `sync-skill-counts.sh` (skill-count
drift) and `check-hookless-cold-start.sh` (fixed-list cold-start gate).
## Scope (and why the exclusions)
`docs/` **minus** surfaces that legitimately/archivally name hooks:
- **archival history** — `CHANGELOG.md`, `releases/`, `learnings/`,
`plans/`, `adr/`, `convergence/`, `sovereignty-proof/` (document the
past / the removal itself)
- **opt-in subsystem** — `contracts/` (hooks-authoring opt-in specs),
`runbooks/` (diagnostic enumeration), `code-map/` (point-in-time audits)
The gate keeps the onboarding / operator / architecture narrative
hookless.
## Also: finishes the ag-t1ca residue the gate flags
The ag-t1ca de-hooking missed 8 live-facing lines (gate caught them);
each is reframed:
- stale `ao hooks` command/smoke refs → removed / `ao doctor`
(`cli-skills-map`, `UPGRADING`, `release-e2e-checklist`,
`contracts/release-readiness`)
- present-tense hooks-as-rules → CI gates (`strategic-direction`)
- hook-runtime mentions → `ao curate constrain` / opt-in framing
(`curation-pipeline`, `leverage-points`, `SCHEMAS` legacy-manifest
label, `workflows/session-lifecycle`)
## Verification
- `scripts/check-doc-hooks-drift.sh` → PASS on this branch (FAILed on
all 8 before the reframes)
- `tests/scripts/check-doc-hooks-drift.bats` → 8/8 (positive /
negative×3 / hedge×2 / exclusion / no-docs error)
- `shellcheck` clean · `markdownlint` 0 errors (9 docs) ·
`validate-cli-skills-map.sh` PASS · `generate-ci-jobs-table.sh --check`
PASS · existing `check-hookless-cold-start.sh` still green
- Wired into `validate.yml` lint/contracts (gated on docs/ci/shell
changes) + auto-run via the bats suite
Closes-scenario: ag-rryf#doc-hooks-drift-gate
Bounded-context: BC2-Validation
Evidence: scripts/check-doc-hooks-drift.sh
2026-06-03 22:38:26 -04:00
b6691ddab1
docs: fix docs asserting Gas City is the reference -> NTM+MCP+managed-agents (ag-r6g1 #docs-slice-2) ( #689 )
...
## What
Fixes the **post-mortem WARN caveat** from the #684–#687 session: 5 docs
still **asserted "Gas City is the reference"** — a now-FALSE claim
contradicting the north star ([`docs/3.0.md`](docs/3.0.md): substrate =
**NTM + MCP + managed-agents**). Re-narrates all 11 refs (**ag-r6g1**,
docs slice #2 ).
## Surfaces (5 files, +21 −20)
- `docs/how-it-works.md` (2) — out-of-session delegation +
Dream-unattended para (de-GC'd the mayor/refinery/cron-`exec`-Order
mechanics → NTM swarm / managed-agent driver).
- `docs/software-factory.md` (2) — prose + Surface Map row.
- `docs/first-value-path.md` (4) — step 6, fast-path table row, the
substrate block (mayor/refinery/Orders/`city.toml` → the
NTM+MCP+managed-agents trio), artifacts row.
- `docs/architecture/ports-and-adapters.md` (1) — autonomous-loops
delegation.
- `docs/workflows/session-lifecycle.md` (2) — substrate prose + table
row.
Kept the correct "AgentOps ships no daemon/scheduler; delegates to a
substrate" framing intact.
## Scope
**ag-r6g1 stays OPEN** — operator runbooks (`nightly-evolution`,
`autonomy-runtime-cycle-1`, deeper GC-specific mechanics) + descriptive
comparison/example/explainer mentions remain for a later slice.
## Verification
- markdownlint 0 errors · `regen-all.sh --check` ALL GREEN (docs-only;
no derived-surface drift).
Closes-scenario: ag-r6g1#docs-slice-2
Bounded-context: BC1-Corpus
Evidence: docs/how-it-works.md
2026-06-02 16:06:22 -04:00
c640ef2379
fix(ops): route work selection through reconciliation
...
Route status/quickstart/release/beads through ao reconcile before backlog selection or release-health claims. Correct release-tag CI skip docs, regenerate registry, and clarify the reconcile release-tag next action.
2026-05-26 19:07:42 -04:00
39bad7d2f3
docs(3.0): ag-p7j W2 — reframe core narrative docs to in-session (ag-p7j) ( #527 )
...
## What
Worker 2 of the ag-p7j 3-way swarm reconciling stale daemon/scheduler
references for AgentOps 3.0. Reframes stale `ao daemon` / `agentopsd` /
`ao schedule` / `ao overnight` prose across 7 core narrative docs to the
**in-session model**: the loop runs in session (the product +
sovereignty floor); always-on / scheduled / unattended execution is
delegated to an orchestration substrate (Gas City is the reference
City), not an AgentOps surface. Those daemon/scheduler/overnight-runner
surfaces were deleted in the 3.0 rearchitecture (ADR-0009). Mirrors
`docs/3.0.md`.
## Files (7, prose only)
- `docs/software-factory.md` — Runtime Variants daemon-submit lane →
in-session `ao rpi phased`; Surface Map drops `ao daemon submit`, adds
an out-of-session (substrate) row; "both paths" note now in-session +
Gas City delegation.
- `docs/cdlc.md` — SDLC→CDLC table: "Software factory daemon (`ao
daemon`)" → in-session loop run on a substrate (Gas City reference).
- `docs/how-it-works.md` — Dream split intro + "Dream — Private
Overnight Operator Mode" section reframed from `ao overnight` to
in-session `/dream` + CLI primitives; unattended = Gas City substrate.
- `docs/philosophy.md` — `/dream and ao overnight` → `/dream` in
session, out-of-session compounding on Gas City.
- `docs/first-value-path.md` — intro item 6, Time-Budget row, Step 7
"Optional Scheduled Lane" (`ao daemon run` / `ao schedule`) → "Optional
Out-of-Session Lane" (Gas City mayor/refinery); First-Artifacts and
Friction rows updated.
- `docs/workflows/session-lifecycle.md` — Option 3 "Bedtime Dream Run"
(`ao overnight setup/start/report`) → "Dream Compounding Run" (`/dream`
foreground); runtime-modes table row updated.
- `docs/architecture/ports-and-adapters.md` — Autonomous-loops adapter
bullet: `agentopsd daemon scheduler` removed; `/dream`,`/evolve` framed
as in-session driving adapters with out-of-session delegated to the
substrate.
No links to deleted daemon contracts existed in these files (verified).
No edits outside the 7.
## Gates
- `grep -E "ao daemon |agentopsd|ao schedule"` across the 7 files:
**CLEAN** (also clean for `ao overnight`/`ao plans`/`ao
watch`/`schedule.yaml`/`--with-schedule`).
- `markdownlint` on the 7 files: **PASS** (exit 0).
- `mkdocs build --strict`: **PASS** (exit 0; only the generic Material
upgrade banner, no link warnings/errors).
- doc-release gate (`tests/docs/validate-doc-release.sh`): **PASS**.
- learning-references check: **PASS**.
Diff stat: 7 files, +65/-72 — balanced, no collateral data loss.
Closes-scenario: ag-p7j#w2-core-docs
Bounded-context: BC1-Corpus
Evidence: docs/software-factory.md
2026-05-24 21:15:43 -04:00
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.
2026-05-16 09:43:08 -04:00
f382d42bc3
docs: clarify AgentOps golden paths
2026-05-03 00:41:17 -04:00
cd0d4b9555
fix(codex): keep session-start hook quiet
2026-04-23 23:15:27 -04:00
22fbfa2253
fix(codex): repair native hook manifest install
2026-04-23 23:15:27 -04:00
ee515c82d6
feat: ship layered dream operator surfaces
2026-04-09 21:06:05 -04:00
fab9eefe49
docs: align dream runtime surfaces
2026-04-09 20:16:15 -04:00
4a179cd94d
docs(codex): update hookless references to reflect native hooks in v0.115.0+
...
Codex CLI v0.115.0+ supports native hooks (SessionStart, Stop,
UserPromptSubmit, PreToolUse, PostToolUse). Update skills, CLI help
text, and docs to reflect this:
- Skills: using-agentops, recover, quickstart, post-mortem, rpi
now document native hooks as primary, hookless as fallback
- CLI: codex.go help text updated (ao codex start/stop are fallback)
- Docs: architecture, contracts, flywheel, session-lifecycle updated
with codex-native-hooks runtime mode alongside hookless fallback
2026-04-07 09:44:47 -04:00
2177edb30f
fix: wire flywheel automation into skill paths
2026-04-03 10:47:44 -04:00
7ed1f19be4
Merge branch 'codex/claude-factory-native' into codex/merge-recent-branches
...
# Conflicts:
# cli/README.md
# docs/workflows/session-lifecycle.md
2026-04-02 15:54:48 -04:00
2fc5234911
refactor(hooks): keep Claude startup surface in CLAUDE.md
2026-04-02 15:52:33 -04:00
6df03bdbb3
feat(hooks): add claude factory startup routing
2026-04-02 15:32:50 -04:00
bc7e7937bb
feat(cli): add software-factory operator lane
2026-04-02 15:11:54 -04:00
03a97978c5
fix(docs): align ASCII box-drawing diagrams across 23 files
...
Fix right-side │ border alignment in box diagrams. Three fix types:
- Trailing space adjustment for border alignment
- Box border widening for content that exceeded width
- Bottom border dash count matching top border
2026-03-29 07:55:25 -04:00
ea5d1148bb
feat: harden codex hookless follow-up flows
2026-03-24 10:09:27 -04:00
9e4ddcf859
feat: add codex hookless lifecycle fallback
2026-03-23 15:24:33 -04:00
0c1d4f6308
docs: align lifecycle docs with primitive chain audit
2026-03-11 12:37:24 -04:00
2b338ee0c3
fix(cli+docs): tech debt sweep — UTF-8 truncation, CORS, stale refs (na-7r3)
...
Go fixes:
- Fix UTF-8 boundary slicing in narrative truncation (rune-safe truncateRunes helper)
- Add signal.Stop to rpi_serve signal handlers (prevent goroutine leak)
- Replace CORS wildcard with localhost-only validation (prevent cross-site reads)
- Surface SSE polling errors to client instead of silent continue
- Extract section name constants (HISTORY/INTEL/TASK) from magic strings
- Add intel_scope enum validation (none/topic/full)
- Sort resolveSkillPath glob matches for deterministic resolution
- Add random suffix to adhoc context IDs (prevent 1-second collision)
- Surface writePromptAuditTrail errors to stderr unconditionally
- Document RPI_RUN_ID env var in ao inject --help
Doc fixes:
- Replace stale /learn skill references with /retro --quick across 9 workflow docs
- Replace .agents/retros/ with .agents/council/ in post-mortem SKILL.md + references
- Reorder GOALS.md directives to sequential 1-8 numbering
- Rename post-mortem Phase 2 steps from 4.x to EX.x
- Update SKILL-TIERS.md: council + retro → council + knowledge lifecycle
- Sync all changes to skills-codex mirror
Epic: na-7r3 (6 issues, 2 waves)
2026-03-04 10:07:01 -05:00
37d4b5b2ae
Merge branch 'codex/rpi-supervisor-cli' into main
2026-02-21 19:41:50 -05:00
Boden Fuller