@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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

@@ -1,51 +1,7 @@
-# Local Pactile Architecture Overview
-
-`pactile-meta` is for user projects that have already run `pactile init`. The user's machine usually has only the npm-installed `pactile` command plus the Pactile files generated inside the project; it may not have the Pactile CLI source code.
-
-Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
-
-- `.pactile/`: workflow, tasks, specs, memory, scripts, and runtime state.
-- Platform directory: `.cursor/` — skills, agents, hooks, commands, rules.
-- Shared skill layer: `.agents/skills/` (industry skill-sharing path; kept when present but not extended by new Pactile behavior).
-
-Do not default to guiding the user to fork the Pactile CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Pactile upstream source, publish an npm package, or contribute a PR.
-
-## Local System Model
-
-Pactile provides three layers inside a user project:
-
-1. **Workflow layer**: `.pactile/workflow.md` defines phases, routing, next actions, and prompt blocks.
-2. **Persistence layer**: `.pactile/tasks/`, `.pactile/spec/`, and `.pactile/workspace/` store tasks, specs, and session memory.
-3. **Platform integration layer**: hooks, settings, agents, skills, commands, prompts, and workflows in platform directories connect the Pactile workflow to different AI tools.
-
-All three layers live inside the user project, so an AI can read and modify them directly.
-
-## Core Paths
-
-| Path | Purpose |
-| --- | --- |
-| `.pactile/workflow.md` | Workflow phases, skill routing, and workflow-state prompt blocks. |
-| `.pactile/config.yaml` | Project configuration, task lifecycle hooks, monorepo package configuration, and journal configuration. |
-| `.pactile/spec/` | The user's project-specific coding conventions and thinking guides. |
-| `.pactile/tasks/` | Each task's PRD, technical notes, research files, and JSONL context. |
-| `.pactile/workspace/` | Per-developer journals and cross-session memory. |
-| `.pactile/scripts/` | Local Python runtime used by commands, hooks, and context injection. |
-| `.pactile/.runtime/` | Session-level runtime state, such as the selected task pointer. |
-| `.pactile/.template-hashes.json` | Template hashes for Pactile-managed files, used by update to determine whether local files were modified by the user. |
-
-## AI Customization Principles
-
-1. **Find the local source of truth first**: Do not edit from memory. Read `.pactile/workflow.md`, `.pactile/config.yaml`, the relevant platform directory, and related task files first.
-2. **Edit the user project, not the npm package cache**: Modify generated files inside the project, not `node_modules` or the global npm install directory.
-3. **Keep platform files aligned with `.pactile/`**: If workflow routing changes, also check whether platform skills or commands still describe the same flow.
-4. **Put project-specific rules in `.pactile/spec/` or a local skill**: Do not put team conventions into `pactile-meta`.
-5. **Preserve user changes**: If a file was already modified locally, work from the current content instead of overwriting it with a default template.
-
-## How To Use This Directory
-
-- To understand which files exist after init, read `generated-files.md`.
-- To change phases, routing, or next actions, read `workflow.md`.
-- To change the task model, JSONL context, or selected task behavior, read `task-system.md`.
-- To change coding convention injection, read `spec-system.md`.
-- To understand journals and cross-session memory, read `workspace-memory.md`.
-- To change hooks or sub-agent context loading, read `context-injection.md`.
+# Local architecture
+
+`.pactile/` holds canonical workflow, tasks, and runtime state. `AGENTS.md` and `.agents/skills/` are the current projected Codex entry surfaces. The ownership ledger records generated claims and protects user-owned content.
+
+Task artifacts contain requirements and evidence. Project rules belong in `.pactile/spec/`. A host integration is ready only after observed readiness and projection checks, not merely because a directory exists.
+
+The Codex cross-session bridge connects independent desktop tasks to Pactile Task lifecycle through Node request and receipt records. The App host invokes its native tools; this bridge is separate from project-file projection.

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

@@ -1,102 +1,102 @@
-# Local Spec System
-
-`.pactile/spec/` is the user's project-specific engineering spec library. Pactile is not about making AI memorize conventions; it injects relevant specs or requires the AI to read them at the right time.
-
-## Directory Model
-
-A common single-repository structure:
-
-```text
-.pactile/spec/
-├── backend/
-│   ├── index.md
-│   └── ...
-├── frontend/
-│   ├── index.md
-│   └── ...
-└── guides/
-    ├── index.md
-    └── ...
-```
-
-A common monorepo structure:
-
-```text
-.pactile/spec/
-├── cli/
-│   ├── backend/
-│   │   ├── index.md
-│   │   └── ...
-│   └── unit-test/
-│       ├── index.md
-│       └── ...
-├── docs-site/
-│   └── docs/
-│       ├── index.md
-│       └── ...
-└── guides/
-    ├── index.md
-    └── ...
-```
-
-`index.md` is the entry point for each layer. It should list the Pre-Development Checklist and Quality Check. Specific guidelines live in other Markdown files in the same directory.
-
-## Package Configuration
-
-`.pactile/config.yaml` can declare packages:
-
-```yaml
-packages:
-  cli:
-    path: packages/cli
-  docs-site:
-    path: docs-site
-    type: submodule
-default_package: cli
-```
-
-The AI can run:
-
-```bash
-python3 ./.pactile/scripts/get_context.py --mode packages
-```
-
-This command lists packages and spec layers for the current project. Use this output as the reference when configuring context JSONL.
-
-## How Specs Enter Tasks
-
-Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
-
-```jsonl
-{"file": ".pactile/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
-{"file": ".pactile/spec/cli/unit-test/conventions.md", "reason": "Test expectations"}
-```
-
-Sub-agents or platform preludes read these JSONL files and load the referenced specs. On platforms without sub-agent support, the AI should read the relevant specs directly according to the workflow.
-
-## What Specs Should Contain
-
-Specs should contain executable engineering conventions for the project, not generic best practices:
-
-- Where files should live.
-- How error handling should be expressed.
-- Input/output contracts for APIs, hooks, and commands.
-- Patterns that are forbidden.
-- Cases that require tests.
-- Project-specific pitfalls and how to avoid them.
-
-When the AI learns a new rule during implementation or debugging, it should update `.pactile/spec/` rather than only summarizing it in chat.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Add a new spec layer | `.pactile/spec/<package>/<layer>/index.md` and corresponding guideline files. |
-| Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.pactile/config.yaml`. |
-| Change which specs AI reads before implementation | The task's `implement.jsonl`. |
-| Change which specs AI reads during checking | The task's `check.jsonl`. |
-| Change when specs should be updated | Phase 3.3 in `.pactile/workflow.md` and the `pactile-update-spec` skill. |
-
-## Boundaries
-
-`.pactile/spec/` is the user's project specification, not a permanent copy of Pactile built-in templates. The AI should encourage the user to update it according to the actual project code instead of treating Pactile default templates as immutable documents.
+# Local Spec System
+
+`.pactile/spec/` is the user's project-specific engineering spec library. Pactile is not about making AI memorize conventions; it injects relevant specs or requires the AI to read them at the right time.
+
+## Directory Model
+
+A common single-repository structure:
+
+```text
+.pactile/spec/
+├── backend/
+│   ├── index.md
+│   └── ...
+├── frontend/
+│   ├── index.md
+│   └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+A common monorepo structure:
+
+```text
+.pactile/spec/
+├── cli/
+│   ├── backend/
+│   │   ├── index.md
+│   │   └── ...
+│   └── unit-test/
+│       ├── index.md
+│       └── ...
+├── docs-site/
+│   └── docs/
+│       ├── index.md
+│       └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+`index.md` is the entry point for each layer. It should list the Pre-Development Checklist and Quality Check. Specific guidelines live in other Markdown files in the same directory.
+
+## Package Configuration
+
+`.pactile/config.yaml` can declare packages:
+
+```yaml
+packages:
+  cli:
+    path: packages/cli
+  docs-site:
+    path: docs-site
+    type: submodule
+default_package: cli
+```
+
+The AI can run:
+
+```bash
+pactile context --mode packages
+```
+
+This command lists packages and spec layers for the current project. Use this output as the reference when configuring context JSONL.
+
+## How Specs Enter Tasks
+
+Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
+
+```jsonl
+{"file": ".pactile/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
+{"file": ".pactile/spec/cli/unit-test/conventions.md", "reason": "Test expectations"}
+```
+
+Sub-agents or platform preludes read these JSONL files and load the referenced specs. On platforms without sub-agent support, the AI should read the relevant specs directly according to the workflow.
+
+## What Specs Should Contain
+
+Specs should contain executable engineering conventions for the project, not generic best practices:
+
+- Where files should live.
+- How error handling should be expressed.
+- Input/output contracts for APIs, hooks, and commands.
+- Patterns that are forbidden.
+- Cases that require tests.
+- Project-specific pitfalls and how to avoid them.
+
+When the AI learns a new rule during implementation or debugging, it should update `.pactile/spec/` rather than only summarizing it in chat.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Add a new spec layer | `.pactile/spec/<package>/<layer>/index.md` and corresponding guideline files. |
+| Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.pactile/config.yaml`. |
+| Change which specs AI reads before implementation | The task's `implement.jsonl`. |
+| Change which specs AI reads during checking | The task's `check.jsonl`. |
+| Change when specs should be updated | Phase 3.3 in `.pactile/workflow.md` and the `pactile-update-spec` skill. |
+
+## Boundaries
+
+`.pactile/spec/` is the user's project specification, not a permanent copy of Pactile built-in templates. The AI should encourage the user to update it according to the actual project code instead of treating Pactile default templates as immutable documents.

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.