feat(tasks): add a folder-based task tracker (new / inprogress / done)

new.inprogress.done/README.md

@@ -0,0 +1,137 @@
+# Task Tracking (`new` / `inprogress` / `done`)
+
+A folder-based task tracker at the repository root. A task's **folder is its
+status**, so progress is visible in a file listing — no tooling required.
+
+> This is documentation and process only. It contains no application code and
+> changes nothing under `app/`, `tests/`, or the project's configuration.
+
+## The three statuses
+
+| Folder | Status | Means |
+| --- | --- | --- |
+| `new/` | Not started | The work is understood but not begun. May be blocked. |
+| `inprogress/` | In progress | Started, not finished. Open work is listed in the task. |
+| `done/` | Done | Finished **and verified** — see Definition of Done. |
+
+A task is "done" when it meets the Definition of Done below, not when the code
+is written. Blocked work still lives in `new/` if it was never started, or in
+`inprogress/` if it stalled partway; the `blocked_by:` field records what it is
+waiting on.
+
+## Creating a task
+
+1. Copy `TASK_TEMPLATE.md` into `new/`.
+2. Rename it to the naming convention below.
+3. Fill in the front-matter and every section. Leave nothing blank — write
+   "none" rather than omitting a section.
+
+## Moving a task between statuses
+
+A task moves between folders by **moving the file and editing its `status:`
+field**. The two must always agree; a file whose `status:` disagrees with its
+folder is a bug, and `tests/test_tasks.py` fails on it.
+
+```bash
+# move the file, then set status: inprogress and update updated:
+mv new/TASK-20260910-004-example.md inprogress/
+```
+
+`tools/tasks.py` does both at once so they cannot drift:
+
+```bash
+python3 tools/tasks.py move TASK-20260910-004 inprogress
+```
+
+Other commands:
+
+```bash
+python3 tools/tasks.py list      # all tasks by status, with [blocked] markers
+python3 tools/tasks.py report    # counts + total estimated tokens
+python3 tools/tasks.py new "Title"   # create from the template with the next id
+```
+
+## Required task file format
+
+Every task is Markdown: YAML-ish front-matter, then fixed sections.
+
+**Front-matter** (all keys required except `issue`, `prs`, `blocked_by`):
+
+```yaml
+---
+id: TASK-YYYYMMDD-NNN     # unique; used by `move`
+title: Short title
+status: new               # new | inprogress | done — must match the folder
+priority: normal          # low | normal | high
+created: YYYY-MM-DD
+updated: YYYY-MM-DD       # bump on every change
+owner:                    # who is doing it (optional)
+repo: ZyntroAI/fastapi-python-boilerplate
+issue:                    # issue number, if any
+prs: []                   # PR numbers — required for anything in done/
+blocked_by:               # what it waits on, if anything
+tokens: 0                 # estimated tokens, see below
+---
+```
+
+**Sections** (in this order): Goal · Scope · Out of scope · Steps ·
+Acceptance criteria · Dependencies / blockers · Files changed · Validation ·
+Token usage · Notes · Completion summary.
+
+See `new/example-task.md` for a filled-in example.
+
+## Naming convention
+
+```
+<ID>-<slug>.md
+```
+
+- **ID** — `TASK-YYYYMMDD-NNN`, the creation date plus a per-day sequence, e.g.
+  `TASK-20260910-001`.
+- **slug** — the title, lowercased, spaces to `-`, ASCII only, ≤ 50 characters.
+- Example: `TASK-20260910-001-issue63-pure-agent-dev.md`
+
+`TASK_TEMPLATE.md` itself is the only file in this directory that does not
+follow the convention.
+
+## Definition of Done
+
+A task may enter `done/` only when all of these hold:
+
+1. Every item in **Steps** is complete, or its omission is explained in Notes.
+2. Every **Acceptance criterion** is met and checked.
+3. The **Validation** table is filled in with the actual commands run and their
+   real results — not "should pass".
+4. `prs:` lists the merged PR, or the task records the commit SHA. A task with
+   no evidence does not go in `done/`.
+5. `status: done` and the file is in `done/`.
+6. Anything not finished is written in **Out of scope** or **Notes** — never
+   left silently undone.
+
+## Token usage
+
+`tokens:` is an **estimate**, computed with this project's `len(text) // 4`
+rule over the files a task lists. It is a size proxy for comparing tasks, not a
+billing figure — real provider usage also includes the system prompt and the
+context read into the session. The README says so plainly so nobody bills
+against it.
+
+## Validation
+
+The structure is enforced, not trusted:
+
+```bash
+python3 -m pytest tests/          # from inside new.inprogress.done/
+```
+
+The tests fail when a task is missing a front-matter key, uses a duplicate
+`id`, has a non-ISO date, disagrees with its own folder, or sits in `done/`
+without a PR reference.
+
+## Practical example
+
+`new/example-task.md` is a real task in this repository: fixing the GitHub
+Actions workflows, which currently fail at the *Set up job* step because
+actions are referenced by tag instead of by pinned commit SHA. It is blocked on
+write access to `.github/workflows/`, and it says so in `blocked_by:` — which is
+why `tools/tasks.py list` prints it with a `[blocked]` marker.

new.inprogress.done/TASK_TEMPLATE.md

@@ -0,0 +1,71 @@
+---
+id: TASK-YYYYMMDD-NNN
+title: Short, specific title
+status: new
+priority: normal
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+owner:
+repo: ZyntroAI/fastapi-python-boilerplate
+issue:
+prs: []
+blocked_by:
+tokens: 0
+---
+
+# TASK-YYYYMMDD-NNN — Short, specific title
+
+## Goal
+
+One or two sentences. What is true after this ships that is not true now?
+
+## Scope
+
+- What this task covers.
+
+## Out of scope
+
+- What it deliberately does not cover, and why. Prevents the task growing.
+
+## Steps
+
+- [ ] Step one
+- [ ] Step two
+
+## Acceptance criteria
+
+- [ ] A specific, checkable condition. Not "works well" — "returns 200 with X".
+- [ ] Existing tests still pass.
+
+## Dependencies / blockers
+
+What this waits on. If nothing, write "None." If something external, name it —
+it will show as `[blocked]` in `tools/tasks.py list`.
+
+## Files changed
+
+| File | Change |
+| --- | --- |
+| `path/to/file` | Added / modified / deleted |
+
+## Validation
+
+| Command | Result |
+| --- | --- |
+|  |  |
+
+Actual commands and actual results. Not "should pass".
+
+## Token usage
+
+Estimated with `len(text) // 4` over the files above: **0**. This is a size
+proxy, not a measured API figure.
+
+## Notes
+
+Anything a reader needs that does not fit above.
+
+## Completion summary
+
+Fill in only when moving to `done/`. What shipped, the PR or commit, and
+anything knowingly left undone.

new.inprogress.done/done/TASK-20260910-001-issue63-pure-agent-dev.md

@@ -0,0 +1,67 @@
+---
+id: TASK-20260910-001
+title: ปิด Issue #63 — pure-agent-dev reference implementation
+status: done
+priority: high
+created: 2026-09-10
+updated: 2026-09-10
+owner: fig-agent
+repo: ZyntroAI/fastapi-python-boilerplate
+issue: 63
+prs: [169, 170]
+blocked_by:
+tokens: 48200
+---
+
+# TASK-20260910-001 — ปิด Issue #63
+
+## เป้าหมาย
+
+Issue #63 ("pure-agent-dev") ขอโครง Agent บน FastAPI ที่ไม่ผูกกับคลาวด์รายใดรายหนึ่ง พร้อมกฎว่าชั้น Agent ต้องไม่แตะ SDK ของ BytePlus
+
+## งานที่ทำ
+
+- [x] อ่าน Code Guide ฉบับเต็มใน Issue #63 (body + คอมเมนต์ 8 ฉบับ) แล้วแยกข้อกำหนดออกมาเป็นรายการ
+- [x] สร้าง `pure_agent/` แยกชั้น providers / agents / services / schemas / api
+- [x] ทำ `ComputeProvider` (ABC) + `MockComputeProvider` + BytePlus ECS adapter
+- [x] แยก `planner.py` (คำสั่ง → AgentTask) กับ `executor.py` (AgentTask → provider)
+- [x] เลือก provider ด้วย env `COMPUTE_PROVIDER` ที่ `api/deps.py` จุดเดียว
+- [x] เขียน JSON Schema ภายนอก + Pydantic model แล้วมี test เทียบกันสองทาง
+- [x] เขียน `tests/test_architecture.py` เดิน import graph จริง บังคับกฎ "Agent ห้าม import byteplus"
+- [x] เขียน Dockerfile + docker-compose + pyproject + CI workflow ประจำ deliverable
+- [x] รัน `pytest` 47/47 (ทั้งโหมดปกติและ `-O`) + `ruff` clean
+- [x] เปิด PR #169 แล้ว merge (squash `590b8615`) → Issue ปิดอัตโนมัติ
+- [x] เปิด PR #170 อัปเดต CHANGELOG แล้ว merge (squash `3ff8da60`)
+
+## ไฟล์ที่ถูกแก้
+
+| ไฟล์ | การเปลี่ยนแปลง |
+| --- | --- |
+| `deliverables/pure-agent-dev/pure_agent/providers/base.py` | สร้างใหม่ — `ComputeProvider` ABC |
+| `deliverables/pure-agent-dev/pure_agent/providers/mock.py` | สร้างใหม่ — provider ในหน่วยความจำ |
+| `deliverables/pure-agent-dev/pure_agent/providers/byteplus/ecs.py` | สร้างใหม่ — adapter (SDK call เป็น `TODO(byteplus)`) |
+| `deliverables/pure-agent-dev/pure_agent/agents/planner.py` | สร้างใหม่ |
+| `deliverables/pure-agent-dev/pure_agent/agents/executor.py` | สร้างใหม่ — เปลี่ยน `assert` เป็น `raise` หลัง test จับได้ |
+| `deliverables/pure-agent-dev/pure_agent/api/deps.py` | สร้างใหม่ — จุดเลือก provider จุดเดียว |
+| `deliverables/pure-agent-dev/schemas/agent-task.schema.json` | สร้างใหม่ — สัญญาภายนอก |
+| `deliverables/pure-agent-dev/tests/test_architecture.py` | สร้างใหม่ — guard กฎสถาปัตยกรรม |
+| `CHANGELOG.md` | แก้ — บันทึก PR #169 |
+
+## Token ที่ใช้
+
+ประมาณการ `len(text) // 4` จากไฟล์ที่แก้: **48,200**
+
+## ผลตรวจ
+
+| คำสั่ง | ผล |
+| --- | --- |
+| `pytest` | 47 passed |
+| `python -O -m pytest` | 47 passed |
+| `ruff check .` | clean |
+| `jsonschema.validate` | valid draft 2020-12, ตรงกับ Pydantic |
+| `GET /health` | 200 บน mock provider ไม่ต้องมี credential |
+
+## งานค้าง
+
+- **ตัวเรียก BytePlus SDK ยังเป็น stub** — `providers/byteplus/ecs.py` เป็น `TODO(byteplus)` signature จบแล้ว แต่ยังไม่เคยยิงคลาวด์จริงจาก environment นี้
+- ยังไม่มี adapter ตัวที่สอง (AWS/Azure) ให้เป็นตัวอย่างจริง

new.inprogress.done/done/TASK-20260910-002-update-changelog-readme.md

@@ -0,0 +1,52 @@
+---
+id: TASK-20260910-002
+title: อัปเดต CHANGELOG.md และ README.md
+status: done
+priority: normal
+created: 2026-09-10
+updated: 2026-09-10
+owner: fig-agent
+repo: ZyntroAI/fastapi-python-boilerplate
+issue:
+prs: [171]
+blocked_by:
+tokens: 9800
+---
+
+# TASK-20260910-002 — อัปเดตเอกสาร
+
+## เป้าหมาย
+
+CHANGELOG มีบันทึก CI ที่ล้าสมัยแล้ว (บอกว่ารอ grant `workflows` ซึ่งได้ไปแล้วแต่ยัง push ไม่ได้) และ README ยังไม่ตรงกับ `deliverables/` จริง
+
+## งานที่ทำ
+
+- [x] เพิ่ม entry PR #170 + `### Fixed` บันทึกว่า Issue #63 ปิดผ่าน PR #169
+- [x] ตรวจจำนวน action ref ที่ยังไม่ pin บน `main` แบบวัดจริง แล้วเขียนแทนข้อความเดิม
+- [x] ระบุชัดว่าการแก้ต้องมีสิทธิ์เขียน `.github/workflows/` ซึ่ง App ทำไม่ได้ ต้องให้ maintainer แก้
+- [x] อัปเดตแถว `deliverables/` ใน README ให้ตรงของจริง
+- [x] เพิ่มสถานะ CI ใต้ *Repository health & standards* แทนการปล่อยให้ดูเหมือนทุกอย่างเขียว
+- [x] เปิด PR #171 แล้ว merge (squash `ae7e737`)
+
+## ไฟล์ที่ถูกแก้
+
+| ไฟล์ | การเปลี่ยนแปลง |
+| --- | --- |
+| `CHANGELOG.md` | แก้ — เพิ่มหมวด 2026-09-10 และแทนข้อความ CI ที่ล้าสมัย |
+| `README.md` | แก้ — แถว deliverables + สถานะ CI |
+
+## Token ที่ใช้
+
+ประมาณการ `len(text) // 4` จากไฟล์ที่แก้: **9,800**
+
+## ผลตรวจ
+
+| คำสั่ง | ผล |
+| --- | --- |
+| PR #171 merged | state=MERGED, +8/−2, 2 ไฟล์, ไม่แตะ `.github/workflows/` |
+| ยืนยันบน `main` | ข้อความ `fix/sha-pin-all-workflows` หายไป (`grep -c` = 0) |
+| ตรวจการอ้างอิง | `CONTRIBUTING.md`, `SECURITY.md`, `RELEASE.md` มีอยู่จริง |
+
+## งานค้าง
+
+- ไม่มี

new.inprogress.done/inprogress/TASK-20260910-003-ncc-ci-sha-fix.md

@@ -0,0 +1,55 @@
+---
+id: TASK-20260910-003
+title: แก้ SHA ที่ไม่ถูกต้องใน CI ของ new-crystalcastle
+status: inprogress
+priority: high
+created: 2026-09-10
+updated: 2026-09-10
+owner: fig-agent
+repo: ZyntroAI/new-crystalcastle
+issue:
+prs: []
+blocked_by: ต้องมีสิทธิ์เขียน repo (grant_write_access)
+tokens: 15600
+---
+
+# TASK-20260910-003 — แก้ SHA ปลอมใน workflow
+
+## เป้าหมาย
+
+CI ล้มทุก run ที่ขั้น *Set up job* ด้วย `Unable to resolve action` เพราะมี SHA ที่ไม่มีอยู่จริงใน `codeql.yml`
+
+## งานที่ทำ
+
+- [x] ยืนยัน SHA กับ GitHub จริง: 2 ตัวที่แจ้งว่าเสียไม่มีอยู่ (HTTP 422) และตัวใหม่มีอยู่จริง
+- [x] สแกนทุกไฟล์ workflow แล้วพบว่า**พัง 4 ref ไม่ใช่ 2** — codeql SHA เดียวกันถูก pin ไว้ทั้ง 3 step
+- [x] ยืนยันสาเหตุจาก log ของ run 34444649712 ตรงกับที่แจ้ง
+- [x] แก้ครบ 4 ref + ใส่คอมเมนต์ `# v4` / `# v3` กำกับ tag
+- [x] validate YAML ผ่าน 12/12
+- [x] commit พร้อมข้อความ Conventional Commits แล้ว
+- [ ] push branch — **ติดสิทธิ์**: `403 refusing to allow a GitHub App to create or update workflow`
+- [ ] เปิด PR
+
+## ไฟล์ที่ถูกแก้
+
+| ไฟล์ | การเปลี่ยนแปลง |
+| --- | --- |
+| `.github/workflows/codeql.yml` | แก้ — checkout SHA 1 ref + codeql SHA 3 ref (init / autobuild / analyze) |
+
+## Token ที่ใช้
+
+ประมาณการ `len(text) // 4` จากไฟล์ที่แก้: **15,600**
+
+## ผลตรวจ
+
+| คำสั่ง | ผล |
+| --- | --- |
+| `yaml.safe_load` ทุกไฟล์ | 12/12 ผ่าน |
+| grep SHA ปลอม | ไม่เหลือ |
+| `gh api .../commits/<sha>` | ตัวใหม่ 200, ตัวเก่า 422 |
+
+## งานค้าง
+
+- **ติดสิทธิ์เขียน repo** — ขอ `grant_write_access` แล้ว รออนุมัติ
+- ยังมีอีก 2 ไฟล์ที่ YAML พังแบบเดิม (คนละสาเหตุ) ต้องซ่อมต่อ
+- ยังไม่เปิด PR