@blxzer/pactile 0.5.0 → 0.6.0-beta.4

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/task-system.md

@@ -1,133 +1,138 @@
-# Local Task System
-
-The Pactile task system is stored entirely under `.pactile/tasks/` in the user project. Each task is a directory containing requirements, context, research, state, and relationship information.
-
-## Task Directory Structure
-
-```text
-.pactile/tasks/
-├── 04-28-example-task/
-│   ├── task.json
-│   ├── prd.md
-│   ├── design.md
-│   ├── implement.md
-│   ├── implement.jsonl
-│   ├── check.jsonl
-│   └── research/
-└── archive/
-    └── 2026-04/
-```
-
-| File | Purpose |
-| --- | --- |
-| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
-| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
-| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
-| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
-| `implement.jsonl` | List of spec/research files the implement agent must read first. |
-| `check.jsonl` | List of spec/research files the check agent must read first. |
-| `research/` | Research artifacts. Complex findings should not live only in chat. |
-
-## `task.json`
-
-`task.json` records task status and metadata. Common fields:
-
-| Field | Meaning |
-| --- | --- |
-| `id` / `name` / `title` | Task identity and title. |
-| `status` | Status such as `planning`, `in_progress`, `review`, or `completed`. |
-| `priority` | `P0`, `P1`, `P2`, `P3`. |
-| `creator` / `assignee` | Creator and assignee. |
-| `package` | Target package in a monorepo; may be empty. |
-| `branch` / `base_branch` | Working branch and PR target branch. |
-| `children` / `parent` | Parent/child task relationships. |
-| `commit` / `pr_url` | Commit and PR information after completion. |
-| `meta` | Extension fields. |
-
-## Parent / Child Task Trees
-
-Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
-
-Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
-
-- Source requirements and user-facing scope.
-- The map of child tasks and their responsibility boundaries.
-- Cross-child acceptance criteria and final integration review.
-
-Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
-
-Create new children with:
-
-```bash
-python3 ./.pactile/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
-```
-
-Link or unlink existing tasks with:
-
-```bash
-python3 ./.pactile/scripts/task.py add-subtask <parent-dir> <child-dir>
-python3 ./.pactile/scripts/task.py remove-subtask <parent-dir> <child-dir>
-```
-
-`children` on the parent is a historical list. When a child is archived, Pactile keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
-
-The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
-
-## Selected Task
-
-The user sees a "selected task," and Pactile stores that selection per live session.
-
-```text
-.pactile/.runtime/sessions/<context-key>.json
-```
-
-`task.py select <task>` writes the task path into the runtime session file for the current session. `task.py selected --source` shows the selected task and where it came from. Different AI windows can point to different tasks without overwriting each other.
-
-If the platform or shell environment has no stable session identity, `task.py select` may be unable to set the selected task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
-
-## JSONL Context
-
-`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
-
-Format:
-
-```jsonl
-{"file": ".pactile/spec/cli/backend/index.md", "reason": "Backend conventions"}
-{"file": ".pactile/tasks/04-28-example/research/api.md", "reason": "API research"}
-```
-
-Rules:
-
-- Include spec and research files.
-- Do not include code files that are about to be modified.
-- Do not treat temporary conclusions in chat as the only context.
-- Seed rows have no `file` field; they only prompt the AI to fill in real entries.
-
-## Common Commands
-
-```bash
-python3 ./.pactile/scripts/task.py create "<title>" --slug <slug>
-python3 ./.pactile/scripts/task.py dashboard
-python3 ./.pactile/scripts/task.py select <task>
-python3 ./.pactile/scripts/task.py selected --source
-python3 ./.pactile/scripts/task.py start-execution <task> --check
-python3 ./.pactile/scripts/task.py start-execution <task> --approved
-python3 ./.pactile/scripts/task.py add-context <task> implement <file> <reason>
-python3 ./.pactile/scripts/task.py validate <task>
-python3 ./.pactile/scripts/task.py exit
-python3 ./.pactile/scripts/task.py archive <task>
-```
-
-When modifying the task system, the AI should prefer script commands to maintain structure. Edit JSON/Markdown directly only when scripts do not cover the need.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Change the default task template | `.pactile/scripts/common/task_store.py` and task creation instructions. |
-| Change status semantics | `.pactile/workflow.md`, workflow-state hook logic, and task usage conventions. |
-| Add task lifecycle actions | `hooks.after_*` in `.pactile/config.yaml`. |
-| Change context rules | Planning artifact guidance in `.pactile/workflow.md` and related platform agent/hook instructions. |
-| Change archive policy | `.pactile/scripts/common/task_store.py` / `task_utils.py`. |
-
-These are local files in the user project. Do not default to editing Pactile CLI source code unless the user wants to contribute upstream.
+# Local Task System
+
+The Pactile task system is stored entirely under `.pactile/tasks/` in the user project. Each task is a directory containing requirements, context, research, state, and relationship information.
+
+## Task Directory Structure
+
+```text
+.pactile/tasks/
+├── 04-28-example-task/
+│   ├── task.json
+│   ├── prd.md
+│   ├── design.md
+│   ├── implement.md
+│   ├── implement.jsonl
+│   ├── check.jsonl
+│   └── research/
+└── archive/
+    └── 2026-04/
+```
+
+| File | Purpose |
+| --- | --- |
+| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
+| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
+| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
+| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
+| `implement.jsonl` | List of spec/research files the implement agent must read first. |
+| `check.jsonl` | List of spec/research files the check agent must read first. |
+| `research/` | Research artifacts. Complex findings should not live only in chat. |
+
+## `task.json`
+
+`task.json` records task status and metadata. Common fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` / `name` / `title` | Task identity and title. |
+| `status` | Status such as `planning`, `in_progress`, `review`, or `completed`. |
+| `priority` | `P0`, `P1`, `P2`, `P3`. |
+| `creator` / `assignee` | Creator and assignee. |
+| `package` | Target package in a monorepo; may be empty. |
+| `branch` / `base_branch` | Working branch and PR target branch. |
+| `children` / `parent` | Parent/child task relationships. |
+| `commit` / `pr_url` | Commit and PR information after completion. |
+| `meta` | Extension fields. |
+
+## Parent / Child Task Trees
+
+Parent/child task relationships describe work structure. A parent groups related deliverables under one requirement set and does not replace each child's planning artifacts. Ordering is declared separately with Kernel `requires` dependencies.
+
+Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
+
+- Source requirements and user-facing scope.
+- The map of child tasks and their responsibility boundaries.
+- Cross-child acceptance criteria and final integration review.
+
+Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, declare it with `pactile task set-deps <child> <dependency>` and explain it in the child plan. Tree position does not imply ordering. `depends_on` becomes a Kernel hard `requires` edge and blocks execution by default until satisfied. `--ignore-deps` on `start-execution --approved` records an explicit user-approved override; it does not mark the dependency satisfied.
+
+Create new children with:
+
+```bash
+pactile task create "<child title>" --slug <child-slug> --parent <parent-dir>
+```
+
+Link or unlink existing tasks with:
+
+```bash
+pactile task add-subtask <parent-dir> <child-dir>
+pactile task remove-subtask <parent-dir> <child-dir>
+```
+
+`children` on the parent is a historical list. When a child is archived, Pactile keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+
+The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
+
+## Selected Task
+
+The user sees a "selected task," and Pactile stores that selection per live session.
+
+```text
+.pactile/.runtime/sessions/<context-key>.json
+```
+
+`pactile task select <task>` writes the task path into the runtime session file for the current session. `pactile task selected --source` shows the selected task and where it came from. Different AI windows can point to different tasks without overwriting each other.
+
+If the platform or shell environment has no stable session identity, `pactile task select` may be unable to set the selected task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
+
+## JSONL Context
+
+`implement.jsonl` and `check.jsonl` are context manifests for the executing and checking agent to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
+
+Format:
+
+```jsonl
+{"file": ".pactile/spec/cli/backend/index.md", "reason": "Backend conventions"}
+{"file": ".pactile/tasks/04-28-example/research/api.md", "reason": "API research"}
+```
+
+Rules:
+
+- Include spec and research files.
+- Do not include code files that are about to be modified.
+- Do not treat temporary conclusions in chat as the only context.
+- Default seed rows point to existing guides; curate them for the task.
+
+## Common Commands
+
+```bash
+pactile task create "<title>" --slug <slug>
+pactile task dashboard
+pactile task select <task>
+pactile task selected --source
+pactile task start-execution <task> --check
+pactile task start-execution <task> --approved
+pactile task set-deps <task> <required-task-id>
+pactile task create "<full title>" --slug <slug> --rigor full
+pactile task record-ac-evidence <task> --map AC-1=verify.md#evidence --code-ref <tested-code-ref>
+pactile task record-independent-check <task> --mode self-review --result PASS --evidence verify.md#check --code-ref <tested-code-ref>
+pactile task record-gate <task> --transition full-task-complete --gate code-review --result PASS --reviewer <id> --evidence verify.md#review
+pactile task add-context <task> implement <file> <reason>
+pactile task validate <task>
+pactile task exit
+pactile task archive <task>
+```
+
+When modifying the task system, use Pactile CLI commands to maintain structure. Edit JSON/Markdown directly only when the CLI does not cover the need.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change the default task template | `.pactile/tasks/locale/` templates and Pactile CLI Node implementation. |
+| Change status semantics | `.pactile/workflow.md`, workflow-state hook logic, and task usage conventions. |
+| Add task lifecycle actions | `hooks.after_*` in `.pactile/config.yaml`. |
+| Change context rules | Planning artifact guidance in `.pactile/workflow.md` and related platform agent/hook instructions. |
+| Change archive policy | Pactile CLI Node implementation. |
+
+These are local files in the user project. Do not default to editing Pactile CLI source code unless the user wants to contribute upstream.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workflow.md

@@ -1,75 +1,75 @@
-# Local Workflow System
-
-`.pactile/workflow.md` is the Pactile workflow source of truth inside the user project. An AI does not need Pactile source code to understand how the current project should move tasks forward; this file is enough.
-
-## File Responsibilities
-
-`.pactile/workflow.md` has three responsibilities:
-
-1. **Explain workflow phases**: Plan, Execute, Finish.
-2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
-3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
-
-## Current Phase Model
-
-```text
-Phase 1: Plan    -> clarify what to build, produce prd.md and required research
-Phase 2: Execute -> implement against the PRD and specs, then check
-Phase 3: Finish  -> final verification, preserve lessons, and wrap up
-```
-
-Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
-
-## Skill Routing
-
-`workflow.md` separates routing by platform capability:
-
-- Platforms with sub-agent support: dispatch `pactile-implement` by default for implementation and `pactile-check` for checking.
-- Platforms without sub-agent support: the main session reads skills such as `pactile-before-dev`, then executes directly.
-
-When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
-
-## Workflow-State Prompt Blocks
-
-The bottom of `workflow.md` can contain state blocks like this:
-
-```text
-[workflow-state:no_task]
-...
-[/workflow-state:no_task]
-```
-
-Hooks choose the right block based on selected task status and inject it into the conversation. Common states include:
-
-| State | Meaning |
-| --- | --- |
-| `no_task` | The current session has no selected task. |
-| `planning` | The task is still in requirements, research, or context configuration. |
-| `in_progress` | The task has entered implementation and checking. |
-| `completed` | The task is complete and waiting for wrap-up or archive. |
-
-If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
-
-## Local Modification Patterns
-
-Common changes:
-
-| Goal | Edit point |
-| --- | --- |
-| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
-| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
-| Change the default implementation/check path | Update Phase 2 and skill routing. |
-| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
-| Change platform differences | Update routing descriptions grouped by platform. |
-
-After editing, make the AI reread `.pactile/workflow.md`; do not assume the flow from the old conversation is still valid.
-
-## Relationship To Platform Files
-
-`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
-
-- skills, such as `pactile-brainstorm` and `pactile-check`.
-- commands/prompts/workflows, such as continue and finish-work.
-- hooks, such as session-start or workflow-state injection.
-
-If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.
+# Local Workflow System
+
+`.pactile/workflow.md` is the Pactile workflow source of truth inside the user project. An AI does not need Pactile source code to understand how the current project should move tasks forward; this file is enough.
+
+## File Responsibilities
+
+`.pactile/workflow.md` has three responsibilities:
+
+1. **Explain workflow phases**: Plan, Execute, Finish.
+2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
+3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
+
+## Current Phase Model
+
+```text
+Phase 1: Plan    -> clarify what to build, produce prd.md and required research
+Phase 2: Execute -> implement against the PRD and specs, then check
+Phase 3: Finish  -> final verification, preserve lessons, and wrap up
+```
+
+Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
+
+## Skill Routing
+
+`workflow.md` separates routing by platform capability:
+
+- Platforms with sub-agent support: dispatch `pactile-implement` by default for implementation and `pactile-check` for checking.
+- Platforms without sub-agent support: the main session reads skills such as `pactile-before-dev`, then executes directly.
+
+When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
+
+## Workflow-State Prompt Blocks
+
+The bottom of `workflow.md` can contain state blocks like this:
+
+```text
+[workflow-state:no_task]
+...
+[/workflow-state:no_task]
+```
+
+Hooks choose the right block based on selected task status and inject it into the conversation. Common states include:
+
+| State | Meaning |
+| --- | --- |
+| `no_task` | The current session has no selected task. |
+| `planning` | The task is still in requirements, research, or context configuration. |
+| `in_progress` | The task has entered implementation and checking. |
+| `completed` | The task is complete and waiting for wrap-up or archive. |
+
+If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
+
+## Local Modification Patterns
+
+Common changes:
+
+| Goal | Edit point |
+| --- | --- |
+| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
+| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
+| Change the default implementation/check path | Update Phase 2 and skill routing. |
+| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
+| Change platform differences | Update routing descriptions grouped by platform. |
+
+After editing, make the AI reread `.pactile/workflow.md`; do not assume the flow from the old conversation is still valid.
+
+## Relationship To Platform Files
+
+`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
+
+- skills, such as `pactile-brainstorm` and `pactile-check`.
+- commands/prompts/workflows, such as continue and finish-work.
+- hooks, such as session-start or workflow-state injection.
+
+If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workspace-memory.md

@@ -1,71 +1,71 @@
-# Local Workspace Memory System
-
-`.pactile/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
-
-## Directory Structure
-
-```text
-.pactile/workspace/
-├── index.md
-└── <developer>/
-    ├── index.md
-    ├── journal-1.md
-    └── journal-2.md
-```
-
-| File | Purpose |
-| --- | --- |
-| `.pactile/.developer` | Current developer identity. |
-| `.pactile/workspace/index.md` | Global workspace overview. |
-| `.pactile/workspace/<developer>/index.md` | Session index for a developer. |
-| `.pactile/workspace/<developer>/journal-N.md` | Session journal. |
-
-## Developer Identity
-
-Run this the first time:
-
-```bash
-python3 ./.pactile/scripts/init_developer.py <name>
-```
-
-This creates `.pactile/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
-
-## Journal
-
-`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
-
-Common command for recording a session:
-
-```bash
-python3 ./.pactile/scripts/add_session.py \
-  --title "Session title" \
-  --summary "What changed" \
-  --commit "abc1234"
-```
-
-Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
-
-## Relationship Between Workspace Memory And Tasks
-
-| System | What it stores |
-| --- | --- |
-| `.pactile/tasks/` | Requirements, design, research, and state for a specific task. |
-| `.pactile/workspace/` | Work records across tasks and sessions. |
-| `.pactile/spec/` | Engineering knowledge preserved as long-term conventions. |
-
-If information is only useful for the selected task, put it in the task directory.
-If information describes what happened in the current session, put it in the workspace journal.
-If information should be followed every time code is written in the future, put it in spec.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Change maximum journal lines | `max_journal_lines` in `.pactile/config.yaml`. |
-| Change session auto-commit message | `session_commit_message` in `.pactile/config.yaml`. |
-| Change session content format | `.pactile/scripts/add_session.py`. |
-| Change how workspace is displayed in context | `.pactile/scripts/common/session_context.py`. |
-
-## AI Usage Rules
-
-The AI should not treat workspace as the only source of truth. When resuming a task, read the selected task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.
+# Local Workspace Memory System
+
+`.pactile/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
+
+## Directory Structure
+
+```text
+.pactile/workspace/
+├── index.md
+└── <developer>/
+    ├── index.md
+    ├── journal-1.md
+    └── journal-2.md
+```
+
+| File | Purpose |
+| --- | --- |
+| `.pactile/.developer` | Current developer identity. |
+| `.pactile/workspace/index.md` | Global workspace overview. |
+| `.pactile/workspace/<developer>/index.md` | Session index for a developer. |
+| `.pactile/workspace/<developer>/journal-N.md` | Session journal. |
+
+## Developer Identity
+
+Run this the first time:
+
+```bash
+pactile init --user <name>
+```
+
+This creates `.pactile/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
+
+## Journal
+
+`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
+
+Common command for recording a session:
+
+```bash
+pactile session add \
+  --title "Session title" \
+  --summary "What changed" \
+  --commit "abc1234"
+```
+
+Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
+
+## Relationship Between Workspace Memory And Tasks
+
+| System | What it stores |
+| --- | --- |
+| `.pactile/tasks/` | Requirements, design, research, and state for a specific task. |
+| `.pactile/workspace/` | Work records across tasks and sessions. |
+| `.pactile/spec/` | Engineering knowledge preserved as long-term conventions. |
+
+If information is only useful for the selected task, put it in the task directory.
+If information describes what happened in the current session, put it in the workspace journal.
+If information should be followed every time code is written in the future, put it in spec.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change maximum journal lines | `max_journal_lines` in `.pactile/config.yaml`. |
+| Change session auto-commit message | `session_commit_message` in `.pactile/config.yaml`. |
+| Change session content format | Pactile CLI `pactile session add` implementation. |
+| Change how workspace is displayed in context | Pactile CLI `pactile context` implementation. |
+
+## AI Usage Rules
+
+The AI should not treat workspace as the only source of truth. When resuming a task, read the selected task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.