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 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)