sanook-cli 0.5.0 → 0.5.2

package/second-brain/Shared/Tech-Standards/verification-standard.md

@@ -31,6 +31,30 @@ Verification:
 - Smoke: <command/result>
 ```
 
+## Final Gate
+
+For non-trivial work, multi-file changes, framework changes, releases, or anything the owner may later audit, instantiate [[Templates/final]] before the final owner-facing answer. Use [[Templates/final-lite]] for smaller tasks that still need evidence, or run:
+
+```text
+sanook brain final --task "<objective>" --from-diff
+sanook brain final --task "<objective>" --lite
+```
+
+The final gate must prove all eight closeout requirements:
+
+1. Objective / DoD is restated and matched.
+2. Checklist items have evidence, not only checked boxes.
+3. Status uses `PASS`, `PARTIAL`, `FAIL`, `N/A`, or `BLOCKED`.
+4. Evidence matrix lists commands, files, artifacts, and sources.
+5. Residual risk and skipped checks are explicit.
+6. Change summary distinguishes changed vs untouched work.
+7. Final answer draft does not overclaim beyond evidence.
+8. Second-brain routing / memory closeout is handled.
+
+If a row has no evidence, it cannot be `PASS`.
+
+`sanook brain review` checks final-gate notes in `Sessions/` for missing sections, unfilled placeholders, `TODO` rows, and `PASS` rows without evidence. `sanook brain eval` checks that the final-gate templates remain bundled and wired into this standard.
+
 ## Never Claim Done If
 
 - Tests were skipped without saying why.

package/second-brain/Shared/User-Memory/_Index.md

@@ -25,6 +25,9 @@ identity static (→User-Persona)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## User-Memory Notes
+
+- [[Shared/User-Memory/user-preferences]] — durable preferences ของเจ้าของ
+- [[Shared/User-Memory/response-examples]] — examples/taste signals ว่าคำตอบ AI แบบไหนดีหรือไม่ดี
 
 up:: [[Shared/_Index]]

package/second-brain/Shared/User-Memory/response-examples.md

@@ -0,0 +1,98 @@
+---
+tags: [user-memory, response-examples, taste]
+note_type: response-examples
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/User-Memory/_Index]]"
+related:: [[Shared/User-Memory/user-preferences]]
+---
+
+# Response Examples & Taste Signals
+
+> Mutable examples of what "good AI behavior" feels like for {{OWNER_NAME}}. These examples are initial working defaults inferred from current vault work; update when the owner gives stronger feedback.
+
+## Preferred Shape
+
+- Thai first, with natural tech English where useful.
+- Lead with the answer or status.
+- Be proactive when the action is safe; ask only when the next step is genuinely risky or ambiguous.
+- Summarize verification evidence without dumping full logs.
+- For framework work, think like Scientist first, then implement like Operator/Librarian.
+
+## Good Pattern: Work Completed
+
+```text
+เสร็จแล้วครับ ผมเพิ่ม benchmark, taste examples, และ context packs เข้า framework แล้ว
+
+หลัก ๆ คือ:
+- Evals/second-brain-benchmarks.md สำหรับวัดคุณภาพ AI
+- Shared/User-Memory/response-examples.md สำหรับ style/taste
+- Shared/Context-Packs/... สำหรับโหลด context ตามงานซ้ำ
+
+ตรวจแล้ว: script/runbook links อยู่ใน index และ git diff --check ผ่าน
+```
+
+Why good:
+
+- Starts with status.
+- Names files.
+- Mentions verification.
+- Does not over-explain unless asked.
+
+## Bad Pattern: Too Vague
+
+```text
+ผมได้ปรับปรุงระบบให้ดีขึ้นแล้ว มีหลายส่วนที่ช่วยให้ AI ทำงานดีขึ้น และน่าจะใช้งานได้ดีมากขึ้นในอนาคต
+```
+
+Why bad:
+
+- No files.
+- No evidence.
+- No next action.
+
+## Good Pattern: Recommendation Before Edit
+
+```text
+ผมไม่แนะนำให้เพิ่ม root folder ใหม่ตอนนี้ครับ เพราะ vault มี zone รองรับอยู่แล้ว
+ทางที่คุ้มกว่าคือเติม benchmark ใน Evals, taste examples ใน User-Memory, และ context packs ใน Shared/Context-Packs
+```
+
+Why good:
+
+- Gives a point of view.
+- Protects the framework from unnecessary complexity.
+- Offers concrete implementation path.
+
+## Good Pattern: Act On All Clear Recommendations
+
+```text
+รับครับ ผมจะทำครบตาม 4 ข้อที่แนะนำไว้: ตรวจ worktree, รัน tests, ใช้ benchmark/framework จริง, แล้วอัปเดต memory/session evidence ให้ครบ
+```
+
+Why good:
+
+- Mirrors the requested scope.
+- Commits to action when the work is safe and clear.
+- Keeps the owner looped in without asking for unnecessary confirmation.
+
+## Good Pattern: Uncertainty
+
+```text
+ผมยังยืนยัน claim นี้ไม่ได้จาก vault ปัจจุบันครับ หลักฐานที่มีบอกได้แค่ว่า X ผ่าน แต่ยังไม่ได้พิสูจน์ Y
+```
+
+Why good:
+
+- Does not pretend certainty.
+- Separates evidence from inference.
+
+## Update Rule
+
+When owner reacts positively/negatively to a response:
+
+1. Classify the signal as style, autonomy, detail level, or evidence expectation.
+2. Update this file or [[Shared/User-Memory/user-preferences]] with ADD/UPDATE/NOOP.
+3. Do not duplicate the same preference in multiple places.
+
+up:: [[Shared/User-Memory/_Index]]

package/second-brain/Shared/User-Memory/user-preferences.md

@@ -15,6 +15,7 @@ parent: "[[Shared/User-Memory/_Index]]"
 
 ## Execution
 - Autonomy: {{AUTONOMY}}
+- เมื่อมีรายการแนะนำที่ scope ชัดและปลอดภัย เจ้าของมักต้องการให้ลงมือทำครบได้เลย ไม่ต้องถามยืนยันซ้ำ
 
 ## Likes
 _(เพิ่มเมื่อเจ้าของบอกว่าชอบอะไรชัดเจน)_

package/second-brain/Templates/_Index.md

@@ -16,6 +16,15 @@ template ไว้ instantiate (session/bug/handoff/project)
 ## ไม่ใส่ที่นี่
 โน้ตจริง
 
+## Templates
+
+- [[Templates/session]] — session log หลังจบงานหรือ checkpoint สำคัญ
+- [[Templates/handoff]] — ส่งต่องานค้างให้ session/agent ถัดไป
+- [[Templates/project]] — project overview
+- [[Templates/bug]] — bug report
+- [[Templates/final]] — final gate เต็มก่อนบอกว่าเสร็จแล้ว; checklist ต้องมี evidence
+- [[Templates/final-lite]] — final gate แบบสั้นสำหรับงานเล็กถึงกลาง; ใช้เกณฑ์ evidence เดียวกัน
+
 ## AI Routing Contract
 
 - ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน

package/second-brain/Templates/final-lite.md

@@ -0,0 +1,111 @@
+---
+tags: [template, final-gate, verification, lite]
+note_type: template
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+parent: "[[Templates/_Index]]"
+---
+
+# YYYY-MM-DD - <task/topic> - Final Gate Lite
+
+> Final gate แบบสั้นสำหรับงานเล็กถึงกลาง: ยังต้องล็อก objective, evidence, risk, final answer, และ memory routing; ถ้า row ไม่มี evidence ห้าม mark `PASS`
+
+## 0. Final Gate Rule
+
+- [ ] Created before the owner-facing final answer.
+- [ ] Every `PASS` has evidence.
+- [ ] If a row has no evidence, it cannot be `PASS`.
+
+Status: `PASS`, `PARTIAL`, `FAIL`, `N/A`, `BLOCKED`, `TODO`.
+
+## 1. Objective / DoD Lock
+
+Original request:
+
+```text
+<paste owner request or goal text here>
+```
+
+| DoD item | Status | Evidence |
+|---|---|---|
+| Objective is concrete. | TODO |  |
+| Deliverable exists in the right place. | TODO |  |
+| Owner-facing answer can be backed by evidence. | TODO |  |
+
+## 2. Evidence-Backed Checklist
+
+| Gate | Status | Evidence |
+|---|---|---|
+| Relevant context was read. | TODO |  |
+| No unrelated worktree changes were reverted. | TODO |  |
+| Verification ran at the right scope. | TODO |  |
+
+## 3. Status Matrix
+
+| Work item / phase | Status | Evidence |
+|---|---|---|
+| Implement/write/edit | TODO |  |
+| Verify | TODO |  |
+| Close memory/session if needed | TODO |  |
+
+## 4. Evidence Matrix
+
+Commands:
+
+| Command | Status | Important output | Scope proven |
+|---|---|---|---|
+| `<command>` | TODO |  |  |
+
+Changed files:
+
+| File | Change summary | Evidence |
+|---|---|---|
+| `<file>` |  |  |
+
+## 5. Residual Risk
+
+| Risk or skipped check | Status | Evidence / reason |
+|---|---|---|
+| `<risk>` | TODO |  |
+
+## 6. Change Summary Audit
+
+What changed:
+
+- <short summary>
+
+What did not change:
+
+- <important non-change or unrelated worktree file>
+
+## 7. Final Answer Draft
+
+```text
+<short final answer>
+
+Verified:
+- <command/result>
+
+Residual risk:
+- <risk or "none known">
+```
+
+## 8. Second-Brain Routing / Memory Closeout
+
+| Routing item | Status | Evidence |
+|---|---|---|
+| Session/index/current-state update needed? | TODO |  |
+| Durable memory/decision update needed? | TODO |  |
+| Search/index refresh needed? | TODO |  |
+
+## Final Verdict
+
+| Verdict | Status | Evidence |
+|---|---|---|
+| Ready to close / caveat / blocked | TODO |  |
+
+One-line final state:
+
+> <state + evidence>
+
+up:: [[Templates/_Index]]

package/second-brain/Templates/final.md

@@ -0,0 +1,231 @@
+---
+tags: [template, final-gate, verification, dod]
+note_type: template
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+parent: "[[Templates/_Index]]"
+---
+
+# YYYY-MM-DD - <task/topic> - Final Gate
+
+> ใช้เป็น phase สุดท้ายก่อนบอกว่า "เสร็จแล้ว" โดยตรวจ objective, DoD, evidence, risk, memory routing และ final answer draft; ไม่ใช้เป็น checklist ลอย ๆ ที่ไม่มีหลักฐาน
+
+## 0. Final Gate Rule
+
+- [ ] This final gate was created before the final owner-facing answer.
+- [ ] Every PASS/PARTIAL/FAIL/BLOCKED claim below has evidence or an explicit reason.
+- [ ] No unchecked item is silently treated as done.
+- [ ] If evidence is missing, status is `PARTIAL`, `FAIL`, or `BLOCKED`, not `PASS`.
+- [ ] If a row has no evidence, it cannot be `PASS`.
+
+Status vocabulary:
+
+| Status | Meaning | When to use |
+|---|---|---|
+| `PASS` | Requirement was satisfied and evidence proves it. | Command output, file path, rendered artifact, source citation, or reviewed diff exists. |
+| `PARTIAL` | Some work was done, but evidence is incomplete or scope is narrower than requested. | Targeted test passed but full affected surface was not checked. |
+| `FAIL` | Requirement was attempted and did not satisfy the gate. | Test failed, artifact missing, output contradicts requirement. |
+| `N/A` | Gate does not apply to this task. | Visual QA for a non-visual note-only change. |
+| `BLOCKED` | Work cannot proceed without owner input or external state. | Missing credential, unavailable service, unclear requirement after reasonable inspection. |
+
+## 1. Objective / DoD Lock
+
+Original request:
+
+```text
+<paste owner request or goal text here>
+```
+
+Expected output:
+
+- [ ] <deliverable 1>
+- [ ] <deliverable 2>
+- [ ] <deliverable 3>
+
+Definition of Done:
+
+| DoD item | Status | Evidence | Notes |
+|---|---|---|---|
+| Objective is restated in concrete terms. | TODO |  |  |
+| Scope and non-goals are explicit. | TODO |  |  |
+| Required artifact(s) exist in the right canonical home. | TODO |  |  |
+| Owner-facing result matches requested language/tone/detail. | TODO |  |  |
+
+Out of scope / non-goals:
+
+- <not doing this because...>
+
+## 2. Evidence-Backed Checklist
+
+> Rule: checkbox alone is not evidence. Each checked row needs proof.
+
+| Gate | Status | Evidence | Notes |
+|---|---|---|---|
+| Relevant source/context was read before editing. | TODO |  |  |
+| Existing canonical note/file was searched before creating a new one. | TODO |  |  |
+| Changes were made in the correct folder/module boundary. | TODO |  |  |
+| No unrelated user/worktree changes were reverted or overwritten. | TODO |  |  |
+| New/changed durable notes have `parent` and `up::`. | TODO |  |  |
+| Index/backlink/discoverability was updated when needed. | TODO |  |  |
+| Verification was run at the right scope. | TODO |  |  |
+| Residual risk is stated clearly. | TODO |  |  |
+
+## 3. Status Matrix
+
+Use this when the work has multiple deliverables or phases.
+
+| Work item / phase | Status | Evidence | Owner-visible outcome |
+|---|---|---|---|
+| Frame objective and DoD | TODO |  |  |
+| Retrieve required context | TODO |  |  |
+| Implement / write / edit | TODO |  |  |
+| Verify behavior or artifact | TODO |  |  |
+| Update memory/index/session if needed | TODO |  |  |
+| Prepare final response | TODO |  |  |
+
+Blocked / partial explanation:
+
+- `PARTIAL`: <what is complete, what is not, why>
+- `BLOCKED`: <blocking condition, attempts made, exact input/state needed>
+
+## 4. Evidence Matrix
+
+Commands:
+
+| Command | Status | Important output | Scope proven |
+|---|---|---|---|
+| `<command>` | TODO |  |  |
+
+Files inspected:
+
+| File/path | Why it matters | Evidence |
+|---|---|---|
+| `<path>` |  |  |
+
+Files changed:
+
+| File/path | Change summary | Evidence |
+|---|---|---|
+| `<path>` |  |  |
+
+Artifacts/rendered outputs:
+
+| Artifact | Status | Evidence |
+|---|---|---|
+| `<artifact>` | TODO |  |
+
+External sources, if any:
+
+| Source | Claim supported | Link / citation |
+|---|---|---|
+| `<source>` |  |  |
+
+## 5. Residual Risk
+
+Known risk:
+
+| Risk | Impact | Mitigation / next check |
+|---|---|---|
+| `<risk>` |  |  |
+
+Checks not run:
+
+| Check | Reason not run | Consequence |
+|---|---|---|
+| `<check>` |  |  |
+
+Do not claim done if:
+
+- [ ] A required check failed.
+- [ ] A required check was skipped without a reason.
+- [ ] The changed behavior was not exercised.
+- [ ] A visual/exported artifact was not opened/rendered when layout matters.
+- [ ] The final answer would overstate evidence.
+
+## 6. Change Summary Audit
+
+What changed:
+
+- <bullet summary of actual changes>
+
+What did not change:
+
+- <important non-changes, especially unrelated worktree files>
+
+Behavior before:
+
+- <before state>
+
+Behavior after:
+
+- <after state>
+
+Compatibility / migration notes:
+
+- <none or details>
+
+## 7. Final Answer Draft
+
+Use this draft as the owner-facing final answer. Keep it consistent with the evidence above.
+
+```text
+<short answer/status first>
+
+Changed:
+- <file/behavior>
+
+Verified:
+- <command/result>
+
+Residual risk:
+- <risk or "none known">
+```
+
+Final-answer safety check:
+
+- [ ] Does not claim tests/build/smoke passed unless listed in Evidence Matrix.
+- [ ] Names files/commands accurately.
+- [ ] Mentions skipped checks or residual risk.
+- [ ] Is concise enough for the owner.
+
+## 8. Second-Brain Routing / Memory Closeout
+
+Session / handoff:
+
+- [ ] Update `Sessions/YYYY-MM-DD-<topic>.md` if the work was non-trivial.
+- [ ] Create/update `Handoffs/` if work remains for another session/agent.
+
+Durable memory:
+
+- [ ] Preference discovered? Route to [[Shared/User-Memory/user-preferences]] or Memory-Inbox.
+- [ ] Decision made? Route to [[Shared/Decision-Memory/decision-log]].
+- [ ] Current focus changed? Update [[Shared/Operating-State/current-state]].
+- [ ] Unclear/conflicting memory? Route to [[Shared/Memory-Inbox/memory-inbox]].
+
+Indexes / discoverability:
+
+- [ ] Update destination `_Index.md` if the new artifact should be found later.
+- [ ] Add backlinks to project/session/source/decision.
+- [ ] Run `sanook index` if retrieval/search should see the change immediately.
+
+Quality loop:
+
+- [ ] Run `sanook brain doctor` if vault structure/config changed.
+- [ ] Run `sanook brain review` if memory/context/session/eval hygiene changed.
+- [ ] Run `sanook brain eval` if framework/hot-path behavior changed.
+- [ ] Update [[Evals/quality-ledger]] for framework/system changes.
+
+## Final Verdict
+
+| Verdict | Choose one | Evidence |
+|---|---|---|
+| Ready to close | TODO |  |
+| Close with caveats | TODO |  |
+| Needs more work | TODO |  |
+| Blocked | TODO |  |
+
+One-line final state:
+
+> <e.g. Ready to close because X passed; caveat Y remains.>
+
+up:: [[Templates/_Index]]

package/second-brain/Vault Structure Map.md

@@ -108,8 +108,9 @@ ai_surface: hot
 | `Shared/Assets/` | รูป/logo/binary | image/logo/asset | โน้ต .md |
 
 ### AI agent config / vendor (root-level)
-| Folder | Role | ใส่ที่นี่ | ห้ามใส่ |
+| Path | Role | ใส่ที่นี่ | ห้ามใส่ |
 |---|---|---|---|
+| `SANOOK.md` | Sanook CLI context adapter | กฎย่อเฉพาะ `sanook` / `sanook chat` ที่ชี้กลับ `CLAUDE.md` | durable note หรือ gateway/desktop setup |
 | `.agents/` `.agents/skills/` | skill folders (SKILL.md) | SKILL.md ที่ agent โหลด on-demand | prose how-to (→Runbooks) |
 | `.agents/workflows/` | workflow guides | multi-step orchestration ที่ทำซ้ำ | one-off task |
 | `copilot/` | vendor export (review/promote) | export จาก Copilot | durable (promote เข้า durable layer) |

package/skills/structured-output-llm/SKILL.md

@@ -13,7 +13,7 @@ Reach for this skill when a program — not a human — consumes the model's out
 - "The model returns ```json fences / prose / trailing commas and my parse breaks ~3% of the time"
 - "Function arguments come back malformed or with hallucinated keys"
 - "Fill this form schema" / "map this text to my DB row"
-- "Open-weights model (Llama/Mistral/Qwen) won't reliably produce valid JSON"
+- "Open-weights model won't reliably produce valid JSON"
 - "Long extraction gets cut off mid-object" or "streaming JSON is unparseable until complete"
 
 NOT this skill: