@galaxy-stack/ai-coder-core 0.3.0-alpha.9 → 0.3.1

package/CHANGELOG.d/2026-09-19-advisory-guard-policy.md

@@ -4,7 +4,7 @@
 
 - `AiCoderRunBudget.noProgressPolicy`: `advisory` (mặc định) và `strict`.
 - `AiCoderRunBudget.observationNudgeThresholds` (mặc định `[3, 5, 8]`, theo
-  tư tưởng repeat-tool-reminder của DeepSeek Harness): các mốc nhắc advisory
+  tư tưởng repeat-tool-reminder của DSH gốc): các mốc nhắc advisory
   cho observation đọc-only; block chỉ xảy ra sau mốc cuối.
 - Checkpoint lưu `noProgress.policy` và `noProgress.observationNudgeThresholds`;
   resume với cấu hình khác bị từ chối `CHECKPOINT_INCOMPATIBLE`, checkpoint cũ

package/CHANGELOG.d/2026-09-26-binary-review-pipe-guidance-finalization-test.md

@@ -0,0 +1,14 @@
+# 2026-09-26 — Binary review không chặn, pipe guidance, test finalization
+
+Vùng: adapters/tools, prompt, runtime/test
+
+## Sau
+- `NodeWorkspaceReviewExecutor`: file **nhị phân/quá lớn** (không đọc được text ổn định) được review **theo hash** với `textReviewed: false` và `opaquePaths` disclosure, thay vì throw `WORKSPACE_REVIEW_FAILED`. `diff_review` evidence vẫn được cấp (hash bao gồm hash file). Entry đặc biệt (symlink/other) và thay đổi đồng thời vẫn fail-closed.
+- Prompt `editing-command-policy` 2.2.0 (prompt `ai-coder-single/2.8.0`): cấm pipe khi cần exit code (`| tail/head/cat/grep` che mã thoát), dùng `validate_project`.
+- Test deterministic `cache-hit.test.ts`: finalization append-only giữ prefix (>95%) còn projection thì sập (<50%).
+
+## Bối cảnh
+- Run GymFlow: `review_changes` fail trên `hero.png` ở turn ~31 rồi lại pass ở turn ~40 (không nhất quán), và model từng đọc sai exit code do pipe.
+
+## Test hồi quy
+- `test/workspace-review.test.ts` (binary), `test/cache-hit.test.ts` (finalization), `test/dist-smoke.mjs` (prompt version).

package/CHANGELOG.d/2026-09-26-cache-capability-and-mcp-reconnect.md

@@ -0,0 +1,16 @@
+# 2026-09-26 — Cache capability và MCP reconnect
+
+Vùng: runtime/prompt/adapters
+
+## Trước
+- Không có cách để route khai báo prefix cache hay cách cập nhật system prompt; runtime luôn ghi đè node 0 khi prompt đổi (lazy activation) → mất prefix cache.
+- MCP client không reconnect khi transport lỗi giữa run.
+
+## Sau
+- `ModelCapabilities` thêm `promptCache` và `systemPromptUpdate` (tùy chọn, mặc định coi như in-place).
+- `AiCoderContextManager.replaceSystemPrompt(..., mode)` hỗ trợ `in-history`: append system prompt mới sau history (giữ head byte-stable) khi route khai báo `in-history`; `in-place` giữ hành vi cũ và dọn các node in-history. `addItem` dedup theo content.
+- Ollama adapter khai báo `promptCache: "unknown"`, `systemPromptUpdate: "unknown"` (không tự nhận hỗ trợ).
+- `McpAgentClient` reconnect sau lỗi transport và retry **chỉ** tool read-only; mutation giữ unknown outcome.
+
+## Test hồi quy
+- `test/cache-prompt.test.ts`: in-history append + dedup; in-place rewrite + dọn node in-history.

package/CHANGELOG.d/2026-09-26-cache-hit-harness.md

@@ -0,0 +1,13 @@
+# 2026-09-26 — Cache-hit (prefix reuse) harness
+
+Vùng: runtime/prompt
+
+## Sau
+- `test/cache-hit.test.ts` mô phỏng prefix cache bằng token hoá request và đo **tỷ lệ tái dùng prefix** khi prompt đổi giữa run:
+  - `in-history` (append system prompt sau history) giữ prefix cũ → reuse cao (>90%);
+  - `in-place` (ghi đè node 0) → reuse sụp (<50%).
+- Assert ledger ghi `cachedInput` từ `prompt_cache_hit_tokens`/`cached_tokens`.
+- Đây là công cụ đo deterministic cho H-full; không cần provider.
+
+## Test hồi quy
+- `test/cache-hit.test.ts` (2 case); chạy trong `npm run verify`.

package/CHANGELOG.d/2026-09-26-cache-hit-rate-and-inhistory-option.md

@@ -0,0 +1,12 @@
+# 2026-09-26 — Cache hit rate, token_ledger event, và systemPromptUpdate option
+
+Vùng: runtime/context/adapters
+
+## Sau
+- `AiCoderTokenLedgerEntry` thêm `cacheHitRate`; log `trace.token_ledger` giờ có số này.
+- Runtime phát event `token_ledger` (`actualInput/cachedInput/cacheHitRate/outputTokens/turn`) để host hiển thị live.
+- `OllamaCodingModel` nhận option `systemPromptUpdate` (`in-place|in-history|unknown`, mặc định unknown).
+- `docs/CACHE_HIT.md`: cách đo, baseline Ollama, và quy trình kiểm chứng template trước khi bật in-history (kết quả gemma3: đọc system message mới nhất).
+
+## Test hồi quy
+- `test/cache-hit.test.ts`: cacheHitRate, capability in-history của adapter.

package/CHANGELOG.d/2026-09-26-cumulative-cache-hit.md

@@ -0,0 +1,13 @@
+# 2026-09-26 — Cache hit luỹ kế
+
+Vùng: context/runtime
+
+## Sau
+- `AiCoderTokenLedgerEntry` thêm `cumulativeActualInput`, `cumulativeCachedInput`, `cumulativeCacheHitRate`.
+- Event `token_ledger` mang thêm `cumulativeCacheHitRate` để host hiển thị số kiểu phiên (như DSH), tách khỏi per-turn.
+
+## Lý do
+- Per-turn `cacheHitRate` dao động mạnh khi context phình/đổi prefix; số luỹ kế phản ánh tỷ lệ prefix tái dùng của cả phiên.
+
+## Test hồi quy
+- `test/cache-hit.test.ts`: cộng dồn qua 2 lượt (200 actual / 120 cached → 0.6).

package/CHANGELOG.d/2026-09-26-finalization-prefix-and-verified-inhistory.md

@@ -0,0 +1,12 @@
+# 2026-09-26 — Finalization tool-free, allowlist in-history, cache accounting
+
+Vùng: runtime/adapters/context
+
+## Sau
+- Lượt finalization vẫn **tool-free** + project context (host conformance): lượt cuối không gửi tool definitions và không dispatch tool call. (Thử nghiệm giữ tools để tối ưu cache đã bị revert vì vi phạm conformance.)
+- `OllamaCodingModel` map `promptCache: "supported"` (Ollama báo `prompt_eval_cached_count`).
+- `verifiedSystemPromptUpdate(model)`: mặc định `in-history` cho model đã probe template (`gemma3*`, `deepseek-v4.1-flash*`); còn lại in-place. Option `systemPromptUpdate` luôn thắng.
+- Token ledger thêm `cachedInput`, `cacheHitRate` và luỹ kế phiên (`cumulativeCacheHitRate`); map `prompt_eval_cached_count` → `cachedInputTokens`.
+
+## Test hồi quy
+- `test/cache-hit.test.ts`: allowlist verified/unverified, capability override, cumulative ledger.

package/CHANGELOG.d/2026-09-26-generated-state-and-churn-guard.md

@@ -0,0 +1,16 @@
+# 2026-09-26 — Generated-state evidence boundary
+
+Vùng: runtime/host
+
+## Trước
+- Snapshotter coi `dist/`, `coverage/`, build output là durable writes, trong khi evidence verifier bỏ qua chúng. Hai chính sách lệch nhau khiến completion gate đòi validation/diff review cho build output, fingerprint đổi mỗi lần typecheck → run lặp build→xoá→validate tới `maxTurns`.
+
+## Sau
+- Policy generated-state **runtime-neutral** (`src/runtime/workspace-generated-path.ts`; adapter `workspace-generated-state.ts` re-export).
+- **Snapshotter** vẫn báo build output (`dist`, `build`, `coverage`, `out`) là **durable host effect** để `run_command` chứng minh mutation nó tạo; chỉ caches/`node_modules`/`*.tsbuildinfo`/`.DS_Store`/`.eslintcache` là derived. Evidence verifier luôn verify active files kể cả trong ignored dir.
+- **Runtime** lọc generated path khỏi **authored evidence** (`session.evidence.writes`) và khỏi `durableAuthoredProgress`: build output không reset no-progress budget cũng không đòi validation/write evidence.
+- Prompt `tool-policy` 2.3.0 (prompt `ai-coder-single/2.8.0`): load first-party skill trước; không pipe khi cần exit code.
+
+## Test hồi quy
+- `test/workspace-generated-state.test.ts`: predicate + snapshot durable/derived + fingerprint.
+- `test/dist-smoke.mjs` cập nhật prompt version.

package/CHANGELOG.d/2026-09-26-mcp-reconnect-fixture.md

@@ -0,0 +1,11 @@
+# 2026-09-26 — Failure-injection test cho MCP reconnect
+
+Vùng: adapters/mcp
+
+## Sau
+- Thêm fixture `test/mcp-crash-fixture.mjs` (tự `process.exit` giữa call) và `test/mcp-reconnect.test.ts`:
+  - tool read-only được reconnect + retry và thành công;
+  - tool mutating **không** bị retry ngầm, nhưng kết nối được phục hồi cho call sau.
+
+## Test hồi quy
+- `npx tsx --test test/mcp-reconnect.test.ts` (2 case).

package/CHANGELOG.d/2026-09-26-memory-hybrid-semantic-consolidation.md

@@ -0,0 +1,16 @@
+# 2026-09-26 — Memory hybrid ranking, semantic port và consolidation
+
+Vùng: adapters/memory
+
+## Trước
+- `search` chỉ sắp theo bm25 + updated_at; không có semantic, không có consolidation; vector/embedding không tồn tại.
+
+## Sau
+- Xếp hạng hybrid: lexical (FTS5 bm25) + **optional** semantic cosine + recency (half-life 14 ngày) + trust, trên cùng một candidate pool.
+- `AgentEmbeddingPort` (tùy chọn, capability-gated): host cấp provider thì lưu vector `Float32` vào `memory_embeddings(model, dims, vector)`; không có provider thì giữ lexical + recency. Vector được dọn bằng trigger khi xoá memory.
+- Không có lexical hit mà có embedding → fallback về recent active để rank semantic.
+- `consolidate({ keepSupersededRevisions })`: prune revision đã superseded + xoá orphan embedding; port có method tùy chọn.
+- CLI thêm `blackhole memory consolidate`.
+
+## Test hồi quy
+- `test/memory-hybrid.test.ts`: trust tie-break, semantic không cần lexical hit, prune superseded, embedding bị xoá khi forget.

package/CHANGELOG.d/2026-09-26-memory-recall-benchmark.md

@@ -0,0 +1,12 @@
+# 2026-09-26 — Memory recall benchmark
+
+Vùng: adapters/memory (test)
+
+## Sau
+- Bộ nhãn dùng chung `test/helpers/recall-set.ts`: 8 note tiếng Việt + 8 truy vấn paraphrase/cross-lingual, cùng embedder giả deterministic.
+- `test/memory-recall.test.ts` (offline): so recall@1/@3 lexical vs hybrid+semantic; kết quả đo `lexical@1=0% @3=13%` vs `semantic@1=100% @3=100%`.
+- `test/embedding-live.test.ts` (env-gated) chạy cùng bộ nhãn với model thật; live `bge-m3` cho `lexical@1=0% @3=13%` vs `semantic@1=88% @3=100%`.
+
+## Test hồi quy
+- Offline: `test/memory-recall.test.ts`.
+- Live: `GALAXY_LIVE_EMBEDDINGS=1 GALAXY_EMBEDDING_MODEL=bge-m3 GALAXY_EMBEDDING_BASE_URL=http://127.0.0.1:11434 npx tsx --test test/embedding-live.test.ts`.

package/CHANGELOG.d/2026-09-26-ollama-cache-usage.md

@@ -0,0 +1,14 @@
+# 2026-09-26 — Ollama báo cache; adapter map vào token ledger
+
+Vùng: adapters/provider
+
+## Trước
+- Bộ chuẩn hoá Ollama chỉ đọc `prompt_eval_count`/`eval_count`, bỏ qua cache; tài liệu nội bộ cho rằng Ollama không báo cache-hit.
+
+## Sau
+- Ollama >= 0.34 báo cache prefix: native `/api/chat` trả `prompt_eval_cached_count`, `/v1` trả `prompt_tokens_details.cached_tokens` (đã đo trực tiếp với `gemma3:latest`: 24/29 cached).
+- `ollama-chat-stream.ts` map `prompt_eval_cached_count` → `cachedInputTokens` trong usage; `token-ledger` đã có `cachedInput` nên log `trace.token_ledger` giờ hiển thị số cache-hit.
+- ⇒ Cache-hit của H-full **đo được live với Ollama, miễn phí**, không cần adapter DeepSeek-official.
+
+## Test hồi quy
+- `test/cache-hit.test.ts`: map `prompt_eval_cached_count` + ledger `cachedInput`.

package/CHANGELOG.d/2026-09-26-ollama-embeddings-provider.md

@@ -0,0 +1,13 @@
+# 2026-09-26 — Ollama embedding provider
+
+Vùng: adapters/memory/config
+
+## Sau
+- `adapters/node/memory/ollama-embeddings.ts`: `OllamaEmbeddings` gọi `/api/embed`, batch ≤64, response bounded 4 MiB, timeout, kiểm tra vector hợp lệ; **không gửi credential tới endpoint localhost**.
+- `ResolvedOllamaConnection` thêm optional `embeddingModel`/`embeddingBaseUrl` đọc từ cùng entry manual.
+- `test/ollama-embeddings.test.ts` (fake fetch): batch, credential localhost vs remote, response lỗi.
+- `test/embedding-live.test.ts` (skip mặc định, bật bằng `GALAXY_LIVE_EMBEDDINGS=1`): semantic recall cho paraphrase tiếng Việt và cross-lingual; đã chạy live với `bge-m3`.
+
+## Test hồi quy
+- Deterministic: `test/ollama-embeddings.test.ts`.
+- Live: `GALAXY_LIVE_EMBEDDINGS=1 GALAXY_EMBEDDING_MODEL=bge-m3 GALAXY_EMBEDDING_BASE_URL=http://127.0.0.1:11434 npx tsx --test test/embedding-live.test.ts`.

package/CHANGELOG.d/2026-09-26-rerecord-live-fixture.md

@@ -0,0 +1,6 @@
+# 2026-09-26 — Re-record live replay fixture
+
+Vùng: testing
+
+## Sau
+- `testing/live/recordings/01-write-and-validate.json` được re-record với prompt `ai-coder-single/2.8.0` (contract + recorded bodies). Fixture cũ ghi `2.6.0` nên `recorded-session-replay` báo "Re-record the fixture".

package/CHANGELOG.d/2026-09-26-skill-index-signing.md

@@ -0,0 +1,11 @@
+# 2026-09-26 — Ký số skill index (Ed25519 trust)
+
+Vùng: adapters/skills
+
+## Sau
+- Index nhận `signature` (base64 Ed25519) trên canonical JSON (key sắp xếp, bỏ `signature`).
+- `SkillMarketplace` nhận `publicKey` (PEM); khi có key thì index **bắt buộc** chữ ký hợp lệ, sai/thiếu bị từ chối (fail-closed). Không key → unsigned chấp nhận.
+- Export `stableSkillIndexJson`, `signSkillIndex`, `verifySkillIndexSignature`; script publisher `scripts/sign-skill-index.mjs`.
+
+## Test hồi quy
+- `test/skill-marketplace.test.ts`: ký hợp lệ cài được; tamper/thiếu chữ ký/sai key đều bị từ chối.

package/CHANGELOG.d/2026-09-26-skill-version-and-marketplace.md

@@ -0,0 +1,14 @@
+# 2026-09-26 — Skill versioning và marketplace
+
+Vùng: adapters/skills
+
+## Trước
+- Skill chỉ có name/description; không version, không cài/update; không có registry.
+
+## Sau
+- Frontmatter nhận thêm `version` (semver) và `tags`; `SkillDescriptor` expose `version`/`tags`. Sai định dạng bị từ chối.
+- `SkillMarketplace`: index JSON (schemaVersion 1) từ **path hoặc HTTP(S) URL**; resolve semver (`*`, exact, `^`, `~`); tải nội dung (bounded), **verify sha256**, ghi atomic mode 0600 ngoài workspace; `search/install/update/remove/listInstalled`; chặn downgrade ngầm và path traversal.
+- Vì core là typed ports, marketplace không tự chạy; host cấu hình index.
+
+## Test hồi quy
+- `test/skill-marketplace.test.ts`: install/resolve/update/remove, idempotent, verify sha256 (tamper reject), discoverable qua `DirectorySkills`.

package/CHANGELOG.d/2026-09-27-workspace-derived-build-output.md

@@ -0,0 +1,16 @@
+# 2026-09-27 — Build output là derived, manifest workspace
+
+Vùng: runtime/host
+
+## Sau
+- Snapshotter dùng `isGeneratedWorkspacePath(segments)` nên `dist/`, `build/`,
+  `coverage/` và `*.tsbuildinfo` được xếp `derived` thay vì `durable write`.
+  Validation/diff-review không còn stale khi build sinh lại output — trước đây
+  gate lặp tới `maxTurns`.
+- Hợp nhất derived dirs từ `.gitignore` (pattern thư mục) và từ
+  `.galaxy/workspace.json` — manifest agent cập nhật khi dự án mở rộng.
+  `.galaxy/` là generated state nên ghi manifest không void validation.
+- Prompt nhắc ghi `.galaxy/workspace.json` sau khi validation sinh build output.
+
+## Test hồi quy
+- `npm run verify` (core) + `npm test` galaxy-code (90/90).

package/CHANGELOG.d/2026-09-28-advisory-lenh-check-va-server.md

@@ -0,0 +1,26 @@
+# 2026-09-28 — Advisory khi lệnh shell trùng check dự án hoặc chạy server
+
+Vùng: tools/prompt
+
+## Trước
+- Model chạy `bun test`/`tsc --noEmit` bằng shell song song với `validate_project`
+  — tốn lượt mà **không** sinh completion evidence (3 lần trong một bước E2E).
+- Model tự bật dev server để "chứng minh" dự án chạy được (xem mục 1 của journal).
+
+## Sau
+- `command.run` trả advisory khi lệnh là check **toàn dự án** hoặc khi lệnh giống
+  server/watch. Advisory của check nói **đúng call cần gọi**, suy ra từ chính lệnh:
+  `cd gymflow-backend && bunx tsc --noEmit` ⇒
+  `validate_project {"path":"gymflow-backend","checks":["typecheck"]}` (đường dẫn lấy
+  từ `cd` trong lệnh, nếu không có thì lấy `cwd` của tool call); nhận cả dạng
+  runner `bunx`/`npx`/`pnpx`/`exec`/`dlx`.
+- Lệnh nhắm một file (`bun test src/x.spec.ts`) **không** bị nhắc, vì
+  `validate_project` không diễn đạt được; package reference (`vite@latest`) và
+  đường dẫn (`assets/vite.svg`) không bị coi là server.
+- Prompt `editing-command-policy` v2.3.0: server nền không phải supervision cũng
+  không phải evidence; xoá file probe trước khi validate; không probe API bằng
+  `bun -e`/`node -e`.
+
+## Test hồi quy
+- `test/command-shape.test.ts`.
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 7, 8, 9.

package/CHANGELOG.d/2026-09-28-clamp-tham-so-vuot-cap.md

@@ -0,0 +1,20 @@
+# 2026-09-28 — Clamp tham số vượt cap thay vì từ chối tool call
+
+Vùng: tools/adapter
+
+## Trước
+- `run_command` với `timeoutMs` > 600000 trả `INVALID_TOOL_ARGUMENTS`
+  (`$.timeoutMs lớn hơn maximum=600000.`): cả lệnh không chạy, mất một lượt model,
+  dù host luôn tự chặn ở 10 phút.
+
+## Sau
+- `clampAiCoderJsonSchemaNumbers` kéo số vượt `maximum` về đúng cap, đi đệ quy
+  theo `properties`/`items`/`$ref`, và nối ghi chú
+  `Arguments clamped to host limits: …` vào summary trả cho model.
+- Giá trị dưới `minimum`, sai kiểu và mọi vi phạm khác vẫn fail như cũ.
+- Kèm sửa test `contracts.test.ts` còn đọc `input.precondition.kind` sau khi
+  precondition thành optional — lỗi này làm `npm run typecheck` (và CI) đỏ ở HEAD.
+
+## Test hồi quy
+- `test/json-schema-clamp.test.ts` (5 case), `npm run verify`.
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 2 và 3.

package/CHANGELOG.d/2026-09-28-digest-context-item.md

@@ -0,0 +1,16 @@
+# 2026-09-28 — Fingerprint từng context item mỗi lượt (chẩn đoán cache)
+
+Vùng: context/diagnostics
+
+## Trước
+- `context_diagnostic` chỉ có tổng token theo nhóm; khi cache hit thấp không thể
+  biết block nào đổi đã reset prefix cache.
+
+## Sau
+- Mỗi lượt ghi thêm `itemDigests` (index, id, kind, tokens, hash theo đúng thứ tự
+  gửi, tối đa 24 item) và `toolHash`/`toolTokens` của block tool. Diff hai lượt
+  liên tiếp là ra item phá cache — chính cách tìm ra mục 6 của journal.
+- Chỉ thêm dữ liệu chẩn đoán; không đổi cách chọn context hay nội dung prompt.
+
+## Test hồi quy
+- `npm run verify`; dùng thực tế trong E2E 2026-09-28.

package/CHANGELOG.d/2026-09-28-gate-bo-qua-path-da-xoa.md

@@ -0,0 +1,20 @@
+# 2026-09-28 — Gate không đòi validation cho path đã bị xoá
+
+Vùng: runtime/completion-gate
+
+## Trước
+- Mọi write trong evidence đều bị đòi validation sau nó, kể cả khi path **đã bị xoá**
+  trong cùng run. Một bước E2E viết file probe `.e2e-sale-check.ts` để chạy thử
+  luồng bán gói rồi xoá đi, và vẫn nhận 2 mục
+  `WRITE_NOT_VALIDATED: .e2e-sale-check.ts` ⇒ phải validate lại vô ích.
+
+## Sau
+- `removedPaths` = các path có `afterHash === null` (đã xoá); write tới path đó
+  (hoặc chính write xoá) **không** còn đòi validation. Kiểm tra
+  `WRITE_EVIDENCE_INVALID` vẫn áp dụng cho mọi write như cũ.
+- Không nới lỏng gì khác: write còn tồn tại vẫn phải có validation sau nó.
+
+## Test hồi quy
+- `test/completion-gate-scope.test.ts`: "a path written and then removed does not
+  demand validation".
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 11.

package/CHANGELOG.d/2026-09-28-ngan-sach-luot-finalization.md

@@ -0,0 +1,20 @@
+# 2026-09-28 — Hết ngân sách lượt thì finalize một lượt trước khi fail
+
+Vùng: runtime
+
+## Trước
+- Chạm `maxTurns` là ném `MAX_TURNS` ngay, kể cả khi evidence đã đủ: một bước E2E
+  fail với `reached maxTurns=48` ngay sau khi tool cuối trả "Project validation
+  passed" (11 validation pass, 21 mutation, hai call cuối là review → validate).
+- CLI không có cách nâng trần, deadline host còn bị hard-code 15 phút.
+
+## Sau
+- Hết lượt ⇒ cấp **đúng một lượt finalization không tool** để model báo cáo trạng
+  thái đã có; completion gate vẫn là bên quyết định; hết lượt lần hai mới fail
+  `MAX_TURNS`. Có trace `policy_decision: budget_finalization_turn`.
+- CLI thêm `--max-turns <n>` và `--run-minutes <n>`; budget controller được canh
+  thẳng với deadline host.
+
+## Test hồi quy
+- `npm run verify` (core) + `npm run check` (galaxy-code, test parse flag).
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 5.

package/CHANGELOG.d/2026-09-28-scope-cua-project-validate.md

@@ -0,0 +1,22 @@
+# 2026-09-28 — project.validate ghi đúng phạm vi theo project path
+
+Vùng: tools/executor
+
+## Trước
+- Mọi validation sinh từ `project.validate` đều được ghi `scope: "workspace"`,
+  kể cả khi check chạy trong một subproject (`path: "frontend"`), và không kèm
+  `paths`. Hệ quả: gate coi nó bao phủ cả workspace nên **một write ở package
+  khác** cũng void (đo được: sửa `backend/` làm stale `lint:frontend` và
+  `build:frontend`, buộc validate lại toàn bộ — mất nguyên một vòng).
+- Vì `paths` luôn rỗng, quy tắc staleness theo phạm vi ở gate không có tác dụng
+  với evidence thật.
+
+## Sau
+- `validationScopeForProjectPath(projectPath)`: `"."`/`""` ⇒ `scope: "workspace"`
+  (vẫn nghiêm ngặt như cũ); subproject ⇒ `scope: "paths"`, `paths: [<path đã
+  chuẩn hoá>]`.
+- Gate nhờ đó chỉ vô hiệu validation khi chính subproject đó bị sửa.
+
+## Test hồi quy
+- `test/validation-scope.test.ts` + `test/completion-gate-scope.test.ts`.
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 4 (bổ sung).

package/CHANGELOG.d/2026-09-28-staleness-theo-pham-vi.md

@@ -0,0 +1,22 @@
+# 2026-09-28 — Validation chỉ stale theo phạm vi nó bao phủ
+
+Vùng: runtime/completion-gate
+
+## Trước
+- Gate so fingerprint **toàn workspace**, nên viết `README.md` hay sửa package
+  khác cũng void **mọi** validation ⇒ bắt validate lại (một ngày chạy: 21
+  write-sau-validation, 5 lần chặn `WORKSPACE_EVIDENCE_STALE`, 340 mục
+  `WRITE_NOT_VALIDATED`).
+
+## Sau
+- Validation chỉ bị void khi có **write trong phạm vi nó bao phủ** sau nó.
+- Write tài liệu (`.md/.mdx/.txt`, `docs/`, LICENSE/CHANGELOG) không đòi và
+  không void validation.
+- Nếu fingerprint workspace lệch mà **không hoạt động nào giải thích được** (thay
+  đổi ngoài luồng) thì mọi validation vẫn bị void; scope `workspace` vẫn nghiêm
+  ngặt như cũ.
+
+## Test hồi quy
+- `test/completion-gate-scope.test.ts` (6 case) + test staleness cũ trong
+  `test/runtime.test.ts`.
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 4.

package/CHANGELOG.d/2026-09-28-thong-bao-guard-dependency.md

@@ -0,0 +1,24 @@
+# 2026-09-28 — Lỗi guard dependency nói rõ đường đọc được phép
+
+Vùng: host/workspace-port
+
+## Trước
+- `readText` trong `node_modules` đã cho phép `package.json`, `README.md`,
+  `*.d.ts` (đúng như orbit-mcp docs mô tả: "đọc .d.ts và package.json trong
+  node_modules (được phép) — KHÔNG grep cả cây"), nhưng `searchText`/`searchPaths`
+  bị chặn bằng message chung *"không đọc source thư viện bằng file tools"*.
+- Hệ quả đo được: model thử lại grep/glob 8 lần trong chiến dịch E2E — đây là mã
+  lỗi tool **nhiều nhất**, mỗi lần mất một lượt, vì message không nói rằng đọc
+  thẳng một file `.d.ts` là hợp lệ.
+
+## Sau
+- `dependencySearchError` cho search/glob: nói rõ grep/glob cả cây không được phép
+  **và** `read_file` trên `package.json`/`README.md`/`*.d.ts` trong node_modules
+  thì hợp lệ; suggestedAction trỏ về MCP tools/skill docs.
+- Không nới quyền đọc source: `.js`/`.mjs`/`.cjs` vẫn bị chặn như cũ.
+
+## Test hồi quy
+- `test/workspace-generated-state.test.ts`: "dependency trees allow ground-truth
+  reads but refuse search and glob".
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục "không phải lỗi" (guard
+  node_modules) — nay có hướng dẫn đúng trong message.

package/CHANGELOG.d/2026-09-28-thu-tu-mandatory-state-cache.md

@@ -0,0 +1,20 @@
+# 2026-09-28 — Đặt run state đổi-mỗi-lượt ra sau prefix ổn định (cache)
+
+Vùng: context/runtime
+
+## Trước
+- `runtime-mandatory-state` (turn budget, editedFiles, phase, nextAction — viết
+  lại mỗi lượt) nằm ở thứ tự mặc định của checkpoint, ngay sau system prompt.
+- Đo trên E2E: item này **đổi đầu tiên trên 38/40 lượt**, `cachedInput` kẹt ở
+  10.752 token suốt 17 lượt dù context tăng tới 60–90k ⇒ cache hit 40%, 1,42M
+  token bị tính lại.
+
+## Sau
+- Block đó mang `physicalOrder` muộn (sau history, ngay trước message của lượt
+  mới) nên toàn bộ prefix ổn định (policy, goal, checkpoint, files, tools, history)
+  vẫn cache được; đo lại: 40% → 61% toàn run, bước 1 từ 10% → 59–73%.
+
+## Test hồi quy
+- `test/context.test.ts`: "the mutable mandatory state is ordered after the stable
+  prefix".
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md mục 6.

package/CHANGELOG.d/2026-09-29-advisory-doc-source-node-modules-bang-shell.md

@@ -0,0 +1,24 @@
+# 2026-09-29 — Advisory khi đọc source node_modules bằng shell
+
+Vùng: tools/adapter
+
+## Trước
+- Guard của host chặn `read_file`/`search_text` trong `node_modules`, nhưng **lệnh
+  shell thì không**: bước `s09-security` của E2E đã chạy
+  `cd backend/node_modules/@galaxy-stack/orbit-security/dist && cat …` để đọc source
+  thư viện — tốn context vào phần không phải tài liệu, đúng thứ guard sinh ra để tránh.
+
+## Sau
+- `dependencyShellReadAdvisory(command)`: khi lệnh vừa có trình đọc
+  (`cat|bat|head|tail|less|more|sed|awk|grep|rg|strings`) vừa trỏ vào `node_modules/`,
+  `command.run` trả advisory nói rõ: đọc source thư viện qua shell cũng tốn như qua file
+  tools; hãy đọc một `package.json`/`README.md`/`*.d.ts` cụ thể (được phép) hoặc dùng
+  MCP knowledge + skill.
+- Không chặn: đọc file workspace, `ls` thư mục dependency hay lệnh không có trình đọc
+  vẫn im lặng.
+
+## Test hồi quy
+- `test/command-shape.test.ts`: "reading library source through the shell is called
+  out, a declaration read is not".
+- Incident: galaxy-code/docs/TEST_FAILURE_ANALYSIS.md — mục "Quan sát chính sách" và
+  phần "Xác minh release".

package/CHANGELOG.d/2026-09-29-retry-khi-model-dung-vi-output-length.md

@@ -0,0 +1,21 @@
+# 2026-09-29 — Dừng vì trần output ('length') là lỗi tạm thời, không phải fail run
+
+Vùng: runtime
+
+## Trước
+- Khi model dừng với `stopReason: 'length'` (đốt hết ngân sách output, thường là cho
+  hidden thinking, trước khi gọi tool hay trả lời), runtime ném
+  `INVALID_MODEL_STREAM` **không retryable** ⇒ cả run fail. Đo được: bước
+  `s22-seed-50` của E2E chết ở trạng thái `planning` với
+  `Model stopped with non-final reason 'length'.`, 0 lần retry.
+
+## Sau
+- `length` được phân loại là `CodingProviderError("MALFORMED_STREAM", …, retryable: true,
+  retryMode: "without_thinking")` ⇒ vòng retry có sẵn của runtime thử lại **đúng context
+  đã kiểm chứng** với hidden thinking tắt, trong ngân sách `maxModelRetries`; thông báo
+  ghi rõ số tool call và số ký tự content đã phát trước khi hết ngân sách.
+- `unknown` vẫn fail như cũ (có thể là lỗi stream thật).
+
+## Test hồi quy
+- `test/runtime.test.ts`: "an output-limit stop retries the verified context with
+  thinking disabled".

package/CHANGELOG.d/README.md

@@ -14,3 +14,6 @@ live.
 
 CHANGELOG.md (file công khai trên npm/GitHub) viết tiếng Anh; fragment ở đây là
 ghi chú làm việc nội bộ, viết tiếng Việt cũng được.
+
+Khi mục `[0.3.0]` được gom, các fragment **được giữ lại** thay vì xoá, vì mục
+CHANGELOG trỏ link tới từng fragment; chỉ xoá khi mục tương ứng cũng bỏ link.

package/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Times are recorded in Asia/Ho_Chi_Minh (+07:00). Per-fix fragments are filed in
 [CHANGELOG.d](CHANGELOG.d/README.md) and compiled here at release time.
 
+## [0.3.1] - 2026-09-29 05:25 +07:00
+
+### Fixed
+
+- Advisory khi đọc source node_modules bằng shell. See [CHANGELOG.d fragment](CHANGELOG.d/2026-09-29-advisory-doc-source-node-modules-bang-shell.md).
+- Dừng vì trần output ('length') là lỗi tạm thời, không phải fail run. See [CHANGELOG.d fragment](CHANGELOG.d/2026-09-29-retry-khi-model-dung-vi-output-length.md).
+
+## [0.3.0] - 2026-09-28 23:10 +07:00
+
+First verified stable line: the 25-prompt end-to-end flow completes with this
+runtime. The failure journal that drove the changes below lives in
+`galaxy-code/docs/TEST_FAILURE_ANALYSIS.md`.
+
+### Changed
+
+- Prompt-cache layout: the mutable run state moved after the stable prefix, so a turn
+  re-bills only its tail (measured run-wide 40% → 61%, per step 10% → 59–87%).
+- `project.validate` records the scope it really covered, so a check in one package
+  is no longer invalidated by a write in a sibling package.
+- The completion gate is scope-aware: documentation writes need no validation, a path
+  written and then removed needs none either, and untracked workspace drift still
+  voids every validation.
+- Reaching the turn budget grants one tool-free finalization turn instead of failing a
+  run whose evidence is already satisfied; `maxTurns` and the host deadline are
+  configurable through the CLI.
+- Arguments above a schema cap are clamped and reported rather than rejected; a
+  shell-run project check and a long-running server answer with an advisory that names
+  the exact `validate_project` call; a refused dependency search names the read that
+  is allowed.
+- `context_diagnostic` fingerprints every context item and the tool block each turn —
+  that is how the cache regression above was found.
+
+<details>
+<summary>Per-fix trail: 39 fragments (2026-09-19 … 2026-09-28)</summary>
+
+- Advisory guard policy cho observation (2026-09-19 00:15 +07:00) (core). [fragment](CHANGELOG.d/2026-09-19-advisory-guard-policy.md)
+- Sửa parser citation bị nhiễu Markdown (2026-09-19 11:55 +07:00) (core). [fragment](CHANGELOG.d/2026-09-19-research-citation-parsing.md)
+- Lưu evidence khi citation bị từ chối (2026-09-19 23:15 +07:00) (core). [fragment](CHANGELOG.d/2026-09-19-research-rejection-evidence.md)
+- Node test reporter ghi nhật ký (2026-09-18 23:45 +07:00) (core). [fragment](CHANGELOG.d/2026-09-19-test-journal-reporter.md)
+- Remediation cho RESEARCH_EVIDENCE_MISSING (2026-09-21 02:20 +07:00) (core). [fragment](CHANGELOG.d/2026-09-21-evidence-missing-remediation.md)
+- Nudge nhận diện bằng arguments hash (2026-09-21 00:55 +07:00) (core). [fragment](CHANGELOG.d/2026-09-21-observation-nudge-context.md)
+- Retry delay theo scenario budget + deadline-aware skip (2026-09-22 07:25 +07:00) (core). [fragment](CHANGELOG.d/2026-09-22-model-retry-budget.md)
+- Recovery turn trước no-progress pause (2026-09-22 01:07 +07:00) (core). [fragment](CHANGELOG.d/2026-09-22-no-progress-recovery-turn.md)
+- Agent platform foundation (core). [fragment](CHANGELOG.d/2026-09-23-agent-platform.md)
+- # 0.3.0-alpha.7 — 2026-09-23 07:00 +07:00 (core). [fragment](CHANGELOG.d/2026-09-23-conservative-output-reserve.md)
+- Request-scoped approvals and scratch workspace review (core). [fragment](CHANGELOG.d/2026-09-24-approval-workspace-review.md)
+- Incremental Ollama streaming (core). [fragment](CHANGELOG.d/2026-09-24-incremental-ollama.md)
+- Tail-anchored tool output bounding (core). [fragment](CHANGELOG.d/2026-09-25-tail-anchored-bounding.md)
+- Binary review không chặn, pipe guidance, test finalization (adapters/tools, prompt, runtime/test). [fragment](CHANGELOG.d/2026-09-26-binary-review-pipe-guidance-finalization-test.md)
+- Cache capability và MCP reconnect (runtime/prompt/adapters). [fragment](CHANGELOG.d/2026-09-26-cache-capability-and-mcp-reconnect.md)
+- Cache-hit (prefix reuse) harness (runtime/prompt). [fragment](CHANGELOG.d/2026-09-26-cache-hit-harness.md)
+- Cache hit rate, token_ledger event, và systemPromptUpdate option (runtime/context/adapters). [fragment](CHANGELOG.d/2026-09-26-cache-hit-rate-and-inhistory-option.md)
+- Cache hit luỹ kế (context/runtime). [fragment](CHANGELOG.d/2026-09-26-cumulative-cache-hit.md)
+- Default model: deepseek-v4.1-flash:cloud (core). [fragment](CHANGELOG.d/2026-09-26-default-model-deepseek.md)
+- Finalization tool-free, allowlist in-history, cache accounting (runtime/adapters/context). [fragment](CHANGELOG.d/2026-09-26-finalization-prefix-and-verified-inhistory.md)
+- Generated-state evidence boundary (runtime/host). [fragment](CHANGELOG.d/2026-09-26-generated-state-and-churn-guard.md)
+- Failure-injection test cho MCP reconnect (adapters/mcp). [fragment](CHANGELOG.d/2026-09-26-mcp-reconnect-fixture.md)
+- Memory hybrid ranking, semantic port và consolidation (adapters/memory). [fragment](CHANGELOG.d/2026-09-26-memory-hybrid-semantic-consolidation.md)
+- Memory recall benchmark (adapters/memory (test)). [fragment](CHANGELOG.d/2026-09-26-memory-recall-benchmark.md)
+- Ollama báo cache; adapter map vào token ledger (adapters/provider). [fragment](CHANGELOG.d/2026-09-26-ollama-cache-usage.md)
+- Ollama embedding provider (adapters/memory/config). [fragment](CHANGELOG.d/2026-09-26-ollama-embeddings-provider.md)
+- Re-record live replay fixture (testing). [fragment](CHANGELOG.d/2026-09-26-rerecord-live-fixture.md)
+- Ký số skill index (Ed25519 trust) (adapters/skills). [fragment](CHANGELOG.d/2026-09-26-skill-index-signing.md)
+- Skill versioning và marketplace (adapters/skills). [fragment](CHANGELOG.d/2026-09-26-skill-version-and-marketplace.md)
+- Build output là derived, manifest workspace (runtime/host). [fragment](CHANGELOG.d/2026-09-27-workspace-derived-build-output.md)
+- Advisory khi lệnh shell trùng check dự án hoặc chạy server (tools/prompt). [fragment](CHANGELOG.d/2026-09-28-advisory-lenh-check-va-server.md)
+- Clamp tham số vượt cap thay vì từ chối tool call (tools/adapter). [fragment](CHANGELOG.d/2026-09-28-clamp-tham-so-vuot-cap.md)
+- Fingerprint từng context item mỗi lượt (chẩn đoán cache) (context/diagnostics). [fragment](CHANGELOG.d/2026-09-28-digest-context-item.md)
+- Gate không đòi validation cho path đã bị xoá (runtime/completion-gate). [fragment](CHANGELOG.d/2026-09-28-gate-bo-qua-path-da-xoa.md)
+- Hết ngân sách lượt thì finalize một lượt trước khi fail (runtime). [fragment](CHANGELOG.d/2026-09-28-ngan-sach-luot-finalization.md)
+- project.validate ghi đúng phạm vi theo project path (tools/executor). [fragment](CHANGELOG.d/2026-09-28-scope-cua-project-validate.md)
+- Validation chỉ stale theo phạm vi nó bao phủ (runtime/completion-gate). [fragment](CHANGELOG.d/2026-09-28-staleness-theo-pham-vi.md)
+- Lỗi guard dependency nói rõ đường đọc được phép (host/workspace-port). [fragment](CHANGELOG.d/2026-09-28-thong-bao-guard-dependency.md)
+- Đặt run state đổi-mỗi-lượt ra sau prefix ổn định (cache) (context/runtime). [fragment](CHANGELOG.d/2026-09-28-thu-tu-mandatory-state-cache.md)
+
+</details>
+
 ## [0.3.0-alpha.7] - 2026-09-23 07:00 +07:00
 
 ### Fixed
@@ -88,7 +165,7 @@ this version; the internal working versions `0.2.0`–`0.2.2` were never publish
 - Configurable observation guard policy:
   - `AiCoderRunBudget.noProgressPolicy`: `advisory` (default) and `strict`.
   - `AiCoderRunBudget.observationNudgeThresholds` (default `[3, 5, 8]`,
-    following the DeepSeek Harness `repeat-tool-reminder` design): escalating
+    following the upstream DSH `repeat-tool-reminder` design): escalating
     trusted nudges for repeated read-only observations; blocking only after the
     final threshold. Advisory nudges no longer count toward
     `maxNoProgressEpisodes`; the `strict` policy preserves the older