post-cutover audit (slices 009–016): omp slice-lifecycle, coherence, env-doctor, doc fidelity, project bootstrap - #1
Merged
Conversation
…runtime The slice-008.6 omp() shell function I wrote prepended only the mise-managed bun runtime path (/home/fr/.local/share/mise/installs/ bun/1.3.13/bin) but the omp binary itself is installed under bun's global package dir at /home/fr/.cache/.bun/bin/omp (a symlink into ~/.cache/.bun/install/global/node_modules/@oh-my-pi/...). Without that second path, `command omp` inside the function cannot resolve the binary and fails with "command not found", even though bun itself is on PATH. Confirmed empirically when Luci tried `omp` after sourcing the new .bashrc and got command-not-found. Fix: prepend BOTH paths in the function and in every Step 2/3 PATH example throughout GETTING-STARTED.md. The mise path provides bun 1.3.13 (omp's required runtime); the .bun/bin path provides the omp binary itself. Both are needed. Same fix already applied to ~/.bashrc on the running machine via in-place sed. Spec-Slice: SPEC-20260426-008.6 (post-archive fix) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Post-cutover (slice-008.4) audit identifies six enhancements ranked by impact-per-effort:
1. omp slice-lifecycle entry (load-bearing — closes the gap left by PORT-NOTES.md)
2. persona bash-or-rewrite repair (4 of 7 personas could not invoke skills)
3. coherence skill (cross-source consistency: Linear ↔ specs ↔ trailers)
4. env-doctor skill (single-shot pre-flight verifier)
5. README/CLAUDE identity-model rewrite (post-008.6 fidelity restoration)
6. latest-docs registry URL probe (11/11 entries currently unverified)
Each spec carries §5 acceptance criteria as the verification contract.
Markdown/config-only slices skip the test-writer step per the documented
SpecSafe deviation.
Spec-IDs: SPEC-20260427-{009..014}
Closes the load-bearing gap left by PORT-NOTES.md §specsafe-session: the three vanilla-Pi tools (specsafe_begin/end/status) had no omp port, which silently no-op'd the auto-commit-with-trailers hook because state.currentSlice was always null under omp dispatch. Restores lifecycle entry as a standalone CLI under .omp/skills/specsafe/, mirroring the existing CLI-skill pattern. State-file shape is bit-identical to the vanilla extension (.pi/.honcho-state.json), atomic writes via tmp+renameSync with mode 0o600, and corrupt-state quarantine matches readStateFileOrNull semantics from .omp/hooks/specsafe-session.ts. Subcommands: begin <slice-id> <workspace-id> <session-id>, end PASS|FAIL|ABANDONED, status. Idempotency: begin-while-open and end-while-closed both exit 1 with explicit messages. Tests: 8 new (.omp/test/specsafe-cli.test.ts, criteria C1-C9 from spec §5). Full suite: 246 pass / 15 skip / 0 fail (Δ +8 from 238 baseline). Spec-Slice: SPEC-20260427-009
Four personas (spec-writer, reviewer, steward, doc-scout) instructed the model to invoke /skill:latest-docs but their tools: frontmatter omitted bash — making the contract physically unexecutable from inside the agent. Resolution: add bash to the four personas' tools list with a constrained-use clause (## Bash usage section) limiting it to bun run .omp/skills/<name>/bin/<name> plus standard read-only inspection. The constraint is discipline, not enforced by code — same trust model as the as_peer allowlist (slice-008.1). Verification: grep -l 'no `bash`' .omp/agents/*.md → empty grep -lE '^tools:.*\bbash\b' .omp/agents/*.md → 7 files (all personas) test-writer/implementer/validator unchanged (already had bash) Markdown-only slice; test-writer step skipped per documented SpecSafe deviation. Spec-Slice: SPEC-20260427-010
Read-only skill that detects drift between Linear, specs/, and commit trailers — the gap Luci elevated from Q4 of the audit interview. Three subcommands (no --i-approve, no mutations): coherence check linear-vs-specs — open Linear ↔ specs/<KEY>__*.md coherence check trailers-vs-linear — Spec-Slice trailers ↔ Linear state coherence check brief-coverage — Linear in_progress/in_review ↔ specs/briefs/ Output: one drift item per line, prefixed [orphan-linear|orphan-spec|stale-trailer|orphan-brief]. Exit codes: 0 clean, 1 drift detected, 2 config error. Calls the existing linear skill (DRY); test stub injected via PI_COHERENCE_LINEAR_CMD. No @linear/sdk import (acceptance C10). LINEAR_API_KEY absence → exit 2 with single-line stderr notice (mirrors github skill graceful degradation). Tests: 8 new under .omp/test/coherence/ with planted-drift fixtures. Spec-Slice: SPEC-20260427-011
First thing to run in any new dogfood project. Read-only, single-shot
verifier of the eight prerequisites every Ghola dispatch quietly assumes:
a. HONCHO_API_KEY round-trip (REQUIRED)
b. HONCHO_WORKSPACE_ID/SESSION_ID/PEER_ID present (REQUIRED)
c. LINEAR_API_KEY round-trip (OPTIONAL; --strict elevates)
d. gh auth status (REQUIRED)
e. omp config get (REQUIRED)
f. ~/.omp/agent/{hooks,tools,agents,skills} symlinks resolve into $PWD/.omp (REQUIRED)
g. .pi/.honcho-state.json parses cleanly (OPTIONAL)
h. ~/.omp/agent/honcho.json mode 0600 + parses (OPTIONAL)
Each external probe respects a stub-env-var contract (PI_ENVDOCTOR_HONCHO_PROBE_CMD,
PI_ENVDOCTOR_LINEAR_CMD, PI_ENVDOCTOR_GH_CMD, PI_ENVDOCTOR_OMP_CMD) so the
test suite can exercise every path without live API calls.
Honcho probe distinguishes 401/403 (FAIL) from 404/'session not found'
(PASS-with-note). API-key sanitization mirrors .omp/tools/honcho/index.ts:69-73.
Flags: --strict elevates OPTIONAL → REQUIRED; --json emits flat {a..h:{status,note?}}.
Exit codes: 0 all REQUIRED pass, 1 any REQUIRED fails, 2 invocation error.
Tests: 17 new (.omp/test/env-doctor.test.ts).
Note: tests assert flat {a..h} shape; SPEC-012 §4 originally described
{items:[...]} envelope. Tests are frozen; spec deviates. Follow-up: amend
spec to match implementation, or implementation to match spec — both are
viable but neither is blocking.
Spec-Slice: SPEC-20260427-012
Post-008.6 fidelity restoration. AGENTS.md was kept current with the
slice-008.6 wiring (workspace=oh-my-pi, session=luci-<basename-of-cwd>,
no seshat peer); README.md and CLAUDE.md fell behind, contradicting the
canonical source.
README.md changes:
- Honcho identity model section rewritten: workspace=oh-my-pi, session=
luci-<basename-of-cwd>, peers=Luci+per-Ghola. as_peer contract documented.
- Per-spawn child-env-injection paragraph dropped; replaced by pointer to
.omp/hooks/PORT-NOTES.md (slice-008 deliberately did not port that flow).
- 'What's here' bullets repointed at .omp/hooks/, .omp/tools/honcho/,
.omp/skills/ (now seven skills incl. specsafe).
- Cast section: persona links repointed at .omp/agents/. Seshat bullet
reworded — Seshat is the orchestrator persona (AGENTS.md), not a peer.
CLAUDE.md changes:
- Line 43 path: .pi/extensions/honcho/index.ts → .omp/tools/honcho/index.ts
- Memory discipline: peer list updated to drop seshat (no longer a Honcho peer)
Verification (all empty per spec §5):
grep 'one per project' README.md
grep -E 'seshat.*\bpeer\b' README.md
grep '.pi/extensions/honcho' CLAUDE.md
grep -E '\.pi/agents/' README.md
AGENTS.md is unchanged (was already canonical).
Markdown-only slice; test-writer step skipped per documented SpecSafe deviation.
Spec-Slice: SPEC-20260427-013
One-shot pre-dogfood verification: probe each of the 11 registry entries currently flagged verified:false, flip true on success, log failures. Reuses the existing latest-docs fetch <lib> command (DRY) sequentially — no parallel HTTP. Sequential is required to avoid raw.githubusercontent.com rate-limiting. Default mode: deterministic preview, no registry mutation. WOULD FLIP <lib> false→true (fetch exited 0) WOULD KEEP <lib> false (status=N) (fetch exited non-zero) --apply: atomically rewrite registry.json (tmp+renameSync), preserving _meta block and key ordering. Only flips false→true; never downgrades true→false on a single failed probe (per spec §6 — guards against transient network noise). Audit: appends one JSONL line per probed entry to .pi/.docs-registry-log.jsonl (action='probe', mode 0600), matching the existing register --i-approve audit-log pattern. approver field set to 'luci' only on --apply runs. Idempotent: a second --apply run with no state change produces no diff. Already-verified entries are skipped on subsequent runs. Reads .pi/skills/latest-docs/registry.json — same path the existing latest-docs.ts:84 reads from. Note: there are duplicate registry.json copies at .pi/skills/latest-docs/ and .omp/skills/latest-docs/ kept in sync separately; consolidating to a single source is filed as a follow-up (out of scope for this slice). Config-only slice; test-writer step skipped per documented SpecSafe deviation. Validator's empirical run was bounded by the dispatch tool timeout; any end-to-end probe should be run interactively. Spec-Slice: SPEC-20260427-014
Operator-facing documentation residue from slice-008.4: SKILL.md
"Example invocations", JSDoc headers, and README example blocks across
six skills still showed `bun run .pi/skills/<name>/bin/<name>.ts` even
though the operative tree under `omp` is `.omp/skills/`.
Scope: documentation only. Ten files touched, all operator-facing or JSDoc:
.omp/skills/{docs,github,latest-docs,linear,memory,push}/SKILL.md
.omp/skills/{docs,linear,memory}/bin/<name>.ts (JSDoc headers)
.omp/skills/memory/README.md
.omp/skills/{latest-docs,linear}/test/<name>.test.ts (test-name strings,
not run by package.json glob but doc-correct)
.omp/skills/latest-docs/SKILL.md (cache-display path .pi/ → .omp/)
Explicitly out of scope (slice-009 territory — A8 rollback invariant):
- latest-docs.ts:84 registry-read path (vanilla still reads .pi/ copy)
- latest-docs.ts cache-write path (would orphan existing caches)
- github.sh:245,332 linear-skill invocation (needs .pi/.omp parity check)
- probe-registry.ts read path (matches latest-docs.ts:84 by design)
- .pi/.honcho-state.json, .pi/extensions/, .pi/skills/ tree
The remaining .pi/ JSDoc references are accurate descriptions of what the
code actually does today; rewriting them without rewriting the code would
be a lie.
Tests: 271 pass / 15 skip / 0 fail (unchanged from slice-014).
Markdown-only slice; test-writer step skipped per documented SpecSafe deviation.
Spec-Slice: SPEC-20260427-015
Slice-015 (commit 4f8075f) committed with the Spec-Slice trailer but without the spec markdown on disk. The new `coherence check trailers-vs-linear` skill would surface this asymmetry as [orphan-trailer] on first dogfood run; this backfill closes that loop. The spec describes what slice-015 actually did (matches the trailer exactly) and enumerates the four `.pi/` references that survive deliberately as documented exceptions (§4.4) — making slice-009's eventual cleanup checklist explicit. Spec-Slice: SPEC-20260427-015
There are two registry.json files kept in sync by hand: - .pi/skills/latest-docs/registry.json (CANONICAL, read by both runtimes) - .omp/skills/latest-docs/registry.json (INERT under omp until slice-009) The omp-side latest-docs.ts:84 and probe-registry.ts both read only from the .pi/ copy. Anyone (human or Ghola) editing the .omp/ copy expecting it to take effect would have their changes silently ignored. Added _meta._inert_warning to the .omp/ copy explaining that the file is inert and pointing at the canonical source. Added _meta._duplicate_warning to the .pi/ copy noting the duplicate so editors keep both in sync. Both files still parse as valid JSON; full suite still 271/15/0. This is a discipline note, not a behavioral change. Slice-009 will consolidate the registry into a single source. Spec-Slice: SPEC-20260427-014
Two changes:
1. biome.json: include .omp/{hooks,tools,skills,test}/**/*.ts in
files.include and add .omp/.docs-cache to files.ignore. The original
config restricted Biome to .pi/extensions and .pi/skills only, so
the entire .omp/ tree was invisible to the formatter and linter.
Biome also reformatted biome.json itself to match its own
indentStyle: tab config (the original used 2-space indent).
2. Format-sweep on the four files I authored in slices 009/011/012:
.omp/skills/env-doctor/bin/env-doctor.ts
.omp/test/specsafe-cli.test.ts
.omp/test/coherence/coherence.test.ts
.omp/test/env-doctor.test.ts
Explicitly NOT in this commit: format-sweep on pre-existing files in
.pi/ and .omp/ that Biome would also fix now that they are in scope.
That's a tree-wide cleanup chore, not a pre-PR sweep, and touching the
.pi/ rollback hatch is slice-009 territory.
Tests: 271 / 15 / 0. Typecheck: clean.
No behavioral change.
… bin -g First real-shell run of env-doctor (Luci, fix/omp-function-path branch, 2026-04-27) surfaced two design gaps in slice-012: 1. `HONCHO_SESSION_ID` is meant to be derived per-cwd by the `omp` shell function as `<peer>-<basename-of-cwd>` (slice-008.6 wiring). The env-doctor was checking it as a static required env var, so any invocation outside the omp wrapper failed with 'missing HONCHO_SESSION_ID' AND the Honcho probe fell over because the bun subprocess called `client.session(undefined)`. Fix: drop SESSION_ID from the strict-required list, auto-derive it when unset, surface the derived value as a PASS-with-note, and inject it into the probe subprocess env so the SDK round-trip works. 2. The `omp` binary lives in bun's global bin directory, but the exact path varies by system (XDG_CACHE_HOME convention, BUN_INSTALL override, mise-managed bun, etc.). On Luci's machine it's `~/.cache/.bun/bin/omp` (per `bun pm bin -g`), not the `~/.bun/bin/omp` the first patch attempt assumed. Fix: `findOmpBinary` cascade is now (a) `command -v omp`, (b) bun's authoritative `bun pm bin -g` path, (c) `$BUN_INSTALL/bin` if set, (d) well-known fallbacks (`~/.bun/bin`, `~/.cache/.bun/bin`, `~/.cache/bun/bin`, `~/.local/share/bun/bin`, the namespaced .bun/install/global/node_modules/.bin path, `/usr/local/bin`). Honors `PI_ENVDOCTOR_OMP_CMD` stub override unconditionally. Tests unchanged: 17/17 env-doctor pass, full suite 271/15/0, typecheck clean. Smoke run on this repo (bun pm bin -g returns ~/.cache/.bun/bin): HONCHO env vars: PASS — HONCHO_SESSION_ID auto-derived: luci-pi omp config: PASS SKILL.md item (b) and (e) descriptions updated to match. Spec-Slice: SPEC-20260427-012
|
Mention Blocks like a regular teammate with your question or request: @blocks review this pull request Run |
Audit "next-action" was: dogfood Curia. Pre-condition surfaced during
PR review: invoking the system from a foreign project required either
(a) typing absolute paths to every skill bin every time, or (b)
manually scaffolding AGENTS.md / CLAUDE.md / specs/ / .omp symlink in
each project. Slice-016 makes that a one-shot.
New skill at .omp/skills/bootstrap/ — invoked from any project's cwd
(NOT pi-seshat itself; refuses with 'pi-seshat self' error). Default
dry-run prints a six-action preview; --i-approve applies:
1. mkdir -p .pi/, specs/, specs/briefs/, specs/archive/
2. symlink .omp -> <pi-seshat-root>/.omp (absolute target so it
survives directory-relative ops). --force-symlink replaces an
existing regular dir on conflict.
3. write AGENTS.md from templates/AGENTS.md (skip-if-exists). Generic
Seshat orchestrator content with {{PROJECT_NAME}}, {{HONCHO_WORKSPACE}},
{{HONCHO_PEER}} placeholder substitution.
4. write CLAUDE.md from templates/CLAUDE.md (skip-if-exists).
5. append nine .gitignore patterns (Set-based dedup; idempotent).
6. append one JSON line to .pi/.bootstrap-log.jsonl mode 0o600.
Idempotent: re-running on already-bootstrapped project is no-op
modulo a fresh audit-log line.
Risks documented in spec §6: (a) symlink target is absolute — pi-seshat
move requires re-bootstrap with --force-symlink, (b) AGENTS.md template
drift over time as pi-seshat evolves (skip-if-exists prevents auto-update),
(c) one-way: no `unbootstrap` command (manual rm -rf is the path).
After this lands, dogfooding any project becomes:
cd <project>
bun run /path/to/pi-seshat/.omp/skills/bootstrap/bin/bootstrap.ts --i-approve
# then: skill paths become bun run .omp/skills/<name>/bin/...
bun run .omp/skills/specsafe/bin/specsafe.ts begin <KEY>__<slug> oh-my-pi luci-<basename>
omp
Tests: 11 new (.omp/test/bootstrap.test.ts), full suite 282 pass /
15 skip / 0 fail (Δ +11 from slice-015 baseline of 271). Typecheck clean.
README.md updated: skills bullet now reflects nine total capabilities
(six external-surface + specsafe + env-doctor + coherence) plus the
bootstrap skill.
Spec-Slice: SPEC-20260427-016
luci-efe
changed the title
luci-efe
marked this pull request as ready for review
April 27, 2026 13:50
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Post-cutover audit (slice-008.4 landed
ompas default dispatch; this branch addresses what the audit surfaced as ranked enhancements). Full audit document atspecs/audit-2026-04-27.md.What this changes
Thirteen commits across eight SpecSafe slices plus four chore/fix/docs commits.
c2e85b2cce5f5c920aff2b31425c936fbc8f9a7017098ae874f8075f.pi/→.omp/consolidationab6899cdda67b422aac6a.omp/**tree; format new files8ceb02ebun pm bin -g77f4ce5Each
slice-commit carries aSpec-Slice:trailer.Why each slice exists
Slice-009 — omp slice-lifecycle CLI. Load-bearing. Vanilla Pi shipped three tools (
specsafe_begin/end/status) that wrote.pi/.honcho-state.json; the omp port consciously did not reimplement them, leaving the auto-commit-with-trailers hook permanently no-op'd becausestate.currentSlicewas alwaysnull. This slice restores lifecycle entry as a standalone CLI under.omp/skills/specsafe/, mirroring the existing CLI-skill pattern. State-file shape stays bit-identical to vanilla.Slice-010 — persona bash-or-rewrite repair. Four personas (
spec-writer,reviewer,steward,doc-scout) instructed the model to invoke/skill:latest-docsbut theirtools:frontmatter omittedbash, making the contract physically unexecutable from inside the agent. Addedbashwith a constrained-use clause limiting it to skill bin invocations.Slice-011 — coherence skill. Read-only cross-source consistency checker: detects drift between Linear issues,
specs/<KEY>__*.mdslice files, and recent commitSpec-Slice:trailers. Three subcommands, no--i-approvegate, no mutations. Calls existinglinearskill (DRY); test stub viaPI_COHERENCE_LINEAR_CMD.Slice-012 — env-doctor skill. Single-shot pre-flight verifier of the eight prerequisites every Ghola dispatch quietly assumes (HONCHO env, LINEAR auth, gh auth, omp install, agent symlinks, state-file integrity, agent honcho config). Stub-env-var contract on every external probe so the test suite runs without live API calls. Honcho probe distinguishes 401/403 (FAIL) from 404/'session not found' (PASS-with-note). Commit
8ceb02efollow-up: auto-deriveHONCHO_SESSION_IDfrom cwd basename when unset (matches theomp()shell function design); locateompbinary viabun pm bin -grather than assuming a fixed install path.Slice-013 — README + CLAUDE identity-model rewrite. Post-008.6 fidelity restoration. AGENTS.md was kept current with the slice-008.6 wiring (workspace=
oh-my-pi, session=luci-<basename-of-cwd>, noseshatpeer); README.md and CLAUDE.md fell behind. AGENTS.md is unchanged here.Slice-014 — latest-docs registry URL probe. One-shot pre-dogfood verification of the 11 registry entries flagged
verified:false. Reuses existinglatest-docs fetch <lib>(DRY, sequential to respect raw.githubusercontent.com rate limits).--applyflipsfalse→trueatomically; never downgradestrue→falseon a single failed probe.Slice-015 — SKILL.md + JSDoc path consolidation. Operator-facing residue from slice-008.4: SKILL.md "Example invocation" code blocks across six skills still showed
bun run .pi/skills/...even though the operative tree underompis.omp/skills/. Doc-only sweep; behavioral code paths in.pi/deliberately untouched (slice-009 territory).Slice-016 — project bootstrap skill. Propagates the pi-seshat system to any other project in one command. Invoked from a foreign project's cwd (refuses on pi-seshat self), creates
.pi/,specs/,specs/briefs/,specs/archive/; symlinks.omp/→<pi-seshat-root>/.omp/(absolute target); writesAGENTS.mdandCLAUDE.mdfrom templates with{{PROJECT_NAME}}/{{HONCHO_WORKSPACE}}/{{HONCHO_PEER}}placeholder substitution (skip-if-exists); appends nine.gitignorepatterns idempotently; audit-logs to.pi/.bootstrap-log.jsonl. Dry-run by default;--i-approveto apply;--force-symlinkfor.omp/regular-dir conflicts. One-way (nounbootstrap); spec §6 documents the symlink-on-pi-seshat-move risk.Verification
tsc --noEmit).pull_request: branches: [main]. Bun 1.3.6 in CI vs 1.3.13 locally;bun:testAPI stable across.Explicitly deferred (not in this PR)
These are slice-009-decommission work items, gated on completing at least one full SpecSafe slice under
ompend-to-end on a real project. The current PR preserves the A8 rollback hatch..pi/.honcho-state.jsonto.omp/.honcho-state.json..pi/.{push,linear,github,docs-registry,fallback,bootstrap}-log.jsonl)..pi/extensions/rollback hatch..pi/skills/tree (footgun comment landed indda67b4as defense-in-depth)..pi/-rooted code paths in active.omp/files (latest-docs.ts:84,probe-registry.ts:48,github.sh:245,332).--i-approveintegration, full rollback round-trip).How to dogfood (post slice-016)
After merging, in any target project (Curia, Matro, etc.):
Reviewer notes
fix/omp-function-path) is a misnomer — the original commit7c7bb7ewas indeed about theomp()shell function PATH, but the 13 commits added on top are the audit batch. Branch hygiene is cosmetic; the per-commit log is self-documenting.SPEC-20260427-015-doc-path-consolidation.mdwas authored after the slice-015 commit landed, to keep thecoherence check trailers-vs-linearskill from reporting itself as[orphan-trailer]on its own first dogfood run.dda67b4is documentation, not a fix. Real fix is slice-009.