sanook-cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, working-memory]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Shared/_Index]]"
+---
+
+# Working-Memory
+
+> scratchpad ระหว่าง 1 task (ลบทิ้งได้)
+
+## ใส่ที่นี่
+ของชั่วคราวระหว่างทำงาน
+
+## ไม่ใส่ที่นี่
+อะไรที่จะเก็บ (→Memory-Inbox)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Shared/Working-Memory/_Index]]"` และท้ายไฟล์ `up:: [[Shared/Working-Memory/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Shared/_Index]]

package/second-brain/Shared/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, shared]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# Shared
+
+> สมองกลาง: memory + rules + coordination
+
+## ใส่ที่นี่
+เข้าผ่าน AI-Context-Index
+
+## ไม่ใส่ที่นี่
+โน้ตงานทั่วไป
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Shared/_Index]]"` และท้ายไฟล์ `up:: [[Shared/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/second-brain/Shared/mcp-servers/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, mcp-servers]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Shared/_Index]]"
+---
+
+# mcp-servers
+
+> vendored local MCP server bundle (code/README)
+
+## ใส่ที่นี่
+โค้ด/README ของ MCP server (config อยู่ Tech-Standards)
+
+## ไม่ใส่ที่นี่
+config การต่อ (→Tech-Standards/mcp.json)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Shared/mcp-servers/_Index]]"` และท้ายไฟล์ `up:: [[Shared/mcp-servers/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Shared/_Index]]

package/second-brain/Skills/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, skills]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# Skills
+
+> reusable unit ที่ executable + ผ่าน verification command
+
+## ใส่ที่นี่
+script/command ที่รัน test ผ่าน (ดู Shared/Rules/skills-admission)
+
+## ไม่ใส่ที่นี่
+prose how-to (→Runbooks) · unverified (→Memory-Inbox)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Skills/_Index]]"` และท้ายไฟล์ `up:: [[Skills/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/second-brain/Templates/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, templates]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# Templates
+
+> แม่แบบโน้ต — instantiate จากที่นี่
+
+## ใส่ที่นี่
+template ไว้ instantiate (session/bug/handoff/project)
+
+## ไม่ใส่ที่นี่
+โน้ตจริง
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Templates/_Index]]"` และท้ายไฟล์ `up:: [[Templates/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/second-brain/Templates/bug.md

@@ -9,6 +9,8 @@ parent: "[[Bugs/_Index]]"
 
 # YYYY-MM-DD — <bug>
 
+> ใช้เมื่อ bug reproduce ได้หรือมีหลักฐานพอให้ debug ต่อ; ต้องแยก symptom, repro, root cause, fix, prevention เพื่อไม่ให้ AI แก้ซ้ำแบบเดิม
+
 ## อาการ (Symptom)
 
 ## Repro (ทำซ้ำยังไง)

package/second-brain/Templates/handoff.md

@@ -8,6 +8,8 @@ parent: "[[Handoffs/_Index]]"
 
 # <project> — Handoff
 
+> ใช้ส่งต่อ state ของงานค้างให้ session/agent ถัดไป โดยสรุป current state, done, in progress, next steps และไฟล์ที่เกี่ยวข้อง; ไม่ใช้เป็น session log ย้อนหลัง
+
 ## Current State
 
 ## Done

package/second-brain/Templates/session.md

@@ -9,6 +9,8 @@ ai_surface: history
 
 # YYYY-MM-DD — <topic>
 
+> ใช้เมื่อจบงานหรือ checkpoint สำคัญ เพื่อบันทึกสิ่งที่ทำจริง หลักฐานที่ verify แล้ว decision และ next step; ไม่ใช้แทน project overview หรือ handoff
+
 ## Summary
 
 ## What Was Tried

package/second-brain/Tools/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, tools]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# Tools
+
+> utility/tooling เฉพาะเครื่องหรือเฉพาะ vault
+
+## ใส่ที่นี่
+local helper, binary wrapper, one-off utility ที่ยังใช้อยู่
+
+## ไม่ใส่ที่นี่
+durable knowledge (→Learning/Runbooks) · verified executable skill (→Skills)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Tools/_Index]]"` และท้ายไฟล์ `up:: [[Tools/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/second-brain/Traces/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, traces]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# Traces
+
+> exploration/reasoning chain ยาว
+
+## ใส่ที่นี่
+การสืบสวนหลายขั้น (คำถามใหญ่เกินโน้ตเดียว)
+
+## ไม่ใส่ที่นี่
+คำตอบสั้น (→โน้ตปกติ)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Traces/_Index]]"` และท้ายไฟล์ `up:: [[Traces/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/second-brain/Vault Structure Map.md

@@ -20,15 +20,22 @@ ai_surface: hot
 | log งานที่ทำ | `Sessions/` | `YYYY-MM-DD-<topic>.md` |
 | preference ของเจ้าของ | `Shared/User-Memory/` | |
 | การตัดสินใจสำคัญ | `Shared/Decision-Memory/` | |
+| priority/current focus เปลี่ยน | `Shared/Operating-State/current-state.md` | update existing |
 | ยังไม่ชัด/ขัดกัน | `Shared/Memory-Inbox/` | |
 | content จากเว็บ/paste | `Intake/_Quarantine/` | (scan ก่อน) |
 | ต้นฉบับดิบ read-only | `Intake/Raw Sources/` | |
+| finding ที่มี source | `Research/` | ใส่ `source::` |
+| scratch ชั่วคราวระหว่างงาน | `Shared/Working-Memory/` | ลบทิ้ง/โปรโมทหลังจบ |
 | script ที่ผ่าน test | `Skills/` | |
 | how-to อ่านแล้วทำเอง | `Runbooks/` | |
 | กลยุทธ์ที่ปรับดีขึ้น | `Playbooks/` | |
+| fixture expected output | `Acceptance/` | input→expected |
+| pre/postflight gate | `Checklists/` | ticklist |
 | page ของคน/องค์กร/concept | `Entities/` | |
 | bug | `Bugs/` | `YYYY-MM-DD-<bug>.md` |
+| bug ระบบ/OS/toolchain | `Bugs/System-OS/` | `YYYY-MM-DD-<bug>.md` |
 | ส่งมอบงานค้าง | `Handoffs/` | |
+| multi-agent task card | `Shared/Coordination/task-board/` | `<id>.md` |
 
 ## §2 Full Reference (ครบทุกโฟลเดอร์ — ใส่อะไร / ห้ามใส่)
 
@@ -44,6 +51,7 @@ ai_surface: hot
 | `Runbooks/` | prose how-to | ขั้นตอน setup/deploy/maintain | runnable unit (→Skills) |
 | `Templates/` | แม่แบบโน้ต | template ไว้ instantiate | โน้ตจริง |
 | `Bugs/` | bug reproducible (global flat) | bug report + link กลับ project | bug ของ project ที่ไม่ reproduce |
+| `Bugs/System-OS/` | bug ระบบ/OS/toolchain | OS, shell, package manager, permission, filesystem, app-runtime bugs | bug ของ project เฉพาะ |
 | `Handoffs/` | ส่งมอบงานค้าง (snapshot) | state + next steps ส่งต่อ | live coordination (→Coordination) |
 
 ### Direction
@@ -81,13 +89,35 @@ ai_surface: hot
 | `Shared/Decision-Memory/` | decision ที่ AI บันทึก | decision locked + supersedes | ground truth คน (→Core-Facts) |
 | `Shared/Memory-Inbox/` | candidate ยังไม่ชัด | observation รอ promote (clear weekly) | durable ที่ชัดแล้ว (→ปลายทาง) |
 | `Shared/Rules/` | กฎ operating always-on | memory/frontmatter/context-assembly | how-to ทำงาน (→Runbooks) |
-| `Shared/Tech-Standards/` | มาตรฐานเทคนิค | MCP/stack/DoD/verification | |
+| `Shared/Tech-Standards/` | มาตรฐานเทคนิค | MCP/stack/DoD/verification | กฎ memory/format (→Rules) |
 | `Shared/Core-Facts/` | ground truth คนเขียน (read-only) | invariant ที่ AI ห้ามแก้ | decision ที่ AI ตัด (→Decision-Memory) |
 | `Shared/Coordination/` | live multi-agent baton | NOW.md + task-board + registry | เอกสารส่งมอบ (→Handoffs) |
+| `Shared/Coordination/task-board/` | file-Kanban task cards | task ต่อชิ้นงาน มี `claimed_by`/`status` | session narrative หรือ handoff snapshot |
 | `Shared/Working-Memory/` | scratchpad 1 task (ลบได้) | ของชั่วคราวระหว่างทำงาน | อะไรที่จะเก็บ (→Memory-Inbox) |
 | `Shared/User-Persona/` | identity static (read-only) | บทบาท/ค่านิยม/ภาษา/timezone | สิ่งที่ AI เรียนรู้ (→User-Memory) |
 | `Shared/Provenance/` | source ledger | บรรทัด ingest ต่อแหล่ง | โน้ต derived (ใส่ `source::` แทน) |
 | `Shared/Archive/` | cold storage (ไม่ลบ) | โน้ต stale/retired ออกจาก retrieval | ของที่ยังใช้ |
+| `Shared/Scripts/` | automation maintenance | lint/graph-audit/metrics script | one-off retired (→Scripts-Archive) |
+| `Shared/Scripts-Archive/` | สคริปต์ one-off retired | script เก่า (ประวัติ) | script ที่ยังใช้ (→Scripts) |
+| `Shared/mcp-servers/` | vendored MCP server bundle | code/README ของ MCP server | config การต่อ (→Tech-Standards) |
+| `Shared/Context-Packs/` | full-context bundle | pack รวม context พร้อมโหลด | โน้ตเดี่ยว |
+| `Shared/Context7-Docs/` | cached lib doc (regenerable) | cache context7/lib doc | durable knowledge (→Learning) |
+| `Shared/AI-Threads/` | saved AI reasoning trail | thread review/resume/promote | durable decision (→Decision-Memory) |
+| `Shared/Prompting/` | prompt-engineering pattern | pattern การเขียน prompt | prompt asset (→Prompts) |
+| `Shared/Glossary/` | vocabulary กลาง | term + นิยาม | entity page (→Entities) |
+| `Shared/Assets/` | รูป/logo/binary | image/logo/asset | โน้ต .md |
+
+### AI agent config / vendor (root-level)
+| Folder | Role | ใส่ที่นี่ | ห้ามใส่ |
+|---|---|---|---|
+| `.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) |
+
+### Optional / Machine-local
+| Folder | Role | ใส่ที่นี่ | ห้ามใส่ |
+|---|---|---|---|
+| `Tools/` | utility เฉพาะเครื่อง/vault | local helper, wrapper, utility ที่ยังใช้ | durable knowledge หรือ verified skill |
 
 ## §3 Decision Rules (เคสกำกวม)
 
@@ -98,6 +128,8 @@ ai_surface: hot
 - **sourced vs self-derived:** มี external source→`Research` · กลั่นเอง→`Learning`
 - **finite vs ongoing:** มีวันจบ→`Goals` · ไม่จบ→`Areas`
 - **event vs cadence vs metric:** หลังงาน→`Retrospectives` · ตามรอบ→`Reviews` · วัดคุณภาพ→`Evals`
+- **system bug vs project bug:** OS/toolchain/runtime กว้างๆ→`Bugs/System-OS` · bug ของงานหนึ่ง→`Bugs`/`Projects/<proj>`
+- **coordination task vs narrative:** claimable task card→`Shared/Coordination/task-board` · เล่า session→`Sessions` · ส่งต่อ state→`Handoffs`
 
 ## §4 Footer
 

package/second-brain/copilot/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, copilot]
+note_type: moc
+created: {{DATE}}
+updated: {{DATE}}
+parent: "[[Home]]"
+---
+
+# copilot
+
+> vendor export (conversation/custom-prompt/memory snapshot) — review/promote, ไม่ใช่ source of truth
+
+## ใส่ที่นี่
+export จาก Copilot ที่เก็บใน-vault
+
+## ไม่ใส่ที่นี่
+durable (promote เข้า durable layer)
+
+## AI Routing Contract
+
+- ก่อนเขียน: เช็กว่าเนื้อหาตรง "ใส่ที่นี่" และไม่เข้า "ไม่ใส่ที่นี่"; ถ้าก้ำกึ่งอ่าน [[Vault Structure Map]] ก่อน
+- ก่อนสร้างไฟล์ใหม่: ค้นหาโน้ตเดิมในโฟลเดอร์นี้และโฟลเดอร์ใกล้เคียงก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[copilot/_Index]]"` และท้ายไฟล์ `up:: [[copilot/_Index]]`
+- หลังเขียน: เชื่อม link ไป source/project/session/decision ที่เกี่ยวข้อง และอัปเดต hub/index ถ้าโน้ตนี้ควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+
+up:: [[Home]]

package/skills/audit-license-compliance/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: audit-license-compliance
+description: Audits open-source license compliance — resolves SPDX identifiers across the full transitive dependency tree (license-checker/scancode), classifies copyleft (GPL/AGPL/LGPL) exposure against the distribution model, enforces an allow/deny CI policy, and generates NOTICE/THIRD-PARTY attribution files.
+when_to_use: Shipping a product/library or prepping a legal/procurement review and needing to clear OSS license obligations. Distinct from supply-chain-sbom-provenance (build integrity, SBOM signing, provenance), dependency-upgrade (version bumps), and publish-package-registry (the publish step).
+---
+
+## When to Use
+
+Reach for this skill when the question is about **license obligations**, not which versions to ship or whether the build is tamper-proof:
+
+- "Can we ship — does anything here have a GPL/AGPL problem?"
+- "Generate the NOTICE / THIRD-PARTY-LICENSES file for the release."
+- "Add a CI gate that fails the build on a forbidden license."
+- "Legal/procurement needs the full list of dependencies and their licenses."
+- "This transitive dep has no license / is dual-licensed — what do we do?"
+- "We're going from internal SaaS to a downloadable binary — what changes?"
+
+NOT this skill:
+- Generating/signing an SBOM, provenance, or attestations → supply-chain-sbom-provenance (it lists *components*; this skill judges their *licenses*)
+- Bumping a version or swapping a GPL dep for an alternative → dependency-upgrade
+- The actual `npm publish` / `twine upload` step and its OIDC gate → publish-package-registry
+- A design-level risk enumeration of the system → threat-model-stride
+
+## Steps
+
+1. **Scan the FULL transitive tree, not just direct deps — and pin the result to a manifest.** Direct deps are a tiny minority; copyleft almost always rides in transitively. Pick the resolver for the ecosystem and emit machine-readable output:
+
+   ```bash
+   # Node — license-checker-rseki (maintained fork) over the *production* tree only
+   npx license-checker-rseki --production --json --out licenses.json
+   # Python
+   pip-licenses --format=json --with-license-file --with-urls > licenses.json
+   # Rust
+   cargo install cargo-deny && cargo deny list -f json > licenses.json
+   # Go
+   go install github.com/google/go-licenses@latest && go-licenses report ./... > licenses.csv
+   # Ground truth when metadata lies — scans actual file headers/text
+   pipx run scancode-toolkit scancode --license --json-pp scancode.json <vendored_dir>
+   ```
+   Scope to what you **distribute**: prod/runtime deps only. devDependencies, test, and build-only tooling are generally not distributed — exclude them (`--production`, `--omit=dev`) or you'll drown in false GPL hits from linters. When package metadata is missing or wrong, `scancode` reading the real LICENSE/headers is the tiebreaker, not the `package.json` `license` field.
+
+2. **Classify each license by risk against YOUR distribution model — this is the whole audit.** The same license is fine or fatal depending on how you ship. Decide the model first, then read the table left-to-right:
+
+   | License class | Examples | SaaS (network only) | Distributed binary / app | Library you publish |
+   |---|---|---|---|---|
+   | Permissive | MIT, BSD-2/3, ISC, Apache-2.0, Unlicense, 0BSD | ✅ allow | ✅ allow (must keep NOTICE) | ✅ allow |
+   | Weak copyleft (file) | MPL-2.0, EPL-2.0, CDDL | ✅ allow | ⚠️ allow if unmodified & file-isolated | ⚠️ review |
+   | Weak copyleft (lib) | LGPL-2.1/3.0 | ✅ allow | ⚠️ **dynamic** link only; static link triggers relink obligation | ⚠️ review |
+   | Strong copyleft | GPL-2.0, GPL-3.0 | ✅ allow (no conveying) | ❌ **deny** — forces whole-program source disclosure | ❌ deny |
+   | Network copyleft | **AGPL-3.0** | ❌ **deny** — network use = conveying, source must be offered to users | ❌ deny | ❌ deny |
+   | Notice-heavy / patent | Apache-2.0, BSD-4-Clause | ✅ (track NOTICE/patent grant) | ⚠️ BSD-4 advertising clause incompatible w/ GPL | ⚠️ review |
+   | Non-OSS / source-available | SSPL, BUSL-1.1, Elastic-2.0, CC-BY-NC, "Commons Clause" | ❌ deny (not OSI; usage-restricted) | ❌ deny | ❌ deny |
+   | Public domain / unclear | WTFPL, "UNLICENSED", no license | ❌ deny pending manual review | ❌ deny pending review | ❌ deny |
+
+   The trap most teams miss: **AGPL bites SaaS** (where GPL does not, because you never "convey" a binary), and **LGPL/GPL bite distributed binaries** (where they're harmless on a server). Set the model once; don't hand-wave it as "it depends."
+
+3. **Encode the policy as allow / deny / review with SPDX IDs and gate CI on it.** A human-readable table isn't enforcement. Use one tool to both classify and fail the build. `cargo-deny`-style config (mirror the shape in `license-checker --failOn` or an `oss-review-toolkit`/`fossa`/`trivy` policy):
+
+   ```toml
+   # deny.toml — explicit allowlist; everything unlisted is a hard failure
+   [licenses]
+   allow = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "MPL-2.0"]
+   confidence-threshold = 0.9          # below this, treat as unknown → fail
+
+   # exceptions: this one crate is allowed despite the policy, with a reason on record
+   [[licenses.exceptions]]
+   crate = "ring"
+   allow = ["OpenSSL"]                 # rationale: leaf TLS dep, OpenSSL terms cleared by legal 2026-05
+   ```
+   ```bash
+   # CI gate — non-zero exit blocks the merge. Run on every PR.
+   cargo deny check licenses
+   # Node equivalent (allowlist must match deny.toml above):
+   npx license-checker-rseki --production --onlyAllow \
+     "MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;MPL-2.0" --excludePrivatePackages
+   ```
+   Default posture is **allowlist, deny-by-default**: an unknown/unparseable license fails closed, so a newly added denied or no-license dep cannot merge silently. Route genuinely-ambiguous cases to a `review` bucket that fails CI with a "needs legal sign-off" message rather than auto-allowing.
+
+4. **Resolve dual-licensed and missing-license deps explicitly — never let the tool pick for you.** SPDX `OR` means *you choose* (e.g. `(MIT OR Apache-2.0)` → pick the one in your allowlist and record the choice). SPDX `AND` means *both apply* (you must satisfy every obligation). For a dep with **no license**, default-deny: open an issue, contact the maintainer, or remove it — "no license" means all-rights-reserved, not free. Pin every resolution and exception in `deny.toml`/policy with a one-line rationale so the next audit doesn't relitigate it.
+
+5. **Generate NOTICE / THIRD-PARTY-LICENSES attribution from the same scan.** Permissive licenses (MIT/BSD/Apache) require you to reproduce their copyright + license text in distributed artifacts; Apache-2.0 also requires propagating any upstream `NOTICE`. Auto-generate, don't hand-maintain:
+
+   ```bash
+   npx oss-attribution-generator ./   # → oss-attribution/attribution.txt
+   # or: license-checker-rseki --production --customPath fields.json --files THIRD-PARTY-LICENSES/
+   pip-licenses --format=plain-vertical --with-license-file --no-license-path \
+     --output-file THIRD-PARTY-LICENSES.txt
+   go-licenses save ./... --save_path=THIRD-PARTY-LICENSES/
+   ```
+   Ship `THIRD-PARTY-LICENSES.txt` (or `NOTICE`) inside the artifact — in the package tarball, the container image, the app's "Licenses" screen, or `/licenses`. Regenerate it in CI from the locked tree and **diff against the committed copy** so a new dep can't slip in without its attribution.
+
+6. **Wire both gates into one CI job.** Policy check (step 3) + attribution drift check (step 5) run on every PR and on the release tag. Fail the build if a denied/unknown license appears OR the generated NOTICE differs from the committed one. This is what makes the audit durable instead of a one-time spreadsheet.
+
+## Common Errors
+
+- **Scanning direct deps only.** The GPL/AGPL almost always arrives 3 levels deep. Always resolve the full transitive tree (`--production` flattens it).
+- **Including devDependencies in the distributed verdict.** A GPL linter or test runner isn't distributed and isn't a violation — it just floods the report and gets the gate disabled. Scope to runtime/prod.
+- **Trusting the package `license` field over the actual files.** Metadata is frequently wrong, stale, or `SEE LICENSE IN ...`. When it matters, let `scancode` read the real LICENSE/headers; that's ground truth.
+- **Treating AGPL like GPL for a SaaS.** AGPL's network clause means serving it over HTTP *is* conveying — source must be offered to every user. Deny AGPL even when GPL would be fine for your server-only model.
+- **Static-linking an LGPL library into a shipped binary.** That triggers the relink obligation (users must be able to swap the lib). Dynamic-link it, or treat it as deny for static builds.
+- **Auto-picking a side of a dual license silently.** `(GPL-2.0 OR MIT)` is only safe because *you* elect MIT — record the election. If the tool defaulted to GPL, you may have manufactured an obligation that didn't exist.
+- **"No license" read as permissive.** Absence of a license = all rights reserved = you have no grant to use it. Default-deny and resolve, don't ship.
+- **Allowlist that fails *open* on unknowns.** A typo SPDX id or low-confidence match must fail the build, not pass. Set `confidence-threshold` and deny-by-default.
+- **Hand-maintaining NOTICE.** It drifts the moment a transitive dep changes. Generate it from the lockfile in CI and diff against the committed copy.
+- **Confusing source-available with open-source.** SSPL/BUSL/Elastic-2.0/"Commons Clause" are usage-restricted and not OSI-approved — deny them unless legal explicitly cleared the specific use.
+
+## Verify
+
+1. **Coverage:** The scan output lists *transitive* deps, not just the handful in `package.json`/`Cargo.toml`. Spot-check a known deep dep appears with a license.
+2. **Policy gate fires (positive control):** Add a dep with a denied license (e.g. a GPL-3.0 package) on a throwaway branch → CI **fails** with a message naming the dep and its license. Revert.
+3. **Unknown fails closed:** Point the scanner at a dep with a stripped/garbled license → it is reported as unknown and the gate **fails**, not passes.
+4. **Distribution-model correctness:** Re-run classification under the other model (flip SaaS↔distributed) and confirm AGPL/LGPL/GPL verdicts change as the table predicts — proves the model is actually driving the verdict, not hardcoded.
+5. **Attribution completeness:** Every distributed (prod) dependency in the lockfile appears in `THIRD-PARTY-LICENSES`/`NOTICE` with its license text. Count of attributed deps == count of distributed deps; no entry is empty.
+6. **Attribution drift gate:** Add a prod dep without regenerating → CI's NOTICE-diff check **fails**. Regenerate → it passes and the new dep+license is present.
+7. **Dual/missing resolved:** No dep is left with an unresolved `OR` expression or empty license; each exception in the policy has a written rationale.
+
+Done = the scan covers the full transitive prod tree, CI blocks a newly added denied-license **and** an unknown-license dep (verified by positive controls), every distributed dependency is listed with its license in the committed NOTICE, and the NOTICE-drift gate fails when that list goes stale.

package/skills/author-codemod/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: author-codemod
+description: Writes, fixture-tests, and runs codebase-wide automated transforms (codemods) that parse source to an AST and rewrite nodes via grammar-aware tools (jscodeshift/ts-morph, ast-grep, Comby, libcst/Bowler, OpenRewrite), dry-running before applying one mechanical change across many files. Use when a structural edit must hit many call sites reliably and find-replace would mangle strings, comments, or shadowed names.
+when_to_use: One mechanical change must land across many files — rename/move an exported API across all call sites, swap a deprecated call, rewrite an import path or signature, migrate an idiom (callbacks→async, class→hooks). Distinct from refactor-cleanup (judgment-driven edits in a few files), dependency-upgrade (bumping versions), and regex-build (a single pattern, not a tree transform).
+---
+
+## When to Use
+
+Reach for this skill when the **same structural edit must hit many files** and correctness depends on understanding the code's grammar, not its text:
+
+- "Rename `getUser` → `fetchUser` everywhere, including imports/exports/JSX, but not the string `"getUser"` in logs"
+- "Replace every `moment(x)` with `dayjs(x)` across the repo"
+- "Change the import path `@old/pkg` → `@new/pkg` and rewrite the now-renamed named exports"
+- "Migrate all `React.Component` classes to function components / hooks"
+- "Add `await` to every call site of a function that became async"
+- "Swap deprecated `assert.equal` → `assert.strictEqual` repo-wide"
+
+NOT this skill:
+- A judgment-heavy cleanup in 1–3 files where each edit is a decision, not a rule → refactor-cleanup
+- Bumping a package version and fixing the fallout it causes → dependency-upgrade (a codemod may be a *step* inside it)
+- One search/replace pattern over text where a tree isn't needed → regex-build
+- Reviewing the resulting diff for bugs → code-review
+- Schema/data changes in a running DB → db-migration-safety
+
+## Steps
+
+1. **Pick the tool by language and edit shape — don't reach for `sed`.** A grammar-aware tool refuses to touch strings, comments, and shadowed bindings; text tools can't tell them apart.
+
+   | Language / scope | Tool | Reach for it when |
+   |---|---|---|
+   | JS/TS, complex semantic rewrite | **jscodeshift** (Babel/recast AST) | rename across imports/exports/JSX, signature changes; preserves formatting via recast |
+   | TS, type-aware, follow references | **ts-morph** | needs the type checker — find *all* references to a symbol, not name matches |
+   | JS/TS/Go/Python/Rust, pattern→pattern | **ast-grep** (`sg`) | declarative `pattern:`/`rewrite:` in YAML, polyglot, fast, no JS to write |
+   | Any language, structural find/replace | **Comby** | lightweight `:[hole]` matchers when you don't want a full AST pass |
+   | Python | **libcst** (or **Bowler** for simple cases) | preserves comments + formatting; libcst for graph-aware, Bowler for fluent one-liners |
+   | Java/Kotlin | **OpenRewrite** (recipes) | type-aware recipes, dependency + API migrations at scale |
+
+   Default: **ast-grep** for a clean pattern→pattern swap in any language; **jscodeshift** when the JS/TS rewrite needs real logic; **ts-morph** when you must follow type references, not text.
+
+2. **Characterize on 2–3 representative files first, then enumerate edge cases.** Open real call sites and write down what must and must NOT change. Hostile cases that break naive transforms:
+   - **Shadowing** — a local `const getUser = ...` that is *not* the imported symbol.
+   - **Re-exports / aliases** — `export { getUser as gu }`, `import { getUser as g }`.
+   - **Dynamic access** — `obj["getUser"]`, computed members, reflection — usually out of AST reach; list them as manual tail.
+   - **Strings & comments** — must be left alone unless explicitly targeted.
+   - **Formatting** — preserve it (recast/libcst/ts-morph do; a naive print does not).
+   - **Partial matches** — `getUserById` must not be caught by a `getUser` rule.
+
+3. **Write the transform as code and test it on fixtures before touching the tree.** The codemod is software — assert before/after so a bad rule can't run silently. jscodeshift skeleton:
+
+   ```js
+   // rename-getUser.js — jscodeshift transform
+   module.exports = function (file, api) {
+     const j = api.jscodeshift;
+     const root = j(file.source);
+     // only rename the IMPORTED binding, follow its local name (handles aliases)
+     root.find(j.ImportSpecifier, { imported: { name: 'getUser' } })
+       .forEach((p) => {
+         const local = p.node.local.name;            // respects `as` alias
+         root.find(j.Identifier, { name: local })
+           .filter((id) => id.parent.node.type !== 'ImportSpecifier')
+           .forEach((id) => { id.node.name = 'fetchUser'; });
+         p.node.imported.name = 'fetchUser';
+       });
+     return root.toSource({ quote: 'single' });
+   };
+   ```
+   ```js
+   // rename-getUser.test.js — the codemod itself is under test
+   const { applyTransform } = require('jscodeshift/dist/testUtils');
+   const t = require('./rename-getUser');
+   test('renames imported symbol, not the shadow or the string', () => {
+     expect(applyTransform(t, {}, { source:
+       `import { getUser } from './api';\nconst x = getUser(1);\nlog("getUser");` }))
+     .toBe(
+       `import { fetchUser } from './api';\nconst x = fetchUser(1);\nlog("getUser");`);
+   });
+   ```
+   ast-grep equivalent needs no test harness but still gets a fixture diff: `sg run -p 'getUser($A)' -r 'fetchUser($A)' --lang ts fixtures/ --dry-run`.
+
+4. **Dry-run across the whole tree; review stats and sampled hunks; tune to zero false hits.** Never let the first run write. jscodeshift `--dry --print` (or `-d -p`), ast-grep `--dry-run`, Comby without `-i`, libcst via a `--no-write` flag. Inspect the **count** of changed files and read a random sample of hunks — if any touch a string, comment, or shadow, fix the rule and re-dry-run. Iterate until the only diff is the intended one.
+
+5. **Apply, then immediately run the toolchain — the codemod's output is unverified until the build agrees.** Run formatter → linter → typecheck → tests in that order: `prettier --write` / `gofmt`, then `eslint --fix`, then `tsc --noEmit`, then the suite. A green typecheck is the strongest signal a JS/TS rename hit every real reference; a red one points straight at a missed or over-eager site.
+
+6. **Handle the long tail manually and document it.** Dynamic access, generated code, vendored files, and cross-package boundaries the AST can't follow stay broken — `grep` the old name to find survivors, fix them by hand, and note in the commit what the codemod could not reach and why.
+
+7. **Commit the transform script alongside its diff.** Check in the codemod file + its fixture test in the same commit as the generated changes, with the exact command in the message. The change becomes reproducible, reviewable as a rule (not N edits), and re-runnable when stragglers appear.
+
+## Common Errors
+
+- **`sed`/find-replace across a grammar.** Rewrites the symbol inside strings, comments, and shadowed locals. Use an AST tool that distinguishes node kinds.
+- **Matching the name, not the binding.** A bare `Identifier` rename also hits an unrelated local `getUser`. Anchor to the import/declaration and follow its references (ts-morph `findReferences`, or trace the local name as in step 3).
+- **Ignoring `as` aliases and re-exports.** `import { getUser as g }` renames nothing if you only look for `getUser` identifiers. Read `local` vs `imported`; rewrite both the export and its consumers.
+- **Substring false positives.** A `getUser` text rule mangles `getUserById`/`getUsers`. AST identifier matching is exact; text rules need word boundaries and review.
+- **Printing instead of patching the AST** (`root.toSource()` from a fresh print) reflows the whole file — huge noise diff. Use recast (jscodeshift default), libcst, or ts-morph to preserve untouched formatting.
+- **No fixture test on the codemod.** A subtle rule bug silently corrupts hundreds of files. Assert before/after on representative inputs *before* the tree run.
+- **Skipping the dry-run.** First run writes; you discover the over-match after it's everywhere. Always dry-run, read sampled hunks, then apply.
+- **Trusting "0 errors" without a typecheck.** A rename can compile-pass yet miss dynamic call sites. Run `tsc`/tests after; `grep` the old name for survivors.
+- **Letting the formatter mask a bad transform.** Running `prettier` first can hide a structural mistake behind reformatting. Diff the raw codemod output, *then* format.
+- **One mega-transform doing five things.** Unreviewable and unrevertable. One codemod = one rule; chain separate scripts.
+
+## Verify
+
+1. **Fixture tests pass:** the codemod's own before/after assertions are green, including a shadow case, an alias/re-export case, and a string-that-must-not-change case.
+2. **Dry-run is clean:** the dry-run diff contains only intended hunks — zero edits inside strings, comments, or shadowed locals (confirm by reading a random sample, not just the count).
+3. **No stragglers:** `grep -rn '\bgetUser\b'` (old name, word-bounded) over the tree returns only the documented manual tail — nothing the codemod should have caught.
+4. **Toolchain agrees:** formatter clean, linter clean, `tsc --noEmit` (or language equivalent) exits 0, full test suite passes on the transformed tree.
+5. **Diff is minimal:** changed lines are the transform's effect only — no incidental reformatting of untouched code.
+6. **Reproducible:** the codemod script + fixture test are committed with the diff and the exact run command; re-running the codemod on the result is a no-op.
+
+Done = fixture tests + dry-run are clean, the post-apply toolchain (format/lint/typecheck/tests) is fully green, no undocumented stragglers remain, and the transform script ships in the same commit so the change re-runs deterministically.