sanook-cli 0.5.1 → 0.5.2

package/second-brain/Sessions/2026-06-18-sanook-brain-final-cli-final.md

@@ -0,0 +1,246 @@
+---
+tags: [final-gate, verification, sanook-cli, second-brain]
+note_type: final-gate
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Sessions/_Index]]"
+---
+
+# 2026-06-18 - Sanook Brain Final CLI - Final Gate
+
+> Evidence-backed closeout for implementing `sanook brain final`, `--from-diff`, [[Templates/final-lite]], final-gate validation, and eval coverage.
+
+## 0. Final Gate Rule
+
+- [x] This final gate was created before the final owner-facing answer.
+- [x] Every PASS/PARTIAL/FAIL/BLOCKED claim below has evidence or an explicit reason.
+- [x] No unchecked item is silently treated as done.
+- [x] If evidence is missing, status is `PARTIAL`, `FAIL`, or `BLOCKED`, not `PASS`.
+- [x] If a row has no evidence, it cannot be `PASS`.
+
+## 1. Objective / DoD Lock
+
+Original request:
+
+```text
+ทำทั้งหมดมาได้เลย
+```
+
+Expected output:
+
+- [x] Add `sanook brain final`.
+- [x] Support `--from-diff`.
+- [x] Add a final-gate validator.
+- [x] Add [[Templates/final-lite]].
+- [x] Integrate final-gate coverage with `sanook brain eval`.
+
+Definition of Done:
+
+| DoD item | Status | Evidence | Notes |
+|---|---|---|---|
+| CLI can create a final gate note in Sessions. | PASS | `src/brain-final.ts`; temp-vault smoke with `node dist/bin.js brain final --task "smoke final gate" --from-diff` | Smoke created `Sessions/2026-06-18-smoke-final-gate-final.md`. |
+| Diff prefill works. | PASS | `src/brain-final.test.ts`; smoke output `from-diff: 23 file(s)` | Prefills changed-file table from git status. |
+| Lite template exists and is scaffolded. | PASS | `second-brain/Templates/final-lite.md`; `src/brain.test.ts`; temp-vault smoke with `--lite --output Sessions/smoke-lite-final.md` | Scaffold test includes full and lite templates; smoke created a lite final gate. |
+| Review validates final-gate evidence. | PASS | `src/brain-review.ts`; `src/brain-review.test.ts` | Test catches TODO and PASS-without-evidence rows. |
+| Eval covers final-gate contract. | PASS | `src/brain-eval.ts`; `src/brain-eval.test.ts` | `SB-FINAL` case added. |
+| Work is documented and discoverable. | PASS | [[Sessions/2026-06-18-sanook-brain-final-cli]], [[Evals/quality-ledger]], [[Templates/_Index]], [[Shared/AI-Context-Index]] | Index and hot path updated. |
+
+Out of scope / non-goals:
+
+- No automatic filling of all final-gate evidence rows from tests; the CLI creates a scaffold and prefilled diff evidence, then the agent/owner must complete it.
+- No broad `sanook brain new TYPE` template generator in this change.
+
+## 2. Evidence-Backed Checklist
+
+| Gate | Status | Evidence | Notes |
+|---|---|---|---|
+| Relevant source/context was read before editing. | PASS | Read `src/brain.ts`, `src/brain-review.ts`, `src/brain-eval.ts`, `src/bin.ts`, existing templates, and tests | Matched local command/test style. |
+| Existing canonical note/file was searched before creating a new one. | PASS | `rg final-lite|brain final|review.final-gates|SB-FINAL` | No existing CLI final generator was present. |
+| Changes were made in the correct folder/module boundary. | PASS | New logic isolated in `src/brain-final.ts`; docs in second-brain templates/standards/evals | Existing `brain context/eval/review` patterns preserved. |
+| No unrelated user/worktree changes were reverted or overwritten. | PASS | `git status --short` showed `src/config.ts` and `src/config.test.ts` as pre-existing modified files; they were not edited | Mention in final answer. |
+| New/changed durable notes have `parent` and `up::`. | PASS | This file and session log include `parent` and `up::`; scaffold hygiene tests passed | Full tests passed. |
+| Index/backlink/discoverability was updated when needed. | PASS | [[Sessions/_Index]], [[Templates/_Index]], [[Shared/AI-Context-Index]], [[Evals/quality-ledger]] | Links added. |
+| Verification was run at the right scope. | PASS | Targeted tests, typecheck, full tests, build, diff check, CLI smoke | Listed in Evidence Matrix. |
+| Residual risk is stated clearly. | PASS | Residual Risk section | Known limitation documented. |
+
+## 3. Status Matrix
+
+| Work item / phase | Status | Evidence | Owner-visible outcome |
+|---|---|---|---|
+| Frame objective and DoD | PASS | Section 1 of this final gate | "ทำทั้งหมด" mapped to five concrete deliverables. |
+| Retrieve required context | PASS | Files inspected list below | Implementation follows existing Sanook brain command structure. |
+| Implement / write / edit | PASS | Files changed list below | New CLI workflow exists. |
+| Verify behavior or artifact | PASS | Commands table below | Tests/build/smoke passed. |
+| Update memory/index/session if needed | PASS | Session, final gate, current-state, quality ledger, Sessions index | Work is traceable. |
+| Prepare final response | PASS | Final-answer draft below | Response can cite verified evidence. |
+
+Blocked / partial explanation:
+
+- `PARTIAL`: none.
+- `BLOCKED`: none.
+
+## 4. Evidence Matrix
+
+Commands:
+
+| Command | Status | Important output | Scope proven |
+|---|---|---|---|
+| `npm test -- src/brain-final.test.ts src/brain-review.test.ts src/brain-eval.test.ts src/brain.test.ts` | PASS | 4 files, 37 tests passed | Targeted final/review/eval/scaffold behavior. |
+| `npm run typecheck` | PASS | `tsc --noEmit` passed | TypeScript compile surface. |
+| `npm test` | PASS | 102 files, 881 tests passed | Full current test suite. |
+| `npm run build` | PASS | `tsc -p tsconfig.build.json` passed | Build output compiles. |
+| `git diff --check` | PASS | No output | No whitespace/conflict-marker issues. |
+| `node dist/bin.js brain init ...` then `node dist/bin.js brain final --task "smoke final gate" --from-diff` | PASS | Created temp-vault final note, linked Sessions index, `from-diff: 23 file(s)` | Real CLI path from built output. |
+| `node dist/bin.js brain init ...` then `node dist/bin.js brain final --task "smoke lite final" --lite --output Sessions/smoke-lite-final.md` | PASS | Created temp-vault lite final note and linked Sessions index. | Real lite CLI path from built output. |
+
+Files inspected:
+
+| File/path | Why it matters | Evidence |
+|---|---|---|
+| `src/brain.ts` | Scaffold/copy pattern | New template covered by scaffold tests. |
+| `src/brain-review.ts` | Existing curator check shape | Added final-gate check in same pattern. |
+| `src/brain-eval.ts` | Existing benchmark runner shape | Added `SB-FINAL`. |
+| `src/bin.ts` | CLI subcommand wiring | Added `runBrainFinal` and dispatcher entry. |
+| `second-brain/Templates/final.md` | Full final gate source | Lite template mirrors section contract. |
+
+Files changed:
+
+| File/path | Change summary | Evidence |
+|---|---|---|
+| `src/brain-final.ts` | New parser, generator, diff prefill, Sessions index update, and validator helpers. | Targeted tests and typecheck passed. |
+| `src/brain-final.test.ts` | Parser/generation/validator coverage. | Targeted tests passed. |
+| `src/bin.ts` / `src/commands.ts` | CLI help and dispatcher wiring for `brain final`. | CLI smoke passed. |
+| `src/brain-review.ts` / `src/brain-review.test.ts` | Review check for final-gate templates and session final gates. | Targeted tests passed. |
+| `src/brain-eval.ts` / `src/brain-eval.test.ts` | `SB-FINAL` eval case. | Targeted tests passed. |
+| `src/brain.test.ts` | Scaffold/template coverage for `final-lite`. | Targeted tests passed. |
+| `second-brain/Templates/final-lite.md` | New compact evidence-backed final gate template. | Scaffold tests passed. |
+| `second-brain/*` indexes/standards/evals/session files | Discoverability and quality-loop closeout. | This final gate and full tests. |
+| `CHANGELOG.md` | User-facing release note. | Diff reviewed. |
+
+Artifacts/rendered outputs:
+
+| Artifact | Status | Evidence |
+|---|---|---|
+| Built CLI smoke final note in temp vault | PASS | Smoke output showed created path and Sessions index link. |
+
+External sources, if any:
+
+| Source | Claim supported | Link / citation |
+|---|---|---|
+| N/A | This task used local repo state only. | N/A |
+
+## 5. Residual Risk
+
+Known risk:
+
+| Risk | Impact | Mitigation / next check |
+|---|---|---|
+| `--from-diff` uses `git status --porcelain=v1` path parsing and does not deeply unescape exotic quoted paths. | Very unusual filenames may need manual adjustment in the generated evidence table. | Keep generated rows editable; add quoted-path parser later if a real case appears. |
+| Generated final gate still contains TODO rows by design. | `brain review` will warn until the gate is filled. | This is intentional; users/agents must complete evidence before claiming done. |
+| Worktree had unrelated config changes before this task. | Full tests cover current tree, but those files are not part of this implementation. | Final answer names them as untouched unrelated changes. |
+
+Checks not run:
+
+| Check | Reason not run | Consequence |
+|---|---|---|
+| Visual/browser QA | No frontend or visual artifact changed. | N/A |
+
+Do not claim done if:
+
+- [x] Required checks passed.
+- [x] Changed behavior was exercised by tests and CLI smoke.
+- [x] Final answer will mention residual risk and unrelated modified files.
+
+## 6. Change Summary Audit
+
+What changed:
+
+- `sanook brain final` can create full or lite final-gate notes in Sessions.
+- `--from-diff` can prefill changed-file evidence rows.
+- `brain review` validates session final gates.
+- `brain eval` includes `SB-FINAL`.
+- Second-brain docs/indexes/quality ledger/session state now point to the workflow.
+
+What did not change:
+
+- No broad template generator was added.
+- No automatic evidence completion was added.
+- Pre-existing `src/config.ts` and `src/config.test.ts` changes were not edited.
+
+Behavior before:
+
+- Final gate existed as a manual template only.
+- Review/eval did not know whether final gates existed or were complete.
+
+Behavior after:
+
+- Sanook can generate final-gate notes from CLI, smoke-tested through built `dist/bin.js`.
+- Review/eval can keep the final-gate workflow from drifting.
+
+Compatibility / migration notes:
+
+- Existing vaults without `Templates/final-lite.md` can still run the command because the generator falls back to bundled templates.
+
+## 7. Final Answer Draft
+
+```text
+ทำครบแล้วครับ: เพิ่ม `sanook brain final`, `--from-diff`, `--lite`, final-gate validator ใน `brain review`, และ `SB-FINAL` ใน `brain eval` พร้อม docs/templates/session closeout.
+
+Verified:
+- npm test -- src/brain-final.test.ts src/brain-review.test.ts src/brain-eval.test.ts src/brain.test.ts: PASS
+- npm run typecheck: PASS
+- npm test: PASS (102 files, 881 tests)
+- npm run build: PASS
+- git diff --check: PASS
+- built CLI smoke: PASS (`--from-diff` and `--lite`)
+
+Note:
+- `src/config.ts` และ `src/config.test.ts` เป็น modified อยู่ก่อนแล้ว ผมไม่ได้แตะสองไฟล์นี้
+```
+
+Final-answer safety check:
+
+- [x] Does not claim tests/build/smoke passed unless listed in Evidence Matrix.
+- [x] Names files/commands accurately.
+- [x] Mentions skipped checks or residual risk.
+- [x] Is concise enough for the owner.
+
+## 8. Second-Brain Routing / Memory Closeout
+
+Session / handoff:
+
+- [x] Added [[Sessions/2026-06-18-sanook-brain-final-cli]].
+- [x] Added this final gate note.
+- [x] Updated [[Sessions/_Index]].
+
+Durable memory:
+
+- [x] Updated [[Shared/Operating-State/current-state]].
+- [x] No new owner preference or protected fact discovered.
+
+Indexes / discoverability:
+
+- [x] Updated [[Templates/_Index]].
+- [x] Updated [[Shared/AI-Context-Index]].
+- [x] Updated [[Evals/quality-ledger]].
+- [x] Updated [[Evals/second-brain-benchmarks]].
+
+Quality loop:
+
+- [x] Added `SB-FINAL` eval case.
+- [x] Ran targeted tests, typecheck, full tests, build, diff check, and CLI smoke.
+
+## Final Verdict
+
+| Verdict | Choose one | Evidence |
+|---|---|---|
+| Ready to close | PASS | Tests, typecheck, build, diff check, and CLI smoke passed. |
+| Close with caveats | PASS | Residual risk around exotic git paths and intentionally unfilled generated gates is documented. |
+| Needs more work | N/A | No required item remains open. |
+| Blocked | N/A | No blocker. |
+
+One-line final state:
+
+> Ready to close: Sanook now has a CLI-backed final-gate workflow with diff prefill, lite template, review validation, eval coverage, and documented evidence.
+
+up:: [[Sessions/_Index]]

package/second-brain/Sessions/2026-06-18-sanook-brain-final-cli.md

@@ -0,0 +1,78 @@
+---
+tags: [session, session-log, sanook-cli, second-brain]
+note_type: session-log
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Sessions/_Index]]"
+ai_surface: history
+---
+
+# 2026-06-18 - Sanook Brain Final CLI
+
+> Session log for turning the manual final-gate template into a Sanook CLI workflow with validation and eval coverage.
+
+## Summary
+
+- Added `sanook brain final [--task "..."] [--from-diff] [--lite]`.
+- Added [[Templates/final-lite]] for smaller evidence-backed closeouts.
+- Added final-gate validation to `sanook brain review`.
+- Added `SB-FINAL` coverage to `sanook brain eval`.
+- Verified with targeted tests, typecheck, full tests, build, diff check, and a temp-vault CLI smoke.
+
+## What Was Tried
+
+- Read the existing `brain context/eval/review` command pattern before adding a new subcommand.
+- Kept the generator pure/testable in `src/brain-final.ts`.
+- Used the existing Sessions folder as the canonical home for generated closeout notes.
+- Let `--from-diff` prefill changed files from `git status --porcelain=v1`.
+- Kept `brain review` non-blocking: incomplete final gates warn instead of failing the whole vault.
+
+## Errors
+
+- Initial typecheck failed because `CreateBrainFinalOptions` inherited required booleans from parsed CLI args even though runtime options are optional.
+
+## Solutions
+
+- Made `CreateBrainFinalOptions` explicitly optional for `fromDiff`, `lite`, `force`, `task`, and `output`.
+- Added tests for parser behavior, full/lite generation, overwrite protection, output path safety, and validator warnings.
+- Added a CLI smoke from `dist/bin.js` using a temp HOME and temp vault.
+
+## Key Decisions
+
+- Default output path is `Sessions/YYYY-MM-DD-<slug>-final.md`.
+- `--output` is confined inside the configured second-brain vault.
+- `--lite` uses the same eight final-gate section names so review/eval can share the same structural validator.
+- `brain review` checks session final gates only, while template files are checked structurally so scaffolded vaults do not fail because templates contain TODO placeholders.
+
+## Files Changed
+
+- `src/brain-final.ts`
+- `src/brain-final.test.ts`
+- `src/bin.ts`
+- `src/commands.ts`
+- `src/brain-review.ts`
+- `src/brain-review.test.ts`
+- `src/brain-eval.ts`
+- `src/brain-eval.test.ts`
+- `src/brain.test.ts`
+- `second-brain/Templates/final-lite.md`
+- `second-brain/Templates/_Index.md`
+- `second-brain/Shared/AI-Context-Index.md`
+- `second-brain/Shared/Tech-Standards/verification-standard.md`
+- `second-brain/Runbooks/ai-second-brain-operating-sequence.md`
+- `second-brain/Evals/second-brain-benchmarks.md`
+- `second-brain/Evals/quality-ledger.md`
+- `second-brain/Shared/Operating-State/current-state.md`
+- `CHANGELOG.md`
+
+Unrelated pre-existing changes left untouched:
+
+- `src/config.ts`
+- `src/config.test.ts`
+
+## Next Steps
+
+- Dogfood `sanook brain final --task "..." --from-diff` in future non-trivial Sanook CLI work.
+- Consider `sanook brain new TYPE` later if template instantiation becomes a broader workflow need.
+
+up:: [[Sessions/_Index]]

package/second-brain/Sessions/2026-06-18-sanook-cli-second-brain-roadmap-correction.md

@@ -0,0 +1,54 @@
+---
+tags: [session, session-log, sanook-cli, second-brain, correction]
+note_type: session-log
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Sessions/_Index]]"
+ai_surface: history
+---
+
+# 2026-06-18 — Sanook CLI Second-Brain Roadmap Correction
+
+> Correction session after owner clarified that the target is Sanook CLI, not Hermes CLI. Captures the Sanook-native direction and leaves Hermes research as reference only.
+
+## Summary
+
+Reframed the previous Hermes-heavy research into a Sanook CLI roadmap. Sanook already has `brain init`, vault context injection, memory routing, index/search, and MCP serving, so the next useful work is CLI features: `brain doctor`, `brain context`, `brain eval`, and later `brain review`.
+
+## What Was Tried
+
+- Read `src/brain.ts`, `src/bin.ts`, `src/commands.ts`, `src/doctor.ts`, `src/knowledge.ts`, and `second-brain/SANOOK.md`.
+- Checked current command surface for `brain init`, `index`, `search`, MCP, and memory behavior.
+- Created a Sanook project workspace note under `Projects/sanook-cli/`.
+
+## Errors
+
+- Initial research over-weighted Hermes-specific implementation because the earlier wording mentioned Hermes CLI.
+
+## Solutions
+
+- Added [[Projects/sanook-cli/second-brain-feature-roadmap]] as the corrected implementation roadmap.
+- Left Hermes research as a compatibility reference, not the main next action.
+
+## Key Decisions
+
+- Do not add `HERMES.md` as the next step for this objective.
+- First Sanook-native slice should be `sanook brain doctor`.
+
+## Files Changed
+
+- `second-brain/Projects/_Index.md`
+- `second-brain/Projects/sanook-cli/_Index.md`
+- `second-brain/Projects/sanook-cli/second-brain-feature-roadmap.md`
+- `second-brain/Sessions/_Index.md`
+- `second-brain/Sessions/2026-06-18-sanook-cli-second-brain-roadmap-correction.md`
+- `second-brain/Shared/Operating-State/current-state.md`
+- `second-brain/Research/2026-06-18-hermes-cli-second-brain-expansion-research.md`
+
+## Next Steps
+
+- [ ] Implement `sanook brain doctor`.
+- [ ] Then implement `sanook brain context [--task]`.
+- [ ] Then implement `sanook brain eval`.
+
+up:: [[Sessions/_Index]]

package/second-brain/Sessions/2026-06-18-token-reduction-framework-integration.md

@@ -0,0 +1,69 @@
+---
+tags: [session, token-reduction, sanook-cli, ai-agent]
+note_type: session-log
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Sessions/_Index]]"
+ai_surface: history
+---
+
+# 2026-06-18 - Token Reduction Framework Integration
+
+> Session log for researching GitHub token-reduction frameworks and integrating a safe default into Sanook CLI.
+
+## Summary
+
+- Compared GitHub frameworks/patterns: Microsoft LLMLingua, Selective Context, and Headroom.
+- Chose a Sanook-native selective context compressor as the default because it works without Python, model downloads, proxy services, or extra keys.
+- Added `contextCompression: selective | headroom | off` with `SANOOK_CONTEXT_COMPRESSION`.
+- Integrated the actual `headroom-ai` Vercel AI SDK adapter as an optional framework mode.
+- Improved local selective mode with query-aware scoring and adaptive budgets for older stale tool outputs.
+- Wired selective compression into the Vercel AI SDK `prepareStep` path, targeting stale huge tool outputs only.
+
+## What Was Tried
+
+- Inspected Sanook's existing token controls: prompt cache, auto-compaction, summarize-compaction, subagents, read ranges, output truncation.
+- Checked `headroom-ai` npm package and Vercel AI adapter.
+- Decided not to require Headroom by default because direct compression requires a proxy/cloud key, but added opt-in support.
+
+## Errors
+
+- A first patch to `selectivelyCompressStaleToolResults()` returned too early and left unreachable code; fixed by returning the mapped output only when a change occurred.
+- A broad test patch missed exact context; re-applied as focused patches.
+
+## Solutions
+
+- Added `src/context-compression.ts` with `selectiveCompressText()`.
+- Added `selectivelyCompressStaleToolResults()` in `src/compaction.ts`.
+- Updated `src/loop.ts` to apply selective compression before `autoCompact()`.
+- The compressor now uses the latest user message to boost relevant lines and spends fewer chars on older stale tool results.
+- Updated config schema, env parsing, CLI validation, README, changelog, and tests.
+- Added `headroom-ai` as a dependency for optional framework-backed compression.
+
+## Key Decisions
+
+- Preserve recent tool results fully.
+- Compress only stale large tool output, not user intent or recent evidence.
+- Keep this zero-LLM by default; use Headroom only when the user opts into a proxy/cloud setup.
+
+## Files Changed
+
+- `src/context-compression.ts`
+- `src/context-compression.test.ts`
+- `src/compaction.ts`
+- `src/compaction.test.ts`
+- `src/config.ts`
+- `src/config.test.ts`
+- `src/loop.ts`
+- `src/bin.ts`
+- `README.md`
+- `CHANGELOG.md`
+- `second-brain/Research/2026-06-18-ai-token-reduction-frameworks.md`
+
+## Next Steps
+
+- Run typecheck and tests.
+- Benchmark local selective mode with real multi-step traces.
+- Smoke test Headroom mode against a real proxy/cloud setup when credentials are available.
+
+up:: [[Sessions/_Index]]

package/second-brain/Sessions/_Index.md

@@ -25,6 +25,20 @@ code/config · subfolder (Sessions = flat เสมอ)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Sessions
+
+- [[Sessions/2026-06-17-ai-second-brain-sequence-experiment]] — ทดลองและปรับ AI operating sequence ของ second-brain
+- [[Sessions/2026-06-17-ai-framework-additional-zones]] — เพิ่ม benchmark, response examples, และ context packs เข้า framework
+- [[Sessions/2026-06-18-framework-dogfood-permission-and-memory]] — ใช้ context packs ใหม่กับ permission/tools + memory update + benchmark dogfood
+- [[Sessions/2026-06-18-cli-args-release-readiness]] — ตรวจ cli-args serve port UX + release readiness gates
+- [[Sessions/2026-06-18-hermes-second-brain-expansion-research]] — วิจัยว่า second-brain ควรเพิ่มอะไรเพื่อรองรับ Hermes CLI ให้ดีขึ้น
+- [[Sessions/2026-06-18-sanook-cli-second-brain-roadmap-correction]] — correction: เป้าจริงคือทำ second-brain feature ใน Sanook CLI
+- [[Sessions/2026-06-18-sanook-brain-cli-p0-implementation]] — implement `brain doctor`, `brain context`, `brain eval`, and `brain review`
+- [[Sessions/2026-06-18-final-gate-template]] — add evidence-backed [[Templates/final]] final gate
+- [[Sessions/2026-06-18-final-gate-template-final]] — evidence-backed closeout for the final gate template work
+- [[Sessions/2026-06-18-sanook-brain-final-cli]] — implement `sanook brain final`, final-lite, review validation, and eval coverage
+- [[Sessions/2026-06-18-sanook-brain-final-cli-final]] — evidence-backed closeout for the Sanook brain final CLI work
+- [[Sessions/2026-06-18-mcp-ecosystem-and-sanook-ux-scan]] — scan Sanook MCP support and registry-based integration opportunities
+- [[Sessions/2026-06-18-token-reduction-framework-integration]] — integrate selective context compression after GitHub framework scan
 
 up:: [[Home]]

package/second-brain/Shared/AI-Context-Index.md

@@ -28,6 +28,23 @@ ai_surface: hot
 4. [[Shared/Decision-Memory/decision-log]] — ตัดสินใจอะไรไปแล้ว
 5. งาน project → [[Projects/_Index]] → overview → context → current-state
 
+## Best AI Operating Sequence
+
+> default สำหรับงานไม่ trivial: [[Runbooks/ai-second-brain-operating-sequence]]
+
+**Frame → Retrieve → Role → JIT Rules → Act → Write → Eval → Consolidate**
+
+- เริ่มด้วย hot path ด้านบนเสมอ
+- เลือกบทบาท AI ก่อนลงมือ: Scientist / Cartographer / Librarian / Operator / Editor / Archivist
+- ถ้ามี pack ตรงงาน ให้ใช้ [[Shared/Context-Packs/_Index]] แทนการประกอบ context ใหม่จากศูนย์
+- โหลด rule/runbook เฉพาะ task นั้นแบบ JIT; อย่าโหลดทั้ง vault
+- งาน framework/หลาย session/แก้ durable memory ให้ eval และบันทึก evidence
+
+## Taste & Benchmarks
+
+- owner-facing tone/examples → [[Shared/User-Memory/response-examples]]
+- framework quality checks → [[Evals/second-brain-benchmarks]]
+
 ## Default Write Path (ก่อนสร้าง/แก้โน้ต)
 
 1. Classify artifact: project work, session log, decision, preference, source, reusable skill, runbook, or temporary scratch
@@ -50,11 +67,16 @@ ai_surface: hot
 | scratch ระหว่างงานเดียว | `Shared/Working-Memory/<topic>.md` |
 | expected output fixture | [[Acceptance/golden-case-template]] |
 | pre/postflight gate | [[Checklists/preflight-postflight-template]] |
+| final phase / evidence-backed closeout | [[Templates/final]] หรือ [[Templates/final-lite]]; CLI: `sanook brain final --task "..." [--from-diff] [--lite]` |
 | entity/person/org page | `Entities/<name>.md` |
 | อื่นๆ / ไม่แน่ใจว่าโฟลเดอร์ไหน | [[Vault Structure Map]] |
 
 ## Framework Rules (โหลดตาม task — ดู CLAUDE.md §19)
 
+- **งานไม่ trivial ทุกงาน** → [[Runbooks/ai-second-brain-operating-sequence]] (Scientific Loop Sequence + roles)
+- **งานซ้ำ/task family ชัดเจน** → [[Shared/Context-Packs/_Index]] (ใช้ context pack แทน assemble ใหม่)
+- **ก่อน/หลังแก้ framework** → [[Evals/second-brain-benchmarks]] (วัดว่าดีขึ้นจริงไหม)
+- **ก่อนตอบว่าเสร็จแล้วในงานไม่ trivial** → `sanook brain final --task "..." [--from-diff]` หรือ [[Templates/final]] / [[Templates/final-lite]] + [[Shared/Tech-Standards/verification-standard]]
 - **ก่อนประกอบ context เสมอ** → [[Shared/Rules/context-assembly-policy]] (head/tail + budget, กัน context-rot)
 - ingest ของนอก → [[Runbooks/ingest-quarantine]] · fact → [[Shared/Rules/frontmatter-standard]] (bi-temporal + `source::`)
 - script ทำซ้ำ → [[Shared/Rules/skills-admission]] (Skills/) · consolidate → [[Runbooks/sleep-time-consolidation]]

package/second-brain/Shared/Context-Packs/_Index.md

@@ -25,6 +25,14 @@ pack รวม context พร้อมโหลด
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Context Packs
+
+- [[Shared/Context-Packs/second-brain-maintenance]] — แก้ vault structure, routing, memory policy, indexes, runbooks, agent adapters
+- [[Shared/Context-Packs/coding-release]] — แก้ code/tests/build/release/CLI scripts
+- [[Shared/Context-Packs/research-to-framework]] — research/experiment → framework update
+
+## Use Rule
+
+โหลด pack เมื่อ task ตรงกับ pack ชัดเจน; ถ้าไม่ตรงให้ใช้ [[Shared/AI-Context-Index]] + JIT rules ปกติ
 
 up:: [[Shared/_Index]]

package/second-brain/Shared/Context-Packs/coding-release.md

@@ -0,0 +1,51 @@
+---
+tags: [context-pack, coding, release, verification]
+note_type: context-pack
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/Context-Packs/_Index]]"
+---
+
+# Context Pack: Coding & Release Work
+
+> Use when changing source code, tests, build/release behavior, CLI commands, or scripts that affect runtime behavior.
+
+## Load Order
+
+1. [[Shared/AI-Context-Index]]
+2. [[Runbooks/ai-second-brain-operating-sequence]]
+3. [[Shared/Tech-Standards/verification-standard]]
+4. Relevant project/source files
+5. Relevant tests
+6. [[Evals/second-brain-benchmarks]] only if the change affects AI/vault framework
+
+## Required Role
+
+- Primary: Operator
+- Secondary: Scientist
+
+## Verification Menu
+
+Pick the narrowest set that proves the change:
+
+- targeted test
+- full test suite
+- typecheck
+- build
+- smoke command
+- diff/scan gate
+
+## Output Artifacts
+
+- Code/test/docs changes
+- Short owner-facing summary with verification
+- Session log if the work is non-trivial or changes durable framework behavior
+
+## Done Criteria
+
+- Source read before editing
+- Tests or explicit unable-to-run note
+- No destructive command without owner approval
+- Residual risk stated if verification is partial
+
+up:: [[Shared/Context-Packs/_Index]]

package/second-brain/Shared/Context-Packs/research-to-framework.md

@@ -0,0 +1,51 @@
+---
+tags: [context-pack, research, framework, ai]
+note_type: context-pack
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/Context-Packs/_Index]]"
+---
+
+# Context Pack: Research To Framework
+
+> Use when the owner asks for best method, comparison, experiment, or turning research into framework changes.
+
+## Load Order
+
+1. [[Shared/AI-Context-Index]]
+2. [[Runbooks/ai-second-brain-operating-sequence]]
+3. [[Shared/Rules/context-assembly-policy]]
+4. [[Evals/second-brain-benchmarks]]
+5. Relevant prior research notes
+6. Target framework files or destination `_Index.md`
+
+## Required Role
+
+- Primary: Scientist
+- Secondary: Librarian
+
+## Method
+
+1. State hypothesis.
+2. Define candidates.
+3. Define metrics before judging.
+4. Run a small reproducible check when possible.
+5. Record result in `Research/` if it is evidence-bearing.
+6. Promote the winner into `Runbooks/`, `Rules/`, `Context-Packs/`, or `Playbooks/` only after evidence.
+7. Wire the result into indexes/hot path.
+
+## Output Artifacts
+
+- Research note with method/results
+- Framework/runbook/rule update
+- Quality-ledger entry for non-trivial changes
+- Session log when files are changed
+
+## Done Criteria
+
+- Recommendation is evidence-backed
+- Tradeoffs are explicit
+- Framework is actually changed, not only summarized
+- Owner-facing final answer names files and verification
+
+up:: [[Shared/Context-Packs/_Index]]