PW-Maker

PW-Maker 是创建、恢复和变更 PiFlow Workflow（PW）项目的 Codex skill。它负责生成与校验 PWP（.pwp）源码发布包；PiFlow Desktop 下载 PWP 后从受控 Runtime Profile 在本机构建 image，Platform 仅分发 PWP 与调度任务。详见 PWP 本地构建方案 与 English guide。

安装 / Installation

使用官方 npm 包

当官方版本已发布到 npm 时，可直接通过 npx 安装到本机 agent（推荐）：

npm view @piflow.org/pw-maker version
npx @piflow.org/pw-maker@latest install --agents codex

该包提供 SKILL.md、模板和维护脚本。npx @piflow.org/pw-maker@latest install 默认使用复制模式，把 pw-maker 安装到本机已存在的 Codex、Cursor、Claude Code、OpenCode skill 目录；这样不会把 agent skill 链接到 npx 的临时目录。未发现对应 agent 根目录时会跳过。若要创建缺失的 agent 目录并全部安装，可运行 npx @piflow.org/pw-maker@latest install --all。安装完成后，请重新加载或重启相关 agent；PW-Maker 不会在当前对话中热切换到刚下载的实现。

如需在项目中保留依赖，仍可安装 npm 包后执行：

npm install @piflow.org/pw-maker
npm exec pw-maker -- install --agents codex

使用 npx skills 安装标准 Skill

npx skills 从 Git 或本地目录发现包含 SKILL.md 的标准 Agent Skill，不从 npm 包名读取技能内容。PW-Maker 的仓库目录符合该格式，可直接安装到 Codex：

npx skills@latest add https://github.com/rudyzhuang/piflow.org/tree/main/skills/PW-Maker --global --agent codex --copy --yes

将 --agent codex 改为目标 agent 即可；省略 --global 时安装到当前项目。--copy 会保留独立文件副本，适合通过临时下载或 CI 执行安装的场景。npm CLI 与 npx skills 是两条独立入口：前者执行发布包的命令，后者安装仓库中的标准技能目录。

若 npm view 返回“找不到包”或权限错误，说明当前没有可用的官方 npm 发布版；请使用下面的源码路径，而不是从非官方来源下载同名包。

从源码使用

在官方包尚未发布，或你正在开发 PW-Maker 时，打开本仓库作为 Codex 工作区即可使用其中的 SKILL.md。不要把源码 checkout 覆盖成受管安装目录；受管更新脚本会刻意拒绝覆盖非受管的 Git 工作区。

前置条件

• 当前 Node.js LTS 与 npm；PW-Maker 的维护脚本以 Node ESM 运行。

• Git；新建 workflow 默认在项目目录初始化 Git。

• 若采用默认的私有 GitHub 仓库初始化，还需要 GitHub CLI 并完成登录：

  gh auth login -h github.com --web

已安装的受管版本可检查更新；先查看版本和影响，确认后安装，最后重启或重新加载 Codex：

npx @piflow.org/pw-maker@latest update check
npx @piflow.org/pw-maker@latest update install --confirm --version <version>

install 只会激活 ~/.piflow/managed-skills/pw-maker/ 下经校验的官方包；如果 ~/.codex/skills/pw-maker 是普通目录、Git checkout 或指向其他位置的链接，它会停止并提示手动更新，不会覆盖源码。

如何使用 / How to use PW-Maker

日常使用应在 Codex 中直接说明目标，例如“使用 PW-Maker 创建一个……”“下一步做什么”或“修改某个 workflow”。PW-Maker 会先读全局注册表中的脱敏摘要；在读取项目源码、作者产物或推进工作前，都会展示停点或计划并请求确认。

下面的 npx @piflow.org/pw-maker ... 命令是生命周期的查看、确认和自动化接口。普通用户不需要、也不应手动使用 advance-change 或 finish-change 把未验证工作标记为完成。

常用生命周期命令

| 命令 | 安全边界与用途 | |---|---| | npx @piflow.org/pw-maker lifecycle overview | 只读取全局注册表和已缓存的版本信息，列出中断工作、待补全/迁移、可升级技能包和可修改项目。 | | npx @piflow.org/pw-maker lifecycle resume --command <workflow-command> | 显示一个已选 workflow 的停点和下一动作；确认后才读取其完整作者上下文。 | | npx @piflow.org/pw-maker lifecycle reconcile --command <workflow-command> --confirm | 对已选旧项目补全步骤清单或迁移状态；确认前不会读取项目作者产物。 | | npx @piflow.org/pw-maker lifecycle start-change --command <workflow-command> --title "<脱敏修改摘要>" --confirm | 在干净、已提交的 Git 工作区中启动既有 workflow 的修改流程。 | | npx @piflow.org/pw-maker piflow rm <workflow-name> | 按全局注册表中的展示名称精确匹配本机 workflow，先删除项目目录，再从 ~/.piflow/registry.json 删除记录；不会删除平台已发布 release、任务、包或设备安装记录。 |

<workflow-command> 是小写 kebab-case 命令，例如 daily-report。项目的完整作者上下文始终保存在该项目的 .piflow/authoring/；~/.piflow/registry.json 只保存发现、停点和待办的脱敏摘要。 npx @piflow.org/pw-maker piflow rm <workflow-name> 的 <workflow-name> 是注册表里的展示名称，不是 <workflow-command>；若同名 workflow 超过一个，它会停止并要求先消除重名，避免误删。

实际示例

以下示例使用名为 daily-report 的 Node.js workflow。生成后的命令、输入文件和 Stage 名称应以该项目实际 README 与 project.yaml 为准。

1. 创建一个新项目

在 Codex 中输入：

使用 PW-Maker 创建一个名为“每日运营报告”的 Node.js workflow。
它读取一个本地 Markdown 需求文件，生成日报，并把结果保存为 Markdown。

PW-Maker 会先澄清输入、输出、权限和外部副作用，推荐并等待确认 Stage Graph。确认项目名和命令后，它默认创建：

~/piflow/workflows/daily-report/

该目录同时是默认源码目录和 Git 工作区；不会再要求你重复选择“新目录、远程仓库还是已有目录”。接下来它会注册项目、初始化 Git/GitHub（默认私有仓库）、逐 Stage 实现并运行自测。每个 Stage 自测通过后，它会询问是否提供补充测试用例；失败时会在当前 workflow 内委托 PW Fixer 修复并重跑原验证。

workflow 生成并完成依赖准备后，示例运行方式如下：

cd ~/piflow/workflows/daily-report
npm run setup
node bin/pw.mjs plan -i examples/req.md
node bin/pw.mjs run --run-id demo-001
node bin/pw.mjs status --run-id demo-001
node bin/pw.mjs logs --run-id demo-001

npm run setup 会检查并安装项目声明的依赖。plan 只生成执行计划；run 执行该计划；status 与 logs 使用同一个 --run-id 查看结果。交付前还必须提供一个安全、真实的验收用例；PW-Maker 会在一次性干净工作区中重新安装、完整运行并验证产物。

2. 继续一个中断的项目

直接在 Codex 中说：

下一步做什么？

或：

继续 daily-report；上次做到哪里了？

PW-Maker 会先执行等价的只读发现：

npx @piflow.org/pw-maker@latest lifecycle overview
npx @piflow.org/pw-maker@latest lifecycle resume --command daily-report

如果有多个未完成项目，它会显示名称、命令、最后停点、更新时间和脱敏下一动作，并要求你先选择一个。即使只有一个候选，也会先说明“上次停在何处、现在将做什么”，等待你的确认；确认后才从 daily-report/.piflow/authoring/ 恢复完整上下文继续。

对于使用旧版 PW-Maker 创建、尚未有步骤清单的已注册项目，可先查看并确认补全：

npx @piflow.org/pw-maker@latest lifecycle reconcile --command daily-report
npx @piflow.org/pw-maker@latest lifecycle reconcile --command daily-report --confirm

补全只依据该项目已有的安全证据；没有证据的步骤会保留待办或阻塞，不会猜测为已完成。

3. 修改或增加既有项目功能

先确认项目工作区没有混入你尚未提交的改动：

git -C ~/piflow/workflows/daily-report status --short

如果输出不为空，请先自行检查、测试并提交原有改动，再启动 PW-Maker 修改流程。随后在 Codex 中输入：

修改 daily-report：增加 CSV 格式报告输出，并在 README 中说明新命令和输出位置。

PW-Maker 会从注册表选择项目，展示将读取源码的范围并请求确认。它随后建立 Git 基线、分析 manifest.yaml、workflow/Stage/Unit、脚本、测试和现有文档的影响，在以下目录保存可追溯记录：

.piflow/authoring/changes/<change-id>/
docs/plans/<date>-daily-report-<change-id>.md

相应的生命周期入口为：

npx @piflow.org/pw-maker@latest lifecycle start-change --command daily-report --title "Add CSV report output"
npx @piflow.org/pw-maker@latest lifecycle start-change --command daily-report --title "Add CSV report output" --confirm

影响分析完成后，PW-Maker 会让你选择这次修改需要通过哪些验收：目标测试、计划验证和/或新设备端到端验收。选择后才实现已确认的范围；如果测试失败，会进入同一套 PW Fixer 修复与原测试重跑闭环。命令、安装、输入输出或用户可见行为变化会同步更新中英 README；Stage、权限、Provider 或依赖变化还会更新相关配置说明、契约和依赖报告。只有实现、所选验证、文档检查和 review 都通过后，才提交并推送该 workflow 项目的修改。

PW-Maker 在展示影响与验证计划、且你确认后，才会使用对应的记录命令：

npx @piflow.org/pw-maker@latest lifecycle confirm-change --command daily-report --change-id <change-id> --validation target-tests,plan --confirm

其中 <change-id> 由 start-change 返回。不要在未完成影响分析或未取得用户确认时自行调用该命令。

4. 生成 PiFlow Desktop 标准包（可选）

在新工作流完成 fresh-device 验收和 review 后，PW-Maker 会询问是否要生成本地 PiFlow Desktop 标准包。对旧项目，可明确输入：

使用 PW-Maker 将 daily-report 打包为 PiFlow 标准包，以便之后上传到 piflow.org。

这会走正常的既有项目变更流程：干净 Git 基线、影响分析、用户确认、PWP 入口/Schema/锁文件适配、文档同步和 review。成功后运行 npm run pack:pwp，输出确定性 .pwp ZIP（源码、pwp.json、输入/输出 Schema、锁文件）。它拒绝 OCI archive、Dockerfile、Docker Compose、秘密、缓存、镜像地址、任意安装命令、挂载与 Docker 参数。

PWP 只能引用 node-20-bookworm-slim 或 python-3.11-slim Runtime Profile，以及 catalog 中的目录化系统依赖（当前包括 ffmpeg）。Node 必须使用 package-lock.json，Python 必须使用每行带 SHA-256 的 requirements.lock.txt。Playwright、Android/ iOS SDK、模拟器与 Xcode 是未来 profile/provider，不应写成当前 PWP 能力。

需要本地模型时，PW-Maker 在项目根创建 managed-models.spec.json。作者将任意 HTTPS 直链文件集合或固定到 40 位 commit 的 Hugging Face snapshot 写入该规格后，显式运行 npm run lock:managed-models 下载、校验并生成可提交的 managed-models.lock.json。常规 npm run pack:pwp 不联网，只验证规格摘要与锁文件，并在包内注入 PWP v2 managedModels；不要在源 pwp.json 手写模型声明。模型名称不受平台白名单限制，PWD 按最终内容摘要复用；容器仅获得本 release 声明的只读目录。

需要复用宿主 CLI 时，使用 PWP v2 的 hostCapabilities：只能声明短命令名候选、安全版本探测、固定操作、$INPUT/$OUTPUT 占位符及可选 catalog 回退。PWD 会逐项探测并要求本机授权；同一工作流安装新版本时，声明未变的已批准权限会继承，任何能力声明变化仍需重新授权。没有宿主实现时只能回退到受控 catalog 依赖。不得声明宿主路径、任意参数、网络权限或安装命令。

PWD 卡片使用名称、功能描述和方形无文字 PNG 图标。创建时应与名称一并确认 description 和 icon_prompt；打包将图标写入 assets/workflow-icon.png，并在 pwp.json 保存其 SHA-256 与生成提示词。若没有图标，只有声明 image.generate 与受控内置 image adapter 的 provider 可生成图标；不可用或失败会阻断打包。

运行 enable:desktop-package 前，必须根据工作流的真实对外输入和结果，编写根目录的 input.schema.json 与 output.schema.json：列出每个支持字段及其真实类型、必填字段，并设为 additionalProperties: false。PW-Maker 会保留并校验这两个工作流契约；缺失、空对象、允许未知字段、仅 status 或猜测类型的占位 Schema 都会被拒绝，不会再被通用 object 模板覆盖。

该阶段不会登录、上传或发布到 piflow.org。默认 network: none；只有确认的外部访问需求可选 bridge。当前桌面端不会向容器注入 API Key、Cookie、浏览器 Profile 或已认证 agent CLI 状态，因此需要这些运行时凭据的工作流会保持打包阻塞，不能把凭据写入包或镜像。

Contents

• SKILL.md: Codex skill entrypoint.
• references/: authoring lifecycle, PW project contract, stage decomposition, runtime scheduling, runner, supervision, and beginner guidance references.
• assets/authoring-workflow/: PW-Maker's own staged authoring workflow with prompts, schemas, stages, and examples.
• assets/skeleton/: default YAML + Prompt + standalone runner skeleton for generated PW projects.
• Generated workflows include Chinese-default README.md, complete English README.en.md, and a confirmation-gated npm run setup entrypoint. The dedicated README author agent puts purpose, requirements, installation, and quick starts before detailed reference. Setup combines declared Node/Python dependencies and verified system-tool mappings; --check is read-only and non-interactive installation requires --approve-installation-plan. Runtime planning also writes a safe dependency report covering Python modules, system commands, and cloud requirements.
• assets/templates/: reusable YAML templates for stages, units, and workflow skills.
• scripts/register-workflow.mjs: helper for creating the workflow project root and maintaining the per-user ~/.piflow/registry.json.
• scripts/authoring-state.mjs: writes redacted authoring checkpoints, lists interrupted workflows, and validates a selected checkpoint before user-confirmed resume.
• scripts/authoring-step-ledger.mjs: defines the safe required/optional authoring checklist and dependency-aware next-step summaries.
• scripts/ensure-pw-fixer.mjs: installs or reuses the workflow-local beta PW Fixer skill and verifies its SKILL.md before a repair pass.
• scripts/pw-maker-proposal.mjs: records a deterministic, project-local, review-only PW-Maker improvement proposal after a verified PW Fixer repair.
• scripts/pw-maker-lifecycle.mjs: unified registry-first entrypoint for recovery, legacy reconciliation, migration advice, and confirmed changes to existing workflows.
• scripts/workflow-git.mjs: project Git/GitHub setup plus requirement history, inspection, detached checkout, and traceable restore commands.
• scripts/record-requirement-revision.mjs: records user input and LLM requirement expansion as immutable authoring revisions.

Documentation Index

• references/authoring-meta-workflow.md: PW-Maker meta-workflow stages, prompts, schemas, .piflow/authoring/ artifacts, and runtime-gap schema contracts.
• references/generated-skeleton-files.md: generated project tree and detailed field guide for manifest.yaml, workflow.yaml, project.yaml, runtime-config.yaml, and package.json.
• references/provider-and-gate-registry.md: built-in agent providers, cloud providers, gate contract, and stage/unit YAML usage.
• references/pw-project-contract.md: required files, command contract, registry contract, Runtime Plan v2 contract, and packaging contract.
• references/runtime-scheduling.md: stage/unit boundaries, unit DAG, snapshots, stale-plan protection, and resume model.
• references/standalone-runtime-pattern.md: local command runner, logs, artifacts, process supervision, and hash gate.
• references/authoring-meta-workflow.md: also documents project-scoped requirement revisions and Git/GitHub recovery behavior.

Workflow Registration

New workflows default to:

~/piflow/workflows/<workflow-command>/

The command defaults to lowercase kebab-case derived from the workflow name and can be customized. Registry metadata is written to ~/.piflow/registry.json on macOS/Linux or %USERPROFILE%\.piflow\registry.json on Windows.

The confirmed workflow project directory is also the default source and Git worktree. PW-Maker initializes Git/GitHub there without asking a separate source-workspace question. Existing local repositories and remote clones are opt-in paths only when the user explicitly requests them.

Stage Validation Loop

For every implemented business Stage, PW-Maker runs and reports a relevant self-test before asking whether the user wants to provide supplemental test cases. User-supplied cases are saved to the workflow's test assets and must pass before the next Stage starts. If a required test fails, PW-Maker checkpoints the Stage as blocked, installs or reuses @piflow.org/pw-fixer@beta in that workflow project, reads its SKILL.md, follows its evidence-first repair process, and reruns the original checks. Install or skill-validation failures stay blocked; PW Fixer is a skill, not a CLI. The repair scope is the current Stage and indispensable dependencies only.

Once a repair and its original retest pass, PW-Maker writes a review-only proposal in .piflow/pw-maker/patches/ and an index.json. Each proposal has a deterministic fingerprint, redacted failure/repair summary, safe recommended targets (rules, templates, tests, or documentation), risk, and confidence. Duplicate repairs update the existing proposal’s occurrence count. A separately authorized review may set its status to accepted, rejected, or expired; that status update still does not apply the proposal. This record never edits PW-Maker, triggers installation or a commit, changes workflow completion, or exposes its contents in the global registry; only a pending count may appear there. Applying a proposal requires a separate explicit user request.

Cross-run artifact reuse

PW-Maker evaluates every Stage and Unit's inputs, outputs, external reads, side effects, credential risk, and determinism during design. The result is a project-local reuseAnalysis with one of reusable_verified, reusable_user_confirmed, run_only, prohibited, or awaiting_confirmation.

An unchanged URL is not evidence that its downloaded video or other resource is unchanged. If a resource is not fully provable, PW-Maker must show the user the resource, evidence, and risk, then wait for a choice: re-fetch every run, expected SHA-256, HTTP version metadata, or a user immutable-resource assertion. No answer blocks the current Stage/Unit design and makes the Runtime Plan non-runnable. Signed/credentialed URLs, external writes, time/random inputs, and unpinned agent outputs cannot use cross-run reuse.

The default cache.enabled remains run-local. Only a confirmed artifact contract may set cache.scope: project, which creates a content-addressed store below .piflow/cache/. Its key uses implementation/configuration, resolved input artifact, provider/tool/dependency, and approved external-resource identities; it excludes run IDs, timestamps, raw URLs, and secrets. Every hit verifies entry schema, object SHA-256, artifact contract, and configured external evidence before it materializes a separate artifact copy for the new run.

# normal run may use confirmed project cache entries
node bin/pw.mjs run --run-id report-002

# ignore all project cache reads and writes
node bin/pw.mjs run --run-id report-clean --no-cache

# rerun and atomically refresh confirmed cache entries
node bin/pw.mjs run --run-id report-refresh --refresh-cache

# inspect, verify, or prune project-local cache entries
node bin/pw.mjs cache status
node bin/pw.mjs cache verify
node bin/pw.mjs cache prune

Each run writes redacted cache evidence to .piflow/runs/<run-id>/audit/cache.json. Fresh-device acceptance excludes .piflow/cache/ and runs with --no-cache, so cached data cannot hide installation or execution failures.

Workflow Delivery Requirements

Before PW-Maker marks a workflow complete, its dedicated README author agent creates Chinese-default README.md and complete English README.en.md. Both link to each other and explain purpose, requirements, installation, quick starts, and detailed use of every workflow command. npm run setup first displays the full dependency plan; it only installs verified npm/pip/system-package actions after one confirmation, or after explicit --approve-installation-plan in non-interactive use. plan writes .piflow/runtime/dependency-report.json, grouping static Python imports, shutil.which()/subprocess commands, and cloud environment/CLI requirements. Missing required dependencies block the plan; optional or dynamic requirements are explicit warnings. Python delivery additionally requires python scripts/verify-clean-venv.py, which installs into a temporary clean .venv, runs pip check, checks imports, and removes the temporary environment.

Final delivery also requires a user-provided case under tests/acceptance/. npm run verify:fresh-device runs that case from a disposable clean project copy: it installs dependencies, plans and runs the workflow end to end, checks its final status and artifacts, supervises each command, and writes redacted project-local evidence. A failure remains blocked until PW Fixer repairs the confirmed workflow and the entire clean install-to-result flow passes again.

Proactively run fresh-device acceptance

Run this whenever you want to validate a completed workflow before delivery, or after changing its implementation:

cd ~/piflow/workflows/<workflow-command>
npm run verify:fresh-device

For a specific real acceptance case, create a safe project-local file such as tests/acceptance/my-e2e-case.json, then run:

node scripts/verify-fresh-device.mjs --case tests/acceptance/my-e2e-case.json

The case must use a relative fixture and describe the completed result and expected artifacts, for example:

{
  "schemaVersion": 1,
  "id": "daily-report-e2e",
  "inputPath": "examples/req.md",
  "expected": {
    "status": "completed",
    "artifacts": ["report.md"]
  },
  "timeoutMs": 120000
}

The verifier makes a disposable copy that excludes Git history, installed dependencies, prior runs, caches, and credentials. In that copy it runs the language-native installer, plan, a complete run --no-cache, status, and the declared artifact assertions. It always removes the temporary workspace and stores redacted evidence at .piflow/authoring/acceptance/latest.json. Do not put secrets, absolute or project-escaping paths, dynamic commands, or unconfirmed external side effects in an acceptance case.

When asking PW-Maker to trigger this flow, say for example: “对 daily-report 主动执行新设备端到端验收，使用 tests/acceptance/my-e2e-case.json。” PW-Maker checkpoints the verification boundary; on failure it delegates the confirmed workflow repair to its workflow-local PW Fixer, then restarts the entire acceptance flow from installation.

Interrupted Authoring Recovery

PW-Maker stores a small, redacted authoringState beside each registered workflow. It records the authoring stop point and never duplicates raw requirements or authoring artifacts. The project-local .piflow/authoring/ directory remains the full recovery source.

# list active, waiting, and blocked authoring flows, newest first
node scripts/authoring-state.mjs list

# inspect one checkpoint; this validates files but does not read artifacts or advance work
node scripts/authoring-state.mjs restore --command <workflow-command>

The skill uses these commands for requests such as “下一步” and “上次做到哪里了”. With multiple candidates it asks the user to choose; it always asks for confirmation before loading the selected project's authoring artifacts.

Existing Workflow Changes

Use the lifecycle entrypoint for a finished workflow that needs modification or a new feature:

node scripts/pw-maker-lifecycle.mjs overview
node scripts/pw-maker-lifecycle.mjs start-change --command <workflow-command> --title "<redacted change summary>"
node scripts/pw-maker-lifecycle.mjs start-change --command <workflow-command> --title "<redacted change summary>" --confirm

The first command is registry-only. The confirmed command requires a clean, committed Git worktree, then writes project-local impact, baseline, plan, validation, documentation-agent, documentation-sync, and review records under .piflow/authoring/changes/, plus a related plan under docs/plans/. Before implementation, the user confirms a validation selection drawn from target tests, plan validation, and fresh-device acceptance. Selected checks are required; failures use the existing PW Fixer loop. Every completed change must run its documentation agent prompt, align both localized README files and all affected configuration/contract documentation, and provide a current documentation-sync.json; missing, incomplete, or stale sync evidence blocks finish-change.

Every registered workflow now has a redacted step ledger for required, optional, and business-Stage validation work. It distinguishes blocked, executable required, executable optional, completed, and skipped items:

node scripts/authoring-state.mjs steps --command <workflow-command>

# discover and safely backfill older registered workflows that predate the ledger
node scripts/pw-maker-lifecycle.mjs reconcile --command <workflow-command>
node scripts/pw-maker-lifecycle.mjs reconcile --command <workflow-command> --confirm

# inspect version/migration state before confirmation; this does not read authoring artifacts
node scripts/pw-maker-lifecycle.mjs overview

# check the official NPM release and, after user confirmation, stage a managed Codex skill update
node scripts/pw-maker-update.mjs check
node scripts/pw-maker-update.mjs install --confirm --version <version>

Backfill only reads the selected project’s authoring artifacts and safe project files. It never treats missing evidence as completed work.

PW-Maker distinguishes package version from the authoring-state and step-definition revisions. A normal package patch does not create artificial workflow work. When an actual migration is needed, show the version and pending steps, obtain confirmation, then run upgrade-ledger. Official NPM installation is staged under the user-managed skill directory and requires a Codex reload/restart; a Git checkout or non-managed skill directory is never overwritten.

Requirement History

After registration, PW-Maker checks git, Git identity, and gh auth status. New projects default to a private GitHub repository; an existing repository or non-GitHub remote is never replaced. If authentication is missing, the user completes:

gh auth login -h github.com --web

Material requirement exchanges are saved under .piflow/authoring/requirements/, committed, and pushed. Git is the recovery mechanism:

node scripts/workflow-git.mjs history --project-root <workflow-root>
node scripts/workflow-git.mjs show --project-root <workflow-root> --ref <commit>
node scripts/workflow-git.mjs checkout --project-root <workflow-root> --ref <commit>
node scripts/workflow-git.mjs restore --project-root <workflow-root> --ref <commit>

checkout is detached and intended for inspection. restore restores only requirement artifacts and creates a new Git commit. Never place credentials, tokens, cookies, or private keys in a requirement record.

Local Verification

npm run check
npm test
npm run pack:dry-run

Use npm publish --dry-run for a final preflight when the debugging documentation is ready. Do not run npm publish until the package is intentionally released.