ranxianglei · ranxianglei · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/devlog/2026-08-13_fix-smoke-harness/REQ.md b/devlog/2026-08-13_fix-smoke-harness/REQ.md
@@ -0,0 +1,44 @@
+# REQ - Repair the root smoke harness
+
+- Task ID: `2026-08-13_fix-smoke-harness`
+- Home Repo: `billion-context-opencode`
+- Created: 2026-08-13
+- Status: Done
+- Priority: P1
+- Owner: 5258MF
+- References: root `smoke.mjs`; PR #12
+
+## 1. Background & Problem Statement
+
+- **Context**: The monorepo build emits the public bundle under `packages/billion-context-opencode/dist/`, while the root smoke harness still uses the pre-monorepo bundle path.
+- **Current behavior (symptom)**: `npm run build && node smoke.mjs` fails before loading the plugin. If the path is corrected locally, the harness assumes assistant ref tags are always visible and recursively deletes the user's entire ACP cache before running.
+- **Expected behavior**: The root smoke loads the actual bundle, exercises compression with whichever visible boundary is available, and cleans up only the state file created by its unique session.
+- **Impact**: Contributors can run the documented end-to-end check without stale path failures, coupling to V1 ref presentation, or loss of local plugin state.
+
+## 2. Reproduction
+
+- **Environment**: Node 22/24; any supported OS.
+- **Minimal reproduction steps**:
+  1. Run `npm run build` from the repository root.
+  2. Run `node smoke.mjs` and observe that `./dist/index.js` does not exist.
+
+## 3. Constraints & Non-Goals
+
+- **Constraints**:
+  - Do not change package source, public APIs, persisted state schemas, or plugin behavior.
+  - Keep the smoke compatible with both current master and V1 assistant-tag omission from PR #12.
+- **Non-Goals**: Real OpenCode process coverage, V2 behavior changes, or replacing the planned e2e harness.
+
+## 4. Acceptance Criteria
+
+- **Correctness**:
+  - [x] The smoke imports the bundle produced by `npm run build`.
+  - [x] Compression/search/decompression complete whether or not the assistant exposes a ref tag.
+  - [x] The smoke never recursively deletes the shared ACP cache.
+- **Regression**:
+  - [x] `npm run typecheck`, `npm run test`, `npm run build`, and `node smoke.mjs` pass.
+
+## 5. Proposed Approach
+
+- Update the root harness path, select the assistant ref with a user-ref fallback, and remove only the unique smoke session state file.
+- **Rollback strategy**: Revert the smoke-only commit; no application or state migration is involved.
diff --git a/devlog/2026-08-13_fix-smoke-harness/WORKLOG.md b/devlog/2026-08-13_fix-smoke-harness/WORKLOG.md
@@ -0,0 +1,61 @@
+# WORKLOG - Repair the root smoke harness
+
+- Task ID: `2026-08-13_fix-smoke-harness`
+- Home Repo: `billion-context-opencode`
+- Status: Done
+- Updated: 2026-08-13
+
+## 1. Summary
+
+- **What was done**: Repaired the root smoke bundle path, removed its destructive shared-cache reset, and made its compression boundary independent of assistant tag presentation.
+- **Why**: Restore the documented post-build check while keeping it safe and compatible with the intentional V1 behavior in PR #12.
+- **Behavior / compatibility changes**: Test harness only; no package or runtime behavior changes.
+- **Risk level**: Low
+
+## 2. Change Log
+
+### Commits
+
+| Commit | Description |
+|--------|-------------|
+| Pending | Repair root smoke harness |
+
+### Key Files
+
+- `smoke.mjs` - load the monorepo bundle, use a visible fallback boundary, and clean up only the smoke session state.
+- `devlog/2026-08-13_fix-smoke-harness/` - task requirements and verification record.
+
+## 3. Design & Implementation Notes
+
+- **Entry point / key function**: Root `smoke.mjs` executed after `npm run build`.
+- **Key configuration items**: None.
+- **Key logic explanation**: Current master exposes an assistant ref, while PR #12 intentionally omits it. The smoke uses the assistant ref when present and otherwise the following user ref, so it tests the tool pipeline rather than enforcing presentation behavior already covered by converter unit tests.
+
+## 4. Testing & Verification
+
+### Build & Test Commands
+
+```sh
+npm run typecheck
+npm run test
+npm run build
+node smoke.mjs
+bash scripts/ci/check-pr.sh 2026-08-13_fix-smoke-harness upstream/master
+git diff --check
+```
+
+### Test Coverage
+
+- New/modified test files: `smoke.mjs`.
+- Test count: 26 total, 26 pass, 0 fail.
+- Key scenarios verified: The built bundle loads; current-master assistant refs are usable; with PR #12 stacked, the missing assistant ref falls back to the next user ref; compression, status, search, and decompression complete in both cases; the smoke-created state file is removed without touching other sessions.
+
+### Results
+
+- **PASS**: `npm run typecheck`, `npm run test` (26/26), `npm run build`, `node smoke.mjs`, PR validation, and `git diff --check`; a detached PR #12 + smoke-fix compatibility build/smoke also passed.
+
+## 5. Risk Assessment & Rollback
+
+- **Risk points**: The fallback boundary includes the next user message when assistant refs are intentionally hidden.
+- **Rollback method**: Revert the smoke-only commit.
+- **Compatibility notes**: No changes to dual-shape export, persisted state format, or config schema.
diff --git a/devlog/2026-08-13_system-prompt-align/REQ.md b/devlog/2026-08-13_system-prompt-align/REQ.md
@@ -0,0 +1,59 @@
+# REQ - Align the shared system prompt with PI
+
+- Task ID: `2026-08-13_system-prompt-align`
+- Home Repo: `billion-context-opencode`
+- Created: 2026-08-13
+- Status: Done
+- Priority: P1
+- Owner: 5258MF
+- References: https://github.com/ranxianglei/billion-context-opencode/pull/5, `billion-context-pi/src/system-prompt.ts`
+
+## 1. Background & Problem Statement
+
+- **Context**: The OpenCode adapter uses `acp-kernel@0.0.19` but its persistent system prompt includes only `COMPRESS_PHILOSOPHY` plus a shortened adapter-authored guide. The mature PI adapter also embeds the kernel's complete compression, tier-2, and tier-3 rules.
+- **Current behavior (symptom)**: Models receive limited guidance about historical summaries, search-before-decompress, detailed KEEP/DROP rules, multi-tier compression, block boundaries, and status-tool views.
+- **Expected behavior**: The shared OpenCode prompt contains the same four kernel rule constants used by PI, plus accurate OpenCode-specific `bili_` tool instructions.
+- **Impact**: Better summary fidelity and more reliable use of the existing compression, search, decompression, status, and multi-tier capabilities.
+
+## 2. Reproduction
+
+- **Environment**:
+  - Node: 22 or 24
+  - Dependency: `acp-kernel@0.0.19`
+- **Minimal reproduction steps**:
+  1. Inspect `packages/core/src/system-prompt.ts` on `master`.
+  2. Observe that only `COMPRESS_PHILOSOPHY` is imported from the kernel.
+  3. Compare it with PI's prompt and the exported kernel rule constants.
+- **Relevant configuration**: The shared `SYSTEM_PROMPT` is injected by both V1 and V2 entry paths.
+
+## 3. Constraints & Non-Goals
+
+- **Constraints**:
+  - Embed `COMPRESS_PHILOSOPHY`, `HOW_TO_COMPRESS_RULES`, `TIER2_DISTILL_RULES`, and `TIER3_CONDENSE_RULES` verbatim.
+  - Keep adapter-authored text host-neutral because the prompt is shared by V1 and V2.
+  - Add no dependencies and change no runtime behavior, tool schema, state, converter, or kernel configuration.
+- **Non-Goals**:
+  - Do not translate, alias, or replace the kernel's generic tool name `compress` with `bili_compress`.
+  - Do not claim the `compress` / `bili_compress` naming mismatch is solved.
+  - Do not modify `acp-kernel`, V1/V2 message conversion, or tool registration.
+
+## 4. Acceptance Criteria
+
+- **Correctness**:
+  - [x] All four kernel constants appear verbatim and exactly once in `SYSTEM_PROMPT`.
+  - [x] The prompt documents all four registered `bili_` tools and their key supported modes.
+  - [x] Adapter-authored ACP-tag guidance does not promise role- or host-specific tag coverage.
+  - [x] The prompt does not claim that the v0.0.19 nudge growth threshold adapts to model context size.
+  - [x] Kernel text still contains its original `` `compress` `` wording; no tool-name conversion is introduced.
+- **Performance / Stability**:
+  - [x] Only the static shared prompt grows; converter, state, tool, and kernel behavior remain unchanged.
+- **Regression**:
+  - [x] Focused system-prompt tests and all repository checks pass.
+
+## 5. Proposed Approach
+
+- **Affected modules & entry files**:
+  - `packages/core/src/system-prompt.ts`
+  - `packages/billion-context-opencode/tests/system-prompt.test.ts`
+- **Risks**: The kernel's generic `` `compress` `` name does not match the registered `bili_compress` tool. This pre-existing nudge mismatch becomes persistent when the full rule constant is embedded; the replacement PR must state this explicitly.
+- **Rollback strategy**: Revert the prompt and its focused tests; no state or schema migration is required.
diff --git a/devlog/2026-08-13_system-prompt-align/WORKLOG.md b/devlog/2026-08-13_system-prompt-align/WORKLOG.md
@@ -0,0 +1,73 @@
+# WORKLOG - Align the shared system prompt with PI
+
+- Task ID: `2026-08-13_system-prompt-align`
+- Home Repo: `billion-context-opencode`
+- Status: Done
+- Updated: 2026-08-13
+
+## 1. Summary
+
+- **What was done**: Expanded the current shared prompt with PI's four verbatim kernel rule constants, accurate OpenCode tool guidance, and four focused regression tests.
+- **Why**: Refresh PR #5 on the current monorepo and align the shared prompt with PI without hiding the kernel tool-name mismatch.
+- **Behavior / compatibility changes**: The static shared system prompt grows; runtime APIs and state are unchanged.
+- **Risk level**: Medium
+
+## 2. Change Log
+
+### Commits
+
+| Commit | Description |
+|--------|-------------|
+| This PR | Shared prompt alignment and focused regression tests |
+
+### Key Files
+
+- `packages/core/src/system-prompt.ts` — embed the complete kernel rules and host-neutral OpenCode guidance.
+- `packages/billion-context-opencode/tests/system-prompt.test.ts` — verify verbatim constants, tool modes, accurate host-neutral claims, and deliberate non-adaptation of the generic kernel tool name.
+- `devlog/2026-08-13_system-prompt-align/REQ.md` — record scope, constraints, and acceptance criteria.
+
+## 3. Design & Implementation Notes
+
+- **Entry point / key function**: `SYSTEM_PROMPT` in `packages/core/src/system-prompt.ts`.
+- **Key configuration items**: `acp-kernel@0.0.19`; no configuration changes.
+- **Key logic explanation**: Import and interpolate the four kernel constants verbatim; keep surrounding OpenCode instructions accurate for both host paths.
+
+## 4. Testing & Verification
+
+### Build & Test Commands
+
+```sh
+npm run typecheck
+npm run test
+npm run build
+bash scripts/ci/check-pr.sh 2026-08-13_system-prompt-align upstream/master
+```
+
+### Test Coverage
+
+- New/modified test files: `packages/billion-context-opencode/tests/system-prompt.test.ts`.
+- Test count: 30 total, 30 pass, 0 fail (four new prompt cases).
+- Key scenarios verified: Four kernel constants verbatim exactly once; four `bili_` guides and supported modes, including single-message decompression; accurate protected-output, host-neutral tag, and threshold claims; generic kernel `` `compress` `` remains unchanged.
+
+### Results
+
+- **PASS/FAIL**: `npm run typecheck` PASS; `npm run test` PASS (30/30); `npm run build` PASS; `scripts/ci/check-pr.sh` PASS; `git diff --check` PASS.
+- **Key logs/data**: Rendered prompt is 15,261 characters (~3,815 chars/4 estimate). Each of the four kernel constants occurs once; the kernel marker `When you call \`compress\`,` occurs once and the adapted `bili_compress` form occurs zero times.
+- **Independent review**: Two separate review agents approved after adversarial checks corrected the protected-output wording and restored the documented single-message decompression mode.
+
+## 5. Risk Assessment & Rollback
+
+- **Risk points**: Prompt size and the explicit unresolved `compress` / `bili_compress` name mismatch.
+- **Rollback method**:
+  - Revert commit(s): the eventual change commit.
+  - Rollback impact: Restores the shorter prompt; no persisted data changes.
+- **Compatibility notes**: No changes to dual-shape export, V1/V2 converters, persisted state, configuration schema, or tool definitions.
+
+## 6. Lessons Learned
+
+- Shared prompts must avoid claims that are true for one host message shape but not the other.
+- Verbatim kernel prompt reuse preserves upstream wording but also preserves its generic tool name; this is an explicit known limitation, not something this PR silently rewrites.
+
+## 7. Follow-ups
+
+- [ ] After this prompt PR is merged, investigate a separate OpenCode adapter PR for exact, fail-closed kernel tool-name adaptation if runtime evidence warrants it.
diff --git a/devlog/2026-08-13_v1-ref-tag-normalization/DESIGN.md b/devlog/2026-08-13_v1-ref-tag-normalization/DESIGN.md
@@ -0,0 +1,65 @@
+# DESIGN - V1-only ref-tag normalization
+
+- Task ID: `2026-08-13_v1-ref-tag-normalization`
+- Home Repo: `billion-context-opencode`
+- Created: 2026-08-13
+- Status: Accepted
+
+## 1. Problem Statement
+
+- **What problem are we solving?** The V1 converter currently copies kernel-prefixed ACP tags directly into both user and assistant text parts, which can encourage tag echo and displace user text from the start of the message.
+- **Why now?** PR #2 predates the monorepo and dual-shape refactor and must be refreshed without extending an unverified assumption to V2.
+
+## 2. Goals & Non-Goals
+
+- **Goals**:
+  - Keep V1 assistant history free of rendered ACP tags.
+  - Append V1 user tags after the body.
+  - Preserve kernel body mutations during V1 reassembly.
+  - Keep the original tag-etiquette wording on V1 only.
+- **Non-Goals**:
+  - No V2 adapter behavior changes.
+  - No changes to kernel rendering or ref allocation.
+
+## 3. Current Architecture
+
+- **How it works today**: V1 parts are projected to kernel cores; the kernel prefixes visible refs; `reassemble` copies the resulting core text back to the original V1 text part.
+- **Pain points**: Role-specific rendering and body/tag ordering cannot be expressed by blindly copying the core text.
+
+## 4. Proposed Architecture
+
+- **Overview**: Keep kernel processing unchanged, then normalize only V1 text during reassembly.
+- **Key components**:
+  - A strict XML ref-tag matcher for kernel-generated leading tags.
+  - A V1 reassembly helper that omits assistant tags, appends user tags, and honors changed core bodies for either role, including empty rewrites.
+  - A V1-only system-hook suffix containing the unchanged tag-etiquette text.
+- **Data flow**: `V1 host message -> CoreMessage -> kernel -> V1 patchRefTag -> V1 host message`.
+- **API / interface changes**: None.
+
+## 5. Design Decisions & Rationale
+
+| Decision | Options Considered | Chosen | Why |
+|----------|--------------------|--------|-----|
+| Scope | Apply to both converters; V1 only | V1 only | Only the V1 host contract has been locally verified. |
+| Assistant handling | Copy tag; relocate tag; omit rendered tag | Omit rendered tag | Avoids giving the model tag-shaped assistant examples while refs remain allocated in kernel state. |
+| Prompt placement | Shared core prompt; V1 system hook | V1 system hook | Prevents V1-specific behavior from being asserted to V2. |
+| Legacy `[mNNNNN]` parsing | Treat as a tag; preserve as text | Preserve as text | The adapter never generated that form, so stripping it risks user-content loss. |
+
+## 6. Impact Analysis
+
+- **Backward compatibility**: The dual-shape export, call/result pairing invariant, and persisted state are unchanged. Only V1 text presentation changes.
+- **Performance**: One small regex match and string comparison per surviving V1 text part.
+- **Security**: Strict matching avoids stripping arbitrary user prefixes.
+- **Dependencies**: No new packages.
+
+## 7. Migration Plan
+
+- **Steps**:
+  1. Refresh the old PR on a standards-compliant branch from current `master`.
+  2. Add V1-only regression tests and run all repository checks.
+  3. Replace PR #2 and close the superseded PR after review.
+- **Feature flags / gradual rollout**: Not required.
+
+## 8. Open Questions
+
+- [ ] Maintainer runtime confirmation on OpenCode V1 after merge.
diff --git a/devlog/2026-08-13_v1-ref-tag-normalization/REQ.md b/devlog/2026-08-13_v1-ref-tag-normalization/REQ.md
@@ -0,0 +1,59 @@
+# REQ - Normalize V1 ref-tag placement
+
+- Task ID: `2026-08-13_v1-ref-tag-normalization`
+- Home Repo: `billion-context-opencode`
+- Created: 2026-08-13
+- Status: Done
+- Priority: P1
+- Owner: 5258MF
+- References: https://github.com/ranxianglei/billion-context-opencode/pull/2
+
+## 1. Background & Problem Statement
+
+- **Context**: The V1 adapter reassembles kernel-rendered text directly into OpenCode messages.
+- **Current behavior (symptom)**: ACP tags are placed before user text and are also copied onto assistant history, giving the model examples it may echo in later replies.
+- **Expected behavior**: In V1, assistant text remains untagged and user tags are appended after the body while kernel body rewrites still reach the host message.
+- **Impact**: Prevents visible ACP XML fragments from being imitated by the model without changing ref allocation or compression state.
+
+## 2. Reproduction
+
+- **Environment**:
+  - Node: 22 or 24
+  - Host: OpenCode V1 message transform
+- **Minimal reproduction steps**:
+  1. Convert user and assistant V1 messages and process them with `renderTags: "text-only"`.
+  2. Reassemble the processed cores into V1 messages.
+  3. Observe that the unmodified adapter copies the kernel's leading tag into both roles.
+- **Relevant configuration**: Default adapter configuration.
+
+## 3. Constraints & Non-Goals
+
+- **Constraints**:
+  - Preserve the dual-shape export, persisted state, and call/result pairing invariant.
+  - Preserve the existing PR #2 tag-etiquette wording.
+  - Keep the change limited to the V1 host path.
+- **Non-Goals**:
+  - No changes to `messages-v2.ts` or claims about OpenCode V2 runtime behavior.
+  - No kernel changes and no persisted-state migration.
+
+## 4. Acceptance Criteria
+
+- **Correctness**:
+  - [x] V1 assistant text is reassembled without an ACP tag.
+  - [x] V1 user text keeps its body first and appends the ACP tag at the end.
+  - [x] Kernel text-body rewrites, including assistant and empty rewrites, are retained during V1 reassembly.
+  - [x] A literal user prefix such as `[m12345]` is not stripped.
+  - [x] The unchanged tag-etiquette text is injected only by the V1 system hook.
+- **Performance / Stability**:
+  - [x] Ref allocation, compression state, and tool call/result pairing remain unchanged.
+- **Regression**:
+  - [x] Four V1 message tests are added and all repository tests pass.
+
+## 5. Proposed Approach
+
+- **Affected modules & entry files**:
+  - `packages/billion-context-opencode/src/messages-v1.ts`
+  - `packages/billion-context-opencode/src/index.ts`
+  - `packages/billion-context-opencode/tests/messages.test.ts`
+- **Risks**: Incorrect tag parsing could drop user-authored content; the parser therefore recognizes only the ACP XML form generated by the kernel.
+- **Rollback strategy**: Revert the replacement PR commit; no state or schema rollback is needed.