# cross_technology_quality_platform **Repository Path**: simplelove520/cross_technology_quality_platform ## Basic Information - **Project Name**: cross_technology_quality_platform - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-12 - **Last Updated**: 2026-09-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Cross-Technology Quality Platform ## V3 Autonomous Context-Aware SDD Automation 本项目使用 `.specify/workflows/quality-platform-sdd/workflow.yml` 和 `sddctl` 管理按 Feature 执行的 SDD 生命周期。V3 不把完整阶段 Prompt 写死在路线索引中； 每个阶段会先读取对应的 `.specify/prompts/builders/-builder.md`，再按当前仓库资料生成该阶段 输入。 ### 权威资料和路线 每个待开发 Feature 的最小路线定义位于： ```text .specify/roadmap//feature.yaml ``` 路线文件只描述目标、依赖、范围、排除项和约束。阶段输入按需读取： ```text .specify/memory/constitution.md docs/product/platform-prd.md docs/architecture/target-architecture.md docs/sdd-context-map.yaml .specify/roadmap//feature.yaml specs// 的当前产物 已完成 Feature 的相关验收/合同/决策 ``` Builder 要求每个事实或决定标记为： - `SOURCE-DERIVED`：来自明确的权威资料或已有批准产物，并注明来源。 - `INFERRED`：为完成当前阶段而作的最小推断，并说明理由。 - `UNRESOLVED`：资料冲突、缺失或需要人工决定；不能用猜测替代。 Codex/Spec Kit 不得发明需求、扩大 Feature 范围或把 Legacy 实现结构当作 目标架构。 每个阶段还必须生成结构化 `agent-report.json` 到 Runner 分配的 Agent-writable staging path（`.sdd-runtime////`）。 Runner 读取、校验并原子发布到 authoritative attempt ledger；Agent 不得直接 写入 `.specify/runs/**`。 Report 的 `SOURCE-DERIVED` 条目必须带 `source_path`、`locator` 和 `authority_dimension`；`INFERRED` 必须带 `justification`；`UNRESOLVED` 必须带 `claim`、`reason` 和 `material`。Report 身份必须与 run、stage、attempt 完全一致， 否则阶段保留已有产物但以 `invalid_agent_report` 安全阻塞。 `stage_outcome` 只表示 Stage Execution Outcome，唯一允许的值是 `COMPLETED`、`PARTIAL`、`FAILED`、`BLOCKED`。Stage 已成功执行但仍发现 Material UNRESOLVED 时，仍使用 `COMPLETED`，并在 `gate_facts` 中记录语义事实； Gate Policy 决定是否进入 Clarify 或 Human Review，不把复合语义塞入 outcome。 Structured `gate_facts` 使用按 Stage 定义的 typed contract，而不是任意 `dict[str, bool | int | str]`。例如 Specify 只允许非负整数的 `material_unresolved_count`、`source_derived_claim_count`、 `inferred_claim_count` 和 `unresolved_claim_count`。`next_stage`、 `semantic_readiness`、`clarify_required`、`checklist_status` 以及 `write_scope_compliant` 等 Runner/Gate-owned 字段不得由 Agent 报告；Runner 从实际执行、Manifest 和 mutation evidence 计算这些事实，Gate 再依据 Gate Policy 决定路由。旧的 `list[str]` 形式仍可读取，但不会覆盖 Runner 或 Route ownership。 ### 常用命令 ```bash ./sdd_roadmap.sh list ./sdd_roadmap.sh next ./sdd_roadmap.sh 002 ./sdd_roadmap.sh resume ./sddctl start 002 --delivery branch-pr ./sddctl status ./sddctl resume ./sddctl validate-local ./sddctl deliver ``` `list` 显示所有 V3 路线；`next` 选择第一个尚未生成 `specs//` 产物 的 Feature；数字命令只执行一个 Feature。开始新 Feature 前要求 Git 工作树 干净，并且所有人工质量 Gate 都必须明确批准。V3 只执行 Feature 002；003–015 保留为精简路线定义，不会被自动启动。`sddctl` 使用独立 feature worktree、 持久化 run ledger 和 resume 状态；它不会自动 commit 或 push。每个 Run 使用由 `feature_id + run_id` 确定的独立 working branch 和 worktree；历史 BLOCKED/FAILED Run 不会永久占用 Feature 的启动入口。 根目录启动器会选择可用的 Python 3.12+；如需固定解释器，可设置 `SDD_PYTHON=/path/to/python`。 生命周期为： ```text context-aware specify → 人工 Gate → clarify → 人工 Gate → plan → 人工 Gate → tasks → analyze → 人工 Gate → implement → bounded convergence（最多三次评估） → acceptance briefing → feature acceptance → candidate freeze → validate-local → delivery Gate → one exact delivery commit → push/release validation → provider reconciliation ``` `resume ` 只按 ledger 中记录的 next action 继续执行；不要通过“最新任务” 猜测远端身份。候选 `candidate_id` 绑定本地验证、验收和 delivery gate，候选 改变会使旧批准失效。发布验证只接受 clean 且与 upstream 同步的 delivery commit。 `PR_REQUESTING` 遇到崩溃时先 reconcile，`AWAITING_PROVIDER` 表示已完成本地/发布 检查但缺少授权 provider；不确定结果进入 `PR_RECONCILIATION_REQUIRED`，不会盲目重建 PR。 收敛阶段必须把停滞或无进展转成显式人工审查，而不是无限重试。 Spec Kit subprocess 默认有 600 秒的单阶段 timeout；可通过构造 `SpecKitStageExecutor(..., timeout_seconds=...)` 覆盖。timeout 或 Ctrl-C 会终止该 子进程组并回收 partial stdout/stderr，Runner 将结果持久化为 `INTERRUPTED`，保留 终止原因、输出哈希、原始输出和 mutation evidence。后续 `resume` 进入 `HUMAN_REVIEW`，不会重复执行同一个已中断 attempt。 当前 public V3 Runner 已自动编排 Feature 002 的 semantic stages，直到 `READY_FOR_DELIVERY`；`validate-local` 和 `deliver` 仍是受保护的下游边界， 在 candidate/delivery controller 接入前不会伪造验证、commit 或 push 成功。 ### 从 V1 迁移 `.specify/quality-platform-roadmap.json` 现在只是 prompt-free 兼容索引，真正 的路线来源是 `.specify/roadmap/`。新增 Feature 时创建一个同结构的 `feature.yaml`，不要再向 JSON 写入 `spec`、`plan` 或阶段 Prompt。修改产品 意图应更新 PRD/Feature spec；修改实现结构应更新 target architecture/ADR， 而不是把这些内容塞回路线文件。 ### V3 安全边界 runner 只治理仓库可见的文件、Git worktree、候选树和持久化证据；它不是主机级 sandbox，也不声称隔离任意网络或外部副作用。阶段输入必须区分 `SOURCE-DERIVED`、`INFERRED`、`UNRESOLVED`，资料冲突或缺失时进入人工 Gate。 阶段 mutation 分为三类：Feature changes（可进入 candidate）、control-plane changes（仅限经过 identity 校验的 `.specify/workflows/runs//**`）和 unrelated changes。Control-plane metadata 不进入 DeliveryCandidate；外来 workflow ID、`.specify` 其他路径、路径遍历 或 symlink escape 都会被拒绝。Runner Result 同时保存三类路径、scope 校验结果、原始 stdout/stderr 和结构化 report，避免把安全控制和业务产物混在一个 changes 列表中。 ### 回归验证 ```bash python -m pytest -q bash -n sdd_roadmap.sh specify workflow info .specify/workflows/quality-platform-sdd/workflow.yml ./final_acceptance.sh ``` `final_acceptance.sh` 是闭合提交上的平台回归检查；它要求工作树干净且本地 HEAD 与 upstream 同步。实施阶段产生未提交改动时，先完成审查和提交，再按 项目发布流程重新运行该脚本。