mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
e1fae0dae63d73be508bb8348a12106df043cab0
17 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Bo
|
e1fae0dae6 |
Make the engineering harness lean and add optional topic memory (#1116)
RPI now owns the authorized outcome through finish, with Plan and Memory
loaded only when useful. Known defects get direct repair, and evidence
can change the approach under unchanged acceptance. Fresh exact-content
validation remains required. Memory provides optional recall, mining and
curation of reviewed topic pages; specialists and the fixed-dispatch
adapter remain optional.
The change reconciles current documentation and generated skill
projections. It preserves native budget and permission authority, BD
work ownership, protected external evidence storage and the distinction
between a supported lesson and demonstrated later benefit. It adds no
scheduler, work store, Go command or evidence schema.
Validation: required local Go/build/vet/race checks, aggregate suite,
generated-output check and 72 gates pass. The complete 44-test executor
suite passes; its shared-deadline fixture now tolerates CI scheduling
jitter while still requiring deadline exhaustion and preventing a third
launch. Fresh author-distinct review passed all 112 changed paths with
no findings; all seven exact-head CI checks passed at
|
||
|
Bo
|
568e99d436 |
Loop restore: converge and crank as control flow under the verdict contract (ADR-0017) (#1099)
## Loop restore: converge and crank as control flow under the verdict
contract (ADR-0017)
Intent source: `docs/plans/2026-09-03-loop-restore.md` (in this PR).
Decision record:
`docs/adr/ADR-0017-loop-as-control-flow-not-knowledge.md`.
**Why.** The 2026-07-14 single-pass cut (`482307762`) removed the
iterate loop (discovery, crank, converge, evolve, the learn write-half)
together with the unproven compounding claim, although ADR-0011 demoted
only the latter. The control flow was never demoted, and its absence
showed on 2026-09-02, when a three-lane fix needed eight validators and
two stops because the contract had no repair phase. This restores the
loop as control flow and nothing else: no knowledge store, no `ao
converge`/`ao crank`, no evolve, no canary. ADR-0004 and ADR-0011 stay
in force.
**What changes.**
- **RPI gains a bounded repair phase.** On `FAIL` or `NOT_PROVEN` with
findings, repair and re-validate freshly under the convergence law:
caller-declared `repair_rounds` (default 2); open finding set keyed by
stable `findings[].id`, union across validator families, non-growing; no
closed id reopens; the subject digest changed or, for `NOT_PROVEN`, new
digest-bound evidence resolved a named gap. Converged = fresh PASS plus
cross-family PASS on risky surfaces. Plan and Implement keep their
single dispatch. `skills/rpi/scripts/run_once.py` models the law as pure
data (33 tests): rounds are validated for shape (digest required, no
duplicate ids, no PASS with findings, no FAIL without findings),
condition 4's evidence branch needs a NOT_PROVEN previous round, a
non-FAIL current round, new evidence, and a resolved finding, and a PASS
over unchanged bytes after a FAIL is a flip that reports NOT_PROVEN.
`workflows/rpi.js` runs validation as legs (spawned or external primary,
plus a caller-supplied `crossFamily.command` on risky surfaces) merged
worst-of with a union of stable ids; a risky surface without a
cross-family leg is `diversity_unsatisfied` and never converges or
enters repair; a failed repair or re-validation returns NOT_PROVEN with
no stale verdict. Validators return `subjectDigest`, stable finding ids,
and `evidenceRefs`.
- **crank returns as a thin wave executor** (113 lines): the caller
selects the wave and the repair bound, crank invokes RPI per lane
(parallel only on disjoint write and regen scopes), runs the wave
acceptance once, returns evidence, and stops. No retry, budget, queue,
claim, lease, Git, closure, or next-work ownership. Routing golden
`rq-07-wave-execution` ranks it first.
- **validate is cross-family by default on risky surfaces**
(`cli/internal/gates/**`, `scripts/check-*.sh`, `tests/**`,
`skills/*/scripts/**`, hook policies, `lib/**`, security-scanned paths)
with the LAW-0 dispatch table: Claude orchestrating uses read-only
`codex exec`; Codex orchestrating uses an interactive Claude session in
an NTM pane, never `claude -p`. No live adapter means
`diversity_unsatisfied`, which on a risky surface is `NOT_PROVEN`. The
full literal CI command set runs once on the final integrated subject;
routine rounds keep the receipt-driven freshness contract.
- **Conformance assertions flipped under ADR-0017 only:**
`scripts/check-cathedral-cut-conformance.py` (crank live; "Stop
regardless" replaced by positive canaries for the law's four conditions;
a bounded `for` loop that compares against `repair_rounds` is required
in `run_repair_phase`, and the gate executes the law's canaries against
the reference behavior), `workflows/rpi.js`,
`skills/rpi/scripts/validate.sh`,
`evals/agentops-core/rpi-behavior.json`,
`skills/rpi/references/rpi.feature`. Every single-pass public surface
(README, AGENTS.md, PRODUCT.md, CI-CD, agent-workflow-reference,
rpi-traversal, cli/README, quickstart and demo commands, the
operating-contract and product-boundary bats, the Codex-description
oracle) now states repair to convergence.
**Known approximation, disclosed.** The Claude conveyor has no
deterministic shell primitive, so changed paths are derived by the fresh
validator (git status and diff against the clean pre-run tree) and
unioned with the implementer's report; risk is classified over that
union and unreported paths are coverage findings. A validator is still a
model; runtime derivation outside every agent is a follow-up. Family
distinctness of the cross-family leg is asserted by the caller's choice
of command and not verified by the script.
**Not in scope.** Premortem stays a single advisory judge and Plan still
only names the first check (phase boundaries unchanged). No `verdict.v2`
or `rpi-report.v1` change. The loop's own effect on outcomes is
unmeasured and owed a seeded-defect probe, like the rest of the corpus.
**Evidence on the tip.** Regen check clean; full gate green with a
HEAD-built binary; CI's bats command green; Go build/vet/test green;
golangci-lint clean; security gate quick PASS; one fresh validator over
the whole diff; one cross-family read of the design before
implementation (13 findings folded) and two of the integrated diff (9
findings in round one, 11 by round two, 15 by round three, each round
repaired and re-reviewed; the fresh validator passed the tip after round
two and the final tip
|
||
|
Bo
|
7a765cde19 |
Align AgentOps around its operations-layer identity (#1051)
Executes docs/plans/2026-08-07-agentops-operations-layer-alignment.md: AgentOps is the operations layer for agentic engineering; the federated integration graph is the topology, the semantic work-and-proof protocol is the contract, and RPI is the standard one-experiment traversal. Retires the ao flywheel command family and all knowledge-flywheel product state, tombstones the seven-move operating-loop workflow, narrows ao init and the .agents state writers to declared destinations, renames the core architecture page to rpi-traversal.md with a compatibility redirect, aligns AGENTS.md, 25 skills, public and package copy, regenerates every owned projection, and strengthens the conformance gates with planted-negative proofs. Both the alignment subject and the follow-up gate-bookkeeping commit carry fresh author-distinct validation PASS verdicts with empty not_checked scope. Test-Removal-Reason: dead knowledge-flywheel and session-store surfaces were deleted with their tests (operations-layer alignment) |
||
|
boshu
|
5bdbb5fd09 | refactor: simplify AgentOps loop and harden CLI | ||
|
boshu
|
4823077621 | refactor: cut AgentOps to a single-pass evidence loop | ||
|
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 |
||
|
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
|
cd37602d5d |
docs(contracts): drift #5 resolved via audit, soc-5yuy COMPLETE (cycle 131)
Fifth and final soc-5yuy child closed. Drift #5 (Session per BC) resolved as audit-only — too big to atomic-rename AND not necessary, because Go's package qualifier already disambiguates the 4 Session concepts. Pre-rename substring audit (cycle-127 checklist): - 342 word-bounded 'Session' refs across 6 packages (storage, search, formatter, forge, context, cmd/ao). - That's 3x cycle 126's QueueClaim rename (108 refs). - Cycle-122 lesson: large mechanical renames burn cycle time with high overreach risk. The cycle-126 sed-overreach added a learning that ratifies "audit before renaming". Cycle 131 finding: the 4 Session concepts are already disambiguated by package qualifier — agentworker.AgentSession, storage.Session (= TranscriptSession by convention), search.Session (= TranscriptSession by convention), gascity.Session (published-API). The daemon package already has no Session type per the contract. No rename needed. Changes: - ubiquitous-language.md drift #5 resolution block rewritten to document "package qualifier IS the disambiguator" and the 342 word-bounded refs that would otherwise have to atomic-rename. - ubiquitous-language.md drift-baseline table row #5 marked AUDITED. - ubiquitous-language.md cycle log entry for cycle 131. - docs/plans/2026-05-12-rescope-evolve-and-architecture.md .5 row marked AUDITED. soc-5yuy EPIC COMPLETE — 5 of 5 children closed: - .1 Gate / Validator: AUDITED cycle 130 (codebase already uses Gate organically; 0 "Validator" in script headers) - .2 Cycle / Run / Iteration: AUDITED cycle 129 (serialized contracts, Runner naming, Runtime substring-coincidence) - .3 Claim → Lease: SHIPPED cycle 126 (108 Go refs) + corrective revert for over-broad sed (rpi work-item claim kept Claim semantics) - .4 Skill / Pattern / Practice / Primitive: AUDITED cycle 128 ('primitive' overload documented as 3 scoped senses) - .5 Session per BC: AUDITED cycle 131 (THIS — 4 Session concepts already disambiguated by package qualifier) Bigger arc insight (12 cycles, 119-131): - Original catalog (cycle 58) flagged 5 drifts as "rename required". - Audit-first discipline (cycles 125, 127 learnings) revealed 4 of 5 were over-flagged — codebase was more disciplined than the catalog implied. - 1 rename shipped + 4 audit-only closures + 1 sed-overreach correction + 1 substring-audit learning + 5 contract refinements. Lesson durable in docs/learnings/2026-05-13-substring-sed-rename- overreach.md. Pattern catalog: drift catalogs from one-shot research mode overstate drift; incremental audit-first cycles prevent wasted rename work. soc-5yuy bd also closed in this cycle. Cycle 131 / soc-5yuy.5 audit-only-resolution + epic-close mode. |
||
|
Boden Fuller
|
1ffda5e577 |
docs(contracts): drift #1 resolved via audit (cycle 130, soc-5yuy.1)
Fourth soc-5yuy child closed. Drift #1 (Gate/Check/Validation/ Validator) resolved as audit-only — catalog overstated drift size. Audit findings: - Zero scripts/check-*.sh headers use the noun "Validator". - 38 of ~90 scripts already use "Gate" in their headers; rest don't repeat the noun. - cli/internal/ratchet.Validator is the only Go Validator type (legitimate ratchet-specific concept; not a check-script validator). KEEP. - "validate"/"validates" as English verbs in header descriptions is fine — not a noun-confusion drift. The "90 scripts inconsistent" claim in the catalog was wrong. The codebase organically drifted toward "Gate" already. No renames needed. Changes: - ubiquitous-language.md drift #1 resolution block rewritten to document the actual state. - ubiquitous-language.md drift-baseline table row #1 marked AUDITED. - ubiquitous-language.md cycle log entry for cycle 130. - docs/plans/2026-05-12-rescope-evolve-and-architecture.md .1 row marked AUDITED. This is doc-only. No code changes. soc-5yuy.1 bd closed. soc-5yuy progress: 4 of 5 children closed. Three via audit-only (.1 cycle 130, .2 cycle 129, .4 cycle 128) and one via rename (.3 cycle 126). Only .5 (Session → TranscriptSession, 97 refs) remains as the actual code-rename work. Pattern crystallizes: when a drift catalog comes from one-shot research mode rather than incremental observation, the actual codebase is often more disciplined than the catalog implied. 3 of 5 cycle-128/129/130 audits resolved without renames. The audit-first discipline (cycle 125 / 127 learnings) is now demonstrably better than execute-first for borderline drifts. Cycle 130 / soc-5yuy.1 audit-only-resolution mode. |
||
|
Boden Fuller
|
320985b9c5 |
docs(contracts): drift #2 resolved via audit (cycle 129, soc-5yuy.2)
Third soc-5yuy child closed via audit-only. Drift #2 (Cycle/Loop/ Iteration/Run consistency) resolved without renames — the catalog over-flagged this. Audit findings: - ~150 RPIRun* identifiers + 132 Iteration* identifiers enumerated. - Most usage falls into one of 5 categories that are NOT drift: 1. Serialized-contract enums (JobTypeRPIRun) — renaming breaks on-disk JSON job spec format and cross-process compatibility. 2. Filesystem path constants (RPIRunRegistryDir) — renaming breaks registry layout. 3. Legitimate Runner/Executor naming (RPIRunner, RPIRunExecutor) — these are role types, not Run-instance synonyms. 4. Substring coincidence — RPIRuntimeCommand and RPIRuntimeMode contain "Run" as part of "Runtime". Not a Run concept. 5. Scoped Dream-internal counters (overnight.IterationSummary, dream_subcycle.MaxIterations) — Dream's convergence-loop term, scoped to Dream surface only. - rpi.RPIRun (the artifact struct) IS the canonical name for an RPI execution; analogous to GitHub Actions' "CI Run". Keep. Conclusion: the codebase's Run/Iteration usage is mostly semantically correct. Drift #2 was a contract-side mistake. The audit IS the resolution. Changes: - ubiquitous-language.md drift #2 resolution block: REWRITTEN to document the 5 categories of correct-but-look-like-drift usage, with explicit "KEEP" annotations. - ubiquitous-language.md drift-baseline table row #2: AUDITED. - ubiquitous-language.md cycle log entry for cycle 129. - docs/plans/2026-05-12-rescope-evolve-and-architecture.md .2 row marked AUDITED. This is doc-only. No code changes. soc-5yuy.2 bd closed with reason linking to this commit. soc-5yuy progress: 3 of 5 children closed (.3 cycle 126 via rename, .4 cycle 128 via audit, .2 cycle 129 via audit). Two remaining: .1 (Gate/Validator) + .5 (Session/TranscriptSession) — both still rename-required but with substring-overreach warnings baked in from cycle 127. Pattern note: the same cycle-126 substring-audit applied to a catalog flag and revealed the catalog was wrong, not that the code needed renaming. The audit-first discipline (cycles 125, 128, 129) is now demonstrably better than execute-first for borderline drifts. Cycle 129 / soc-5yuy.2 audit-only-resolution mode. |
||
|
Boden Fuller
|
3117933203 |
docs(contracts): drift #4 resolved via audit (cycle 128, soc-5yuy.4)
Second soc-5yuy child closed. Drift #4 (Skill/Pattern/Practice/ Primitive cross-reference consistency) resolved as audit-only — no code renames needed. Audit findings: - Skill is consistently "invokable harness module" across all SKILL.md files. No drift. - Pattern is consistently "reusable promoted knowledge". No drift. - Practice is consistently "citation annotation in primitive frontmatter". No drift. - Primitive IS overloaded — three distinct concepts share the word: 1. BC1 Corpus Primitive (the annotated unit; canonical sense for the cross-cutting `practices: [slug]` annotation) 2. Domain Primitive (skills/domain/ — 6 structural primitives: Entry, Index, Citation, Primitive, Slice, Anti-Pattern) 3. Runtime primitive (skills/converter/ + skills/standards/ — atomic tool/feature exposed by a runtime, e.g., a Claude-only hook event) The 3 senses do NOT conflict because each is scoped to its own surface (BC1 cross-cutting vs the domain skill only vs converter + standards). No renames are needed — the audit IS the resolution. Changes: - ubiquitous-language.md drift #4 section: added a sub-overload table enumerating all 3 `primitive` senses with their scope + distinguishing context. - ubiquitous-language.md drift-baseline table row #4: marked AUDITED cycle 128. - ubiquitous-language.md cycle log entry for cycle 128. - docs/plans/2026-05-12-rescope-evolve-and-architecture.md: marked .4 done. This is doc-only. No code changes. soc-5yuy.4 bd closed with reason linking to this commit. soc-5yuy progress: 2 of 5 children closed (.3 cycle 126 via rename, .4 cycle 128 via audit). Three rename-required children (.1, .2, .5) still open with the cycle-127 substring-overreach warning baked into their descriptions. Cycle-shape note: "audit-only" is a legitimate cycle-sized deliverable when the catalog turns out to NOT reflect real drift. Cycle 125 also did contract-refinement after audit (drift #5). Cycle 128 takes the simpler path — surveyed and documented the overload as scoped, no follow-up code work needed. Cycle 128 / soc-5yuy.4 audit-only-resolution mode. |
||
|
Boden Fuller
|
5e0df8a4f7 |
fix(rpi): revert over-broad QueueLease rename for work-item claim identifiers
Cycle 126 follow-up: the bulk sed s/QueueClaim/QueueLease/g caught
identifiers from TWO different concepts:
1. daemon.QueueClaim (struct) → daemon.QueueLease ✓ INTENDED
(job-slot lease with token + expiration; correct rename)
2. rpi.ErrQueueClaimConflict + rpi.RequireQueueClaimOwner +
the cli/cmd/ao wrappers → renamed by substring overlap, but
these are about WORK-ITEM CLAIM COORDINATION in
.agents/rpi/next-work.jsonl — when two workers race to claim the
same harvested work item. That IS a Claim concept (per the BC2
contract: Claim = public assertion), not a Lease concept.
The post-commit hook self-review surfaced the over-reach by showing
the diff to me — I noticed `EnsureQueueItemClaimable` (kept Claim
language) returning `ErrQueueLeaseConflict` (sed-renamed to Lease
language). That semantic inconsistency was the smoking gun.
Surgical revert: just the 4 identifiers across 4 files. Daemon
side (QueueLease struct + method signatures) untouched.
Identifiers restored:
- rpi.ErrQueueClaimConflict (and its declaration)
- rpi.RequireQueueClaimOwner
- cli/cmd/ao errQueueClaimConflict (alias)
- cli/cmd/ao requireQueueClaimOwner (wrapper)
All consumers re-resolve; build clean; tests pass (rpi, daemon,
cmd/ao, llmwiki).
ubiquitous-language.md cycle-126 log entry rewritten to record the
correction inline. New lesson captured: substring-based sed can
over-reach across different concepts that share a prefix; an audit
needs to enumerate ALL identifiers containing the substring, not
just the type definition. The cycle-125 audit-then-execute pattern
is necessary but not sufficient — must include identifier-enumeration
even when the type-definition site is unambiguous.
Two commits closing soc-5yuy.3:
|
||
|
Boden Fuller
|
4c74bc8d4d |
refactor(daemon): rename QueueClaim → QueueLease (soc-5yuy.3, drift #3)
First soc-5yuy child to close. Mechanical rename of `daemon.QueueClaim` to `daemon.QueueLease` across 108 Go references in 28 files — cli/internal/daemon (76 refs), cli/cmd/ao (22), cli/internal/rpi (7), cli/internal/llmwiki (3). Resolves drift #3 from docs/contracts/ubiquitous-language.md. Why QueueLease, not QueueClaim: - `Claim` is the BC2 noun for what the project says publicly (e.g., AOP-CLAIM-*, factory-claim-ledger.json). - The daemon's QueueClaim was semantically a LEASE on a job slot with a token + expiration, not a public assertion. The struct has fields `ClaimToken`, `LeaseEpoch`, `LeaseExpiresAt` — three out of four already named "Lease". - The name collision tax was real: a fresh contributor reading factory-claim-ledger could not tell whether daemon.QueueClaim was the same concept. Audit-then-execute (cycle-125 pattern): 1. Pre-rename audit: counted refs by package (76+22+7+3+5+0). 2. Checked for split-concept surprise (cycle-125 lesson): all 111 baseline refs are the same concept (no Session-like split). 3. Checked for serialization keys: no `"queue_claim"` JSON tags; no string literals containing "QueueClaim". 4. Then bulk sed across 4 Go packages; build clean; vet clean; tests pass (daemon 11s, rpi 4s, llmwiki 0.1s, cmd/ao 53s). Docs updated: - docs/contracts/ubiquitous-language.md drift #3 resolution block, schedule table row, baseline table row, and cycle log entry — all reflect "DONE cycle 126" + "0 refs (from 111)". - docs/plans/2026-05-12-rescope-evolve-and-architecture.md soc-5yuy .3 row marked DONE. soc-5yuy.3 bd closed with reason linking to this commit. Net delta: 113 insertions, 112 deletions across 28 files. Zero QueueClaim refs remain in tracked code/docs (testdata excluded — those are immutable transcript fixtures). Cycle 126 / soc-5yuy.3 audit-then-execute mode (first real rename following the audit-then-execute discipline from cycle 125). |
||
|
Boden Fuller
|
24a4fe2b35 |
docs(contracts): refine ubiquitous-language drift #5 — Session is 3 concepts (cycle 125)
soc-5yuy.5 first-execution attempt surfaced a contract gap. The "rename bare Session types per BC" bead assumed the 3 bare type Session declarations were all one concept (BC5 AgentSession). A close read of each file shows they're 3 different concepts and the surface area is much larger than the bead implied. Changes: 1. Updated drift #5 resolution block to enumerate FOUR Session concepts (was implicitly 2): - AgentSession (BC5 ephemeral provider) — already canonical - OperatorSession (BC5 interactive CLI) — already canonical - TranscriptSession (BC1 Corpus — extracted knowledge from a Claude Code .jsonl) — NEW. Currently bare `storage.Session` (93 refs) + `search.Session` (4 refs). - GasCitySession (gascity package — published worker-session API, 79 refs across 7 types). RENAME OUT OF SCOPE — would break the API contract; document as alias in code instead. 2. Updated drift baseline table row for #5 with the 3-concepts note + actual ref counts (97 + 79 = 176 instead of the implied 3). 3. Cycle log entry explains: the original bead assumed the rename was uniform; it isn't. soc-5yuy.5 was refined in bd with the actual scope so a future cycle picking it up doesn't waste another cycle re-discovering the split. Why ship this as a doc cycle: the actual rename (97 refs) is too big for one cycle but the contract gap can be closed now. Future cycle that claims soc-5yuy.5 gets a sharper acceptance criterion ("storage+search Session→TranscriptSession; gascity stays") and doesn't have to re-do the audit. Concrete next-cycle prereq: with the bd description refined, the actual storage.Session → TranscriptSession rename becomes a single search-and-replace + go test cycle. ~97 refs is still large but all mechanical. Cycle 125 / soc-5yuy.5 contract-refinement-after-audit mode. |
||
|
Boden Fuller
|
bcaf989ed1 |
docs(contracts): ubiquitous-language gets drift baseline (cycle 123)
soc-5yuy (cross-cutting ubiquitous-language cleanup) has 5 ranked
drifts to resolve via rename PRs. Each rename PR's fitness delta is
"legacy term count: X → 0", but the doc had no baseline numbers
captured. New "Current drift baseline (cycle 123)" section pins the
starting counts so:
1. Each rename PR can claim a concrete fitness delta in its commit
message ("QueueClaim: 111 → 0").
2. Future cycles can re-measure cheaply and see progress.
3. The five rename PRs become independently trackable rather than
"in this epic somewhere".
Baselines captured this cycle:
- Drift #3 (QueueClaim → QueueLease): 111 refs (vs 3 QueueLease)
- Drift #5 (bare type Session): 3 packages (search, storage,
gascity)
- Drift #1 (Gate): ~90 scripts/check-*.sh (filenames stay)
- Drift #2 (rpi.Run), #4 (Skill term mix): "measure on demand"
— the grep needs more thought than a single command, so deferred
Each baseline row carries its own grep command so re-measurement is
mechanical, not interpretive.
Why not just do one of the renames: the smallest, QueueClaim →
QueueLease, has 111 refs. That's a real multi-file PR — would burn
context inside the /evolve cycle window and per cycle-122 learning
("avoid manufactured intra-package migration") is the wrong cycle
shape. The baseline IS the right cycle-sized contribution.
This is doc-only. No code changes. Sets future cycles up to ship
the rename PRs as discrete, measurable work units.
Cycle 123 / soc-5yuy baseline-capture mode.
|
||
|
Boden Fuller
|
cd542b73a1 |
fix(docs): markdownlint MD049 in ubiquitous-language.md
Cycle 58 commit |
||
|
Boden Fuller
|
5a39f7c977 |
docs(contracts): land ubiquitous-language meta-contract per BC
Pins canonical names per bounded context (BC1 Corpus, BC2 Validation,
BC3 Loop, BC4 Factory, BC5 Runtime) for the 5 ranked naming drifts
from the bounded-context inventory:
1. Gate vs Check vs Validation vs Validator (BC2)
2. Cycle vs Loop vs Iteration vs Run (BC3)
3. Claim vs Assertion vs Evidence (BC4/BC2; daemon.QueueClaim →
QueueLease to remove collision)
4. Skill vs Primitive vs Pattern vs Practice (cross-BC; pinned per
definition not by BC alone)
5. Session (BC5; scope per AgentSession / OperatorSession)
Rename schedule binds soc-5yuy children .1–.5 to specific drifts.
Each rename ships as a single-concern commit per the update-
principles meta-contract (cycle 52 commit
|