@blxzer/pactile 0.5.0 → 0.6.0-beta.4

package/dist/templates/common/bundled-skills/pactile-check/SKILL.md

@@ -1,161 +1,161 @@
----
-name: pactile-check
-description: "Comprehensive quality verification on two axes — Standards (spec compliance, lint, type-check, tests, code smells, cross-layer data flow) and Spec (prd fidelity, scope, learning/spec-sync). Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
----
-
-# Code Quality Check
-
-Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
-
----
-
-## Step 1: Identify What Changed
-
-```bash
-git diff --name-only HEAD
-git status
-```
-
-## Step 2: Read Task Artifacts and Applicable Specs
-
-Read the selected task artifacts in order:
-
-- `prd.md`
-- `design.md` if present
-- `implement.md` if present
-
-```bash
-python ./.pactile/scripts/get_context.py --mode packages
-```
-
-For each changed package/layer, read the spec index and follow its **Quality Check** section:
-
-```bash
-cat .pactile/spec/<package>/<layer>/index.md
-```
-
-Read the specific guideline files referenced — the index is a pointer, not the goal.
-
-## Step 3: Run Project Checks
-
-Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
-
-## Step 4: Review Against Checklist (dual-axis)
-
-Report **Standards and Spec in two separate sections** — never merge them into a single severity ranking. Standards findings first, then Spec findings; the same issue may be cross-referenced on both sides, but one axis must not mask the other. Do NOT output a "combined top risks" list mixing spec violations with requirement deviations.
-
-### Dual-axis dispatch (Full+ only)
-
-- **Lite / no task context**: single pass — the main agent runs Standards then Spec sequentially (no parallel split).
-- **Full+ and sub-agents available**: may dispatch two read-only review sub-agents in parallel (a Standards-agent and a Spec-agent). They **only report findings, never modify code**; the main agent consolidates and fixes per Step 6.
-- **Sub-agents unavailable**: degrade to single pass — do not block the check.
-
-### Standards (did we write it right)
-
-#### Code Quality
-
-- [ ] Linter passes?
-- [ ] Type checker passes (if applicable)?
-- [ ] Tests pass?
-- [ ] No debug logging left in?
-- [ ] No suppressed warnings or type-safety bypasses?
-
-#### Test Coverage (verification strength — not TDD)
-
-Follow `.pactile/framework/verification-strength-guide.md` for **graded** validation depth by closeout profile. pactile does **not** mandate red-green TDD or per-function unit tests.
-
-- [ ] **Lite:** focused validation on touched behavior recorded in `verify.md` (`Validation:` line + result)
-- [ ] **Full:** above + `Check evidence:` + `Reviewed change-set:` when contract requires code-review gate
-- [ ] New function / bug fix → add or update tests **when the project's norms and task scope require it** — not as automatic TDD ceremony
-- [ ] `python ./.pactile/scripts/task.py validate <task>` passing JSONL schema **≠** task acceptance; substantive `verify.md` signals still required
-
-#### Fowler 12 Smells
-
-Scan the change surface against `references/fowler-12-smells.md` (12 named smells, one-line criterion + don't-report boundary each). Report when hit, `N/A` when not — do not pad the report with misses.
-
-#### False-positive calibration (AI cross-review)
-
-Before prioritizing any CRITICAL/WARNING finding, read `.pactile/spec/guides/index.md` → **"When Verifying AI Cross-Review Results"**: verify each finding against the actual code; budget ~35% false-positive rate for AI reviews; typical patterns: trust boundary confusion, ignoring design comments, variable misreading.
-
-### Spec (did we build the right thing)
-
-#### prd / design / implement fidelity
-
-- [ ] Against `prd.md` Goal / Requirements / Acceptance Criteria: is the implementation faithful, and does it stay **within scope** (no over-scope)?
-- [ ] Are `design.md` / `implement.md` boundaries violated (if present)?
-
-#### Durable Learning (Phase 3.3)
-
-- [ ] `verify.md` contains exactly one token: `Learning decision: update-spec` | `no-update` | `unsure`
-- [ ] If `update-spec` or `unsure`: `research/learning-proposal.md` exists (or documented `N/A` with reason) and matches the decision
-- [ ] If `no-update`: includes `no durable learning` (or guide-equivalent) plus brief rationale
-- [ ] If `update-spec`: spec was written only after confirmation; `Spec update evidence:` points at `.pactile/spec/...`
-- [ ] No silent edits to `.pactile/spec/` without confirmation
-
-#### Spec Sync
-
-- [ ] Does `.pactile/spec/` need updates? (route through semi-automatic flow: proposal → confirm → `pactile-update-spec`)
-
-> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
-
-#### Retrieval evidence (when task used research / smart-search / optional pack)
-
-- [ ] **`verify.md` lists unresolved retrieval gaps** — external facts still unverified, missing `research/` or `research/smart-search/` evidence, or claims without source/Git/test corroboration
-- [ ] If `{TASK}/research/retrieval-pack-latest.json` exists, top `contextPack.selected` items are cited or gaps are explicitly noted in `verify.md`
-
-**Evidence pack (graceful):** Path `{TASK}/research/retrieval-pack-latest.json`. If absent, skip — no error.
-
-When present, Read the pack and ensure `verify.md` has `## Evidence pack reference` citing `contextPack.selected` (`title`, `source`, `reference`, `score`) or explicit gaps. Empty `selected` with existing `research/` → note stale pack or scoring failure in `verify.md`.
-
-#### Terminology / ADR consistency (one line)
-
-- [ ] Read root `CONTEXT.md`: do terms in the change mix `_Avoid_` aliases? If an irreversible decision was introduced, should there be an ADR? (Prompt only — do not force creating a file.)
-
-### Report format
-
-```markdown
-## Standards findings
-- [sev] ...
-
-## Spec findings
-- [sev] ...
-
-## Summary
-- Standards: N issues (not ranked against Spec)
-- Spec: M issues
-```
-
-## Step 5: Cross-Layer Dimensions (if applicable)
-
-Skip this step if your change is confined to a single layer.
-
-### A. Data Flow (changes touch 3+ layers)
-
-- [ ] Read flow traces correctly: Storage → Service → API → UI
-- [ ] Write flow traces correctly: UI → API → Service → Storage
-- [ ] Types/schemas correctly passed between layers?
-- [ ] Errors properly propagated to caller?
-
-### B. Code Reuse (modifying constants, creating utilities)
-
-- [ ] Searched for existing similar code before creating new?
-  ```bash
-  grep -r "pattern" src/
-  ```
-- [ ] If 2+ places define same value → extracted to shared constant?
-- [ ] After batch modification, all occurrences updated?
-
-### C. Import/Dependency (creating new files)
-
-- [ ] Correct import paths (relative vs absolute)?
-- [ ] No circular dependencies?
-
-### D. Same-Layer Consistency
-
-- [ ] Other places using the same concept are consistent?
-
----
-
-## Step 6: Report and Fix
-
-Report violations found (Standards and Spec sections per Step 4 format) and fix them directly. Parallel review sub-agents **do not fix** — the main agent owns all fixes. Re-run project checks after fixes.
+---
+name: pactile-check
+description: "Comprehensive quality verification on two axes — Standards (spec compliance, lint, type-check, tests, code smells, cross-layer data flow) and Spec (prd fidelity, scope, learning/spec-sync). Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
+---
+
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Task Artifacts and Applicable Specs
+
+Read the selected task artifacts in order:
+
+- `prd.md`
+- `design.md` if present
+- `implement.md` if present
+
+```bash
+pactile context --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .pactile/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist (dual-axis)
+
+Report **Standards and Spec in two separate sections** — never merge them into a single severity ranking. Standards findings first, then Spec findings; the same issue may be cross-referenced on both sides, but one axis must not mask the other. Do NOT output a "combined top risks" list mixing spec violations with requirement deviations.
+
+### Dual-axis dispatch (Full+ only)
+
+- **Lite / no task context**: single pass — the main agent runs Standards then Spec sequentially (no parallel split).
+- **Full+ and sub-agents available**: may dispatch two read-only review sub-agents in parallel (a Standards-agent and a Spec-agent). They **only report findings, never modify code**; the main agent consolidates and fixes per Step 6.
+- **Sub-agents unavailable**: degrade to single pass — do not block the check.
+
+### Standards (did we write it right)
+
+#### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+#### Test Coverage (verification strength — not TDD)
+
+Follow `.pactile/framework/verification-strength-guide.md` for **graded** validation depth by closeout profile. pactile does **not** mandate red-green TDD or per-function unit tests.
+
+- [ ] **Lite:** focused validation on touched behavior recorded in `verify.md` (`Validation:` line + result)
+- [ ] **Full:** above + `Check evidence:` + `Reviewed change-set:` when contract requires code-review gate
+- [ ] New function / bug fix → add or update tests **when the project's norms and task scope require it** — not as automatic TDD ceremony
+- [ ] `pactile task validate <task>` passing JSONL schema **≠** task acceptance; substantive `verify.md` signals still required
+
+#### Fowler 12 Smells
+
+Scan the change surface against `references/fowler-12-smells.md` (12 named smells, one-line criterion + don't-report boundary each). Report when hit, `N/A` when not — do not pad the report with misses.
+
+#### False-positive calibration (AI cross-review)
+
+Before prioritizing any CRITICAL/WARNING finding, read `.pactile/spec/guides/index.md` → **"When Verifying AI Cross-Review Results"**: verify each finding against the actual code; budget ~35% false-positive rate for AI reviews; typical patterns: trust boundary confusion, ignoring design comments, variable misreading.
+
+### Spec (did we build the right thing)
+
+#### prd / design / implement fidelity
+
+- [ ] Against `prd.md` Goal / Requirements / Acceptance Criteria: is the implementation faithful, and does it stay **within scope** (no over-scope)?
+- [ ] Are `design.md` / `implement.md` boundaries violated (if present)?
+
+#### Durable Learning (Phase 3.3)
+
+- [ ] `verify.md` contains exactly one token: `Learning decision: update-spec` | `no-update` | `unsure`
+- [ ] If `update-spec` or `unsure`: `research/learning-proposal.md` exists (or documented `N/A` with reason) and matches the decision
+- [ ] If `no-update`: includes `no durable learning` (or guide-equivalent) plus brief rationale
+- [ ] If `update-spec`: spec was written only after confirmation; `Spec update evidence:` points at `.pactile/spec/...`
+- [ ] No silent edits to `.pactile/spec/` without confirmation
+
+#### Spec Sync
+
+- [ ] Does `.pactile/spec/` need updates? (route through semi-automatic flow: proposal → confirm → `pactile-update-spec`)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+#### Retrieval evidence (when task used research / smart-search / optional pack)
+
+- [ ] **`verify.md` lists unresolved retrieval gaps** — external facts still unverified, missing `research/` or `research/smart-search/` evidence, or claims without source/Git/test corroboration
+- [ ] If `{TASK}/research/retrieval-pack-latest.json` exists, top `contextPack.selected` items are cited or gaps are explicitly noted in `verify.md`
+
+**Evidence pack (graceful):** Path `{TASK}/research/retrieval-pack-latest.json`. If absent, skip — no error.
+
+When present, Read the pack and ensure `verify.md` has `## Evidence pack reference` citing `contextPack.selected` (`title`, `source`, `reference`, `score`) or explicit gaps. Empty `selected` with existing `research/` → note stale pack or scoring failure in `verify.md`.
+
+#### Terminology / ADR consistency (one line)
+
+- [ ] Read root `CONTEXT.md`: do terms in the change mix `_Avoid_` aliases? If an irreversible decision was introduced, should there be an ADR? (Prompt only — do not force creating a file.)
+
+### Report format
+
+```markdown
+## Standards findings
+- [sev] ...
+
+## Spec findings
+- [sev] ...
+
+## Summary
+- Standards: N issues (not ranked against Spec)
+- Spec: M issues
+```
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found (Standards and Spec sections per Step 4 format) and fix them directly. Parallel review sub-agents **do not fix** — the main agent owns all fixes. Re-run project checks after fixes.

package/dist/templates/common/bundled-skills/pactile-check/references/fowler-12-smells.md

@@ -1,28 +1,28 @@
-# Fowler 12 Smells — Quick Criterion Reference
-
-Scan the change surface line by line: report when a smell is hit, write `N/A` when not. Each criterion is a one-line "is" definition; the **don't-report** boundaries guard against false positives (paired with the ~35% false-positive discipline in `.pactile/spec/guides/index.md`).
-
-1. **Mysterious Name** — a name fails to express the code's intent (what it does / why it exists); the reader must read the implementation to understand it.
-   Don't report: evaluate only within the changed lines; do not opportunistically flag historical naming outside the change surface.
-2. **Duplicated Code** — the same structure/expression is repeated in 2+ places, so a change must be synced across several sites.
-   Don't report: small test boilerplate (e.g. a one-line setup) where extraction would reduce readability.
-3. **Feature Envy** — a method uses another object's data/methods far more than its own.
-   Don't report: an orchestration point that coordinates multiple collaborators is the method's job, not envy.
-4. **Data Clumps** — the same group of fields/parameters keep appearing together and should be bundled into an object.
-   Don't report: don't force types that only bundle without adding behavior (lazy creation discipline).
-5. **Primitive Obsession** — primitives (string/number/bool) carry concepts that deserve their own type (IDs, amounts, states).
-   Don't report: when the value domain is already constrained by an existing validation/config layer and adds no new behavior.
-6. **Repeated Switches** — the same discriminating field (kind/type/status) drives switch/if-else chains repeated in multiple places.
-   Don't report: 1–2 occurrences where that is the language idiom (e.g. ADT pattern matching).
-7. **Shotgun Surgery** — one conceptual change requires synchronized edits scattered across many places.
-   Don't report: when the multiple edits are concentrated in one cohesive module (locality holds).
-8. **Divergent Change** — one module changes frequently for many different reasons.
-   Don't report: when the module is an intentional facade/aggregator.
-9. **Speculative Generality** — abstractions/parameters/hooks are built for imagined future needs with no current caller.
-   Don't report: abstractions actually used in this change.
-10. **Message Chains** — a long call chain `a.b().c().d()` is needed to reach a target value, with intermediate links being pure pass-through.
-    Don't report: when the fluent/builder chain is itself the public interface.
-11. **Middle Man** — a class/method mostly forwards to somewhere else and adds little value of its own.
-    Don't report: when the forwarding provides encapsulation/seam value (e.g. an adapter sitting at a seam).
-12. **Refused Bequest** — a subclass barely uses inherited parent behavior/fields, making the inheritance relationship nominal.
-    Don't report: when inheritance is used only for type identity/interface satisfaction (is-a semantics) or the unused members are minimal.
+# Fowler 12 Smells — Quick Criterion Reference
+
+Scan the change surface line by line: report when a smell is hit, write `N/A` when not. Each criterion is a one-line "is" definition; the **don't-report** boundaries guard against false positives (paired with the ~35% false-positive discipline in `.pactile/spec/guides/index.md`).
+
+1. **Mysterious Name** — a name fails to express the code's intent (what it does / why it exists); the reader must read the implementation to understand it.
+   Don't report: evaluate only within the changed lines; do not opportunistically flag historical naming outside the change surface.
+2. **Duplicated Code** — the same structure/expression is repeated in 2+ places, so a change must be synced across several sites.
+   Don't report: small test boilerplate (e.g. a one-line setup) where extraction would reduce readability.
+3. **Feature Envy** — a method uses another object's data/methods far more than its own.
+   Don't report: an orchestration point that coordinates multiple collaborators is the method's job, not envy.
+4. **Data Clumps** — the same group of fields/parameters keep appearing together and should be bundled into an object.
+   Don't report: don't force types that only bundle without adding behavior (lazy creation discipline).
+5. **Primitive Obsession** — primitives (string/number/bool) carry concepts that deserve their own type (IDs, amounts, states).
+   Don't report: when the value domain is already constrained by an existing validation/config layer and adds no new behavior.
+6. **Repeated Switches** — the same discriminating field (kind/type/status) drives switch/if-else chains repeated in multiple places.
+   Don't report: 1–2 occurrences where that is the language idiom (e.g. ADT pattern matching).
+7. **Shotgun Surgery** — one conceptual change requires synchronized edits scattered across many places.
+   Don't report: when the multiple edits are concentrated in one cohesive module (locality holds).
+8. **Divergent Change** — one module changes frequently for many different reasons.
+   Don't report: when the module is an intentional facade/aggregator.
+9. **Speculative Generality** — abstractions/parameters/hooks are built for imagined future needs with no current caller.
+   Don't report: abstractions actually used in this change.
+10. **Message Chains** — a long call chain `a.b().c().d()` is needed to reach a target value, with intermediate links being pure pass-through.
+    Don't report: when the fluent/builder chain is itself the public interface.
+11. **Middle Man** — a class/method mostly forwards to somewhere else and adds little value of its own.
+    Don't report: when the forwarding provides encapsulation/seam value (e.g. an adapter sitting at a seam).
+12. **Refused Bequest** — a subclass barely uses inherited parent behavior/fields, making the inheritance relationship nominal.
+    Don't report: when inheritance is used only for type identity/interface satisfaction (is-a semantics) or the unused members are minimal.

package/dist/templates/common/bundled-skills/pactile-handoff/SKILL.md

@@ -1,117 +1,117 @@
----
-name: pactile-handoff
-description: "Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path."
-argument-hint: "What will the next session use this for?"
-disable-model-invocation: true
----
-
-# pactile-handoff — Session handoff
-
-Condense the current session into a **portable** handoff document (`pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md`), written to the **OS temp directory** (does not pollute the workspace), so a new agent can continue without the original session. User-invoked (`disable-model-invocation: true` — the agent never triggers it on its own; it is written only when the user invokes `/pactile-handoff`).
-
----
-
-## How this differs from a task `handoff.md` (read first)
-
-**The two have opposite purposes — not interchangeable:**
-
-| | This skill (session handoff) | Task `handoff.md` |
-| --- | --- | --- |
-| What | Portable cross-session summary | Child-task integration / implementation-window **delivery evidence** |
-| Where | OS temp directory (volatile) | `.pactile/tasks/<task>/` (durable, archived with the task) |
-| Lifecycle | Single transfer; dead once the work lands | Kept with the task evidence for Parent / review traces |
-
-A task directory's `handoff.md` is the evidence file for `integrate-child` / `review-child`, **not** a session handoff document; the temp file this skill produces is **not** task evidence.
-
-## When to use / when not (five-question tree)
-
-At stage boundaries first ask: **does the work still continue in this session?**
-
-1. **Continue** — default preference: keep going in this session
-2. **Clear** — context can be dropped; clear and restart
-3. **Handoff** — the work needs to travel → this skill
-4. **Subagent** — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
-5. **Compact** — same harness, same directory, only intent compression needed → use the platform compact
-
-**Handoff only when the work needs to travel**, triggered by exactly four situations:
-
-| Situation | Why a file is needed |
-| --- | --- |
-| Switch harness (e.g. Cursor → Codex) | The new harness cannot see the old context |
-| Switch directory / repo | Common for prototype directories and new repos |
-| Hand to a colleague | They need something they can read independently |
-| Fork a side branch (main line continues) | You stay in this session; a second agent takes a copy in parallel |
-
-**Same harness, same directory continuation → compact / continue, not handoff.** The value of handoff is **portability**, not better compression; if only intent compression is wanted, `/compact` is the better fit.
-
-## Steps
-
-1. **Read the user argument**: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
-2. **Write the temp file** (path rules below).
-3. **Report the full absolute path** (required): temp paths are long and differ per OS; the user must get the path first.
-4. **Remind about volatility**: the temp file may be cleaned by the environment (Codex clears temp across sessions; `/private/tmp` is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately (this also applies to other temp files referenced by the document).
-
-### Path rules (Windows first)
-
-```text
-$env:TEMP\pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md
-```
-
-- Windows: `$env:TEMP` (i.e. `%TEMP%`), e.g. `C:\Users\<user>\AppData\Local\Temp\pactile-handoff-20260808-153000-migrate-ts.md`
-- Linux / macOS: `$TMPDIR/pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md` (`/tmp` when `$TMPDIR` is unset)
-- After writing, always report the **full absolute path** to the user (Write-Host or plain text) — never just the filename.
-
-## Content template (English skeleton)
-
-> Follow `artifact_locale` when the project uses it; English by default.
-
-```markdown
-# Session handoff — <work summary>
-
-> Generated by pactile-handoff at <time> · Next-session purpose: <user argument>
-
-## Goal
-<what the in-flight work is trying to achieve>
-
-## Done
-- <items>
-
-## Not done / Blocked
-- <items>
-
-## Next steps
-1. <ordered steps>
-
-## Key whys (trimmed by next-session purpose)
-- <decision + reason; whys unrelated to this purpose can be omitted>
-
-## Facts vs unverified beliefs
-- Facts: <verified>
-- Beliefs (unverified): <assumptions — never write them as facts>
-
-## Pointers (reference paths only, never copy bodies)
-- Task: `.pactile/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
-- Context: `CONTEXT.md` · Research: `<task>/research/`
-- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.py` (see `.pactile/spec/guides/prototype-guide.md` §9)
-- Other: ADR / issue / commit / diff paths or URLs
-
-## Suggested skills (for the continuing agent)
-- <skill name list, e.g. pactile-brainstorm, pactile-check, pactile-continue>
-```
-
-## Rules
-
-- **Reference, don't copy**: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim. The document should be a small part of the session; a path list replaces copying.
-- **Redact**: API keys, tokens, passwords, PII → replace with `<REDACTED>` before writing; when unsure, write `<REDACTED>`.
-- **Facts vs beliefs**: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
-- **Prototype evidence pointer**: when the session involved a prototype, list the prototype evidence path in the pointers section (`prototype-guide.md` §9: git throwaway branch or a task `research/` path snapshot) and confirm the evidence is captured before cleanup.
-- **Delivery**: have the new agent **read the file path**; do not stuff the summary into shell quotes to launch the new agent (backticks / `$(...)` get swallowed and silently truncated).
-
-## Anti-patterns
-
-- ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in `AGENTS.md` / spec, not handoff)
-- ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
-- ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
-- ❌ Not reporting the full path / not reminding about temp volatility
-- ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
-- ❌ Writing keys / tokens into the document
+---
+name: pactile-handoff
+description: "Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path."
+argument-hint: "What will the next session use this for?"
+disable-model-invocation: true
+---
+
+# pactile-handoff — Session handoff
+
+Condense the current session into a **portable** handoff document (`pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md`), written to the **OS temp directory** (does not pollute the workspace), so a new agent can continue without the original session. User-invoked (`disable-model-invocation: true` — the agent never triggers it on its own; it is written only when the user invokes `/pactile-handoff`).
+
+---
+
+## How this differs from a task `handoff.md` (read first)
+
+**The two have opposite purposes — not interchangeable:**
+
+| | This skill (session handoff) | Task `handoff.md` |
+| --- | --- | --- |
+| What | Portable cross-session summary | Child-task integration / implementation-window **delivery evidence** |
+| Where | OS temp directory (volatile) | `.pactile/tasks/<task>/` (durable, archived with the task) |
+| Lifecycle | Single transfer; dead once the work lands | Kept with the task evidence for Parent / review traces |
+
+A task directory's `handoff.md` is the evidence file for `integrate-child` / `review-child`, **not** a session handoff document; the temp file this skill produces is **not** task evidence.
+
+## When to use / when not (five-question tree)
+
+At stage boundaries first ask: **does the work still continue in this session?**
+
+1. **Continue** — default preference: keep going in this session
+2. **Clear** — context can be dropped; clear and restart
+3. **Handoff** — the work needs to travel → this skill
+4. **Subagent** — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
+5. **Compact** — same harness, same directory, only intent compression needed → use the platform compact
+
+**Handoff only when the work needs to travel**, triggered by exactly four situations:
+
+| Situation | Why a file is needed |
+| --- | --- |
+| Switch tasks or hosts | The destination may not see the previous context |
+| Switch directory / repo | Common for prototype directories and new repos |
+| Hand to a colleague | They need something they can read independently |
+| Fork a side branch (main line continues) | You stay in this session; a second agent takes a copy in parallel |
+
+**Same harness, same directory continuation → compact / continue, not handoff.** The value of handoff is **portability**, not better compression; if only intent compression is wanted, `/compact` is the better fit.
+
+## Steps
+
+1. **Read the user argument**: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
+2. **Write the temp file** (path rules below).
+3. **Report the full absolute path** (required): temp paths are long and differ per OS; the user must get the path first.
+4. **Remind about volatility**: the temp file may be cleaned by the environment (Codex clears temp across sessions; `/private/tmp` is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately (this also applies to other temp files referenced by the document).
+
+### Path rules (Windows first)
+
+```text
+$env:TEMP\pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md
+```
+
+- Windows: `$env:TEMP` (i.e. `%TEMP%`), e.g. `C:\Users\<user>\AppData\Local\Temp\pactile-handoff-20260808-153000-migrate-ts.md`
+- Linux / macOS: `$TMPDIR/pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md` (`/tmp` when `$TMPDIR` is unset)
+- After writing, always report the **full absolute path** to the user (Write-Host or plain text) — never just the filename.
+
+## Content template (English skeleton)
+
+> Follow `artifact_locale` when the project uses it; English by default.
+
+```markdown
+# Session handoff — <work summary>
+
+> Generated by pactile-handoff at <time> · Next-session purpose: <user argument>
+
+## Goal
+<what the in-flight work is trying to achieve>
+
+## Done
+- <items>
+
+## Not done / Blocked
+- <items>
+
+## Next steps
+1. <ordered steps>
+
+## Key whys (trimmed by next-session purpose)
+- <decision + reason; whys unrelated to this purpose can be omitted>
+
+## Facts vs unverified beliefs
+- Facts: <verified>
+- Beliefs (unverified): <assumptions — never write them as facts>
+
+## Pointers (reference paths only, never copy bodies)
+- Task: `.pactile/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
+- Context: `CONTEXT.md` · Research: `<task>/research/`
+- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.mjs` (see `.pactile/spec/guides/prototype-guide.md` §9)
+- Other: ADR / issue / commit / diff paths or URLs
+
+## Suggested skills (for the continuing agent)
+- <skill name list, e.g. pactile-brainstorm, pactile-check, pactile-continue>
+```
+
+## Rules
+
+- **Reference, don't copy**: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim. The document should be a small part of the session; a path list replaces copying.
+- **Redact**: API keys, tokens, passwords, PII → replace with `<REDACTED>` before writing; when unsure, write `<REDACTED>`.
+- **Facts vs beliefs**: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
+- **Prototype evidence pointer**: when the session involved a prototype, list the prototype evidence path in the pointers section (`prototype-guide.md` §9: git throwaway branch or a task `research/` path snapshot) and confirm the evidence is captured before cleanup.
+- **Delivery**: have the new agent **read the file path**; do not stuff the summary into shell quotes to launch the new agent (backticks / `$(...)` get swallowed and silently truncated).
+
+## Anti-patterns
+
+- ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in `AGENTS.md` / spec, not handoff)
+- ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
+- ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
+- ❌ Not reporting the full path / not reminding about temp volatility
+- ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
+- ❌ Writing keys / tokens into the document