skills/boshu2__agentops
1
0
Fork 0
mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(contracts): refine ubiquitous-language drift #5 — Session is 3 concepts (cycle 125)

Browse Source 
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.
This commit is contained in:
Boden Fuller
2026-05-12 20:33:03 -04:00
parent bcaf989ed1
commit 24a4fe2b35
1 changed files with 10 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/ubiquitous-language.md
+10 -2
View File
@@ -76,7 +76,14 @@ BC1 is largely drift-free at the aggregate level. The one term to lock: **Contex
| Runtime-specific skill/hook implementation | **Harness** | _no drift_ |
| Claude Code event (PreToolUse, etc.) | **HookEvent** | "tool event", "claude event" |
**Ranked drift #5 (Session) resolution:** scope per BC. `AgentSession` (BC5, ephemeral provider instance) vs. `OperatorSession` (BC5, interactive CLI session). The `daemon` package should NOT have a `Session` type — anything that looked like one is either an AgentSession or an OperatorSession. Daemon manages **WorkerSlots** and **DaemonJobs**, not Sessions.
**Ranked drift #5 (Session) resolution (refined cycle 125):** scope per BC. Four distinct Session-shaped concepts exist:
- **AgentSession** (BC5, ephemeral provider instance — Claude/Codex/etc.)
- **OperatorSession** (BC5, interactive CLI session)
- **TranscriptSession** (BC1 Corpus — extracted knowledge from a Claude Code transcript .jsonl). Currently bare `storage.Session` (93 refs) and `search.Session` (4 refs). Cycle 125 surfaced this — was NOT in the original drift catalog.
- **GasCitySession** (gascity package — daemon-managed worker session API; 79 refs across `Session`, `SessionCreateRequest`, `SessionListParams`, `SessionListResponse`, `SessionGetOptions`, `SessionSubmitRequest`, `SessionSubmitResponse`). Conceptually overlaps with AgentSession but the gascity API surface uses Session as the user-facing noun. Rename to AgentSession would break a published API contract; keep as-is, document the alias in code.
The `daemon` package should NOT have a `Session` type — anything that looked like one is either an AgentSession, OperatorSession, or TranscriptSession. Daemon manages **WorkerSlots** and **DaemonJobs**, not Sessions.
## Ranked drift #4: Skill vs Primitive vs Pattern vs Practice
@@ -133,7 +140,7 @@ soc-5yuy child PR ratchets one of these counts toward 0.
| #2 Cycle / Loop / Iteration / Run | `rpi.Run` callers outside Phase context | _measure on demand_ | `grep -rn 'rpi\.Run\b\|RpiRun\b' cli/` |
| #3 Claim / Assertion / Evidence | `QueueClaim` references | 111 (vs 3 `QueueLease`) | `grep -rn 'QueueClaim' cli/ scripts/ docs/` |
| #4 Skill / Primitive / Pattern / Practice | mixed terms in `skills/*/SKILL.md` cross-references | _measure on demand_ | (audit per file; no single grep) |
| #5 Session | bare `type Session struct` declarations | 3 (`cli/internal/{search,storage,gascity}/types.go`) | `grep -rn 'type Session ' cli/` |
| #5 Session | bare `type Session struct` declarations | 3 (`cli/internal/{search,storage,gascity}/types.go`); refined cycle 125 — these are 3 DIFFERENT concepts (storage/search = TranscriptSession 97 refs; gascity = published-API Session 79 refs, keep as-is) | `grep -rn 'type Session ' cli/` |
Excluded from counts: `cli/testdata/` (transcript fixtures), test
files (`*_test.go`) where Session/Claim mock types are legitimate.
@@ -142,3 +149,4 @@ files (`*_test.go`) where Session/Claim mock types are legitimate.
- 2026-05-12 cycle 58: contract written; rename schedule binds soc-5yuy.1–.5 to specific drift resolutions.
- 2026-05-13 cycle 123: added current-drift baseline section so rename PRs have a starting-count to ratchet against. QueueClaim sits at 111 refs (vs 3 QueueLease); `type Session struct` appears in 3 packages.
- 2026-05-13 cycle 125: refined drift #5 — the 3 bare `Session` types are 3 different concepts, not one. Added TranscriptSession (BC1) as missing canonical name. gascity.Session is a published-API surface — rename out of scope; keep + alias-document. storage.Session (93 refs) + search.Session (4 refs) rename to TranscriptSession is the actual soc-5yuy.5 unit; gascity stays.