/audit-session

name: audit-session
description: 审计工作流的跨会话状态机 — 在 <audit-root>/.audit-state/<session-id>.json 持久化轮次/发现项/收敛状态，支持 Token 中断后精准恢复

Audit Session Skill

适用范围

• 触发：意图为 `audit` 且预期轮次 ≥3（即所有非 chat 审计场景）
• 不适用：analyze（仅 ≥3 轮收敛但无 audit finding 交接状态机）、chat（无审计语义）

状态文件路径

<audit-root>/.audit-state/<session-id>.json

`<audit-root>` 取值：

• 旧布局：`<项目根>/.devcodex`
• 集中布局单项目：`<工作区根>/.devcodex/<project>`
• 集中布局全工作区：`<工作区根>/.devcodex/workspace`

• `<session-id>` 取首次启动审计的时间戳：`YYYYMMDD-HHmmss`
• `<audit-root>/.audit-state/` 目录由本 Skill 首次写入时创建（不随 `init` 分发）
• `.gitignore` 须覆盖 `<audit-root>/.audit-state/` 对应路径（如 `.devcodex/.audit-state/`、`.devcodex/*/.audit-state/`，同记忆策略）

状态机

active ──┬─> paused (Token 防护触发 / 用户中断)
         ├─> resumed (跨会话 resume 重新进入)
         ├─> converged (CRS + PCV 通过 + 连续3轮零发现)
         └─> closed (用户确认审计闭环)

paused ──> resumed ──> active
converged ──> closed

| 状态 | 进入条件 | 退出条件 | |------|---------|---------| | `active` | 首次 audit 意图识别成功 | 任一退出条件触发 | | `paused` | C08 Token 防护（>15 轮）或 用户中断 | resume 意图 + 当前 session 命中 | | `resumed` | resume 意图 + 读取本文件 | 立即转 `active` 继续审计 | | `converged` | `zeroFindingStreak ≥ 3` 且 `crsPassed` 且 `pcvPassed` | 用户确认 → `closed` | | `closed` | 用户确认审计完成或放弃 | 终态（不再写入）|

状态文件 schema

{
  "schemaVersion": "AuditSessionStateV2",
  "sessionId": "20260520-143055",
  "startedAt": "2026-05-20T14:30:55+08:00",
  "lastUpdatedAt": "2026-05-20T16:12:33+08:00",
  "target": {
    "type": "spec | tech-design | requirements | project | report | document",
    "scope": "<被审查文件 glob 或目录>"
  },
  "dimensions": ["D1", "D2", "..."],
  "round": 3,
  "state": "active | paused | resumed | converged | closed",
  "findings": [
    {
      "id": "F-001",
      "round": 1,
      "dim": "D5",
      "file": "instructions/12-audit.instructions.md",
      "severity": "🔴 | 🟡 | 💡",
      "summary": "<一句话>",
      "status": "open | pending | in-progress | fixed | wontfix | accepted | recorded | transferred | superseded",
      "category": "spec-defect | release-pending | v{X.Y.Z}-candidate",
      "fixPlan": "<修复方案概述>",
      "fixCommit": "<git commit hash, 修复后写入>",
      "linkedPF": "PF-NNN | null"
    }
  ],
  "regressionProbes": [
    {
      "findingId": "F-007",
      "scanCmd": "grep -c 'PC5' CLAUDE.md",
      "expectedMatches": 3,
      "lastVerifiedRound": 4,
      "lastVerifiedAt": "2026-05-21T03:30:00+08:00"
    }
  ],
  "r2Probes": [{"name": "<probe>", "status": "✅|⚠️|❌"}],
  "r3Probes": [{"name": "<probe>", "status": "✅|⚠️|❌"}],
  "r4Probes": [{"name": "<probe>", "status": "✅|⚠️|❌"}],
  "zeroFindingStreak": 0,
  "crsPassed": false,
  "pcvPassed": false,
  "remoteReleased": {
    "gitPush": false,
    "npmPublish": false,
    "recordedAt": "ISO8601",
    "source": "user-confirmed-manual | ci-automation"
  },
  "lastCheckpoint": {
    "round": 3,
    "writtenAt": "2026-05-20T16:12:33+08:00",
    "reason": "round-end | token-protect | user-interrupt | switching-to-release-vX.Y.Z | release-pending-vX.Y.Z"
  },
  "linkedMemory": "tasks/20260520.md",
  "linkedReport": "<active-root>/<task-kind>/<task>/reports/<agent>/20260520/01--<name>.md",
  "linkedRelease": "<active-root>/requirements/<task>/reports/<agent>/YYYYMMDD/01--vX.Y.Z-release.md"
}

`.audit-state` 兼容读取边界

`.audit-state` 是多类运行态证据的共享目录名，不代表目录内每个 JSON 都属于当前审计会话。读取者必须先分类，再决定校验方式：

| 分类 | 识别 | 处理 | |---|---|---| | current session | exact `AuditSessionStateV1` / `AuditSessionStateV2` | 按本 Skill 的状态、finding 与 regression probe 合同严格校验 | | legacy audit | `AuditStateV1` 或可识别的历史无 schema 审计形状 | 只读导航与取证，不要求满足当前枚举或新探针，不改写历史字节 | | non-audit | SkillRoute、batch plan、validation 等其他 schema | 跳过审计会话校验，由各自 owner 负责 | | unsupported current | 未支持的 `AuditSessionStateV*` | 明确报告不支持，禁止猜测或降成 legacy | | invalid | JSON 损坏或顶层不是 object | 报告结构错误，不静默忽略 |

兼容分类只解决 reader 误判，不授予旧状态新的写权限，也不得伪造 `superseded`、重算旧 finding 或迁移历史文件。

v1.9.4+ schema 字段说明

| 字段 | 引入 | 用途 | |------|:----:|------| | `findings[].category` | v1.9.4 | 分类标识：`spec-defect`（规范缺陷）/ `release-pending`（仅发版动作未启动导致）/ `v{X.Y.Z}-candidate`（推迟到下版本同源合并）| | `findings[].fixPlan` | v1.9.4 | 修复方案概述，留作 release/dev 工作流参考 | | `findings[].fixCommit` | v1.9.4 | 独立 fix/self-fix 工作流产生的修复 commit hash；audit 只读取并验证，不自行提交 | | `regressionProbes[]` | v1.9.5+ | 已修复 finding 的回归扫描定义；audit-common §收敛门禁第 7 步触发；任一回归 → status 切回 open，streak 归零 | | `r{N}Probes[]` | v1.9.4 | 第 N 轮的探针清单与状态，便于跨会话 resume 时审计深度可追溯 | | `remoteReleased` | v1.9.4 | 远端发版动作状态（git push + npm publish），消除 release-pending findings 的依据 | | `lastCheckpoint.reason` | v1.9.4 | 扩充值：`switching-to-release-vX.Y.Z`（切 release 流程缓冲）/ `release-pending-vX.Y.Z`（等下版本合并）| | `linkedRelease` | v1.9.4 | 关联 release 报告路径，建立 audit → release 双向链 |

findings[].status 枚举

| 状态 | 含义 | 是否未解决 | |------|------|:----------:| | `open` | 当前审计仍需处理 | 是 | | `pending` | 已确认但等待后续批次处理 | 是 | | `in-progress` | 正在修复或验证中 | 是 | | `fixed` | 已修复并通过回归验证 | 否 | | `wontfix` | 已确认不修复，需保留理由 | 否 | | `accepted` | 已接受为项目例外或可接受风险，需保留理由 | 否 | | `recorded` | 已记录到外部台账、问题池或报告，当前审计不再直接处理 | 否 | | `transferred` | 已转入其他报告、需求或问题池继续跟进 | 否 | | `superseded` | 已被后续报告或新版结论取代 | 否 |

> 终态 `converged` / `closed` 不得保留 `open`、`pending`、`in-progress` findings；允许 `fixed`、`wontfix`、`accepted`、`recorded`、`transferred`、`superseded` 作为已处置状态。

写入时机

`AuditMutationBoundaryGate`：audit session 只记录 finding/交接/外部修复证据；`sourceMutationAuthorized` 在 audit 中恒为 `false`，用户修复授权由独立 fix/self-fix 的 CP/ExecutionContract 持有。

| 时机 | 动作 | 字段更新 | |------|------|---------| | 首轮启动 | 创建文件，state=active | sessionId / startedAt / target / dimensions | | 每轮结束 | 追加 findings + 更新 round | round / findings / zeroFindingStreak | | CRS 完成 | 标记通过状态 | crsPassed | | PCV 完成 | 标记通过状态 | pcvPassed | | Token 防护（C08 >15轮）| state=paused | state / lastCheckpoint.reason=token-protect | | 收敛 | state=converged | state | | 用户确认 | state=closed | state |

与其他 Skill / Instruction 的协同

| 关联点 | 说明 | |--------|------| | `instructions/12-audit.instructions.md` | 审计工作流入口须读取/创建本文件；收敛门禁须校验 `crsPassed && pcvPassed && zero