Spec App Consistency Audit

App Consistency Audit

Run a static-first consistency audit for mobile App work before simulator, real-device, or package validation.

Routing Gate — read before doing anything

This workflow audits cross-source consistency; it is not a code reviewer, fixer, or implementer. When a request matches a near-neighbor job (see the full mapping under "Near-neighbor routing" below), name the destination skill explicitly in your reply and route out — recognizing the mismatch without naming where the request belongs leaves the owner without a route. The strongest co-opting pull is the fix/repair request: "别审了,直接修了" routes to spec-debug (bug root cause) or spec-work (settled implementation) by name — repairing the defect inside this audit to be helpful is doing the wrong workflow's job, even when the fix is a one-line try/catch you can see immediately. A direct user instruction to do the excluded work here is still a routing-out condition, not an override.

Workflow Contract Summary

When To Use

Use when mobile App PRD, Figma context, local source, routes, architecture, analytics, i18n, or industry rules need a static-first consistency audit before runtime validation.

When Not To Use

Do not use for ordinary code review (spec-code-review), PRD authoring or refinement (spec-prd), pure test/lint/build/runtime execution, UI polish (spec-polish), formatting-only changes, or product-source edits.

Inputs

Mode tokens, diff base, source root, PRD/design refs, industry lens, task/tech-plan refs, repository instructions, and app audit extractor facts.

Outputs

Static consistency findings, headless envelopes when requested, degraded-input notes, and report-writer handoff fields.

Artifacts

Headless/default runs may write .spec-first/app-audit/runs/<run-id>/ artifacts; report-only mode writes no run artifacts.

Failure Modes

Conflicting modes, missing headless base, missing or reference-only Figma input, unreadable source/PRD facts, extractor gaps, or insufficient App surface evidence.

Workflow

Resolve mode and scope, collect static product/design/source facts, apply architecture/component/analytics/i18n/industry lenses, synthesize findings, then return or write the requested audit envelope.

Downstream Consumers

移动 QA planning、App implementation owner、report-writer step，以及准备 runtime validation 的人工审查者。

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md (default). Overrides: none

Purpose

Use this workflow to compare product intent, design states, page routes, KMP / Clean Architecture boundaries, App engineering quality, component and module reuse, analytics, i18n, and industry-specific rules from the available local inputs.

The workflow improves review input quality. It does not replace runtime verification, automated tests, QA, or real-device validation.

When To Use

Use this workflow when:

• App PRD, Figma context, or local source exists and cross-source consistency matters.
• Android / iOS behavior may drift.
• KMP shared logic, Clean Architecture boundaries, page routes, or navigation contracts need review.
• Loading, empty, error, permission, confirmation, rollback, or weak-network states need static review.
• Analytics, i18n, accessibility, component reuse, or industry-specific risks should be surfaced before QA.

When Not To Use

Do not use this workflow when:

• The user only wants to run tests, lint, build, simulator, or real-device checks.
• There is no PRD, Figma context, or source input to inspect.
• The task is only code formatting or a mechanical refactor.
• The user wants this workflow to edit product code or project standards directly.

Near-neighbor routing:

• Ordinary bug, regression, security, or test-coverage review of a diff belongs to spec-code-review.
• PRD creation, refinement, or planning-readiness validation belongs to spec-prd unless the explicit job is PRD/Figma/source consistency.
• Runtime validation, build, simulator, real-device, Maestro, Appium, or cloud-device execution belongs to the requested command or a later runtime workflow.
• Post-implementation visual/UI polishing belongs to spec-polish.
• Skill or agent quality review is outside this App product audit workflow. Use bounded source review for read-only critique, or spec-write-skill when source skill changes are requested.

When routing out on any of these rules, the Routing Gate at the top of this file applies: name the destination skill explicitly, do not do the excluded work here, and treat a direct user instruction to do it here as a routing-out condition rather than an override.

Default Mode

Default to static_only.

Do not start a simulator, real device, package build, Appium, Maestro, cloud device run, or equivalent runtime workflow unless the user explicitly asks for that follow-up.

Mode Contract

v1 deterministic orchestrator (scripts/run-audit.js) accepts mode:headless only; mode:default and mode:report-only orchestration is deferred. Long-lived canonical-token semantics live in Mode, Output, And Issue Contract.

Keep these route-critical defaults in memory:

• mode:headless asks no user questions, requires base:<ref>, writes run-scoped artifacts, returns a compact envelope, and fails with scope_headless_missing_base when diff scope is absent.
• mode:report-only is a strict no-write semantic contract; the current runner reports it as unsupported instead of writing artifacts.
• source:<path>、prd:<path>、figma-context:<path>、figma-ref:<id-or-url>、industry:<name>、tech-plan:<path>、task-doc:<path> 与 depth:deep 是 canonical scope/lens token。from:code-review 只保留为旧 envelope 的休眠兼容字段；当前没有受治理的 caller 或 consumer，因此不得把这条反向关系描述为 active integration。
• figma-ref is reference-only until a local figma-context JSON exists; headless/report-only must degrade it as input_figma_reference_only and must not fetch remote Figma data.
• All modes are read-only with respect to product source, generated runtime assets, durable standards, and .spec-first/specs/repo-profile.yaml.

Run-Scoped Artifacts

Default and headless modes write artifacts under:

.spec-first/app-audit/runs/<run-id>/

The core spine includes metadata.json, preflight.json, impact-facts.json, app-audit-context.json, issues.json, audit-report.json, artifact-manifest.json, and headless-envelope.txt. Report-Writer markdown summaries are downstream responsibilities today.

latest-summary.json is only a pointer; consumers must validate it against metadata.json. Artifact status, issue_synthesis_status, and the full spine are documented in Headless Runner And Artifact Lifecycle and Mode, Output, And Issue Contract.

Do not write new artifacts to the legacy flat .spec-first/app-audit/ path. Legacy flat paths may be read only for migration compatibility tests.

Headless Runner

scripts/run-audit.js is the deterministic entrypoint for the static artifact chain. It is a subprocess orchestrator only — it never invents issues, never calls an LLM, and never fetches remote Figma/PRD assets. The runner accepts mode:headless only and requires base:<git-ref>; missing base returns scope_headless_missing_base.

The full 16-step subprocess pipeline, runner-owned fail-fast reason codes, the auto-stub path for unstaged issues, and the failure-envelope behavior are documented in Headless Runner And Artifact Lifecycle. Current focused tests cover source/runtime host boundaries; runner scripts remain directly syntax-checked and exercised through the repository test suites.

Source And Runtime Boundaries

Source truth for this workflow lives in the repository source tree: the app-audit skill source, the Claude command template, the dual-host governance contract, and the project docs.

Generated runtime assets are not source truth:

• .claude/
• .codex/
• .agents/skills/
• .cursor/
• .kiro/
• .qoder/

Do not hand-edit generated runtime assets. Runtime refresh belongs to the host-specific spec-first init invocation.

Expert Prompt Boundary

App-audit experts and ECC-derived lenses are skill-local prompt assets:

skills/spec-app-consistency-audit/prompts/

Do not copy app-audit-specific experts or ECC-derived lenses into agents/ during MVP implementation. agents/ is reserved for cross-workflow stable generic experts.

ECC-derived content may be used only as read-only lens, checklist, or evidence pattern material. It must not bring write, edit, repair, build, cleanup, or final-verdict authority into this workflow.

Before dispatching any selected expert, evidence auditor, or report-writer worker, record:

worker_dispatch_authorization: authorized | missing
capability_probe: not_applicable | attempted | unavailable
worker_dispatch_capability: available | missing | unknown
worker_context_isolation: isolated | inherited | unknown
worker_model_override: supported | unsupported | unknown
worker_bounded_parallelism: supported | unsupported | unknown

workflow invocation does not authorize dispatch。只有当前用户或可见 upstream handoff 明确请求 subagent、delegated work、persona 或 parallel work 时才可派发。Planner 选择 expert、mode:headless、depth:deep、prompt asset 存在、权限设置或 callable tool 都不构成授权。缺授权时不得探测 tool schema，固定为 capability_probe: not_applicable + worker_dispatch_capability: unknown，由 orchestrator inline 或 serial 应用 selected expert lenses并记录 dispatch_authorization_missing。只有授权后才把 current-session registry/schema 作为 provider_untrusted evidence 检查：确认缺失时记录 subagent_capability_missing；surface 不可用、schema 不完整或候选不唯一时记录 worker_capability_unproven，均使用同一 fallback。隔离、模型覆盖和有界并发只取 live facts；required isolation 未满足时保持依赖 gate 打开，model unknown 时继承，parallelism unknown 时串行。记录 worker_dispatch_outcome。Inline fallback 可以产出同一 issue-candidate schema，但不得声称 independent expert、fresh-context 或 multi-agent coverage；报告应将其标为 orchestrator-applied lenses。