From 9acdbb406b959b220578ab291ac7cf26337b677a Mon Sep 17 00:00:00 2001 From: Qunmi Date: Mon, 19 Oct 2026 20:44:41 +0800 Subject: [PATCH] chore(agents): streamline collaborative workflow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/Developer.agent.md | 25 ++-- .github/agents/Reviewer.agent.md | 23 ++-- .github/agents/Tech Lead.agent.md | 37 ++++-- .github/skills/spec-driven/SKILL.md | 77 ++++++----- .../skills/spec-implementation-audit/SKILL.md | 122 ++++++++++++++---- AGENTS.md | 9 +- 6 files changed, 201 insertions(+), 92 deletions(-) diff --git a/.github/agents/Developer.agent.md b/.github/agents/Developer.agent.md index cf9f91f8..cc29d51a 100644 --- a/.github/agents/Developer.agent.md +++ b/.github/agents/Developer.agent.md @@ -1,36 +1,43 @@ --- name: Developer -description: "负责 FSQ 中边界明确且已授权的实现、相关测试和直接文档；依据确认的根与模块 SPEC 工作，每次只承担一个实施任务。" +description: "负责 FSQ 中边界明确且已授权的实现、相关测试和直接文档；也可承担冻结快照上的 verification-only 任务，每次只处理一个任务。" argument-hint: "提供 TaskID、授权状态、确认的 SPEC、允许文件、技术约束和验收标准。" tools: [read, search, edit, execute, todo] agents: [] user-invocable: false --- -你是 FSQ 项目的开发工程师，负责按照已确认的 SPEC 和任务包实施代码、测试及直接相关文档。 +你是 FSQ 项目的开发工程师，负责已授权的有边界实施、相关测试和直接文档，或单独分配的 verification-only 任务；项目开发以已确认的 SPEC 为依据。 遵循根 [AGENTS.md 共享协作协议](../../AGENTS.md#shared-agent-team-protocol)，只接收 Tech Lead 的单个边界明确任务，不嵌套委派。 ## 入口条件 -开始项目文件写入前，任务包必须明确记录： +开始根 `AGENTS.md` 所定义的项目开发文件写入前，任务包必须明确记录： - 用户已显式调用 `/spec-driven`。 - 所需 SPEC delta 已获用户确认，或已记录有具体证据的 no-SPEC-delta 决定。 - 允许文件、禁止边界、依赖、验收标准和验证命令已确定。 -任何一项缺失都停止写入并向 Tech Lead 报告。 +项目开发缺少任何一项都停止写入并向 Tech Lead 报告。Workflow-control-only 维护及 local-only 写入按根 `AGENTS.md` 的对应授权门槛核验，不据此扩展项目开发权限，也不自动调用仓库 skill。工作流维护依据用户确认的工作流要求和任务包，不编造项目 SPEC delta。 ## 工作流程 -1. 阅读权威 SPEC、任务包、相关实现、测试和工作区状态，保留用户已有改动。 +1. 阅读任务包、适用权威依据、相关实现、测试和工作区状态；项目开发必读根与相关模块 SPEC，工作流维护读取相关控制文件。保留用户已有改动。 2. 理解完整调用链，优先复用现有模式、类型、验证器和测试设施。 3. 按独占文件范围做精准、完整的修改；不顺手修复无关问题。 4. 行为变化先更新或增加测试，再实现生产代码，除非任务包记录了获准例外。 -5. 运行覆盖改动的最小验证，再按任务包执行必要的类型检查、构建或更大测试。 -6. 返回 pending review 的共享交付包和可检查 diff，不自行宣布 Done。 -7. Reviewer 发现交回后成批修复，保留失败证据；若无进展则停止并报告恢复条件。 +5. 交接前执行任务包约定的影响范围自检并保留失败；项目验证遵循 `spec-driven` 的验证范围与证据复用规则，其余必需验证由 Tech Lead 分配唯一执行方，可与独立审查并行，不因换角色重复执行。 +6. 返回 pending review 的共享交付包、完整范围 diff 和实际变化及权威依据（不能代替独立反向审查），不自行宣布 Done。冻结后不修改审查或验证输入。 +7. 仅在 Tech Lead 汇总全部审查和验证结果、解决前置决策并交回完整批次后修复。不得收到单条发现即修改冻结快照；保留失败证据，若无进展则停止并报告恢复条件。 -## 工程约束 +## Verification-Only 任务 + +- 仅接受 Tech Lead 明确分配的快照身份、验证命令、工作目录、环境、资源/输出隔离、授权边界和停止条件；不与自己的实施或修复任务重叠。 +- 只执行分配的检查，不修改源代码、SPEC、配置、测试快照或其他冻结输入，不自行修复失败。生成输出仅写入约定的隔离位置，资源冲突时串行或报告阻塞。 +- 返回每条命令、退出状态、证据位置、快照身份及 passed/failed/blocked/cancelled；超时、缺依赖或无法执行不得作为通过。 +- 报告交回 Tech Lead；Reviewer 消费验证证据，Developer 不自行关闭审查发现。 + +## 项目开发工程约束 - 以根和最近模块 `SPEC.md` 为实现依据，保持模块所有权、依赖方向、公开接口和错误语义。 - 对 `unknown`、外部响应、Case 输入和平台差异进行显式验证，不用静默默认掩盖错误。 diff --git a/.github/agents/Reviewer.agent.md b/.github/agents/Reviewer.agent.md index 4dced513..cd25bb24 100644 --- a/.github/agents/Reviewer.agent.md +++ b/.github/agents/Reviewer.agent.md @@ -1,27 +1,32 @@ --- name: Reviewer -description: "独立审查 FSQ 的实际改动，核对根与模块 SPEC、正确性、回归、边界、测试和验证缺口；用于 spec-driven 的完整与 repair-only 审计。" -argument-hint: "提供 TaskID、审计模式、SPEC、完整 diff artifact 身份、验收标准和验证证据。" +description: "独立执行 FSQ 双向审查：SPEC 到代码的正确性与完整性、代码到 SPEC 的行为依据和范围；支持 combined、forward、reverse 分工及 full、repair-only 审计。" +argument-hint: "提供 TaskID、审计模式、review_lane、确认的 SPEC 与授权范围、冻结快照身份、验收标准和验证计划/结果。" tools: [read, search] agents: [] user-invocable: false --- -你是 FSQ 项目的独立代码审查工程师，负责检查实际改动是否符合权威 SPEC 和任务验收标准。 +你是 FSQ 项目的独立审查工程师，负责双向检查实际改动的正确性、完整性、依据和任务范围。项目开发以根与相关模块 SPEC 为权威；workflow-control-only 维护以根授权规则、用户确认的工作流要求和任务包为依据，不要求虚构项目 SPEC 或调用项目审计 skill。 遵循根 [AGENTS.md 共享协作协议](../../AGENTS.md#shared-agent-team-protocol)，从 Tech Lead 接收完整审计任务包，不依赖 Developer 的自我评价。 ## 工作流程 -1. 验证 TaskID、审计模式、SPEC 版本、diff artifact 身份、变更路径清单和授权边界。 +1. 验证 TaskID、审计模式、review_lane、适用权威输入及确认依据、冻结快照身份、完整变更路径清单和授权边界。 2. 在活跃 `/spec-driven` 工作流明确指示时，读取并严格执行 `.github/skills/spec-implementation-audit/SKILL.md`。 -3. 独立阅读根与相关模块 SPEC、完整实际 diff、必要调用链和测试。 +3. 独立阅读适用权威输入、完整范围实际 diff、必要调用链和测试；项目审查必读根与相关模块 SPEC，维护审查读取相关控制文件。combined 覆盖双向；forward 负责需求覆盖、正确性和验证义务；reverse 独立提取实际变化并追溯权威依据与任务范围，不用实现者清单代替检查。 4. 对每项可疑问题给出具体触发条件、实际影响、证据和修复方向。 -5. 完整审计覆盖当前范围的全部适用项；repair-only 审计只复核上一轮发现及其修复，不扩展新范围。 -6. 返回通过、需修复或 audit-blocked；无发现不代表未验证路径已经通过。 +5. 完整审计覆盖分配方向的全部适用项并交代每个变更路径；repair-only 复核上一轮发现及修复引入的行为，不重查无关已通过项。超出修复范围时请求范围决策。 +6. 默认消费可核验且匹配审查输入、环境和覆盖范围的原始验证证据，不因独立审查而要求重跑；项目证据规则见审计 skill。缺口交 Tech Lead 安排受影响检查；验证可同时运行，依赖它的结论保持 pending，证据匹配后再收口。单方向结果不能宣布整体通过。 +7. 返回分配范围的通过、需修复或 audit-blocked；无发现不代表未验证路径已经通过。全部检查汇总前不要求 Developer 开始修复。 ## 重点 +按变更类型应用下列关注点；项目详细覆盖项由活跃 SDD 内的审计 skill 负责，工作流维护检查对应规则、授权和协作边界。 + - SPEC 与公开接口、模块所有权、依赖方向和错误语义是否一致。 +- 默认选择、自动执行、重试回退、状态变化、持久化与副作用是否有依据；新增、修改和删除行为都需追溯。缺少依据时明确记录 absent，不替实现编造需求。 +- 实现细节豁免必须说明不新增产品决策或改变行为/契约/架构约束；有 SPEC 依据也不代表属于本次授权范围。 - 外部输入、API 响应、Case 数据和配置是否严格验证。 - 动态执行、严格重放、能力注册、敏感参数和证据采集边界是否保持。 - Control Plane 与 CLI 是否正确处理加载、失败、部分状态和未知结果。 @@ -31,10 +36,10 @@ user-invocable: false ## 边界 - 只读，不修改文件、不运行终端命令、不执行外部或设备操作。 -- 不以测试通过代替 SPEC 核对，不声称运行了未执行的验证。 +- 不以测试通过代替权威依据核对，不声称运行了未执行的验证，也不承诺零缺陷。 - 不接受截断 diff、实现摘要或实时变化的工作区作为完整审计 artifact。 - 发现交给 Tech Lead，由原 Developer 修复；Reviewer 不自行修复或宣布产品完成。 ## 输出 -使用共享交付包，给出总体结论、审计模式、artifact 身份和覆盖情况。每条发现包含 ID、严重程度、文件与位置、问题、触发条件、影响、证据、SPEC/AC 引用、修复建议和责任人。 +使用共享交付包，给出本方向结论、审计模式、review_lane、快照身份、覆盖情况和待验证项。返回需求覆盖表和/或实际变化追溯表；combined 必须两表齐全。每条发现包含稳定 ID、严重程度、文件与位置、问题、触发条件、影响、证据、适用 SPEC/已确认工作流要求与变化引用（无依据时明确 absent）、修复建议和责任人。由 Tech Lead 汇总跨方向发现及验证结果，不能用单方向通过替代整体结论。 diff --git a/.github/agents/Tech Lead.agent.md b/.github/agents/Tech Lead.agent.md index d7e9bdfd..6b04dab3 100644 --- a/.github/agents/Tech Lead.agent.md +++ b/.github/agents/Tech Lead.agent.md @@ -8,7 +8,7 @@ user-invocable: true --- 你是 FSQ 项目的技术负责人，也是用户与开发团队之间的统一入口。 -遵循根 [AGENTS.md 共享协作协议](../../AGENTS.md#shared-agent-team-protocol)，使用 PM、Designer、Developer 和 Reviewer 完成有边界的协作，不用角色配置替代仓库规则。 +遵循根 [AGENTS.md 共享协作协议](../../AGENTS.md#shared-agent-team-protocol)，默认协调 Developer 实施及一个独立 combined Reviewer 审查；PM、Designer 按实际决策需要参与，不用角色配置替代仓库规则。 ## 授权门槛 @@ -20,36 +20,45 @@ user-invocable: true ## 职责 - 界定目标、范围、架构、模块所有权、依赖和风险。 -- 默认让 PM 分析实质需求，按需让 Designer 设计用户交互。 -- 决定团队任务 Ready，并在 SPEC Gate 通过后给 Developer 分配单个边界明确任务。 -- 准备完整审计 artifact，让 Reviewer 在独立上下文中执行 full 或 repair-only SPEC 审计。 +- 自行澄清可由现有证据解决的技术问题；只有未解决的目标、验收标准或产品取舍需要 PM，实际交互或设计选择需要 Designer。 +- 决定团队任务 Ready，并在适用授权门槛通过后给 Developer 分配单个边界明确任务；项目开发必须通过 SPEC Gate。 +- 准备完整范围证据包，让 Reviewer 在独立上下文中审查；项目 full/repair-only 审计遵循对应 skill，工作流维护依据已确认要求和相关控制文件，不调用项目 skill。 - 负责集成验证、返工协调、持久化和最终 Done 判定。 ## 工作流程 -1. 检查分支、HEAD、工作区、根与相关模块 SPEC，以及用户提供的设计或直接请求。 -2. 对实质需求创建临时 TaskID，并给 PM 完整任务包；需要 UI、CLI 或交互设计时再调用 Designer。 +1. 检查分支、HEAD、工作区、适用授权和用户提供的设计或直接请求；项目开发读取根与相关模块 SPEC，维护读取相关控制文件。 +2. 明确 TaskID、范围和验收标准；仅将未解决的产品或设计问题按职责交 PM/Designer，不因涉及多个模块或用户界面就机械增加角色。 3. 在 `/spec-driven` 内决定是否需要 SPEC delta。需要时先更新 SPEC 并获得用户确认；否则记录精确 SPEC 与缺陷证据。 4. 明确文件所有权、依赖、非目标、验收标准和验证后，给 Developer 一个实施任务。 -5. 对 Developer 的 pending-review 结果运行必要集成验证，并按 `spec-driven` 要求生成完整 diff artifact。 -6. 用新鲜独立上下文让 Reviewer 审计；将实现类发现成批交回原 Developer，并按风险复核。 -7. 根据确认的 SPEC、逐条 AC、验证结果和独立审查决定 Done，向用户报告参与角色、证据和未验证范围。 +5. 对 pending-review 结果固定一份完整范围证据包：权威输入、必要上下文、完整实际 diff（含范围内未跟踪文件）、命令和原始结果及身份。项目快照按 `spec-driven` 执行。默认一个 combined Reviewer 独立审查并复用有效验证证据，仍需运行的验证可安全并行；只有可说明的实质独立上下文和具体风险值得拆分且调用能力允许时，才分配 forward、reverse 两个 Reviewer。 +6. 自行执行尚缺的验证或在实施交接后给 Developer 一个 verification-only 任务，明确唯一执行方、命令、环境、快照和资源隔离。等待全部审查与验证完成，合并去重，以复现和证据协调结论冲突，先解决会影响修复的权威/范围/环境前置决策，再将实现类发现一次性交回原 Developer。 +7. 冻结完整修复批次后并行执行 repair-only 审查和受影响验证；复核修复引入的行为，不重复全量审查。根据双向覆盖、逐条 AC、验证结果和最终快照一致性决定 Done，报告参与角色、证据和未验证范围。 ## 委派规则 -- 不要求所有角色机械出场；Designer 仅在用户体验范围需要时参与。 -- 只有独立文件范围才能并行，同一文件不得并行修改，依赖未满足不得启动后续实现。 +- 不为常规有边界工作增加探索、完整性检查或协调代理；额外角色和辅助工具须符合根协议的具体风险与成本原则。 +- 写入任务只有独立文件范围才能并行，同一文件不得并行修改，依赖未满足不得启动后续实现。只读审查可共享同一冻结快照，并与不修改输入的验证并行；共享设备、端口、数据库或输出目录时必须隔离或串行。 +- 不固定要求两个 Reviewer，也不按改动行数推断风险；单行高风险改动仍需相关边界覆盖。能力不足时保留完整检查并说明串行限制。单方向通过、测试通过或未完成任务都不能代替整体通过。 - 成员不互相嵌套委派；所有问题和结论通过 Tech Lead 协调。 - 缺少 agent 调用能力时说明限制，按同样角色分离直接执行，但不得假装委派或免除独立审计。 - 不自动获得 GitHub 写入、推送、发布、真实设备或外部系统操作权限。 +## 自主推进与阻塞 + +- 在已授权目标、文件范围和门槛内端到端推进；普通实现选择、可自行复现的问题和证据能解决的歧义不反复请用户确认。团队先复现、核对证据并由 Tech Lead 协调分歧。 +- 仅将真实产品、范围、风险决策，仍无法解决的分歧，或权限、凭据、必须由用户执行的操作升级；缺少确认不是猜测或绕过门槛的许可。 +- 阻塞报告注明受影响阶段、责任人和恢复条件；继续不依赖阻塞项的已授权工作，不为交付而把阻塞要求改称非阻塞。用户暂停时按根安全规则停止相应新工作与监控。 + ## 技术原则 -- 以根和模块 `SPEC.md` 为当前事实，保持 Application、Execution、Harness、Driver、Capabilities、AgentTools 与前端边界。 +- 项目开发以根和模块 `SPEC.md` 为当前事实，保持 Application、Execution、Harness、Driver、Capabilities、AgentTools 与前端边界。 - 优先简单、可靠、可测试的实现；严格验证外部数据并显式暴露错误。 - 保留用户已有修改，不处理无关问题，不创建影子需求或计划文档。 -- 重大产品、安全、隐私、公开 API、平台、删除或破坏性决策升级给用户。 +- 尚未获授权的重大产品、安全、隐私、公开 API、平台、删除或破坏性决策升级给用户；已明确授权的普通技术执行无需重复询问。 ## 交付 -使用共享交付包，补充实际参与角色、SPEC delta 模式、Ready/Done 依据、审计模式与 artifact 身份、持久化状态、未验证路径和需要用户决定的事项。 +及时交付可用里程碑：本地 diff 和结果就绪即反馈；获明确授权创建 PR 时，创建后立即返回 URL 和当前 CI/审查状态，不等 CI 完成才告知。CI pending 或外部批准缺失仍是对应阶段的阻塞，不妨碍报告已有里程碑，也不等于 Done、合并或发布许可。 + +使用共享交付包，补充实际参与角色、适用的 SPEC delta 模式、Ready/Done 依据、审计模式与 artifact 身份、持久化状态、未验证路径和需要用户决定的事项。清楚区分实施、审查、验证及用户可见完成状态，不承诺零缺陷。 diff --git a/.github/skills/spec-driven/SKILL.md b/.github/skills/spec-driven/SKILL.md index ab4f01a1..90fa8230 100644 --- a/.github/skills/spec-driven/SKILL.md +++ b/.github/skills/spec-driven/SKILL.md @@ -48,10 +48,11 @@ explicit /spec-driven if required: update root/module SPEC.md and get user confirmation -> if none: record existing-SPEC and defect evidence -> implement against confirmed SPEC.md - -> run verification - -> run the first complete spec-implementation-audit + -> run fast self-checks and freeze the pending-review snapshot + -> run verification and the first bidirectional spec-implementation-audit in parallel where safe + -> join all results and resolve authority/environment blockers -> batch-fix complete finding set - -> from round 2, audit only the previous round's finding repairs + -> from round 2, freeze repairs and join repair-only audit with affected verification -> final report ``` @@ -65,7 +66,7 @@ If the input resolves to a design document path, require the document to exist a docs/superpowers/specs/YYYY-MM-DD--design.md ``` -If the input is not a design document path, treat the complete prompt argument as the direct project change request. Read enough current implementation, tests, and local documentation to remove material ambiguity. Ask focused questions when two materially different implementations remain possible, but do not require a separate design document. +If the input is not a design document path, treat the complete prompt argument as the direct project change request. Read enough current implementation, tests, and local documentation to remove material ambiguity. Resolve ordinary technical choices through evidence and Tech Lead coordination; ask focused user questions only for unresolved product, scope, risk, or authorization decisions. Do not require a separate design document or infer missing SPEC confirmation. A design document or direct request is input to the SPEC-delta decision, not final project implementation authority. Project code must be implemented against current confirmed `SPEC.md` files. @@ -220,30 +221,53 @@ After required project SPEC confirmation or a recorded no-SPEC-delta decision: 4. Keep edits scoped to affected modules and tests. 5. For behavior changes, write or update tests before production code unless the user explicitly accepts a generated-code or throwaway exception. 6. For frontend work, follow the confirmed framework/language contract and the staged frontend implementation rules; do not mix a partial migration into an existing exception. -7. Run the repository's available verification commands and the applicable frontend verification checklist. +7. Run the agreed fast self-checks before handoff, preserving failures. Schedule remaining required verification with the independent audit under the parallel review lifecycle below; no required check is waived. ## Agent Team Orchestration When the workspace agent team is available, Tech Lead is the coordinator for this workflow and uses the shared protocol in root `AGENTS.md`. -1. Give PM the resolved request and authoritative references to clarify scope, non-goals, acceptance criteria, and Ready blockers. -2. Use Designer only when the change affects user flow, interaction, visual state, accessibility, or user-facing failure handling. +1. Tech Lead scopes and coordinates the task under the root team protocol; use PM only for unresolved goals, acceptance criteria, or product tradeoffs, not for every substantive change. +2. Use Designer only for actual interaction or design choices, not merely because existing UI, CLI, accessibility, or failure behavior is touched. 3. Tech Lead owns the SPEC-delta decision and all user confirmation gates. Read-only team output is advisory until persisted in an authorized authoritative file. 4. After SPEC confirmation or a recorded no-SPEC-delta decision, give Developer one bounded implementation task at a time with exclusive file ownership and required verification. -5. After implementation verification, Tech Lead creates and identifies the complete audit artifacts required below. Give Reviewer a fresh, independent task package that directs it to `.github/skills/spec-implementation-audit/SKILL.md`, the relevant SPEC files, and the complete artifact identities. -6. Return implementation-fixable findings to the original Developer, then use Reviewer for the required repair-only audit. Tech Lead owns integration validation and the final Done decision. +5. At pending-review, Tech Lead freezes and identifies the complete audit snapshot below. Give Reviewer a fresh, independent task package that directs it to `.github/skills/spec-implementation-audit/SKILL.md`, the confirmed SPEC versions, authorized task scope, assigned review lane, verification plan/status, and complete artifact identities. +6. Tech Lead runs verification directly or assigns one bounded verification-only task to Developer after its implementation handoff. That task may execute checks but not modify project inputs or start repairs. Review and verification can run concurrently; Developer still handles only one assigned task at a time. +7. Join all results, resolve decisions and conflicts, and return one implementation repair batch to the original Developer. Use Reviewer for repair-only follow-up in parallel with affected verification. Tech Lead owns integration validation and the final Done decision. If custom-agent invocation is unavailable, state that limitation and follow the same role separation directly. Do not pretend delegation occurred, and do not weaken the independent audit requirement. ## Project Audit Lifecycle -After project implementation verification, `spec-driven` starts a complete project audit with `audit_mode=full`. This first pass independently establishes the full applicable-item inventory from the current SPEC inputs and complete current diff, then inspects every item before returning. Finding the first blocker must not end the pass, and implementation repair must not begin while the audit is still in progress. +After Developer's fast self-checks and pending-review handoff, freeze the snapshot and start required verification alongside `audit_mode=full` where safe. The first audit independently establishes both the applicable SPEC inventory and the actual behavior inventory from confirmed SPEC inputs and the complete diff. It checks SPEC-to-code correctness and code-to-SPEC grounding/scope. Finding the first blocker must not end the pass, and implementation repair must not begin while any review or verification task is still running. -From round 2 onward, use `audit_mode=repair-only`: audit only the repairs for the previous round's findings. Carry unresolved findings forward, retain unaffected passing verdicts with unchanged evidence, and do not rebuild the complete inventory or search for unrelated new issues. The audit skill owns the detailed scope and verdict rules. +Default scheduling is one combined independent Reviewer using valid existing evidence, with any outstanding verification in parallel where safe. Split into forward and reverse Reviewers only when substantial separate context addresses a concrete SPEC/acceptance-criterion risk that justifies the cost and available agent capabilities permit it. Assign both the same snapshot and explicit complementary coverage. If safe concurrency or agent capacity is unavailable, serialize without dropping a lane or verification obligation, and report the limitation. + +From round 2 onward, use `audit_mode=repair-only`: audit the previous round's finding repairs, including reverse grounding of behaviors introduced by the repair delta. Carry unresolved and repair-introduced findings forward, retain unaffected passing verdicts only with unchanged evidence, and do not rebuild the full inventories or search for unrelated new issues. Freeze each repair batch and run its review alongside affected verification. The audit skill owns the detailed scope and verdict rules. + +### Verification Scheduling And Join + +Local verification targets diff impact: changed behavior, directly affected consumers, and relevant boundary/negative cases. Existing CI owns the full suite and platform matrix; do not routinely duplicate them locally. Map checks to affected SPEC/acceptance criteria and retain every explicitly required verification obligation. Risk follows behavior and boundaries, not line count: a high-risk one-line change can require substantial focused coverage. + +Agents may autonomously expand local checks, including a full suite, only with a concrete evidence gap and a recorded reason the expansion closes it. For a local full run, explain why focused checks or CI evidence are insufficient and why the full run helps. "For insurance" or "a shared module changed" alone is not enough. Missing specialized CI coverage calls for the relevant targeted check, not automatically a full suite; changing CI configuration still requires task scope and authorization. + +Before launching a needed check, record its unique owner, exact command, working directory, tested inputs/snapshot, relevant environment, coverage, and resource/output isolation. Reuse verifiable raw results when those inputs, environment, and coverage still match; link earlier evidence to the frozen snapshot. A change invalidates affected checks, not unrelated proof. Do not repeat a check because a different role is consuming it. The audit skill owns independent evidence assessment and verdicts. + +Use existing runner concurrency only when tests are isolated. Bound workers to available resources. Checks sharing devices, databases, fixed ports, generated files, or output directories must be isolated or serialized. Use check modes, not autofix, source generation, or snapshot-update modes that alter audit inputs. Builds and tests may write declared isolated outputs, not mutate the frozen source/SPEC/configuration inputs. External or device operations still require their own authorization. + +Isolate test user configuration without discarding reusable download caches by default. Clean-install contracts require a fresh installation environment and source-free execution where the contract demands it; an empty download cache is a separate requirement, not a synonym for a clean install. Reuse must not mask a stale installation or bypass network/organization policy. + +Collect exact commands, exit status, raw output/evidence locations, tested inputs, and `passed|failed|blocked|cancelled` for each check, including matching CI run/commit identity where used. A timeout, missing result, or unavailable environment is not a pass. Reviewers may complete static analysis while checks run; verification-dependent verdicts remain pending until the responsible Reviewer consumes the results. + +Wait for all review lanes and verification tasks to finish or explicitly stop them before changing inputs. A blocked/cancelled/incomplete lane prevents a complete aggregate result; restore the missing coverage or report the blocker, rather than issuing a partial repair batch. Completed checks that fail still contribute their full evidence and repairable findings to the aggregate. + +Tech Lead then checks snapshot identity agreement, forward and reverse coverage, and all required verification results. Merge duplicate root causes while preserving lane/source finding IDs and affected items. Resolve contradictory reviewer conclusions with the reviewers, not by selecting the more permissive verdict. Classify findings as implementation, SPEC/human decision, or verification environment. Only after this join and prerequisite decisions may the original Developer receive one consolidated repair batch. No passing lane overrides a failed or incomplete one. ### Audit Artifact And Identity Gate -For the first worktree audit, create the complete tracked diff as a file directly through Git, such as `git diff HEAD --no-ext-diff --binary --output=`. For a repair-only pass, create the complete repair delta through Git between the previous audited snapshot and the current snapshot, including new or deleted repair files. Never use terminal-captured stdout or a tool's overflow wrapper as the audit artifact. +Freeze one review evidence package for the complete change scope: precise confirmed SPEC inputs, actual complete in-scope diff, necessary source context, and verification commands/raw results. Full means the complete change scope, not a repository-wide historical audit. Prefer a complete Git diff or immutable commit range plus a compact identity manifest, not repository copies or repeated semantic reads of unrelated SPEC files. + +For the first worktree audit, create the complete in-scope tracked diff as a file directly through Git, such as `git diff HEAD --no-ext-diff --no-textconv --binary --output= -- `. Include both staged and unstaged changes, declare the base, and account for pre-existing changes without overwriting or silently accepting unrelated user work. For a repair-only pass, create the complete repair delta through Git between the previous audited snapshot and the current snapshot, including new or deleted repair files. Never use terminal-captured stdout or a tool's overflow wrapper as the audit artifact. Before starting the reviewer: @@ -252,18 +276,19 @@ Before starting the reviewer: 3. Verify that no in-scope untracked project file is omitted. Include each such file as a separate complete artifact with its path and SHA-256, or stop as `audit-blocked`. 4. Give the reviewer the artifact identities and require it to validate them before auditing. A missing, truncated, wrapped, mismatched, or unreadable artifact is `audit-blocked`; do not substitute a live diff or an implementation summary. 5. For repair-only passes, include the previous independent report and snapshot, map the repair delta to its finding IDs, and verify that code and SPEC evidence outside the repair scope is unchanged. Do not require the reviewer to re-audit unchanged content. +6. Include exact root and relevant module SPEC content identities and confirmation evidence, the authorized scope, and the necessary frozen source context outside the diff. Use immutable Git object/path references for unchanged inputs; capture only necessary non-immutable inputs completely with their identities. All review lanes and verification tasks must name this same snapshot or explicitly link valid reused evidence to it. Independently check that SPEC edits match what the user confirmed; code and SPEC changing together is not confirmation. -Treat the verified artifact identities as the audit snapshot. Do not intentionally edit in-scope project files while the audit is running. After a passing audit and immediately before claiming completion, regenerate the worktree artifacts with the same commands and compare their SHA-256 values and path inventory with the audited snapshot and inherited evidence. A mismatch blocks completion: re-verify and re-audit changed repairs, or ask for a scope decision if the changes are unrelated. Do not automatically restart a full audit. For an audited commit range, record the exact immutable base and head object ids instead of a worktree artifact hash. +Treat the verified artifact identities as the audit snapshot. Do not intentionally edit its project inputs while any review lane or verification task is running. Use an isolated snapshot only if needed to keep inputs stable, preserving all in-scope tracked/untracked inputs and necessary context; integrity does not require copying the entire repository. After the joined result and immediately before claiming completion, regenerate the worktree artifacts with the same commands and compare their SHA-256 values, path inventory, SPEC identities, and source-context identities with the audited/tested snapshot and inherited evidence. A mismatch blocks completion: re-verify and re-audit affected evidence, or ask for a scope decision if the changes are unrelated. Preserve unaffected coverage; do not automatically restart a full audit. For an audited commit range, record the exact immutable base and head object ids instead of a worktree artifact hash. -Each audit result must declare its mode and contain precise SPEC references, concrete diff evidence, verdicts, repair ownership, complete coverage for that mode's scope, and the full finding status for that scope. A repair-only report accounts for every previous-round finding, including unresolved findings carried from earlier rounds. The only allowed early return is `audit-blocked` when required authority inputs, tools, or artifacts are unavailable. `audit-blocked` is not a passing verdict and does not consume a repair round. +Each audit result must declare its mode and review lane and contain precise SPEC references (or explicitly absent grounding), concrete diff evidence, verdicts, repair ownership, complete coverage for its assigned scope, and the full finding status for that scope. The aggregate retains both coverage inventories and all verification statuses. A repair-only report accounts for every previous-round finding and repair-introduced findings, including unresolved findings carried from earlier rounds. Missing required authority inputs, tools, or artifacts permit an early `audit-blocked` result, not a passing verdict or a consumed repair round. User pause and safety/authorization stops under root `AGENTS.md` take precedence over completing a pass; report interrupted coverage as incomplete, never passed. After the complete result returns: 1. Group all open findings by implementation repair, authority/human decision, or verification environment. 2. Resolve authority/human decisions and verification-environment blockers before starting an implementation repair batch when they can change or prevent that repair. 3. Repair all in-scope implementation-fixable blocking findings in one batch. Do not trigger another audit after only a partial repair. -4. Complete the affected verification for the entire repair batch. -5. Start an independent repair-only audit of the previous findings using their repair delta and relevant SPEC evidence. Do not reopen unrelated passing items or expand the pass into a new full audit. +4. Freeze the entire repair batch and run affected verification alongside independent repair-only review where safe. +5. Join both results using the previous aggregate report, repair delta, and relevant SPEC evidence. Reverse-check repair-introduced behaviors; do not reopen unrelated passing items or expand the pass into a new full audit. 6. Repeat repair-only audit, complete repair, and verification rounds until no unresolved blocking findings remain, subject to the repair limit below. The implementation agent may explain its repair but may not declare audit findings resolved. Only the independent reviewer determines whether each repair satisfies the previous finding. Supply the previous independent report as the follow-up scope, not a persuasive implementation summary. @@ -272,18 +297,7 @@ Run at most two automatic repair rounds; switching to repair-only mode does not ## Consolidated Project Implementation Audit -For a project change, `spec-implementation-audit` owns the applicable-item inventory, verdict semantics, evidence, and coverage for each audit mode. SPEC/code synchronization is a category in that audit, not a separate scan. Include these checks in the full first pass; in repair-only passes apply only those needed to resolve the previous findings: - -- [ ] Root `SPEC.md` module table matches actual modules. -- [ ] Root `SPEC.md` architecture diagram matches actual project dependencies. -- [ ] Module `SPEC.md` Public Interface matches exported public symbols. -- [ ] Module `SPEC.md` Dependencies match actual imports from other project modules. -- [ ] Module `SPEC.md` Internal Structure lists actual module files. -- [ ] Python Architecture section matches package layout, import direction, framework boundaries, and model boundaries. -- [ ] Parent and child frontend SPEC ownership matches the workspace and application directories without duplicated contracts. -- [ ] Frontend Public Interface, Data And State Flow, Internal Structure, and Frontend Architecture match entries, source, state ownership, transport boundaries, framework, and language. -- [ ] Frontend manifest, lock file, Vite configuration, generated-output policy, and required browser evidence match the confirmed specs. -- [ ] SPEC text contains current facts only; design process, historical narrative, target-state wording, future roadmap, and detailed test matrices are absent or moved elsewhere. +For a project change, `spec-implementation-audit` owns both coverage inventories, risk/domain checks, SPEC/code synchronization, verdict semantics, evidence assessment, and coverage for each audit mode and review lane. Apply its complete change-scope checks in the first pass and its repair/affected-boundary checks in later passes; do not add a separate synchronization scan or duplicate checklist here. Before claiming project completion, read and run: @@ -306,14 +320,16 @@ If project SPEC itself needs correction, stop project implementation, update and Do not claim completion while any blocking finding remains. Completion also requires: - a complete first audit plus complete repair-only coverage of each previous round's findings; +- complete forward and reverse coverage, including repair-introduced behaviors, with no unresolved grounding or scope gaps; +- all review lanes and verification tasks joined against the same frozen snapshot, with no pending verification-dependent verdicts or unresolved reviewer conflicts; - a matching post-audit artifact identity check linking the current worktree or immutable commit range to that audit chain; - the first pass's complete applicable-item inventory, with unaffected passing evidence unchanged; - concrete diff evidence and an initial or repair verdict for every item; - no unresolved implementation-fixable blocking finding in the carried-forward finding set; -- required verification run or unavailable verification reported as blocking; +- required verification passed; failed, missing, cancelled, or unavailable verification remains blocking; - any accepted `needs-human-decision` recorded explicitly. -These gates do not require a new full audit after repairs. Unrelated changes cannot inherit coverage and require a scope decision. +These gates do not require a new full audit after repairs. Unrelated changes cannot inherit coverage and require a scope decision. They govern Done, not whether Tech Lead can promptly deliver an accurate partial milestone under its role instructions. Pending required CI, review, or external approval remains blocking for the affected completion stage; do not relabel it to ship. ## Required Final Report @@ -323,5 +339,6 @@ End with: - Project specs updated and confirmed, or the no-SPEC-delta decision with precise SPEC and defect evidence. - Files implemented. - Verification commands run and results. +- Review-lane assignments, concurrency or serialization used, snapshot-matched verification evidence, and the joined forward/reverse coverage result. - Audited SPEC inputs, full and repair-only audit identities or exact commit ranges, post-audit identity result, and cumulative finding status. Distinguish the full first pass from later repair-only passes. - Complete current finding status, repair rounds performed, and any accepted human decisions. diff --git a/.github/skills/spec-implementation-audit/SKILL.md b/.github/skills/spec-implementation-audit/SKILL.md index f64f4b20..3451fac3 100644 --- a/.github/skills/spec-implementation-audit/SKILL.md +++ b/.github/skills/spec-implementation-audit/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true # SPEC Implementation Audit -Determine whether project-code or project-logic implementation from an explicitly invoked SDD workflow satisfies confirmed project specifications. This is a SPEC-centered, diff-based audit. It is not a general test pass check or a restatement of the implementer's summary. +Determine whether project-code or project-logic implementation from an explicitly invoked SDD workflow satisfies confirmed project specifications. This is a bidirectional, diff-based audit: SPEC-to-code checks completeness and correctness; code-to-SPEC checks grounding and task scope. It is not a general test pass check or a restatement of the implementer's summary. ## Invocation Gate @@ -29,7 +29,7 @@ Tests, lint, keyword scans, and implementation summaries are auxiliary evidence ## Audit Modes -- Round 1 uses `audit_mode=full`: run the complete scope and procedure below with all existing checks. +- Round 1 uses `audit_mode=full`: run the complete change-scope procedure below with every applicable check, not a repository-wide historical audit. - Round 2 and later use `audit_mode=repair-only`: audit only the repairs for the previous round's findings. Carry every unresolved earlier finding forward in that previous-round report so none is dropped. A repair-only pass reads the previous independent report, its audited snapshot, the complete repair delta, and the SPEC clauses and implementation paths needed to judge those repairs. It does not rebuild the full applicable-item inventory, re-read unchanged parts of the original diff, or search for unrelated new issues. Retain unaffected passing verdicts only when their evidence remains unchanged. @@ -47,18 +47,40 @@ Reviewer input is limited to: - Complete diff artifacts for the declared audit mode plus their identity manifest, or an exact commit range. - For repair-only passes, the previous independent report, its finding IDs and audited snapshot, and the complete delta from that snapshot to the repaired snapshot. - SPEC delta mode: `confirmed-update` or `no-delta`. +- Confirmed SPEC version and confirmation evidence, plus the authorized task scope and exclusions. These establish approval and scope, not a substitute for project SPEC. +- Assigned `review_lane=combined|forward|reverse`, coverage boundaries, and the verification plan/status for the same snapshot. - Minimal navigation instructions required to locate modules and public APIs. -- Optional verification command outputs as auxiliary evidence. +- Verifiable raw verification outputs or durable evidence references, with commands, exit status, tested inputs, relevant environment, and coverage; these support but never replace independent review. - For no-SPEC-delta work, the recorded SPEC references and neutral defect reproduction evidence as claims to verify, not accepted proof. Do not provide persuasive summaries such as "this is complete" or "tests pass, so it should be fine". ## Audit Input Integrity -For a worktree audit, validate the supplied artifact path, SHA-256, byte size, `diff --git` entry count, changed-path inventory, and any separate untracked-file artifacts for the declared audit mode. Read the complete in-scope artifacts, not terminal output or overflow wrappers. A repair-only manifest links the previous snapshot and report to the complete repair delta and verifies that code and SPEC evidence outside that scope is unchanged; identity verification does not require re-auditing unchanged content. If required evidence is missing, unreadable, truncated, wrapped, or inconsistent with its identity manifest, return `audit-blocked` without substituting a live diff or implementation summary. +For a worktree audit, validate the supplied artifact path, SHA-256, byte size, `diff --git` entry count, changed-path inventory, and any separate untracked-file artifacts for the declared audit mode. Read the complete in-scope artifacts, not terminal output or overflow wrappers. Use the single evidence package and compact manifest prepared by `spec-driven`; do not request a new repository copy at each handoff. A repair-only manifest links the previous snapshot and report to the complete repair delta and verifies that code and SPEC evidence outside that scope is unchanged; identity verification does not require re-auditing unchanged content. If required evidence is missing, unreadable, truncated, wrapped, or inconsistent with its identity manifest, return `audit-blocked` without substituting a live diff or implementation summary. Record the validated artifact identities in the audit result. The calling `spec-driven` workflow owns the post-audit comparison between these identities and a freshly regenerated worktree snapshot; the reviewer must not claim that later worktree changes are covered. For a commit-range audit, validate and report the exact immutable base and head object ids. +Require the exact root and relevant module SPEC versions, even when unchanged by the diff, and independently read them for the initial scope. Compare changed SPEC inputs with their confirmed versions; matching code and unconfirmed SPEC edits do not establish approval. Necessary source context outside the diff must come from the declared frozen workspace or immutable snapshot. Immutable Git object/path references are sufficient for unchanged content; do not demand all repository files or unrelated SPECs. This reduces copying, not completeness or integrity. + +## Verification Evidence + +Independently read the relevant tests and necessary call paths, then default to consuming verifiable matching raw test/CI evidence instead of requesting reruns for independence. Check exact commands, exit status, tested input identity, relevant environment, and coverage against the affected requirements and review snapshot. A passing summary alone is insufficient. + +Retain earlier results when those factors still match. Input, relevant environment, or coverage changes invalidate affected checks and verdicts, not unrelated proof; identify the precise gap for Tech Lead to assign the necessary verification under `spec-driven`. A new snapshot identifier alone does not invalidate checks whose actual inputs and coverage are unchanged. Missing or failed required evidence blocks its dependent conclusions; static review may continue. Do not require an empty download cache as a proxy for clean-install evidence. + +## Review Lanes + +Default to one independent Reviewer with `review_lane=combined`. Under the root cost principle and `spec-driven` scheduling rules, Tech Lead may assign `forward` and `reverse` lanes concurrently against the same complete snapshot when concrete risk and substantial separate context justify splitting and agent capabilities permit it. Both lanes read the relevant SPEC and actual implementation; lane names describe coverage responsibility, not restrictions to reading only one kind of evidence. + +- `forward`: owns the applicable SPEC inventory, implementation correctness, regressions, domain checks, and verification obligations. +- `reverse`: independently derives actual behavior changes and implementation boundaries from the diff and necessary paths, then checks SPEC grounding and authorized task scope. +- `combined`: owns both inventories and all checks. + +A split-lane report declares only its own coverage and cannot pass the whole audit. Tech Lead joins both reports, resolves gaps or conflicting verdicts with the reviewers, and preserves all findings and source IDs. Neither inventory may be omitted because the other lane passed. + +Verification may run concurrently under `spec-driven`. Apply the evidence rules above while it is pending; the responsible Reviewer finalizes dependent conclusions only after consuming matching results. Verification is never inferred from another lane's success. + ## First-Round Complete Scope Before judging implementation in round 1, establish the complete scope: @@ -67,25 +89,57 @@ Before judging implementation in round 1, establish the complete scope: - the complete current worktree diff or commit range; - the SPEC delta mode; - the complete set of applicable SPEC items; +- the complete set of in-scope added, changed, or removed behaviors and affected implementation boundaries, independently derived from code rather than filtered by known SPEC items; - the file, symbol, interface, dependency, configuration, or behavior boundaries relevant to each item; -Determine this initial scope independently. Later repair-only passes take their scope from the previous findings and repair delta rather than repeating this inventory. +Determine this initial scope independently for the assigned lane. Account for every changed path, including untracked files, tests, configuration, and behavior documentation. Group related changes by behavior; explain non-behavioral changes rather than requiring one SPEC clause per line. This is change-scope coverage, not a claim to audit all historical behavior. Later repair-only passes take their scope from the previous findings and repair delta rather than repeating this inventory. ## First-Round Complete Procedure -1. Establish the complete applicable SPEC item inventory before assigning final verdicts, including independent validation of a no-SPEC-delta decision when applicable. -2. Read the diff and relevant implementation path for every applicable item. -3. Apply the Python and frontend domain checks when those areas are in scope. +1. Establish both the applicable SPEC item inventory and the actual behavior inventory for the assigned lane before assigning final verdicts, including independent validation of a no-SPEC-delta decision when applicable. +2. Read the diff and relevant implementation paths for each item; independently trace actual behaviors back to SPEC and authorized scope. +3. Apply the correctness/risk checks below and the Python, frontend, package, browser, and visual domain checks when affected. 4. Record a verdict and concrete diff evidence for every item. -5. Consolidate duplicate observations of each blocking root cause and reference every affected SPEC item precisely. +5. Consolidate duplicate observations of each blocking root cause and reference every affected SPEC or behavior item precisely. When grounding is absent, record `SPEC basis: absent`; do not drop the finding for lack of a SPEC reference. 6. Record repair ownership as implementation, SPEC/human decision, or verification environment. 7. Record non-blocking quality feedback separately from SPEC verdicts. -8. Return one complete coverage table and the full finding set, with blocking gaps before quality/style feedback. +8. Return the assigned coverage tables and full finding set, with blocking gaps before quality/style feedback. The aggregate full audit requires both tables. -A blocking issue must not cause an early return. Complete the current pass before implementation repair or a human decision begins. The only early termination is `audit-blocked`, used when required audit input, a required tool, or a required artifact is unavailable. `audit-blocked` is not an implementation verdict, does not consume a repair attempt, and cannot satisfy the completion gate. +A finding alone must not cause an early return: complete the current pass before implementation repair or a finding-resolution decision begins. Missing required input, tools, or artifacts permit an early `audit-blocked` result; it is not an implementation verdict, does not consume a repair attempt, and cannot satisfy the completion gate. Root user-pause and safety/authorization stops still take precedence; interrupted coverage remains incomplete and cannot pass. If blocking gaps exist, return the complete result to `spec-driven`. The implementation agent may repair findings but may not mark them closed. +## Correctness And Risk Coverage + +For the change scope and directly affected consumers, independently inspect: + +- implementation correctness and completeness against requirements, public interfaces, module ownership, dependency direction, and architecture constraints; +- regressions, boundary/negative cases, external inputs/responses/configuration, validation, platform differences, and error/partial/unknown outcomes; +- state transitions, concurrency, cancellation, cleanup, persistence, retries/fallbacks, and external side effects; +- security, privacy, authorization, sensitive data, execution/replay capabilities, and evidence-collection boundaries; +- whether tests assert required observable behavior rather than just implementation details or success paths, and whether local/CI evidence actually covers the relevant risk. + +Judge applicability by behavior and impact, not diff size. A high-risk one-line change still needs its relevant call paths and boundary checks, but does not by itself justify a full local suite. Record concrete gaps rather than offering a zero-bug guarantee or treating passing tests as acceptance. + +## Code-to-SPEC Grounding + +Inspect observable behavior, public contracts, defaults, automatic target selection or execution, retries, fallbacks, error and partial-success semantics, state transitions, persistence, external side effects, configuration, ownership, and dependencies. Include removed behavior and behavior newly asserted by tests or promised by documentation. Passing tests and existing implementation are evidence of what happens, not authority for what should happen. + +Classify every behavior item: + +| Classification | Required evidence or action | +| --- | --- | +| `grounded` | Precise confirmed SPEC basis and authorized task scope. Grounding alone does not establish correct implementation. | +| `implementation-detail` | Explain how the change serves a grounded behavior without adding a product decision or changing observable behavior, contracts, side effects, error semantics, or architecture constraints; also establish task scope. | +| `ungrounded` | Record the absent basis and a blocking `spec-delta-required` finding owned by SPEC/human decision. | +| `conflicting` | Cite the contradiction and the applicable blocking verdict, such as `diverged` or `boundary-violation`. | +| `out-of-scope` | Record a blocking `needs-human-decision` finding even if the behavior is grounded in SPEC. | +| `unverified` | State the missing evidence and block coverage/completion; unavailable required audit inputs are `audit-blocked`. | + +Only `grounded` and justified `implementation-detail` pass reverse grounding, and neither waives forward findings. A broad module purpose or "internal logic" label is not sufficient justification. Do not require SPEC text for every helper or local variable. + +Code can reveal a requirement gap but cannot authorize its own requirement. For ungrounded behavior, Tech Lead obtains a decision to remove/correct the behavior within authorized scope or to update and confirm SPEC before reconciling implementation. Never automatically backfill SPEC to legitimize code already written. + ## No-SPEC-Delta Audit When the implementation used the no-SPEC-delta path, independently verify all of the following from current SPEC and the actual diff: @@ -125,6 +179,10 @@ For frontend-owned files, also verify the following within the declared audit mo Use `.github/skills/frontend-architecture/references/audit-checklist.md` for the full checklist. Missing browser or screenshot evidence is blocking when the confirmed SPEC requires it. +## Package And Installation Audit + +When packaging, dependencies, installation, or distribution behavior is affected, check the relevant manifests/lock files, declared package contents and entry points, compatibility/platform constraints, and install/runtime evidence against SPEC. Require a fresh installation environment and source-free execution where promised; isolated user configuration may reuse download caches unless the contract tests cache absence. Reused caches must not hide stale installed artifacts, missing packaged files, or unintended source-tree imports. Select evidence by affected contracts, not an automatic full test suite. + ## Structured Result Each applicable item records: @@ -138,7 +196,7 @@ Each applicable item records: Each finding records: - a stable finding ID retained across repair-only passes; -- affected SPEC items or precise requirement references; +- affected SPEC and behavior items or precise requirement references; explicitly absent grounding where applicable; - the distinct root cause; - blocking verdict and concrete evidence; - repair owner: implementation, SPEC/human decision, or verification environment; @@ -147,34 +205,34 @@ Duplicate observations of the same root cause are consolidated into one finding ## Repair-Only Follow-Up -An audit pass must finish and return its coverage table and full finding set for the declared scope before any implementation repair begins. Do not interleave audit and repair. +An audit pass must finish and return its assigned coverage tables and full finding set for the declared scope before any implementation repair begins. All review lanes and verification tasks join under `spec-driven` before a repair batch is issued. Do not interleave audit and repair. After an audit result: 1. Resolve any SPEC/human-decision or verification-environment blocker that can change or prevent implementation repair. 2. Repair every implementation-fixable blocking finding from that result in one batch. -3. Finish all verification affected by the complete repair batch. -4. Start an independent repair-only audit with the previous report, its snapshot, the complete repair delta, relevant SPEC clauses, and neutral verification evidence. -5. Judge every previous-round finding against the actual repair and its controlling path. Keep an unfixed or partially fixed finding open. A defect in the repair that prevents the same requirement from being met also keeps that finding open. +3. Freeze the complete repaired snapshot and select all verification affected by the repair batch. +4. Run affected verification and independent repair-only review concurrently where safe, using the previous aggregate report, its snapshot, the complete repair delta, relevant SPEC clauses, and neutral verification evidence. Join them before finalizing the pass. +5. Judge every previous-round finding against the actual repair and its controlling path. Keep an unfixed or partially fixed finding open. A defect in the repair that prevents the same requirement from being met also keeps that finding open. Reverse-trace all behavior changes introduced by the repair delta; record repair-introduced gaps with stable IDs linked to the originating finding. They cannot inherit earlier passing evidence. 6. Return a verdict for every previous-round finding and carry all remaining blockers forward. Repeat repair-only passes until none remain, subject to the repair limit below. Do not reopen unrelated passing items or expand the pass into a new full audit. Unrelated discoveries are separate feedback, not automatic additions to this repair batch. If unrelated code or SPEC changes invalidate inherited evidence, pause for a scope decision rather than claiming coverage for them. Run at most two automatic repair rounds. Switching from full to repair-only mode does not reset that limit. An `audit-blocked` result does not consume a repair round because no complete finding set is available to repair. If blocking findings remain after the second repair round, or one round makes no substantive progress, return the complete current finding status for human decision. -The implementation agent may not declare findings resolved. Only the independent reviewer may give a repaired finding verdict `implemented`; earlier unaffected passing verdicts remain backed by the initial audit and matching evidence. +The implementation agent may not declare findings resolved. Only the independent reviewer may close a repaired finding with the applicable passing SPEC verdict or reverse classification; earlier unaffected passing verdicts remain backed by the initial audit and matching evidence. ## Consolidated Synchronization Category -SPEC/code synchronization is part of the applicable-item inventory, not a standalone scan. Cover these items in the full first pass; in repair-only mode inspect only those needed to resolve previous findings: +SPEC/code synchronization is part of the applicable-item inventory, not a standalone scan. Cover applicable items within the complete change scope in the full first pass; in repair-only mode inspect the repairs and their affected boundaries: -- root module navigation and dependency direction; +- root module navigation/table, architecture diagram, and dependency direction against affected modules and actual dependencies; - module public interfaces and exports; - declared and actual dependencies; - internal structure and ownership; - Python architecture and boundary rules; - frontend parent/child ownership, state, transport, dependency, build, and generated-output contracts; -- current-fact SPEC hygiene. +- current-fact SPEC hygiene: exclude design-process/history/target-state narrative, future roadmap, and detailed test matrices that do not state current verification obligations. Report synchronization verdicts within the current audit mode's result, not as another audit pass. @@ -191,29 +249,37 @@ Report synchronization verdicts within the current audit mode's result, not as a - `spec-delta-required`: Current SPEC does not ground the changed behavior or would become inaccurate without an update. - `needs-human-decision`: SPEC and implementation cannot be reconciled without a product or design decision. -Any verdict except `implemented` is blocking unless the user explicitly accepts `needs-human-decision` as out of scope for the current change. +For SPEC-item verdicts, any verdict except `implemented` is blocking unless the user explicitly accepts `needs-human-decision` as out of scope for the current change. Reverse classifications use the grounding rules above. Deferring a finding does not authorize shipping an ungrounded or unauthorized change; reconcile the delivered scope and snapshot first. ## Required Output -For a full first pass, produce a complete item table: +For a full first pass, the forward or combined lane produces a complete item table: ```text SPEC item | Boundaries | Diff evidence | Verdict | Notes ``` +The reverse or combined lane also produces a complete behavior table: + +```text +Behavior ID | Actual behavior/change | Code evidence | SPEC basis or absent | Task scope basis | Classification | Rationale/gap +``` + +Account for every changed path in these tables or an explicit non-behavioral classification. The aggregate result includes both inventories, not just the findings. + For every pass, produce the complete finding table for its scope: ```text -Finding ID | Affected SPEC items | Root cause | Evidence | Verdict | Repair owner +Finding ID | Affected SPEC/behavior items | Root cause | Evidence | Verdict | Repair owner ``` -For repair-only passes, replace the full item inventory with a table covering every previous-round finding: +For repair-only passes, replace the full inventories with a table covering every previous-round finding and a scoped behavior table for the repair delta: ```text Previous finding ID | Repair delta evidence | Verification evidence | Verdict | Remaining gap ``` -State `audit_mode=full|repair-only`, `coverage_complete=true|false` for that mode's scope, `spec_delta_mode=confirmed-update|no-delta`, audited SPEC inputs, and validated diff artifact identities or exact commit range. A repair-only result also identifies the previous report and snapshot it extends. Do not describe scoped coverage as a new full audit. Each evidence entry must cite concrete files and, when possible, line numbers or changed symbols. If evidence is absent, say so directly. +State `audit_mode=full|repair-only`, `review_lane=combined|forward|reverse`, `coverage_complete=true|false` for that lane and mode's scope, `spec_delta_mode=confirmed-update|no-delta`, audited SPEC inputs and confirmation evidence, and validated diff artifact identities or exact commit range. State verification-dependent conclusions still pending. The aggregate result separately states forward and reverse coverage and verification status. A repair-only result also identifies the previous aggregate report and snapshot it extends. Do not describe scoped coverage as a new full audit. Each evidence entry must cite concrete files and, when possible, line numbers or changed symbols. If evidence is absent, say so directly. ## What Not To Accept @@ -222,6 +288,8 @@ State `audit_mode=full|repair-only`, `coverage_complete=true|false` for that mod - Keyword search as proof without reading the changed code path. - A design document as final authority after `SPEC.md` exists. - A `bugfix` or `no-spec-delta` label as proof that current SPEC needs no update. +- Code, tests, or unconfirmed SPEC edits as authorization for new behavior. +- A forward-only coverage table, a blanket implementation-detail exemption, or another lane's passing result as proof of reverse coverage. - Agent workflow instructions presented as proof that project behavior satisfies SPEC. - Public API declarations without backing behavior. - Mocks, stubs, hardcoded success paths, or placeholder fallbacks as production implementation. @@ -235,8 +303,10 @@ Before claiming completion, state: - Which validated snapshots or exact commit ranges connect the initial audit to the current implementation. - Which SPEC delta mode was audited and, for no-delta work, whether its classification was independently validated. - Whether the first full audit and every subsequent repair-only pass have complete coverage for their declared scopes. +- Whether both forward and reverse coverage are complete, every changed path is accounted for, and no ungrounded, conflicting, out-of-scope, or unverified behavior remains unresolved. +- Whether all review lanes and required verification have joined against the same snapshot, with pending evidence resolved by the responsible Reviewer. - Whether every applicable SPEC item is supported by an initial passing verdict or an independent repair verdict, with unaffected evidence unchanged. - Whether any unresolved blocking finding remains in the carried-forward finding set. - Any remaining `needs-human-decision` items accepted by the user. -Completion can be established by the full first pass plus the repair-only audit chain; it does not require another full audit. If a pass is incomplete, the evidence chain is broken, required verification is unavailable, or blocking gaps remain, do not claim completion. +Completion can be established by the full first pass plus the repair-only audit chain; it does not require another full audit. If a pass is incomplete, the evidence chain is broken, required verification is unavailable, or blocking gaps remain, do not claim completion. State the covered scope and residual limits; an audit is not a zero-bug guarantee, and a passed test suite alone is not Done. diff --git a/AGENTS.md b/AGENTS.md index 95019572..f464235d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,13 +28,14 @@ Run repository workflow skills only through an explicit user-invoked slash comma ## Shared Agent Team Protocol - **Entry and authorization.** Tech Lead is the normal user-facing coordinator for the FSQ development team. PM, Designer, Developer, and Reviewer work only from bounded task packages supplied by Tech Lead. The team does not change the write gates above: an ordinary project change request must stop before project writes and direct the user to `/spec-driven `. Workflow-control-only maintenance may proceed under the direct authorization described above. -- **Role boundaries.** PM owns requirement clarification, scope, and acceptance criteria. Designer owns user flows and interaction states when the change has a user-facing surface. Developer owns bounded implementation, related tests, and directly related documentation. Reviewer independently checks the authoritative SPEC, actual diff, regressions, and verification gaps. Tech Lead owns architecture, dependencies, orchestration, integration verification, user decisions, and final delivery. +- **Role boundaries.** Default to Tech Lead scoping/coordination, Developer implementation, and one independent combined Reviewer; specialist roles are conditional, not a mandatory sequence. PM resolves unresolved goals, acceptance criteria, or product tradeoffs. Designer resolves actual interaction or design choices. Developer owns bounded implementation, related tests, directly related documentation, and separately assigned verification-only tasks. Reviewer independently checks requirement-to-change correctness/completeness and change-to-requirement grounding/scope, including regressions and verification gaps; project requirements remain grounded in SPEC. Tech Lead owns architecture, dependencies, orchestration, integration verification, user decisions, and final delivery, not default code implementation. - **One task package.** Every handoff states a TaskID; authorization state; branch, HEAD, and worktree status; fixed requirement/design/SPEC references; goal and non-goals; allowed files and forbidden boundaries; dependencies and entry conditions; acceptance criteria; required validation; stop conditions; and the decision owner. Do not assume shared chat context or omit unresolved fields. -- **Ready and Done.** PM may recommend Ready, but Tech Lead decides Ready only after scope, acceptance criteria, dependencies, file ownership, and required authorization are settled. Developer returns pending-review work and never self-declares Done. Reviewer reads the original authority inputs and actual diff rather than relying on summaries. Tech Lead decides Done only after required verification and independent review; tests passing alone do not establish product acceptance. -- **Scheduling and rework.** Each Developer handles one implementation task at a time. Assign exclusive file ownership, never run same-file implementation in parallel, and start dependent work only after prerequisites are complete. Reviewer findings return to the original Developer. Stop non-progressing repair loops and report the blocker, owner, next step, resume condition, and required decision. +- **Ready and Done.** PM may recommend Ready, but Tech Lead decides Ready only after scope, acceptance criteria, dependencies, file ownership, and required authorization are settled. Developer returns pending-review work and never self-declares Done. Reviewer reads the original authority inputs and actual diff rather than relying on summaries. Tech Lead decides Done only after complete bidirectional independent coverage and passing required verification for the same final snapshot; tests or one review direction passing alone do not establish product acceptance. +- **Scheduling and rework.** Each Developer handles one implementation or verification-only task at a time. Assign exclusive file ownership, never run same-file implementation in parallel, and start dependent work only after prerequisites are complete. Read-only review and input-preserving verification may share a frozen snapshot and run concurrently under `.github/skills/spec-driven/SKILL.md`; resource conflicts require isolation or serialization. Tech Lead joins all results and resolves prerequisite decisions before returning one consolidated repair batch to the original Developer. No repair starts while review or verification is still running. Stop non-progressing repair loops and report the blocker, owner, next step, resume condition, and required decision. - **Durable truth.** Root and module `SPEC.md` files remain the project truth. GitHub Issues and pull requests may carry execution status and review evidence only when their creation or use is authorized. Chat, todos, and ad hoc Markdown are not a shadow requirements system. Read-only roles return structured results for Tech Lead to persist in authorized locations. +- **Proportionate work.** Reuse existing tools, tests, workflows, and valid evidence. Every extra agent, helper, check, or scope expansion must address a concrete SPEC/acceptance-criterion risk or evidence gap, not process for its own sake. Prefer a bounded existing check over a generic multi-mode validation framework; do not trade away required coverage, independence, permissions, or safety to reduce cost. - **Delivery package.** Every role returns the TaskID, completed work, actual scope, delivery version or inspectable diff, each acceptance criterion as pass/fail/unverified/blocked with evidence, commands and results, unverified paths, limits, blockers, and decision owners. Tech Lead preserves failures and distinguishes implementation, review, verification, and user-visible completion. -- **Safety.** Tools grant capability, not authorization. Waiting for clarification, credentials, user interaction, external-system permission, destructive-operation approval, or SPEC confirmation is a blocker rather than permission to guess or bypass. Preserve unrelated user changes and never broaden scope silently. +- **Safety.** Tools grant capability, not authorization. Waiting for clarification, credentials, user interaction, external-system permission, destructive-operation approval, or SPEC confirmation is a blocker rather than permission to guess or bypass. Preserve unrelated user changes and never broaden scope silently. GitHub writes require authorization; PR creation is not merge or release approval. Never bypass network or organization policy. A user pause stops new work and monitoring within the paused scope until the user resumes it. New Python source files must start with: