@blxzer/pactile 0.5.0 → 0.6.0-beta.4

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

@@ -1,68 +1,68 @@
-# Local Context Injection System
-
-Pactile context injection aims to make AI read the right files at the right time instead of relying on model memory. In a user project, injection is implemented by `.pactile/` scripts together with platform hooks, agents, and skills.
-
-## Injected Context Types
-
-| Type | Source | Purpose |
-| --- | --- | --- |
-| session context | `.pactile/scripts/get_context.py` | Current developer, git status, selected task, Task Dashboard, active tasks, journal, packages. |
-| workflow context | `.pactile/workflow.md` | Current Pactile flow and next action. |
-| spec context | `.pactile/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
-| task context | `.pactile/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Selected task requirements, design, execution plan, and research. |
-| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
-
-## session-start
-
-Platforms with session-start support inject a Pactile overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
-
-- workflow summary.
-- selected task status.
-- active tasks.
-- spec index paths.
-- developer identity and git status.
-
-If the user feels the AI does not know the selected task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
-
-## workflow-state
-
-workflow-state is a lightweight hint injected around each user turn. Based on selected task status, it selects a block from `.pactile/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
-
-If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.pactile/workflow.md` first.
-
-## sub-agent context
-
-Implement and check agents need task context. Pactile has two loading modes:
-
-1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
-2. **agent pull**: the agent definition instructs the agent to read the selected task, jsonl context, and task artifacts after startup.
-
-In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
-
-## JSONL Reading Rules
-
-`implement.jsonl` and `check.jsonl` contain one JSON object per line:
-
-```jsonl
-{"file": ".pactile/spec/backend/index.md", "reason": "Backend rules"}
-```
-
-Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
-
-## Selected Task And Context Key
-
-Selected task state lives in `.pactile/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `PACTILE_CONTEXT_ID`.
-
-If shell commands cannot see the same context key, `task.py selected --source` may report no selected task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Change session-start injected content | The platform's `session-start` hook or plugin file. |
-| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
-| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
-| Change JSONL validation/display | `.pactile/scripts/common/task_context.py`. |
-| Change selected task resolution | `.pactile/scripts/common/active_task.py`. |
-
-When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.
+# Local Context Injection System
+
+Pactile context injection aims to make AI read the right files at the right time instead of relying on model memory. The Node CLI compiles context from `.pactile/` artifacts for the host and worker bridge.
+
+## Injected Context Types
+
+| Type | Source | Purpose |
+| --- | --- | --- |
+| session context | `pactile context` | Current developer, git status, selected task, Task Dashboard, active tasks, journal, packages. |
+| workflow context | `.pactile/workflow.md` | Current Pactile flow and next action. |
+| spec context | `.pactile/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
+| task context | `.pactile/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Selected task requirements, design, execution plan, and research. |
+| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
+
+## session-start
+
+Platforms with session-start support inject a Pactile overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
+
+- workflow summary.
+- selected task status.
+- active tasks.
+- spec index paths.
+- developer identity and git status.
+
+If the user feels the AI does not know the selected task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
+
+## workflow-state
+
+workflow-state is a lightweight hint injected around each user turn. Based on selected task status, it selects a block from `.pactile/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
+
+If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.pactile/workflow.md` first.
+
+## sub-agent context
+
+Implement and check agents need task context. Pactile has two loading modes:
+
+1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
+2. **agent pull**: the agent definition instructs the agent to read the selected task, jsonl context, and task artifacts after startup.
+
+In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
+
+## JSONL Reading Rules
+
+`implement.jsonl` and `check.jsonl` contain one JSON object per line:
+
+```jsonl
+{"file": ".pactile/spec/backend/index.md", "reason": "Backend rules"}
+```
+
+Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
+
+## Selected Task And Context Key
+
+Selected task state lives in `.pactile/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `PACTILE_CONTEXT_ID`.
+
+If shell commands cannot see the same context key, `pactile task selected --source` may report no selected task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change session-start injected content | The platform's `session-start` hook or plugin file. |
+| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
+| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
+| Change JSONL validation/display | Pactile CLI Node implementation. |
+| Change selected task resolution | Pactile CLI Node implementation and platform session bridge. |
+
+When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.

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

@@ -1,83 +1,7 @@
-# Local Files Generated After Init
-
-`pactile init` writes the Pactile runtime into the user project. Later, `pactile update` tries to update Pactile-managed template files, but it uses `.pactile/.template-hashes.json` to determine which files have already been modified by the user.
-
-This page only describes files that are visible and editable inside the user project.
-
-## `.pactile/`
-
-```text
-.pactile/
-├── workflow.md
-├── config.yaml
-├── .developer
-├── .version
-├── .template-hashes.json
-├── .runtime/
-├── scripts/
-├── spec/
-├── tasks/
-└── workspace/
-```
-
-| Path | Usually editable? | Notes |
-| --- | --- | --- |
-| `.pactile/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
-| `.pactile/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
-| `.pactile/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
-| `.pactile/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. |
-| `.pactile/workspace/` | Yes | Session records, usually written by `add_session.py`. |
-| `.pactile/scripts/` | Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
-| `.pactile/.runtime/` | No | Runtime state, usually written automatically by hooks/scripts. |
-| `.pactile/.developer` | Carefully | Current developer identity. |
-| `.pactile/.version` | No | Pactile version record used by update/migration logic. |
-| `.pactile/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
-
-## Platform Directories
-
-On a fresh `pactile init --cursor`, the only platform directory created is `.cursor/`. Pactile previously generated per-platform directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.); those legacy directories are preserved by `pactile update` but new Pactile behavior ships to `.cursor/` only.
-
-Common categories inside `.cursor/`:
-
-| Category | Path | Purpose |
-| --- | --- | --- |
-| hooks | `.cursor/hooks/` | Hook scripts invoked from `.cursor/hooks.json`. Inject session context, workflow-state, and sub-agent context. |
-| settings/registration | `.cursor/hooks.json` | Registers which scripts run on which Cursor events. |
-| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt. |
-| agents | `.cursor/agents/` | Define agents such as `pactile-research`, `pactile-implement`, and `pactile-check`. |
-| skills | `.cursor/skills/` | Skills that auto-trigger or can be read by AI. |
-| commands | `.cursor/commands/` | Legacy compatibility-only user-invoked entry points. |
-
-When modifying a platform directory, also confirm whether `.pactile/workflow.md` still describes the same flow.
-
-## Meaning Of Template Hashes
-
-`.pactile/.template-hashes.json` records the content hash from the last time Pactile wrote a template file. `pactile update` uses it to distinguish three cases:
-
-| Case | Update behavior |
-| --- | --- |
-| File was not modified by the user | It can be updated automatically. |
-| File was modified by the user | Prompt the user to overwrite, keep, or generate `.new`. |
-| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
-
-When an AI customizes local Pactile files, it does not need to maintain hashes manually. It is normal for Pactile update to recognize the result as "modified by the user."
-
-## Local Customization Boundaries
-
-Editable by default:
-
-- `.pactile/workflow.md`
-- `.pactile/config.yaml`
-- `.pactile/spec/**`
-- `.pactile/scripts/**`
-- Platform hooks, settings, agents, skills, commands, prompts, and workflows
-
-Do not edit by default:
-
-- Global npm install directory
-- `node_modules/@blxzer/pactile`
-- Pactile GitHub repository source code
-- Concrete state files under `.pactile/.runtime/**`
-- Hash contents inside `.pactile/.template-hashes.json`
-
-Switch to the Pactile CLI source-code perspective only when the user explicitly wants to contribute upstream.
+# Generated files
+
+A new `pactile init --codex` prepares canonical framework files under `.pactile/`, a managed block in `AGENTS.md`, and shared Skills under `.agents/skills/`. Optional native Codex bindings depend on readiness.
+
+`.pactile/spec/`, tasks, workspace notes, and personal host settings are user-owned. `pactile update` reviews modified framework files before replacing them and does not treat a directory's existence as ownership.
+
+Files from older host integrations may remain in upgraded projects. The active adapter does not refresh them; review the ownership ledger before cleanup.

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.