@blxzer/pactile 0.5.0

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Verification evidence probe — repeatable false-green detection.
+
+Evaluates a fixture verify.md against closeout-profile evidence requirements
+by reusing task_gates.verify_evidence_status() (no duplicate rule set).
+
+Exit 0 when actual outcome matches --expect; exit 1 on mismatch or error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+_SCRIPTS = Path(__file__).resolve().parent
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+from common.task_gates import verify_evidence_status  # noqa: E402
+
+if sys.platform.startswith("win"):
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None and _stream_name != "stdin":
+            continue
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(
+                    sys,
+                    _stream_name,
+                    io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"),
+                )
+            except Exception:
+                pass
+
+PROFILE_REQUIRED_SIGNALS: dict[str, list[str]] = {
+    "lite": ["validation", "acceptance", "durable_learning"],
+    "full": [
+        "validation",
+        "acceptance",
+        "durable_learning",
+        "check_evidence",
+        "reviewed_change_set",
+    ],
+    "parent": [
+        "validation",
+        "acceptance",
+        "durable_learning",
+        "integration",
+    ],
+}
+
+
+def evaluate_fixture(fixture_path: Path, profile: str) -> tuple[bool, dict[str, bool], list[str]]:
+    """Return (passes, status_map, missing_signals) for a fixture verify.md."""
+    profile = profile.lower().strip()
+    if profile not in PROFILE_REQUIRED_SIGNALS:
+        raise ValueError(f"unknown profile: {profile}")
+
+    required = PROFILE_REQUIRED_SIGNALS[profile]
+    task_data: dict = {"children": ["probe-child"] if profile == "parent" else []}
+
+    with tempfile.TemporaryDirectory(prefix="pactile-verify-probe-") as tmp:
+        task_dir = Path(tmp)
+        shutil.copy2(fixture_path, task_dir / "verify.md")
+        status = verify_evidence_status(task_dir, task_data)
+
+    missing = [signal for signal in required if not status.get(signal)]
+    return len(missing) == 0, status, missing
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Probe verify.md fixture against closeout evidence requirements.",
+    )
+    parser.add_argument(
+        "--fixture",
+        required=True,
+        type=Path,
+        help="Path to fixture verify.md",
+    )
+    parser.add_argument(
+        "--profile",
+        required=True,
+        choices=sorted(PROFILE_REQUIRED_SIGNALS),
+        help="Closeout profile to evaluate against",
+    )
+    parser.add_argument(
+        "--expect",
+        required=True,
+        choices=("pass", "fail"),
+        help="Expected probe outcome",
+    )
+    args = parser.parse_args(argv)
+
+    fixture = args.fixture.resolve()
+    if not fixture.is_file():
+        print(f"verify-evidence-probe: fixture not found: {fixture}", file=sys.stderr)
+        return 2
+
+    try:
+        passes, status, missing = evaluate_fixture(fixture, args.profile)
+    except ValueError as exc:
+        print(f"verify-evidence-probe: {exc}", file=sys.stderr)
+        return 2
+
+    actual = "pass" if passes else "fail"
+    expected = args.expect.lower()
+
+    print(f"fixture: {fixture}")
+    print(f"profile: {args.profile}")
+    print(f"status: {status}")
+    if missing:
+        print(f"missing: {', '.join(missing)}")
+    print(f"actual: {actual}")
+    print(f"expect: {expected}")
+
+    if actual == expected:
+        print("result: OK")
+        return 0
+
+    print("result: MISMATCH", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/pactile/tasks/locale/en/default-prd.md

@@ -0,0 +1,27 @@
+# {title}
+
+## Goal
+
+{goal}
+
+## User Stories
+
+- [ ] (User-visible behaviors; enumerate as a long checkable list, not implementation steps)
+
+## Requirements
+
+- TBD
+
+## Acceptance Criteria
+
+- [ ] TBD
+
+## Implementation Decisions
+
+- (Recorded decisions; **do not write file paths** — paths go stale; keep them in design/implement)
+
+## Notes
+
+- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
+- Lightweight tasks can remain PRD-only.
+- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start-execution --check`.

package/dist/templates/pactile/tasks/locale/zh/default-prd.md

@@ -0,0 +1,27 @@
+# {title}
+
+## 目标
+
+{goal}
+
+## 用户故事
+
+- [ ] （用户可见行为；用极长可勾选列表穷举，不是实现步骤）
+
+## 需求
+
+- 待补充
+
+## 验收标准
+
+- [ ] 待补充
+
+## 实现决策
+
+- （已定决策；**不要写文件路径**——路径会过时，放 design/implement）
+
+## 备注
+
+- `prd.md` 聚焦需求、约束与验收标准。
+- 轻量任务可仅保留 PRD。
+- 复杂任务在 `task.py start-execution --check` 前补充 `design.md` 与 `implement.md`。

package/dist/templates/pactile/tasks/templates/release-execution/design.md

@@ -0,0 +1,61 @@
+# Design — Release execution
+
+## Boundary
+
+This task **may** mutate remotes **only** after explicit user approval captured in `verify.md` (quote or paraphrase the approval request/response).
+
+## Release status model (this task)
+
+| Status | When to use |
+| --- | --- |
+| **published** | npm and/or git remote actions completed for the approved version |
+| **not published** | Execution aborted or only dry-run/preflight completed |
+| **blocked** | Preflight failed; do not publish until fixed |
+| **waived** | User approved proceeding despite a listed risk |
+| **deferred** | User postponed publish after readiness |
+
+Do not mark **ready to publish** here — that remains the readiness task outcome.
+
+## Approval gate (mandatory)
+
+Before any of the following, stop and obtain explicit user approval:
+
+- `node scripts/release.js …` (bundles bump, commit, tag, push)
+- `npm publish` / CI publish workflow dispatch
+- `git tag` / `git push` (including `--tags`)
+- GitHub **Create release** or promotion workflows
+
+Document in `verify.md`:
+
+```markdown
+## Publish approval evidence
+
+User explicitly approved: yes/no
+Approved version: …
+Approved dist-tag: …
+Approved remote actions: tag / push / npm publish / …
+```
+
+## Evidence contract (`verify.md`)
+
+1. **Readiness link** — path to readiness `handoff.md`.
+2. **Publish approval evidence** — as above.
+3. **Preflight results** — `check-versions`, `publish-plan`, `verify-packed-cli`.
+4. **Execution log** — commands run (redact tokens); pass/fail.
+5. **Post-publish smoke** — registry check, `pactile --version`, dogfood smoke commands.
+6. **Validation evidence** — tests run after publish if applicable.
+
+## Pactile CLI reference sequence (after approval)
+
+Typical human/CI sequence (do not automate without approval):
+
+```bash
+cd packages/cli
+node scripts/release-preflight.js check-versions
+node scripts/release-preflight.js publish-plan
+# After approval:
+pnpm --filter @blxzer/pactile release:beta   # or patch/minor/major per policy
+node scripts/release-preflight.js verify-npm --package all
+```
+
+`release.js` performs commit, tag, and push — treat it as a single approved bundle or decompose manually per policy.

package/dist/templates/pactile/tasks/templates/release-execution/handoff-template.md

@@ -0,0 +1,29 @@
+# Handoff — Release execution — `{task-id}`
+
+## Published
+
+| Action | Evidence |
+| --- | --- |
+| Version bumped | `{yes/no}` — `{version}` |
+| Git tag | `{tag or none}` |
+| Git push | `{ref or none}` |
+| npm publish | `{package@version + dist-tag or none}` |
+| Post-publish smoke | `{summary}` |
+
+## Not published
+
+- `{Describe aborted or dry-run-only session}`
+
+## Ready to publish
+
+_Refer to readiness task:_ `{path to readiness handoff.md}`
+
+## Blockers
+
+| Blocker | Severity | Disposition | Notes |
+| --- | --- | --- | --- |
+| `{if any}` | | | |
+
+## Residual risks
+
+- `{registry lag, global CLI hygiene, consumer dist-tag confusion, etc.}`

package/dist/templates/pactile/tasks/templates/release-execution/implement.md

@@ -0,0 +1,29 @@
+# Implementation Plan — Release execution
+
+## Development Strategy Contract
+
+execution_mode: lite-task
+isolation: none
+verification_profile: standard
+retrieval_profile: structure
+optional_capabilities: []
+quality_gates:
+  mode: profile
+  profile: standard
+  enabled: []
+  disabled: []
+
+## Steps
+
+1. Read linked readiness `handoff.md` and confirm **ready to publish**.
+2. Ask user for explicit approval; record in `verify.md` **Publish approval evidence**.
+3. Run preflight checks (no publish yet).
+4. On approval only, run approved release commands.
+5. Run post-publish smoke and registry verification.
+6. Write `handoff.md` (**Published** / **Not published** / residual risks).
+7. `task.py validate` and archive when complete.
+
+## Validation
+
+- Preflight must pass or be explicitly waived before publish.
+- If user denies approval, end with **not published** and no remote mutations.

package/dist/templates/pactile/tasks/templates/release-execution/prd.md

@@ -0,0 +1,31 @@
+# Release execution — {package_or_product}
+
+## Goal
+
+Execute an **already prepared** release after explicit user approval, with auditable evidence for each remote mutation.
+
+## Preconditions
+
+- A completed **release-readiness** task (or equivalent evidence) with **ready to publish** status.
+- Explicit user approval in this session for **each** of: version bump (if not done), git tag, git push, npm publish (and GitHub release if used).
+- No execution without naming the approved version and dist-tag.
+
+## Requirements
+
+- Link readiness task path and restate approved version/channel in `verify.md`.
+- Run project release preflight (`check-versions`, `publish-plan`, `verify-packed-cli`) immediately before publish.
+- Execute only approved steps; record exact commands, timestamps, and outcomes.
+- Capture post-publish smoke (registry visibility, installed CLI version, or project-specific smoke).
+- Write `handoff.md` with **Published** evidence separate from readiness artifacts.
+
+## Acceptance Criteria
+
+- [ ] `handoff.md` documents what was published/tagged/pushed vs skipped.
+- [ ] `verify.md` lists validation and post-publish smoke results.
+- [ ] No publish/tag/push occurred before documented user approval.
+- [ ] Readiness task remains **not published** if execution was aborted.
+
+## Out Of Scope
+
+- Re-doing full readiness research (fix blockers in readiness or a new readiness task).
+- Publishing without user approval “because checks passed”.

package/dist/templates/pactile/tasks/templates/release-readiness/design.md

@@ -0,0 +1,50 @@
+# Design — Release readiness
+
+## Boundary
+
+This task is **readiness only**. It produces evidence and recommendations; it does not change registry or remote git state.
+
+## Release status model (this task)
+
+Use these labels in `handoff.md` and `verify.md` (not `task.json.status` — see workflow release guidance).
+
+| Status | Meaning |
+| --- | --- |
+| **ready to publish** | Evidence complete; operator may proceed after explicit approval |
+| **not published** | No remote release actions were performed in this task |
+| **blocked** | A required gate failed; publish must not proceed until fixed or waived |
+| **waived** | User explicitly accepted a known blocker; document approver + rationale |
+| **deferred** | Publish intentionally postponed (e.g. wait for another child / dogfood) |
+
+**published** belongs only in a **release-execution** task after verified remote actions.
+
+## Evidence contract (`verify.md`)
+
+Include grep-friendly sections (archive checks may reference these families):
+
+1. **Version recommendation** — current vs proposed; channel; dist-tag expectation.
+2. **Changelog / release notes** — draft text or path to notes file.
+3. **Migration manifest** — new/updated manifest id or “no manifest change”.
+4. **Build evidence** — commands + pass/fail summary.
+5. **Test evidence** — focused suite scope; note full-suite gaps if publish pipeline would fail.
+6. **Pack dry-run evidence** — `npm pack --dry-run` / `publish-plan` / `verify-packed-cli` as applicable.
+7. **Prepublish blockers** — table with severity and disposition (`blocking` / `fixed` / `waived` / `deferred`).
+
+## Pactile CLI reference commands (dry-run / check only)
+
+From the Pactile monorepo `packages/cli` (adjust paths for other products):
+
+```bash
+node scripts/check-manifest-continuity.js
+node scripts/release-preflight.js check-versions
+node scripts/release-preflight.js publish-plan
+node scripts/release-preflight.js verify-packed-cli
+pnpm --filter @blxzer/pactile exec npm pack --dry-run
+```
+
+Do **not** run `scripts/release.js`, `npm publish`, or `git push` in readiness.
+
+## Safety
+
+- Agents must not run publish/tag/push even if checks are green.
+- Waiving a blocker requires explicit user words in chat or `handoff.md`, not agent assumption.

package/dist/templates/pactile/tasks/templates/release-readiness/handoff-template.md

@@ -0,0 +1,39 @@
+# Handoff — Release readiness — `{task-id}`
+
+## Ready to publish
+
+**Materials are prepared; explicit user approval still required before any remote release.**
+
+| Area | Status |
+| --- | --- |
+| Version recommendation | `{proposed-version}` via `{channel}` |
+| Changelog / release notes | Draft in `verify.md` |
+| Migration manifest | `{manifest-id or none}` |
+| Build / test / pack dry-run | `{summary}` |
+
+**Operator checklist before publish (not executed in readiness task):**
+
+1. Resolve or waive each **blocking** row in Blockers below.
+2. Create or select a **release-execution** task; obtain explicit publish approval.
+3. Only then run release scripts (`release.js` / CI publish) per project policy.
+
+## Not published
+
+- No npm publish, git tag, git push, or GitHub release in this task session.
+- Workspace `package.json` versions unchanged unless a separate task already bumped them.
+
+## Blockers
+
+| Blocker | Severity | Disposition | Notes |
+| --- | --- | --- | --- |
+| Explicit user approval for publish | **Required gate** | blocking | Out of scope for readiness by design |
+| `{example}` | blocking / fixed / waived / deferred | `{disposition}` | `{notes}` |
+
+## Published
+
+_Not applicable in a readiness task. Record publish evidence only in release-execution `handoff.md`._
+
+## Integration notes
+
+- Link execution task: `{path or pending}`
+- Parent / dogfood notes: `{optional}`

package/dist/templates/pactile/tasks/templates/release-readiness/implement.md

@@ -0,0 +1,29 @@
+# Implementation Plan — Release readiness
+
+## Development Strategy Contract
+
+execution_mode: lite-task
+isolation: none
+verification_profile: standard
+retrieval_profile: structure
+optional_capabilities: []
+quality_gates:
+  mode: profile
+  profile: standard
+  enabled: []
+  disabled: []
+
+## Steps
+
+1. Read product release spec (e.g. `.pactile/spec/**/release*.md`) and recent integrated task handoffs.
+2. Record current versions from `package.json` (and lockstep packages).
+3. Draft version recommendation and changelog.
+4. Run non-mutating guards and validation (manifest, build, focused tests, typecheck, pack dry-run).
+5. Fill `verify.md` using the evidence contract in `design.md`.
+6. Write `handoff.md` with **Ready to publish**, **Not published**, and **Blockers** tables.
+7. Run `python ./.pactile/scripts/task.py validate <this-task>` and `archive --check` when finishing.
+
+## Validation
+
+- Dry-run and `--check` commands only.
+- No version bump, tag, push, or publish.

package/dist/templates/pactile/tasks/templates/release-readiness/prd.md

@@ -0,0 +1,31 @@
+# Release readiness — {package_or_product}
+
+## Goal
+
+Prepare a **ready-to-publish** release recommendation and evidence **without** publishing, tagging, pushing, or bumping versions in this task.
+
+## Requirements
+
+- Record current workspace versions (CLI, core, or product packages as applicable).
+- Recommend next version and release channel (`patch` / `minor` / `major` / `beta` / `rc` / `promote`) with rationale.
+- Draft changelog / release notes for the scoped changes.
+- Document migration manifest expectations when the Pactile CLI ships template or script changes.
+- Run **non-mutating** validation: build, focused tests, typecheck, pack dry-run, manifest/docs guards (dry-run only).
+- Structure prepublish blockers as `blocking` / `fixed` / `waived` / `deferred`.
+- Write `verify.md` and `handoff.md` that clearly separate **ready to publish** from **published**.
+
+## Acceptance Criteria
+
+- [ ] `handoff.md` includes **Ready to publish**, **Not published**, and **Blockers** sections.
+- [ ] `verify.md` includes validation commands/results and standardized release evidence headings.
+- [ ] No `npm publish`, `git tag`, `git push`, version bump commits, or GitHub release created in this task.
+- [ ] Any waived blocker names the approver and rationale in `handoff.md`.
+
+## Out Of Scope
+
+- Release execution (publish / tag / push / bump).
+- Fixing unrelated full-suite failures unless required to document a publish blocker.
+
+## Operator handoff
+
+When readiness is complete, open a separate **release-execution** task (or explicit user approval in-session) before any remote mutation. Link the readiness task directory in execution `prd.md`.

package/dist/templates/pactile/workflow.md

@@ -0,0 +1,64 @@
+# Development Workflow
+
+> **Human overview — not runtime SSOT.** Gates, Rigor, Topology, and Task state are Kernel / `task.json` projections. Do not parse this document as the runtime program of record.
+
+## Interfaces
+
+Constraints live in artifacts and Kernel records:
+
+| Interface | Role |
+| --- | --- |
+| `prd.md` | Definition and acceptance |
+| `implement.md` | Execution / verification contract (when present) |
+| `verify.md` | Evidence (when recorded) |
+| `task.json` | Status and metadata (accounting) |
+| `kernel.json` | Audit chain |
+| `task.py archive` | Close: `status=completed`, Kernel audit, notes projection |
+
+## User commands
+
+- `pactile-continue` — resume the selected task. Details: `.pactile/framework/index.md`.
+- `pactile-finish-work` — closeout / archive path. Details: `.pactile/framework/index.md`.
+- `pactile-handoff` — session handoff (reports a temp path). Details: `.pactile/framework/index.md`.
+- `pactile-start` — only when the framework needs a refresh and no task is selected.
+
+## Gates
+
+- **Execute:** `python ./.pactile/scripts/task.py start-execution <task> --approved` (`--check` is preflight only; it does not impersonate approval).
+- **Close:** `python ./.pactile/scripts/task.py archive <task>` — writes `completed`, Kernel audit, and notes projection.
+
+## Pointers
+
+Start at `.pactile/framework/index.md`. Do not expand methodology here.
+
+- Parallel first → `.pactile/framework/parallel-first-execution.md`
+- Pool → `.pactile/pool/`
+- Full Quality / graded verify → `.pactile/framework/verification-strength-guide.md`
+- Retrieval → `.pactile/framework/retrieval-daily-guide.md`
+- Subagent dispatch → `.pactile/framework/cursor-subagent-policy.md`
+
+<!--
+  Codex/Claude UserPromptSubmit parses [workflow-state:STATUS] blocks.
+  Bodies are status facts (1–2 sentences), not process teaching.
+  STATUS charset: [A-Za-z0-9_-]+
+-->
+
+[workflow-state:no_task]
+No task is selected.
+This status is an accounting fact, not a step list.
+[/workflow-state:no_task]
+
+[workflow-state:planning]
+Selected task status is `planning`.
+Constraints are `prd.md` and optional `design.md`/`implement.md`; Execute starts only after `task.py start-execution --approved`.
+[/workflow-state:planning]
+
+[workflow-state:in_progress]
+Selected task status is `in_progress`.
+Implement against the approved artifacts; Close is `task.py archive` (Kernel audit plus notes projection).
+[/workflow-state:in_progress]
+
+[workflow-state:completed]
+Task status is `completed`.
+`task.py archive` writes this status in the same call that moves the directory.
+[/workflow-state:completed]