# Workflow Audit

> Use when auditing whether the repo-local workflow rooted at `docs/workflows/新项目开发工作流/` has same-version maintenance issues in workflow assets, install/embed flows, CLI-native adaptation, or post-install verification boundaries, including a user-approved patch-only stable version mismatch in the current run; do not use for ordinary business code, application features, or generic implementation review, and use `workflow-capability-audit` instead for broader Trellis version-drift or upgrade-compatibility audits.

- Skill: `starforall/workflow-audit` (Agent Skill, multi-file: 42 files)
- Install (CLI): `npx skillmds@latest add starforall/workflow-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starforall/workflow-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: starforall (https://skillmd.com/u/starforall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starforall/workflow-audit

---


# workflow-audit

> Repo-local maintainer skill contract for auditing workflow definitions and workflow embed/adaptation behavior.

---

## Purpose

`workflow-audit` exists to audit workflows themselves, not ordinary application code.

This skill covers:

- workflow source-asset maintenance for the workflow rooted at `docs/workflows/新项目开发工作流/`
- workflow install / embed / post-install validation
- CLI-native adaptation checks for Claude Code / OpenCode / Codex
- evidence-first validation of candidate workflow issues before any source edits

`workflow-audit` is not a generic selector for arbitrary entries under `docs/workflows/`.
Its only supported workflow target is `docs/workflows/新项目开发工作流/`.

It does not cover:

- ordinary business code review
- product feature auditing
- generic implementation quality review outside workflow definitions
- Trellis version-drift or compatibility-upgrade analysis across versions; use `workflow-capability-audit` for that path

## Version Gate and Supported Surface

`workflow-audit` is a same-version workflow-maintenance audit only, with one narrow user-approved exception for a patch-only stable mismatch.

Before any audit step, it must:

1. Read `COMPATIBLE_TRELLIS_VERSION` from `docs/workflows/新项目开发工作流/commands/workflow_assets.py`
2. Run `trellis -v`
3. Classify the version relationship using the rules below

For this contract, a `minor version mismatch` means all of the following:

- same `major`
- same `minor`
- different `patch`
- neither version carries a prerelease label such as `-rc` or `-beta`

Examples:

- `0.5.0` vs `0.5.5` = contract-defined `minor version mismatch`
- `0.5.0-rc.1` vs `0.5.0` = not a `minor version mismatch`
- `0.5.0-beta.1` vs `0.5.0` = not a `minor version mismatch`
- `0.5.0-rc.1` vs `0.5.0-rc.3` = not a `minor version mismatch`

Despite the field name, this contract term does **not** mean semver minor-number drift such as `0.5.x` vs `0.6.x`. It refers only to a same-`major.minor` stable `patch` difference.

Equivalent natural-language instructions are allowed only when they unambiguously limit the bypass to that same-`major.minor` stable `patch` difference. If the wording is ambiguous, treat it as `allow_minor_version_mismatch: no`.

If the versions match exactly:

- continue normally

If the versions are a `minor version mismatch` and the user explicitly set `allow_minor_version_mismatch: yes` or gave an equivalent natural-language instruction:

- continue normally
- report both versions and the user-approved gate bypass explicitly
- treat the bypass as run-local only; do not reinterpret it as compatibility approval
- do **not** continue by rewriting `COMPATIBLE_TRELLIS_VERSION`

If the versions differ in any other way, or the `minor version mismatch` was not explicitly allowed:

- stop immediately
- classify the stop as `Blocked / Version Drift`
- report both the compatible version and the actual version
- if the mismatch is the contract-defined `minor version mismatch`, also explain that the user may rerun with `allow_minor_version_mismatch: yes` for this audit run only
- otherwise direct the user to `workflow-capability-audit`
- do **not** continue into target resolution, A/B/C evidence gathering, task creation, `/tmp` project creation, `trellis init`, or embed/post-install validation

Supported workflow audit surface is limited to:

- `Claude Code`
- `OpenCode`
- `Codex`

That support limit applies to:

- per-CLI adaptation conclusions
- temporary target-project artifact checks
- hidden-directory scope during install/post-install verification

Repo-local directories for other CLIs or carriers are out of scope for `workflow-audit` unless the workflow's own managed-surface contract explicitly adds them in the future.

Currently excluded repo-local CLI directories and the reason:

- `.kiro/` — not part of the workflow's managed surface; skill deployment there is handled independently by Trellis, not by the workflow-audit contract
- `.qoder/` — same as above

These exclusions are a design decision, not a coverage gap. Extending the supported surface to include additional platforms requires an explicit update to `workflow_assets.py`'s managed-surface contract first; `workflow-audit` will then incorporate the new platform in the same change.

Note on `.opencode/`, `.codex/`, and `.agents/skills/`: these paths participate in the three-platform managed surface, but not all in the same way. `.agents/skills/` has a dual role: in this source repository it is the shared deployment layer for compatible skill loaders, while in workflow-installed target projects it is also the shared workflow skill carrier visible to Codex and potentially OpenCode. Its presence alone is therefore not a defect. For Codex, `.codex/config.toml` and `.codex/hooks.json` are primary carrier/config surfaces, while `.codex/skills/` remains a conditional secondary carrier rather than the default baseline artifact set. Codex hook activation is also runtime-gated by user-level enablement or approval, so installed carrier shape and live runtime activation must be audited separately. The absence of skill files under `.opencode/skills/workflow-audit/` or `.codex/skills/workflow-audit/` is therefore expected and not a defect.

Current execution policy for this skill:

- `workflow-audit` runs in the invoking CLI's main interactive session
- do not dispatch Claude Code or OpenCode agents/sub-agents to execute audit steps for this skill
- if runtime validation reaches the formal embed boundary, the audit must stop and require a human operator to run the remaining formal embed commands in an interactive system terminal
- this is a workflow execution-boundary contract, not a temporary efficiency preference

## Audit Coverage Requirements

This skill **must** fully validate the following aspects for any workflow under audit:

1. **Script-behavior consistency** - For every script referenced in workflow documentation (e.g., `detect-embed-state.py`, `install-workflow.py`, `upgrade-compat.py`), the audit must verify:
   - The script exists at the documented path
   - The script's actual behavior (via static analysis or runtime) matches documented claims
   - Exit codes and output format are machine-parseable if the workflow depends on them
   - Required environment-variable contracts are still honored. In particular, `install-workflow.py` must continue to refuse formal install unless `WORKFLOW_EMBED_HUMAN_CONFIRMED=1` is set, and formal install must remain gated to a human-operated interactive system terminal

2. **CLI adaptation completeness** - For each supported CLI (Claude Code, OpenCode, Codex), the audit must confirm:
   - All workflow commands/skills/agents are correctly mapped to the CLI's native location
   - No CLI-specific behavior drifts exist for the same semantic action
   - Missing or incomplete adaptations are flagged as `present-but-incompatible` or `missing-but-valuable`
   - Native-adaptation conclusions must combine:
     - the latest official CLI documentation available at audit time
     - repo-local validated evidence from this workflow authoring repository
     - actual development-use evidence: the real maintainer/operator path, runtime gating behavior, and which carriers are primary vs conditional in day-to-day use
   - The audit must not judge native adaptation from memory alone, or from carrier-file presence/absence alone

3. **Post-install artifact verification** - The audit must compare documented installation artifacts against actual files created in the target project, separating the clean `trellis init` baseline from the workflow-installed state after `install-workflow.py`, including:
   - Hidden directories (`.trellis/`, `.claude/`, `.opencode/`, `.agents/`, `.codex/`)
   - `.agents/skills/` must be interpreted with its dual role in mind: repo-local shared deployment layer in this source repo, shared workflow skill carrier in target projects
   - Command scripts, skill definitions, agent configurations
   - The audit must report discrepancies as confirmed issues with source-layer tags
   - Generated target-project files may only be attributed to the workflow after that baseline-vs-installed comparison
   - Do not classify the absence of source-repo authoring tests (for example `test_workflow_state.py`) inside the generated target project as a defect by itself; those tests belong to the authoring repository, while target-project runtime validation should be performed via source-repo fixture tests and explicit runtime command checks

   Special interpretation rule:
   - install-only low-stakes reminder artifacts such as the workflow-created root `todo.txt` are **not** defects by default
   - if such an artifact is documented as “does not change stage gates / command routing / runtime closure,” the audit must not classify its existence alone as over-management, corruption, or drift without stronger contradictory evidence
   - such artifacts may still be mentioned as contextual outputs, but they are not mandatory managed-surface failures in the same class as hidden-directory carriers, command copies, helper scripts, or routing blocks

4. **Human-terminal boundary** - When runtime validation reaches the formal embed step, the skill must:
   - stop and emit the dedicated human-terminal-required block
   - require a human operator to execute the remaining formal embed commands in an interactive system terminal
   - require the returned terminal transcript and key command outputs to be merged back into the audit report before any final runtime conclusion

5. **Runtime validation triggers** - The audit must automatically escalate to runtime validation (task-based runtime mode) when:
   - Any of the above checks cannot be conclusively resolved via static analysis
   - The workflow documentation or scripts contain conditional logic based on the environment
   - The user explicitly requests `/tmp` validation or human-terminal-boundary testing

6. **Change-worthiness and negative-optimization guardrail** - The audit must separate real defects from non-defect differences:
   - Do not classify a path as change-worthy merely because another arrangement seems cleaner or more uniform
   - Do not recommend optimization when the current state is evidence-backed, intentionally scoped, and does not break behavior, closure, or maintainability
   - If the latest official docs, repo-local evidence, and actual development-use evidence all support the current state, record the item as a false alarm / non-defect rather than manufacturing a fix
   - When a candidate issue turns out to be non-defective, ignore it rather than turning it into a low-value optimization target
   - The default threat model is **ordinary personal use / honest operator behavior**, not adversarial bypass analysis
   - If a problem appears only after deliberate file tampering, forged state, or intentional bypass of the documented command/routing constraints, and the ordinary supported path does not trigger it, do not classify it as a workflow defect by default
   - Escalate such cases only when the user explicitly asks for adversarial / security / bypass analysis, or when the workflow contract itself already claims resistance to that class of misuse

7. **Task-level vs project-level gate distinction** - When auditing workflow closure logic:
   - Treat task-level `check` and project-level `project-audit` as separate dimensions, not as two names for the same carrier
   - Do not misclassify "delivery requires both the current active task's `check.md` and the formal `PROJECT-AUDIT` carrier" as carrier conflation; that is the intended dual-gate model when project-level audit is declared
   - A real defect exists only when the workflow asks the wrong artifact to prove the wrong dimension, or when transition-time and validation-time gates disagree about which dual-gate evidence is required
   - If a dedicated `PROJECT-AUDIT` task exists, the audit must distinguish:
     - whether the workflow correctly treats that task as the formal project-level carrier
     - whether the workflow still separately requires the current active task's task-level `check`
   - If the workflow leaves project-level `project-audit` to re-enter task-level `check` or `review-gate`, the audit must verify the handoff model explicitly:
     - whether the workflow switches back to the task named by `task_level_check_task` before entering the task-level stage
     - whether the workflow blocks or warns against entering a task-level gate directly on the project-level `PROJECT-AUDIT` carrier when the carrier is not the task-level owner
   - Under the current strong-gate single-active-task model, an explicit `task.py start <task-dir>` handoff may be the correct boundary behavior rather than a defect by itself
   - Do not report "project-audit cannot directly become review-gate/check on the same carrier" as a defect by itself; that restriction is often the correct enforcement of the dimension boundary
   - The real defect in that area is missing or contradictory handoff semantics between the project-level carrier and the task-level owner
   - Findings that complain only that both dimensions are required at once, without showing a dimension mismatch or gate inconsistency, are false alarms

Each confirmed issue in the audit report must include a validation action that describes how the issue was detected. The detailed schema lives in `## Report Contracts`.

---

## Trigger Conditions

Use `workflow-audit` when the user wants to:

- audit or verify the maintained workflow rooted at `docs/workflows/新项目开发工作流/`
- confirm whether workflow issues are real before changing source files
- validate workflow embed/install behavior against a `/tmp + trellis init` baseline
- verify CLI adaptation or formal-embed human-terminal boundaries

When a temp-project workflow issue reappears after one or more scan/repair
rounds, use the repo-level
`guides/workflow-repeat-issue-triage.md` first to decide whether the current
branch is same-lineage same-family recurrence, a new family on the same
lineage, or a version-drift path.

Do not use it for normal code review or ordinary product implementation tasks.
Do not use it to determine whether a newer or older Trellis version is compatible with the workflow; that is `workflow-capability-audit`.

---

## Input Contract

Natural language is allowed, but the recommended contract is:

- `workflow_path`
  - only supported value: `docs/workflows/新项目开发工作流/`
  - when omitted, resolve it to `docs/workflows/新项目开发工作流/`
  - natural-language requests such as "audit this workflow" or "check the workflow" must bind to the same fixed workflow root
  - must resolve to exactly one workflow root, and that root must be `docs/workflows/新项目开发工作流/`
- `candidate_issues`
  - default: empty, meaning the skill discovers issues proactively through the full evidence mainline
  - when supplied: supplementary focus points injected into each evidence step; the evidence mainline still executes in full regardless
  - always treated as hypotheses, never as confirmed defects
  - does not switch execution paths
- `need_runtime_validation`
  - default: `auto`
- `force_full_brainstorm`
  - default: `no`
- `allow_minor_version_mismatch`
  - default: `no`
  - `yes` allows Step 0 to continue only for the contract-defined `minor version mismatch` above
  - it never allows prerelease-related mismatches or broader version drift
  - despite the name, it does **not** mean semver minor-number drift
  - if the field form is not used and the wording is ambiguous about the patch-only stable scope, treat it as `no`
- `current_cli`
  - infer from runtime when possible
  - ask the user only if a CLI-sensitive path is reached and ambiguity remains
  - if provided explicitly, it must be one of: `claude`, `opencode`, `codex`

The contract intentionally omits any AI-CLI takeover preference field for formal embed continuation.
Once the audit reaches the formal embed boundary, the only supported continuation is a human operator running the shell command chain in an interactive system terminal.

If multiple workflow targets are supplied in one request, the skill must stop, explain that it supports only `docs/workflows/新项目开发工作流/`, and require the user to continue with that single supported root only.

If the resolved `workflow_path` is anything other than `docs/workflows/新项目开发工作流/`:

- stop immediately
- classify the stop as `Blocked / Invalid Input`
- explain that this skill audits only `docs/workflows/新项目开发工作流/`
- do not silently replace the requested target with the supported root

If the supported `docs/workflows/新项目开发工作流/` root does not exist on disk:

- stop immediately
- classify the stop as `Blocked / Invalid Input`
- explain that the supported workflow root is missing from the repository checkout
- do not continue until the repository state is repaired

---

## Evidence Mainline

A, B, C always execute in order, regardless of whether `candidate_issues` are supplied. `candidate_issues` serve as supplementary focus points referenced within each step — they do not change the mainline.

D (Runtime Validation) is conditional, determined by findings from A/B/C and input parameters.
E (Output Findings) always executes as the final report step.

### Step Naming Map

The workflow may refer to the same control flow with either evidence-step labels or numbered step labels. Treat the following names as equivalent:

- `Target Resolution and Binding` = `Step 1`
- `A. Understand Target System Mechanics` = `Step 2a`
- `B. Static Evidence Gathering` = `Step 2b`
- `C. Structured Gap Analysis` = `Step 2c`
- `D. Runtime Validation` = `Step 5`
- `E. Output Findings` = `Step 6`

`Step 3` and `Step 4` are orchestration stages between `C` and `D`/`E`:

- `Step 3` decides lightweight vs task-based execution mode
- `Step 4` creates task context and enters `trellis-brainstorm` when the task-based path is chosen

They do not replace or rename the evidence-mainline labels above.

Three execution modes determine which evidence steps run and how findings are delivered:

| Mode | Steps | Task | trellis-brainstorm | prd.md | audit-report.md |
|------|-------|------|------------|--------|-----------------|
| Lightweight static | A, B, C, E | N | N | N | N |
| Task-based static | A, B, C, E (D skipped) | Y | Y | Y | Y |
| Task-based runtime | A, B, C, D, E | Y | Y | Y | Y |

Mode selection is described in the Execution Modes section below.

Every piece of evidence collected throughout the mainline must be tagged with its source layer:

- `source repo` — files, documents, scripts within the workflow directory under `docs/workflows/`
- `generated target project` — files inside the `/tmp` target project, including the clean `trellis init` baseline and the workflow-installed state after `install-workflow.py`
- `runtime command output` — stdout/stderr/exit code from executed commands

This labeling is mandatory because the core audit operation (gap analysis) compares what the source repo declares against what the target project actually contains. Without source-layer tags, the two are easily conflated.

Within the `generated target project` layer, the audit must explicitly distinguish whether evidence came from the clean `trellis init` baseline or from the post-install workflow state. The comparison model is:

- `source repo`
- `generated target project` baseline (`trellis init`)
- `generated target project` workflow-installed state (`install-workflow.py`)
- `runtime command output`

Per-CLI adaptation conclusions follow this scope rule:

- the section is in scope when the audit examines CLI-specific carrier mapping, adaptation drift, CLI-specific installed artifacts, or the formal-embed human-terminal boundary
- lightweight output should still keep the section even when CLI adaptation is not in scope; in that case, mark each CLI entry as `not-applicable` with a brief reason instead of omitting the section
- if a CLI entry is `not-applicable`, a brief reason is sufficient; do not force the detailed evidence trio fields for that CLI
- when official docs, repo-local evidence, and practical development-use evidence disagree, record the disagreement explicitly instead of silently choosing one source as the winner

### Step 0: Version preflight

Before target resolution or evidence gathering:

- read `COMPATIBLE_TRELLIS_VERSION` from `docs/workflows/新项目开发工作流/commands/workflow_assets.py`
- run `trellis -v`
- classify the version relationship:
  - exact match -> continue
  - contract-defined `minor version mismatch` + explicit `allow_minor_version_mismatch: yes` (or equivalent, unambiguous natural-language instruction) -> continue and record the bypass explicitly
  - anything else -> stop as `Blocked / Version Drift`
- if the field form is not used and the wording is ambiguous about the patch-only stable scope, treat it as `allow_minor_version_mismatch: no`

If the audit stops for version drift:

- report both values explicitly
- if the mismatch is the contract-defined `minor version mismatch`, explain that the user may rerun with `allow_minor_version_mismatch: yes` for this run only
- otherwise recommend `workflow-capability-audit`
- do not proceed to Step 1 or any later step

### Target Resolution and Binding

Before step A begins:

- resolve exactly one workflow target
- if `workflow_path` is omitted, or the user says "this workflow" / "the workflow" without naming another path, bind the target to `docs/workflows/新项目开发工作流/`
- if the resolved target is anything other than `docs/workflows/新项目开发工作流/`, stop as `Blocked / Invalid Input`
- do not treat the current repo root, active task directory, or temporary target-project root as the workflow target
- record the resolved workflow root explicitly in the output/report target section

### A. Understand Target System Mechanics

Before auditing the workflow, understand the system it operates within:

- fixed audit target root: `docs/workflows/新项目开发工作流/`
- current workflow authority for managed surfaces: `docs/workflows/新项目开发工作流/commands/workflow_assets.py`
- current CLI boundary contract: `docs/workflows/新项目开发工作流/CLI原生适配边界矩阵.md`
- current hidden-directory / managed-boundary contract: `docs/workflows/新项目开发工作流/装后隐藏目录与托管边界核对清单.md`
- `.trellis/` is the runtime truth layer for workflow, task, and session state
- active-task resolution is session-scoped under `.trellis/.runtime/sessions/`, not a repo-global `.trellis/.current-task`
- hidden platform directories (`.claude/`, `.opencode/`, `.codex/`, `.agents/`) are carrier layers with platform-specific loading models, not equal authorities to `.trellis/`
- when CLI-native adaptation is in scope, the latest official docs for Claude Code / OpenCode / Codex are part of the authoritative mechanics set, not optional background reading
- trellis `init` baseline carrier set: `.trellis/`, `.claude/`, `.opencode/`, `.agents/skills/`, `.codex/`
- `.agents/skills/` 双角色：在当前 source repo 中是 shared deployment layer，在 workflow-installed target project 中是 shared workflow skill carrier；presence alone is not a defect
- OpenCode carrier model: plugin-driven context loading plus native command/agent carriers; adaptation checks must account for both halves
- Codex carrier model: `.codex/config.toml` / `.codex/hooks.json` are primary carrier/config surfaces; `.codex/skills/` is a conditional secondary carrier, not a default baseline artifact
- Codex hook execution is runtime-gated by local enablement or approval, so installed carrier shape and live activation are separate audit questions
- 各 CLI 的原生承载方式（commands / skills / agents / hooks 的目录约定）
- 各 CLI 在实际开发使用中的主路径、条件路径、运行时 gating，以及“目录存在”与“真实可用”之间的区别
- workflow 自身的 install / upgrade / uninstall 脚本实际行为
- 工作流嵌入执行规范中的状态机与前置条件
- current repo root, active task directory, and temporary target-project root are context inputs, not substitute audit targets
- generated target-project evidence is about the temporary target project created for the audit, not this source repository's own hidden directories
- generated target-project evidence must distinguish the clean `trellis init` baseline from the workflow-installed state after `install-workflow.py`

### B. Static Evidence Gathering

Read authoritative entry documents and indexes first, then trace references outward:

- bind default static reading scope to `docs/workflows/新项目开发工作流/` and files it references; do not treat the repo root as the primary audit target
- catalog every claim the workflow makes: steps, artifacts, boundaries, contracts
- note every referenced file path, script, template
- identify every cross-reference dependency
- cross-check referenced paths against actual filesystem
- for scripts that gate later workflow behavior, verify the documented exit-code and output-shape contract from static evidence first
- when per-CLI adaptation is being judged, fetch and compare the latest official docs for Claude Code / OpenCode / Codex against repo-local evidence before concluding compatibility
- capture practical-use evidence for each CLI when needed: which path maintainers actually rely on, which carrier is primary, which carrier is conditional, and which runtime gate decides live behavior
- practical development-use evidence should prefer inspectable artifacts when possible: the CLI boundary matrix, platform READMEs, live carrier/config files, runtime gate definitions, and if Step D runs, command transcripts or runtime observations

### C. Structured Gap Analysis

Compare document claims against actual definition completeness:

- 文档声明了某步骤 / 产物 / 边界，但对应定义文件缺失或不完整 → 确认为 gap
- 流程层面"有"但执行闭环层面"没做完"的内容 → 记录为 incomplete closure
- 跨文档引用的一致性：是否引用了不存在的文件、旧路径、或已过时的路径名
- 各 CLI 适配层之间是否存在行为漂移（同一语义在不同 CLI 下实现不一致）
- CLI 适配缺口必须归类为 `present-but-incompatible` 或 `missing-but-valuable`
- `.agents/skills/` presence alone is not a defect; only contradictory managed-surface behavior or misleading duplicate exposure counts as a workflow issue
- `.codex/skills/` 缺失默认不算 defect，除非当前 managed-surface contract 明确要求这个 secondary carrier
- 结合“最新官方文档 + repo-local 证据 + 实际开发使用视角”判断每个 CLI 的原生适配结论；禁止只凭记忆或静态目录存在性下结论
- 当三源证据冲突时：runtime observation 只决定“当前实际观察到的行为”；repo-local evidence 决定“当前 workflow 的声明/实现”；官方文档决定“当前上游文档契约”
- 若三源冲突仍不能证明真实缺陷，则保守落到 `Evidence Gap` / `Needs Clarification`，而不是直接生成 confirmed issue；若冲突更像上游 CLI capability drift，则提示转到 `workflow-capability-audit`
- 对“看起来可以更统一/更干净”的点，先判断是否真是缺陷；不是缺陷的就忽略，不得做负面优化
- 明确的人类/维护者意图可以作为解释差异为何存在的上下文，但意图本身不会自动把 non-defect 变成 defect；除非用户明确要求设计变更，否则不要把这类差异升级成 confirmed issue 或默认修复方向
- 默认只按**正常使用 / 诚实使用路径**判断真实缺陷，不把刻意篡改文件、伪造状态、故意绕过命令约束后才出现的问题，直接升级成 confirmed issue
- 隐藏目录托管边界：安装后产物是否与 trellis 基线 + workflow 声明的托管范围一致
- `generated target project` 证据必须区分 clean `trellis init` baseline 与 workflow-installed state；不得把 baseline 自带产物直接归因给 workflow
- 不得把 repo-local 的其他平台隐藏目录直接当作当前 workflow 缺失适配的证据；除非 `workflow_assets.py` 明确把它们纳入 managed surface

### D. Runtime Validation

Required when embed / install / post-install behavior must be verified:

- confirm the temporary target project's `.trellis/.version` matches the Step 0 actual `trellis -v` result; otherwise stop as `Blocked / Version Drift`
- this runtime check is independent from the Step 0 `COMPATIBLE_TRELLIS_VERSION` gate; it verifies that the temporary baseline project was initialized by the same current runtime version, even if Step 0 used an allowed bypass
- 在 `/tmp` 创建纯净 Git 项目，满足安装前置条件后执行 `trellis init`
- 在 `trellis init` 完成后、执行 `install-workflow.py` 前，记录当前文件系统状态作为 clean baseline 快照；后续 post-install 比较与产物归因必须以该快照为基准
- 到达嵌入执行边界时，不再由 audit 自身继续执行任何嵌入命令；必须停止并把完整 shell 命令链交给人类操作者手动执行
- 检查安装后隐藏目录（`.trellis/`, `.claude/`, `.opencode/`, `.agents/`, `.codex/`）与 baseline 快照 + workflow 托管声明是否一致
- 比较文档声明的安装产物与实际落盘产物
- 如果 Step D 在 baseline 快照已捕获后失败，保留该 baseline 证据，并将后续 installed state 标记为 incomplete / unverified，禁止把未完成安装状态当作完整 workflow-installed 结论
- 当运行时验证到达正式嵌入边界时，停止并要求人类终端 transcript（见 CLI and Handoff Rules）

### E. Output Findings

Classify every finding:

- confirmed issues: P0 / P1 / P2 with full confirmed-issue schema
- unconfirmed items / false alarms
- blocked items: Blocked / Evidence Gap / Needs Clarification

Blind guessing is forbidden. If critical branches remain unresolved, partial conclusions are allowed only when blocked branches are explicitly labeled.

---

## Execution Modes

Mode is not a pre-decision made at input time. It is the outcome of evidence mainline steps A, B, and C. Steps A, B, and C always execute regardless of mode.

After step C, two independent judgments determine the execution mode:

**Judgment 1 — Taskify?** Should the audit create a task, enter trellis-brainstorm, and maintain `prd.md` + `audit-report.md`?

- `force_full_brainstorm: yes` → yes: enter task-based path
- `need_runtime_validation: yes` → yes: enter task-based path (D needed, which always requires task context)
- `need_runtime_validation: auto` AND Step 2 findings indicate D trigger conditions are met → yes
- Otherwise → no: lightweight static mode (skip to step E directly)

**Judgment 2 — Execute D?** (Only meaningful if the answer to Judgment 1 is "yes")

Step D is required when any of these are true:

- `/tmp` temporary project validation is needed
- `trellis init` must be executed
- embed/install/post-install behavior must be verified
- human-terminal boundary may be triggered
- `need_runtime_validation` is `yes`

`force_full_brainstorm: yes` does NOT by itself force Step D. D must be justified by one of the conditions above.

When neither Judgment 1's conditions nor D-trigger conditions are met: lightweight static mode.
When Judgment 1 is "yes" but D is not needed: task-based static mode (create task, enter trellis-brainstorm, maintain `prd.md` and `audit-report.md`, then skip D and go to E).
When both judgments are "yes": task-based runtime mode (create task, enter trellis-brainstorm, maintain `prd.md` and `audit-report.md`, execute D, then output E).

### Lightweight static mode

- does not create a task
- does not create `prd.md`
- does not create `audit-report.md`
- outputs using the simplified chat structure from `references/lightweight-output-template.md`

### Task-based static mode

When the skill determines task context is warranted but runtime validation is not required:

- create audit task context (child task if another non-audit task is active, otherwise top-level)
- resolve active-task state from the current session-scoped Trellis runtime; do not assume a repo-global active-task marker
- enter the `trellis-brainstorm` mainline explicitly as the control container
- create and maintain `prd.md` through the `trellis-brainstorm` path
- maintain `audit-report.md` using `references/audit-report-template.md`
- seed `audit-report.md` with findings from steps A/B/C already collected
- skip step D → proceed to step E (report via `audit-report.md`)
- may use `grill-me` as a conditional clarification submode
- stop with a controlled next-step recommendation

### Task-based runtime mode

When the skill determines both task context and runtime validation are required:

- all task-based static mode behaviors above, plus:
- execute step D only up to the pre-embed boundary: `/tmp` project creation, `trellis init`, baseline snapshot, and evidence needed to prepare the manual shell command block
- merge runtime evidence into `audit-report.md`
- when D reaches the embed-execution boundary: emit the human-terminal-required block with the full manual shell command chain and stop (see CLI and Handoff Rules)
- output step E via `audit-report.md`
- stop with a controlled next-step recommendation

If `/tmp` project creation, `trellis init`, or any required runtime-validation command fails before step D completes:

- stop immediately
- classify the stop as `Blocked / Runtime Execution Failure`
- record the failing command, exit status, key stdout/stderr evidence, and what remains unverified

### Mode transition boundary

When transitioning from step C to a task-based mode:

1. explain the rationale for the chosen mode
2. if entering task-based static: explain why task context is warranted and why D is not needed
3. if entering task-based runtime: explain why runtime validation is necessary
4. proceed to create task context and enter trellis-brainstorm
5. seed `audit-report.md` with already-collected evidence from steps A/B/C

Never switch modes silently. Never discard A/B/C findings when entering a task-based mode.

If task-based mode is chosen but the required `trellis-brainstorm` entrypoint for the current CLI is unavailable:

- stop immediately
- classify the stop as `Blocked / Dependency Unavailable`
- preserve the already-collected A/B/C evidence
- do not silently fall back to lightweight mode

### User-set `need_runtime_validation: no` conflict

When the user explicitly set `need_runtime_validation: no` but step C findings conclusively demonstrate that runtime validation is necessary (D trigger conditions are met):

- do NOT silently skip D
- output a Needs Confirmation block using `references/needs-confirmation-template.md`
- let the user decide whether to override their original setting
- do not proceed to D without explicit user confirmation

---

## Task Model

All task references in this section are resolved from the current session-scoped Trellis runtime, not from a repo-global active-task file.

### Task-based Audit with Existing Active Non-audit Task

- create a dedicated child audit task
- switch execution into that child task immediately

### Task-based Audit with No Active Task

- create a new top-level audit task

### Task Naming

Default title:

`workflow-audit: <workflow-name>`

### Child Audit Task Completion

A child audit task is not complete when the audit report is merely produced.

It becomes complete only after:

1. audit conclusion has been produced
2. user has confirmed the conclusion
3. remediation work driven by that conclusion is completed
4. the human confirms the child task is complete

Only then may execution return to the parent task.

### Remediation Splitting

Inside a top-level or child audit task:

- ordinary remediation stays in the same audit task by default
- create implementation subtasks only when the repair scope is genuinely complex

`workflow-audit` itself does not own remediation execution. It stops at the audit-conclusion boundary; later normal phases/skills handle the repair work in the same audit task.

---

## Report Contracts

### Lightweight Static Output

Use the simplified structure from `references/lightweight-output-template.md`.

### Task-based Audit Report

Maintain `audit-report.md` in the task directory. This applies to both task-based static and task-based runtime modes.

Rules:

- filename is fixed: `audit-report.md`
- update incrementally during the active audit
- treat the same file as the current finalized report at the stop-and-confirm boundary
- require it only for task-based audits
- record `Compatible Anchor Version`, `Current Trellis Version`, and `Version Gate` (`passed` or `bypassed`) in the audit boundary section
- when `Version Gate` is `bypassed`, also record `Bypass Detail` with the user-approved reason and the run-local-only disclaimer
- when evidence is tagged as `generated target project`, record whether it came from the clean `trellis init` baseline or the workflow-installed state after `install-workflow.py`
- when per-CLI adaptation is judged, record for each CLI:
  - the official-doc source checked
  - the repo-local evidence checked
  - the practical development-use evidence checked
  - whether these sources agree or where they differ

### Confirmed-Issue Schema

Every confirmed issue must include:

- priority (`P0` / `P1` / `P2`)
- conclusion
- evidence source (with source layer tag: `source repo` / `generated target project` / `runtime command output`)
  - when the layer is `generated target project`, include `Stage` as `baseline after trellis init` or `workflow-installed state after install-workflow.py`
- validation action
- impact scope
- fix direction

The audit must not emit a confirmed issue or fix direction for a non-defect “optimization” idea unless evidence shows real behavioral, closure, or maintainability harm. Evidence-backed non-defects belong in `Unconfirmed Items / False Alarms`, not in `Confirmed Issues`.

#### Priority Rubric

Use the following rubric to assign `P0` / `P1` / `P2` consistently. When in doubt between two levels, pick the more severe one and explain the borderline case in the issue conclusion.

- `P0` — blocks workflow execution, install, or audit itself
  - the workflow cannot finish a documented step under any supported CLI
  - install / embed / upgrade scripts crash, exit with an undocumented non-zero status, or silently corrupt state
  - a security or boundary contract is broken (e.g., `install-workflow.py` no longer enforces `WORKFLOW_EMBED_HUMAN_CONFIRMED` and human-terminal confirmation for formal install)
  - documented post-install artifact is entirely missing
- `P1` — drift with real behavioral impact, but a workaround or partial path exists
  - documented behavior diverges from actual script behavior in a way an auditor or operator would notice (exit code shape, output schema, side-effect ordering)
  - one CLI's adaptation is materially incomplete or behaviorally inconsistent with the other CLIs for the same semantic action
  - cross-document references point at moved/renamed files but a manual workaround still works
- `P2` — surface-level inconsistency, no behavioral impact
  - wording, naming, or label drift between docs that does not change runtime behavior
  - non-breaking documentation gaps that do not mislead an auditor about behavior
  - cosmetic or formatting issues in templates that still render and parse correctly

A finding that requires runtime validation to confirm severity must stay in the Blocked / Evidence Gap section until D is run, rather than be guessed into a P-level.

### Blocked-State Rules

If some critical branches remain unresolved, partial confirmed conclusions are allowed only when blocked branches are explicitly labeled as:

- `Blocked`
- `Evidence Gap`
- `Needs Clarification`

Blind guessing is forbidden.

This partial-findings blocked-item set is distinct from hard-stop exit classifications such as:

- `Blocked / Version Drift`
- `Blocked / Invalid Input`
- `Blocked / Dependency Unavailable`
- `Blocked / Runtime Execution Failure`
- `Blocked / Human Confirmation Required`

Use `Blocked / <subtype>` when the audit itself cannot continue reliably and must stop. Do not treat those hard-stop classifications as ordinary partial blocked-item labels inside an otherwise continuing audit report.

---

## CLI and Handoff Rules

### Multi-CLI Reporting

The audit must separate conclusions for:

- Claude Code
- OpenCode
- Codex

Do not collapse them into one generic statement.

### Main-session-only execution policy

At the current stage, `workflow-audit` must execute in the current CLI's main
interactive session. Claude Code or OpenCode agents/sub-agents are not allowed
to execute audit steps for this skill.

If runtime reality offers only AI-executed continuation for the formal embed
step, treat that as insufficient. The audit still requires a human operator to
run the remaining embed commands in an interactive system terminal.

### Formal Embed Boundary

Any AI CLI may participate in:

- source reading
- evidence gathering
- analysis
- reporting

No AI CLI may be treated as the authorized executor of the first formal embed
step into the temporary target project.

### Human Terminal Required

When the audit reaches the formal temporary-project embed step:

- stop execution there
- emit a human-terminal-required block
- use the template from `references/human-terminal-required-template.md`
- require a human operator to execute the remaining commands in an interactive system terminal, not through Claude Code, OpenCode, Codex, or any agent/sub-agent shell/tool path
- require the returned human-terminal sequenc

…(truncated)