@pzy560117/codex-harness 0.1.6 → 0.1.8

package/README.md

@@ -26,6 +26,8 @@ npm install -g @pzy560117/codex-harness
 harness
 ```
 
+执行 `harness init` 时如果发现 `%USERPROFILE%\\.codex\\packages\\codex-harness\\` 的用户级 package cache 缺失或版本落后，会先自动刷新这层共享缓存，再继续项目初始化。
+
 ## Quick Start
 
 ### 1. 初始化当前项目
@@ -37,6 +39,7 @@ harness init
 ```
 
 如果当前目录还不是 Git 仓库，CLI 会调用安装器并按默认策略初始化项目所需的 Harness runtime。
+如果用户级 package cache 版本落后，CLI 会先自动补齐 `install-user.ps1` 对应的共享缓存。
 
 ### 2. 运行 doctor
 
@@ -103,7 +106,7 @@ harness init --plan
 ### 钉住远程版本初始化
 
 ```powershell
-npx @pzy560117/codex-harness init --version 0.1.6
+npx @pzy560117/codex-harness init --version 0.1.8
 ```
 
 适合 release smoke 或回滚到某个已发布版本。

package/lib/commands/init.js

@@ -9,7 +9,8 @@ import {
   getDownloadedShaPath,
   getDownloadedZipPath,
   getPackageInstallRoot,
-  getReleaseAssetNames
+  getReleaseAssetNames,
+  getUserPackageLockPath
 } from "../release/cache-layout.js";
 import { downloadToFile, fileExists } from "../release/download-release.js";
 import { buildReleaseAssetUrl } from "../release/release-config.js";
@@ -27,6 +28,57 @@ function getCliPackageRoot() {
   return path.resolve(import.meta.dirname, "..", "..");
 }
 
+async function readManifestVersion(packageRoot) {
+  const manifestPath = path.join(packageRoot, "install-manifest.json");
+  const manifestDocument = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+  const version = typeof manifestDocument.version === "string" ? manifestDocument.version.trim() : "";
+  if (version === "") {
+    throw new Error(`install-manifest.json 缺少 version: ${manifestPath}`);
+  }
+
+  return version;
+}
+
+async function readInstalledUserCacheVersion(userProfile) {
+  const lockPath = getUserPackageLockPath(userProfile);
+  if (!fileExists(lockPath)) {
+    return "";
+  }
+
+  try {
+    const lockDocument = JSON.parse(await fs.readFile(lockPath, "utf8"));
+    return typeof lockDocument.version === "string" ? lockDocument.version.trim() : "";
+  } catch {
+    return "";
+  }
+}
+
+export function shouldRefreshUserPackageCache(expectedVersion, installedVersion, installRootExists) {
+  if (!installRootExists) {
+    return true;
+  }
+
+  return expectedVersion !== installedVersion;
+}
+
+async function ensureUserPackageCache(options) {
+  const expectedVersion = await readManifestVersion(options.packageRoot);
+  const installedVersion = await readInstalledUserCacheVersion(options.userProfile);
+  const expectedInstallRoot = getPackageInstallRoot(options.userProfile, expectedVersion);
+
+  if (!shouldRefreshUserPackageCache(expectedVersion, installedVersion, fileExists(expectedInstallRoot))) {
+    return;
+  }
+
+  const scriptPath = path.join(options.packageRoot, "tools", "install", "install-user.ps1");
+  process.stdout.write(`刷新用户级 codex-harness 缓存到 ${expectedVersion}...\n`);
+  const args = [];
+  if (options.force) {
+    args.push("-Force");
+  }
+  await invokePowerShellScript(scriptPath, args, { cwd: options.packageRoot });
+}
+
 export async function initCommand(options) {
   const localPackageRoot = getLocalPackageRoot();
   const embeddedPackageRoot = path.join(getCliPackageRoot(), "package-source");
@@ -80,6 +132,14 @@ export async function initCommand(options) {
     effectivePackageRoot = packageInstallRoot;
   }
 
+  if (!options.plan) {
+    await ensureUserPackageCache({
+      packageRoot: effectivePackageRoot,
+      userProfile,
+      force: options.force
+    });
+  }
+
   const scriptPath = path.join(effectivePackageRoot, "tools", "install", "install-agent.ps1");
   const args = ["-ProjectRoot", projectRoot];
 

package/lib/release/package-source-layout.js

@@ -1,13 +1,25 @@
 export const RELEASE_SOURCE_ENTRIES = [
-  "AGENTS.md",
-  "README.md",
-  "PACKAGE.md",
-  "install-manifest.json",
-  "install-manifest.schema.json",
-  "tools/install",
-  "docs/codex-harness-engineering/templates"
+  { source: "AGENTS.md", destination: "AGENTS.md" },
+  {
+    source: "docs/codex-harness-engineering/templates/package-assets/root/README.md",
+    destination: "README.md"
+  },
+  {
+    source: "docs/codex-harness-engineering/templates/package-assets/root/PACKAGE.md",
+    destination: "PACKAGE.md"
+  },
+  { source: "install-manifest.json", destination: "install-manifest.json" },
+  {
+    source: "install-manifest.schema.json",
+    destination: "install-manifest.schema.json"
+  },
+  { source: "tools/install", destination: "tools/install" },
+  {
+    source: "docs/codex-harness-engineering/templates",
+    destination: "docs/codex-harness-engineering/templates"
+  }
 ];
 
 export function shouldIncludeReleaseSource(relativePath) {
-  return RELEASE_SOURCE_ENTRIES.includes(relativePath);
+  return RELEASE_SOURCE_ENTRIES.some((entry) => entry.source === relativePath || entry.destination === relativePath);
 }

package/package-source/AGENTS.md

@@ -7,6 +7,13 @@
 - 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
 - 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。
 
+## 任务结构硬门禁
+
+- 未经用户明确同意，不得把标准 `task.json` 模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
+- P0/P1 项目禁止跳过 `TESTCASE-001`；缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`ACCEPTANCE_CRITERIA.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md`、`verify-matrix.md` 任一项，都不得生成最终 `task.json`。
+- `feature_impl` 没有 `qa_contract` 不得进入正式任务队列；`qa_contract` 没有完整 `tdd_contract`、`development_validation`、`acceptance_validation` 不得开始实现。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
+
 ## 目录级规则
 
 - 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：

package/package-source/PACKAGE.md

@@ -25,19 +25,19 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agen
 显式 thin project：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope project
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope project
 ```
 
 显式 legacy full：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
 ```
 
 显式 vendor：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
 ```
 
 ## Smoke

package/package-source/README.md

@@ -4,34 +4,9 @@
 
 SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
 
-## 云端 CLI 安装
+## 安装
 
-全局安装：
-
-```powershell
-npm install -g @pzy560117/codex-harness
-```
-
-一次性使用：
-
-```powershell
-npx @pzy560117/codex-harness init
-```
-
-项目内常用命令：
-
-```powershell
-harness init
-harness doctor
-harness verify
-harness run
-```
-
-`harness init` 优先使用 npm 包内置的 `package-source/` 完成初始化；只有在 npm 包未携带内置 source 时，才回退到 GitHub Release 下载 package source 到 `%USERPROFILE%\.codex\packages\codex-harness\<version>\`。项目级 `.agents/skills/` 与 `.agents/workflows/` 仍只安装到当前项目，不会提升成全局 active surface。
-
-## 本地源码安装
-
-从包含 `agent/` 包目录的项目父目录运行：
+从包含 当前仓库包根目录的项目父目录运行：
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
@@ -40,46 +15,38 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agen
 从已安装的 `.agents/` 自更新：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
 ```
 
 ## 安装产物
 
 - 项目根 `AGENTS.md`
-- `tools/harness/` 下的 `codex-loop.ps1`、`doctor.ps1`、`verify.ps1`
-- `tools/install/` 下的 `bootstrap-codex-harness.ps1`、`env-check.ps1`、安装脚本
+- `tools/harness/` 下的 `tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`
+- `tools/install/` 下的 `tools/install/bootstrap-codex-harness.ps1`、`tools/install/env-check.ps1`、安装脚本
 - 项目根 `task.json`、`progress.txt`
-- `tools/harness/templates/` 下的 `smoke-task.json`、`project-task-template.json`
+- `tools/harness/templates/` 下的 `smoke-task.json`、`tools/harness/templates/project-task-template.json`
 - `docs/harness/trace.schema.json`
 - 项目根 `.codex/`
-- 项目根 `.agents/` active surface，包括 skills、workflows 和安装后需要的运行辅助面
-
-说明：
-
-- 默认 `thin project` 安装不会把 `docs/harness/`、`docs/testing/`、`docs/knowledge/` 整包复制到项目根。
-- 这些深文档默认位于 `.codex-harness/state/config.json` 里的 `packageRoot` 下；只有显式 `-Mode full` / legacy full 场景才会在项目根保留完整副本。
+- 项目根 `docs/harness/`、`docs/testing/`
+- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
 
 ## 使用顺序
 
 1. 读取项目根 `AGENTS.md`。
-2. 如果项目根存在 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*`，直接读取；若是 thin project 且这些文件缺失，则先读 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下读取同路径文件。
+2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
 3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
 4. 将确认后的任务写入 `task.json`。
 5. 运行：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/verify.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1
 ```
 
 ## 验证安装包
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
 ```
 
-发布产物会输出到 `dist/release/<version>/`，包含：
-
-- `codex-harness-<version>-win.zip`
-- `codex-harness-<version>-win.sha256`
-- `release-manifest.json`
+该脚本现在只验证 full 安装形状。

package/package-source/docs/codex-harness-engineering/templates/bootstrap-codex-harness.ps1

@@ -57,7 +57,7 @@ function Resolve-TemplateRoot {
     }
 
     $agentsTemplate = Join-Path $resolved "runtime\AGENTS.md"
-    $driverTemplate = Join-Path $resolved "runtime\codex-loop.ps1"
+    $driverTemplate = Join-Path $resolved "runtime\codex-loop.ps1"
     if ((Test-Path -LiteralPath $agentsTemplate) -and (Test-Path -LiteralPath $driverTemplate)) {
       return $resolved
     }
@@ -225,16 +225,28 @@ function Ensure-TaskFile {
     return Copy-ManagedFile -SourceRoot $SourceRoot -SourceRelativePath "runtime\task.json" -DestinationRoot $DestinationRoot -DestinationRelativePath "task.json" -Overwrite:$true
   }
 
-  $taskDocument = $taskContent | ConvertFrom-Json
-  if ($null -eq $taskDocument.runtime) {
-    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
-  }
-
-  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
-    $taskDocument.runtime.driver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1"
-    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
-    return [PSCustomObject]@{
-      Path = $taskPath
+  $taskDocument = $taskContent | ConvertFrom-Json
+  if ($null -eq $taskDocument.runtime) {
+    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
+  }
+
+  $canonicalDriver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1"
+  $driverPattern = 'tools[\\/]+harness[\\/]+tools[\\/]+harness[\\/]+codex-loop\.ps1'
+
+  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
+      Action = "updated"
+    }
+  }
+
+  if ([string]$taskDocument.runtime.driver -match $driverPattern) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
       Action = "updated"
     }
   }
@@ -293,11 +305,25 @@ function Resolve-LockManifestSourcePath {
   return Join-Path $PackageRoot ($normalizedSource.Replace('/', '\'))
 }
 
-function Get-FileSha256 {
-  param([string]$Path)
-
-  return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
-}
+function Get-FileSha256 {
+  param([string]$Path)
+
+  $hashAlgorithm = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $stream = [System.IO.File]::OpenRead($Path)
+    try {
+      $hashBytes = $hashAlgorithm.ComputeHash($stream)
+    }
+    finally {
+      $stream.Dispose()
+    }
+  }
+  finally {
+    $hashAlgorithm.Dispose()
+  }
+
+  return ([System.BitConverter]::ToString($hashBytes)).Replace('-', '').ToLowerInvariant()
+}
 
 function Add-LockManagedFile {
   param(
@@ -561,13 +587,14 @@ $results = @()
 
 $rootFiles = @(
   @{ Source = "runtime\AGENTS.md"; Destination = "AGENTS.md" },
-  @{ Source = "tools/install/bootstrap-codex-harness.ps1"; Destination = "tools\\install/bootstrap-codex-harness.ps1" },
-  @{ Source = "runtime\codex-loop.ps1"; Destination = "tools\\harness/codex-loop.ps1" },
-  @{ Source = "runtime\doctor.ps1"; Destination = "tools\\harness/doctor.ps1" },
+  @{ Source = "bootstrap-codex-harness.ps1"; Destination = "tools\install\bootstrap-codex-harness.ps1" },
+  @{ Source = "runtime\codex-loop.ps1"; Destination = "tools\harness\codex-loop.ps1" },
+  @{ Source = "runtime\doctor.ps1"; Destination = "tools\harness\doctor.ps1" },
   @{ Source = "config\codex-config.toml"; Destination = ".codex\config.toml" },
   @{ Source = "config\codex-readme.md"; Destination = ".codex\README.md" },
-  @{ Source = "hooks\hooks.json"; Destination = ".codex\hooks.json" },
+  @{ Source = "hooks\hooks.json"; Destination = ".codex\hooks.json" },
   @{ Source = "hooks\hook-stop-verify.ps1"; Destination = "tools\harness\hook-stop-verify.ps1" },
+  @{ Source = "scripts\harness\harness-governance-check.ps1"; Destination = "scripts\harness\harness-governance-check.ps1" },
   @{ Source = "scripts\ai-workflow\check-ai-sync-drift.ps1"; Destination = "tools\install\ai-workflow\check-ai-sync-drift.ps1" },
   @{ Source = "runtime\task-run-profile.json"; Destination = ".codex\task-run-profile.json" },
   @{ Source = "prompts\implement-one-task.md"; Destination = ".codex\prompts\implement-one-task.md" },
@@ -586,33 +613,16 @@ $rootFiles = @(
   @{ Source = "prompts\worker-role\harness-writer.md"; Destination = ".codex\prompts\worker-role\harness-writer.md" },
   @{ Source = "runtime\smoke-task.json"; Destination = "tools\harness\templates\smoke-task.json" },
   @{ Source = "runtime\project-task-template.json"; Destination = "tools\harness\templates\project-task-template.json" },
-  @{ Source = "runtime\verify.ps1"; Destination = "tools\\harness/verify.ps1" },
-  @{ Source = "tools\harness\spec-lint.ps1"; Destination = "tools\\harness/spec-lint.ps1" },
-  @{ Source = "tools\harness\docs-lint.ps1"; Destination = "tools\\harness/docs-lint.ps1" },
-  @{ Source = "tools\harness\data-lint.ps1"; Destination = "tools\\harness/data-lint.ps1" },
-  @{ Source = "tools\harness\integration-lint.ps1"; Destination = "tools\\harness/integration-lint.ps1" },
-  @{ Source = "tools\harness\mobile-lint.ps1"; Destination = "tools\\harness/mobile-lint.ps1" },
-  @{ Source = "tools\harness\acceptance-lint.ps1"; Destination = "tools\\harness/acceptance-lint.ps1" },
-  @{ Source = "tools\harness\context-lint.ps1"; Destination = "tools\\harness/context-lint.ps1" },
-  @{ Source = "tools\harness\architecture-lint.ps1"; Destination = "tools\\harness/architecture-lint.ps1" },
-  @{ Source = "tools\harness\directory-lint.ps1"; Destination = "tools\\harness/directory-lint.ps1" },
-  @{ Source = "tools\harness\component-lint.ps1"; Destination = "tools\\harness/component-lint.ps1" },
-  @{ Source = "tools\harness\business-lint.ps1"; Destination = "tools\\harness/business-lint.ps1" },
-  @{ Source = "tools\harness\contract-lint.ps1"; Destination = "tools\\harness/contract-lint.ps1" },
-  @{ Source = "tools\harness\state-lint.ps1"; Destination = "tools\\harness/state-lint.ps1" },
-  @{ Source = "tools\harness\ui-lint.ps1"; Destination = "tools\\harness/ui-lint.ps1" },
-  @{ Source = "tools\harness\backend-lint.ps1"; Destination = "tools\\harness/backend-lint.ps1" },
-  @{ Source = "tools\harness\security-lint.ps1"; Destination = "tools\\harness/security-lint.ps1" },
-  @{ Source = "tools\harness\testing-lint.ps1"; Destination = "tools\\harness/testing-lint.ps1" },
-  @{ Source = "tools\harness\impact-lint.ps1"; Destination = "tools\\harness/impact-lint.ps1" },
-  @{ Source = "tools\harness\performance-lint.ps1"; Destination = "tools\\harness/performance-lint.ps1" },
-  @{ Source = "tools\harness\config-lint.ps1"; Destination = "tools\\harness/config-lint.ps1" },
-  @{ Source = "tools\harness\observability-lint.ps1"; Destination = "tools\\harness/observability-lint.ps1" },
-  @{ Source = "tools\harness\refactor-lint.ps1"; Destination = "tools\\harness/refactor-lint.ps1" },
-  @{ Source = "tools\harness\session-lint.ps1"; Destination = "tools\\harness/session-lint.ps1" },
-  @{ Source = "tools\harness\style-lint.ps1"; Destination = "tools\\harness/style-lint.ps1" },
-  @{ Source = "config\tools/install/env-check.ps1"; Destination = "tools\\install/env-check.ps1" },
-  @{ Source = "trace\docs/harness/trace.schema.json"; Destination = "docs\\harness/trace.schema.json" }
+  @{ Source = "tools\harness\task-structure-lint.ps1"; Destination = "tools\harness\task-structure-lint.ps1" },
+  @{ Source = "runtime\verify.ps1"; Destination = "tools\harness\verify.ps1" },
+  @{ Source = "tools\harness\docs-lint.ps1"; Destination = "tools\harness\docs-lint.ps1" },
+  @{ Source = "tools\harness\data-lint.ps1"; Destination = "tools\harness\data-lint.ps1" },
+  @{ Source = "tools\harness\integration-lint.ps1"; Destination = "tools\harness\integration-lint.ps1" },
+  @{ Source = "tools\harness\mobile-lint.ps1"; Destination = "tools\harness\mobile-lint.ps1" },
+  @{ Source = "tools\harness\acceptance-lint.ps1"; Destination = "tools\harness\acceptance-lint.ps1" },
+  @{ Source = "tools\harness\session-lint.ps1"; Destination = "tools\harness\session-lint.ps1" },
+  @{ Source = "config\env-check.ps1"; Destination = "tools\install\env-check.ps1" },
+  @{ Source = "trace\trace.schema.json"; Destination = "docs\harness\trace.schema.json" }
 )
 
 foreach ($file in $rootFiles) {
@@ -735,7 +745,6 @@ if ($Profile -eq "legacy" -and $IncludeDocs) {
     @{ Source = "docs\prompt-knowledge-integration.md"; Destination = "docs/harness/prompt-knowledge-integration.md" },
     @{ Source = "docs\mcp-knowledge-governance.md"; Destination = "docs/harness/mcp-knowledge-governance.md" },
     @{ Source = "docs\code-semantics-and-navigation.md"; Destination = "docs/harness/code-semantics-and-navigation.md" },
-    @{ Source = "docs\code-style-and-naming.md"; Destination = "docs/harness/code-style-and-naming.md" },
     @{ Source = "docs\rule-governance.md"; Destination = "docs/harness/rule-governance.md" },
     @{ Source = "docs\regression-rules.md"; Destination = "docs/harness/regression-rules.md" },
     @{ Source = "docs\team-knowledge-sync.md"; Destination = "docs/harness/team-knowledge-sync.md" },

package/package-source/docs/codex-harness-engineering/templates/docs/new-project-usage.md

@@ -27,6 +27,8 @@
 
 `full` 行为作为显式 legacy 兼容入口保留。当前包已经提供 package lock、只读升级/卸载计划、安全 `-Upgrade` 和 vendor `-Uninstall`。新分层入口优先使用 wrapper 或等价 `-Scope user|project|vendor` 命令：`tools\\install/install-user.ps1` 等价于 `tools\\install/install-agent.ps1 -Scope user`，`tools\\install/init-project.ps1` 等价于 `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project`。当前不提供 `harness install-user` 子命令。当前不提供 `harness init-project` 子命令。Windows PowerShell 主链路请直接运行这两个 wrapper，避免误以为存在独立 CLI。`-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 输出，只生成项目运行必需 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/ai/`、`docs/architecture/constraints.md`、`docs/spec/01..14` 和 `tools/`，不复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。`-Scope user` 只安装用户级 package source 并写入用户级 lock。
 
+如果你是通过全局 npm CLI 执行 `harness init`，当前实现会先检查 `%USERPROFILE%/.codex/packages/codex-harness/` 的 user package cache；发现缺失或版本落后时，会自动执行等价于 `install-user.ps1` 的刷新，再继续项目初始化。只有在 `harness init --plan` 下，这层缓存不会被改写。
+
 ## `docs/ai/` 导航层
 
 - `repo-map.md`

package/package-source/docs/codex-harness-engineering/templates/docs/task-session-strategy.md

@@ -26,12 +26,16 @@
 - 标准交接入口是 `tools/harness/templates/project-task-template.json`，首个任务固定为 `INIT-001`，用于锁定 spec 输入、任务依赖、验证矩阵、`execution.mode` 和 owned paths。
 - 如果 `task.json` 为空文件，先初始化为合法 JSON；如果仍是 smoke 模板或示例任务，先替换为当前项目真实任务。
 - 交互开发模式可以决定新增或更新哪些待办任务，但实际写入必须委派给 `harness-writer` 等匹配 writer。
+- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
 - 任务进入 driver 前必须冻结交付语义：`scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`。不适用字段必须写 `not_applicable`，不能留给实现会话猜。
 - 进入实现前，`docs/ai/CURRENT_TASK.md` 必须能回答本轮已完成内容、剩余问题、修改文件、测试结果、风险点和下一步，不允许只靠聊天记忆续跑。
+- `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 的 testing truth source 产物必须在生成最终 `task.json` 前补齐：`docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/REGRESSION_PLAN.md`、`docs/testing/verify-matrix.md`。缺任一项都不得进入正式任务队列。
 - 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`requirement_ids`、`owned_paths`、`context_files`、`produces_artifacts`、`test_command`、`acceptance`、自然语言测试用例、测试数据、开发验证、最终验收验证、证据路径和 `qa_contract`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
 - PRD / 需求文档完成后、进入实现前必须有自然语言测试用例阶段；每条 P0/P1 需求必须按 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并回溯到 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
 - 每个 `feature_impl` 任务必须声明两段验证：`development_validation` 用于编码过程中的 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint；`acceptance_validation` 用于代码写完后从用户故事入口重新跑完整链路。
 - 每个 `feature_impl.qa_contract.tdd_contract.red.source_case_ids` 必须能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；缺少自然语言用例来源时不得进入实现阶段。
+- 每个 `feature_impl.qa_contract.required_layers` 必须至少包含 `unit_or_component`、`contract_or_api`、`story_full_chain`、`affected_regression`；`tdd_contract` 必须同时包含 `red`、`green`、`refactor_guard`，且 `source_case_ids` 不得为空。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。只有用户明确批准时，才允许在任务中增加 `decomposition_exemption` 记录例外原因。
 - 不适合作为 TDD RED 的自然语言用例必须通过 `story_full_chain.source_case_ids`、`acceptance_validation.source_case_ids`、回归计划或 `verify-matrix` 进入验收链路；不得只保留在 PRD 或测试设计文档中。
 - 每个 `feature_impl` 的验收链路必须包含入口、动作、Oracle、副作用/无副作用证据、测试数据、失败态证据和 release 影响。单元测试、小范围 smoke、静态检查或 `git diff --check` 只能作为开发验证的一层，不能替代最终验收链路。
 - 后端、CLI、worker、数据同步和外部集成类 `feature_impl` 必须按 `static`、`unit`、`chain`、`failure`、`writeback` 五层声明验证；没有 UI 可见结果时，链路验证和失败验证不能省略。

package/package-source/docs/codex-harness-engineering/templates/hooks/hook-stop-verify.ps1

@@ -608,6 +608,57 @@ function Invoke-HarnessGovernanceCheck {
   }
 }
 
+function Invoke-TaskStructureValidation {
+  param([string]$Root)
+
+  $scriptPath = Join-Path $Root "tools\harness\task-structure-lint.ps1"
+  if (-not (Test-Path -LiteralPath $scriptPath -PathType Leaf)) {
+    return [pscustomobject]@{
+      status = "fail"
+      findings = @([pscustomobject]@{
+          severity = "error"
+          code = "missing_task_structure_lint"
+          message = "缺少 task structure lint: tools\\harness\\task-structure-lint.ps1"
+          task_id = ""
+          field = "tools/harness/task-structure-lint.ps1"
+        })
+    }
+  }
+
+  try {
+    return (& powershell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -ProjectRoot $Root -JsonOutput | ConvertFrom-Json)
+  }
+  catch {
+    return [pscustomobject]@{
+      status = "fail"
+      findings = @([pscustomobject]@{
+          severity = "error"
+          code = "task_structure_lint_failed"
+          message = "task structure lint 执行失败: $($_.Exception.Message)"
+          task_id = ""
+          field = "task.json"
+        })
+    }
+  }
+}
+
+function ConvertTo-TaskStructureFindingText {
+  param([object]$ValidationResult)
+
+  $lines = @()
+  foreach ($finding in @($ValidationResult.findings)) {
+    $taskLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.task_id)) { "" } else { " task=$($finding.task_id)" }
+    $fieldLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.field)) { "" } else { " field=$($finding.field)" }
+    $lines += "- [$($finding.severity)] $($finding.code)$taskLabel${fieldLabel}: $($finding.message)"
+  }
+
+  if ($lines.Count -eq 0) {
+    return "- (none)"
+  }
+
+  return ($lines -join "`n")
+}
+
 function Block-WithState {
   param(
     [string]$Root,
@@ -759,16 +810,31 @@ Initialize task.json with a valid harness task queue, then rerun the driver or v
 "@
   }
 
-  if ($tasks.Count -eq 0) {
-    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_queue_empty" -Reason @"
-Harness stop gate: task.json contains no tasks.
-
-Next action:
-Initialize a real harness task queue before ending the session.
-"@
-  }
-
-  $pendingCount = Get-PendingTaskCount -Tasks $tasks
+  if ($tasks.Count -eq 0) {
+    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_queue_empty" -Reason @"
+Harness stop gate: task.json contains no tasks.
+
+Next action:
+Initialize a real harness task queue before ending the session.
+"@
+  }
+
+  $taskStructureResult = Invoke-TaskStructureValidation -Root $resolvedProjectRoot
+  if ([string]$taskStructureResult.status -eq "fail") {
+    $findingText = ConvertTo-TaskStructureFindingText -ValidationResult $taskStructureResult
+    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_structure_invalid" -Reason @"
+Harness stop gate: task.json 未通过结构门禁。
+
+Findings:
+$findingText
+
+Next action:
+补齐缺失 phase、testing truth source、qa_contract、tdd_contract 或拆分过大的 feature_impl 后，再运行:
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
+"@
+  }
+
+  $pendingCount = Get-PendingTaskCount -Tasks $tasks
   if ($pendingCount -le 0) {
     Block-OnTraceEvidenceIfNeeded -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -TraceInfo $latestTraceInfo
     Exit-Allow

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/task.json

@@ -1,6 +1,6 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\codex-loop.ps1",
     "run_profile": ".codex\\task-run-profile.json"
   },
   "tasks": [
@@ -43,7 +43,7 @@
         "如有需要补齐 demo 资产",
         "运行 tools/harness/verify.ps1 验证 demo 闭环"
       ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1",
       "acceptance": [
         "demo 目录同时具备 product、design、frontend architecture、dev-plan、contract、component、story、generated client",
         "tools/harness/verify.ps1 通过",

package/package-source/docs/codex-harness-engineering/templates/runtime/AGENTS.md

@@ -30,6 +30,10 @@
 - 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
 - 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
 - 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
+- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 三段测试左移与实施计划 phase。
+- P0/P1 任务禁止跳过 `TESTCASE-001`；没有自然语言测试用例、测试数据矩阵、回归计划和验证矩阵，不得生成最终 `task.json`。
+- `feature_impl` 没有 `qa_contract` 不得进入正式 `task.json`；`qa_contract` 没有完整 `tdd_contract`、开发验证和最终验收验证，不得开始实现。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
 - 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
 - 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
 - `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。