@blxzer/pactile 0.5.0

package/dist/templates/pactile/pool/README.md

@@ -0,0 +1,149 @@
+# Review Pool（审核池）
+
+> Purpose: one place for product ideas, directions, and review gaps — enter the pool for triage, leave via a development plan.
+> The pool holds candidates; the plan holds commitments.
+
+## Directory layout
+
+```
+.pactile/pool/
+├── README.md            ← this file (mechanism)
+├── plan.md              ← development plan (references item ids only)
+├── items/               ← one small markdown file per adjudicable item
+├── knowledge-base/      ← optional: rejected rationale by concept (lazy)
+└── archive/             ← optional: terminal home for rejected items (lazy)
+```
+
+## State machine
+
+```
+inbox ──► review ──► accepted (enter development plan)
+          │
+          ├──► rejected (move to archive + knowledge-base; reason required)
+          └──► rework (missing info / not shippable → rewrite with user → back to inbox)
+```
+
+- `accepted`: Agent proposes; user confirms before the status flips. **Does not mean the work is done.** Completion is `delivery` (see below).
+- `rejected`: terminal; item moves under `archive/`; rationale goes to `knowledge-base/` (one file per concept; Prior requests for dedupe).
+- `rework`: transit state, not terminal; after rewrite, return to `inbox`.
+- **Exception**: “already implemented / duplicate” items do **not** enter knowledge-base (that would poison dedupe). Point at the existing implementation and close.
+
+## Item fields (adjudicable four-pack + type + links)
+
+Each file under `items/` needs frontmatter:
+
+```yaml
+---
+id: P01            # item id (plan.md references this only)
+title: Short title
+status: accepted   # inbox | review | accepted | rejected | rework
+type: mechanism    # research | prototype | grilling | task (decision-type tag)
+locale: zh
+created: 2026-08-08
+approved: 2026-08-08  # only when accepted
+priority: P1       # optional; accepted only. P0 | P1 | P2. Missing → treat as P2
+delivery: standing  # accepted only. open | in-slice | landed | standing | deferred
+linked_tasks:      # optional: task directory names (slice index, not completion)
+  - 08-08-example-task
+---
+```
+
+Body must include four sections: **Intent (one line) / Motivation / Coarse acceptance / Non-goals**. Notes that fail the four-pack stay notes; they are not “ready for review”.
+
+## Delivery (orthogonal to status)
+
+`status` is adjudication. `delivery` is remaining obligation. Do not collapse them.
+
+| delivery | Meaning | Attention board |
+| --- | --- | --- |
+| `open` | Accepted; work not started or remaining obligation exists | Yes |
+| `in-slice` | Linked tasks currently executing | Yes |
+| `landed` | Finite deliverable discharged | Closed, not a queue |
+| `standing` | Live rule / discipline; never a todo | Standing list, not a queue |
+| `deferred` | Accepted but explicitly not doing now | Closed, not a queue |
+
+- Required on `accepted`. `inbox` / `review` / `rejected` omit it.
+- `pool.py status` prints the groups. `plan.md` Mainline only cites `open` / `in-slice`.
+- `depends_on: ["pool:Pxx"]` uses `delivery`, not linked-task Close: standing / landed / deferred → SATISFIED; open / in-slice → NOT_SATISFIED; missing `.pactile/pool/` (no Capture) → ignored (does not block Close); missing item → UNRESOLVED.
+
+## Links and validation (pool CLI)
+
+Item ↔ task links use the CLI as the authoritative write path (both sides in one call):
+
+- Item side: frontmatter `linked_tasks` (task directory name) — **slice index for humans**, not completion
+- Task side: `task.json` → `meta.pool_items` (pool item id, e.g. `"P01"`)
+- Many-to-many; de-duplicated, order-preserving
+- Hand-editing one side is caught by `validate` (`link-missing-task-side` / `link-missing-item-side`)
+
+| Command | Role | Exit |
+| --- | --- | --- |
+| `python3 ./.pactile/scripts/pool.py validate` | Four-pack / required keys / status / delivery / unique id / dangling links / bidirectional consistency | error-level → 1 |
+| `python3 ./.pactile/scripts/pool.py plan-check` | plan.md referenced ids exist (ghost id → error) | same |
+| `python3 ./.pactile/scripts/pool.py link <item-id> <task-ref>` | Bidirectional link (idempotent) | missing → 1 |
+| `python3 ./.pactile/scripts/pool.py unlink <item-id> <task-ref>` | Bidirectional unlink | item missing → 1 |
+| `python3 ./.pactile/scripts/pool.py show <item-id>` | Print item + delivery + linked task status summary | missing → 1 |
+| `python3 ./.pactile/scripts/pool.py status` | Print delivery groups (queue / standing / closed) | 0 |
+
+- WARN-only issues exit 0 (same discoverability stance as depends_on Plan A).
+- `depends_on: ["pool:Pxx"]` satisfaction is `delivery` via `pool_refs` (not `pool_store`). See Delivery above.
+
+All commands accept `--root <path>` when the Pactile root is not the current working directory.
+
+## Process rules
+
+1. New idea / gap → write an `items/` entry with status `inbox`.
+2. Review: Agent proposes a decision; user adjudicates → `accepted` / `rejected` / `rework`.
+3. `accepted` → add to `plan.md` (plan cites item ids only; do not rewrite a second narrative). **Does not split into tasks and does not create task directories.**
+4. When the user says to **start implementing** an accepted item → write or update `## 切片` on that item (see below), then Open (`task.py create` + `pool.py link`). Not before Open.
+
+## Starting implementation (split)
+
+`accepted` freezes the requirement only. Do not treat it as a Task.
+
+When the user asks to start implementing an accepted item:
+
+1. Propose a slice list **on the item body** under the heading **`## 切片`**. Each row: short name, `touches`, Lite / Full / Parent, parallel vs `serial_reason`.
+2. After Open, create directories and `pool.py link`. Empty task dirs before Open are forbidden.
+3. One slice = one closable write-set + cohesive AC. Prefer several Fulls that can Close on their own. Use Parent only when one integration authority is required.
+4. Default: isolatable Fulls run in parallel. Colliding `touches` → resplit or write `serial_reason`. No numeric size cap; if it cannot Close / cannot be proven / `touches` span unrelated modules, resplit. Intake must propose that split if the user opens a giant task; the user may insist with range risk / `serial_reason`.
+5. Progress stays `delivery` + `linked_tasks` + `pool.py status`. Unsplit `open`; work running `in-slice`; remaining obligation done `landed`. One slice Close does **not** land the whole item. Remainder may be `deferred`.
+6. Default one pool item per task. Extra links need per-item duties in that task’s PRD (`## 池义务` / `## Pool obligations`). Closing the task only advances the declared duties.
+7. More slices may be added while the item is `open` / `in-slice`. Do not reopen a Closed task to stuff new scope. New slices still need Open.
+8. This split rule applies to **new Open after the rule landed**. Already-open tasks are not force-resplit.
+
+`pool.py validate` **does not fail** when `## 切片` is missing. The heading is an Open-proposal convention, not a new schema.
+
+In-session tiny work still skips the pool (clear request → Intake → Open Task).
+
+## Choosing the next item (attention, not a serial lock)
+
+Priority is **attention + start preference**, not a queue lock. Isolatable write-sets still run in parallel (see `.pactile/workflow.md` Parallel-first). Agent proposes; user chooses. Agent must not auto-start, and must not refuse an independent item because a higher band is unfinished.
+
+1. Run `python3 ./.pactile/scripts/pool.py status`. Rank **only** `open` and `in-slice`.
+2. Within the queue, group by attention band: `priority: P0` → `P1` → unlabeled/`P2`.
+3. `standing` / `landed` / `deferred` / inbox hold / `rejected` do not rank. `rework` drops until re-accepted.
+4. Show the band order **and** the parallel groups → **ask the user**.
+
+`inbox` hold items are not ranked. Do not invent a scheduler CLI. Serial exceptions are the same set as Parallel-first (`serial_reason`).
+
+When this repo is PACTILE itself: the workflow package and optional BYOK are **independent ships**. See `.pactile/framework/release-boundary.md`. BYOK readiness is not a workflow-package gate.
+
+## Fog hygiene
+
+- Once an item or mechanism lands, **move it out** of “Not yet specified” into closed/mainline and keep the task id. Do not leave shipped work in fog.
+- Fog holds only truly open, uncommitted directions; if fog is empty, delete the whole section.
+
+## Boundary with the Task Ladder
+
+- **In-session requests** (clear, directly actionable) → Lite / Full / Parent task creation — **not** the pool.
+- **Ideas / directions / gaps / unformed thoughts** → pool.
+- Pool = candidates; Task = commitment. Only `accepted` items should become tasks.
+
+## Language
+
+Items and plans are human-reviewed artifacts and follow `artifact_locale`. Frontmatter keys and status values stay English (infrastructure).
+
+## Maintenance
+
+- Record adjudication notes on the item (decision log) so rationale is not lost.
+- After terminology-related items land, consider adding consistency checks at archive / check time when the project cares about glossary drift.

package/dist/templates/pactile/pool/plan.md

@@ -0,0 +1,50 @@
+# Development plan (pool)
+
+> Plan cites **pool item ids** only. Do not paste full item bodies here.
+> Update this file when items are accepted, started, or closed.
+>
+> **Token rule:** `plan-check` treats bare letter-P plus digits as item ids.
+> In this file's prose, write attention bands as `priority-0` / `priority-1` /
+> `priority-2`. Put illustrative item ids only inside fenced code blocks.
+
+## Conventions
+
+- **Mainline**: only `delivery: open` or `in-slice` (accepted remaining obligation), grouped by attention band. Same band + isolatable write-set = a parallel group. Serial needs a written reason (shared write-set / HITL / unmet depends / user asked / cannot isolate).
+- **Standing**: `delivery: standing` live rules. Not a queue; do not rank them as next work.
+- **Closed**: `delivery: landed` or `deferred` (keep a one-line pointer to task dir or reason).
+- **Attention ≠ lock**: unlabeled accepted items count as `priority-2` and remain startable. A higher band still open does not block an independent lower-band item.
+- **Release tracks** (when this repo ships PACTILE): the workflow package and optional BYOK are independent ships. See `.pactile/framework/release-boundary.md`. Do not treat BYOK as a workflow-package gate.
+- **Not yet specified (fog)**: open directions without an accepted item yet — keep short; empty → delete section.
+
+## Mainline
+
+### Attention band 0 (this batch / release-blocking)
+
+_(empty — only `delivery: open` or `in-slice` with that band)_
+
+### Attention band 1 (wanted, not release-blocking)
+
+_(empty)_
+
+### Attention band 2 (unlabeled default; still startable)
+
+_(empty)_
+
+Example shape (ids belong in a fence so they are not scanned):
+
+```text
+- <item-id> — short title (link task when created)
+  parallel with: <other-id>
+```
+
+## Standing (live rules, not a queue)
+
+_(empty)_
+
+## Closed
+
+_(empty)_
+
+## Not yet specified (fog)
+
+_(empty — delete this section when unused)_

package/dist/templates/pactile/scripts/__init__.py

@@ -0,0 +1,5 @@
+"""
+Pactile Python Scripts
+
+This module provides Python implementations of Pactile workflow scripts.
+"""