@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -Command \"Write-Output 'Load project AGENTS.md and docs/harness before editing.'\"",
+            "statusMessage": "Loading harness context"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -Command \"Write-Output 'PreToolUse policy placeholder'\"",
+            "statusMessage": "Checking shell policy"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -Command \"& { & (Join-Path (git rev-parse --show-toplevel) 'tools/harness/hook-stop-verify.ps1') }\"",
+            "timeout": 120,
+            "statusMessage": "Running stop gate and continuation check"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package-source/docs/codex-harness-engineering/templates/knowledge/catalog.md

@@ -0,0 +1,6 @@
+# Knowledge Item Catalog
+
+| ID | Type | Maturity | Title | Tags | Path |
+| --- | --- | --- | --- | --- | --- |
+| DECISION-HARNESS-001 | decision | draft | Harness 从执行闭环扩展为知识闭环 | harness, knowledge | `docs/knowledge/decisions/DECISION-HARNESS-001.md` |
+| GUIDELINE-RULES-001 | guideline | draft | 规则必须短入口、深文档、可验证 | rules, governance | `docs/knowledge/guidelines/GUIDELINE-RULES-001.md` |

package/package-source/docs/codex-harness-engineering/templates/knowledge/decisions/DECISION-HARNESS-001.md

@@ -0,0 +1,39 @@
+---
+id: DECISION-HARNESS-001
+type: decision
+maturity: draft
+tags: [harness, knowledge]
+applicable_phases: [analysis, plan, implement, review, archive]
+source_references:
+  - docs/doc/Harness不是目的，知识才是护城河.md
+last_referenced:
+contributors:
+  - codex
+---
+
+# Harness 从执行闭环扩展为知识闭环
+
+## Context
+
+当前 harness 已经能通过 `task.json`、`tools/harness/codex-loop.ps1`、验证命令、Stage 1/2 review、trace 和 commit gate 建立执行闭环，但缺少知识复用与归档机制。
+
+## Decision
+
+将 `docs/knowledge/` 作为项目级知识层，并在 trace、任务模板和归档阶段中显式记录知识引用与知识产出。
+
+## Consequences
+
+正面影响：
+
+- 后续任务可以复用已验证经验，减少重复推导。
+- review finding 和失败经验能沉淀为可检索资产。
+- 规则升级可以基于 proven 知识，而不是单次偏好。
+
+代价：
+
+- 需要维护 catalog 和条目成熟度。
+- 需要在归档阶段控制噪音，避免把一次性结论误升为规则。
+
+## Evidence
+
+本条来自 `docs/doc/` 中对 Harness Engineering 和知识沉淀实践的分析，初始成熟度为 `draft`。

package/package-source/docs/codex-harness-engineering/templates/knowledge/guidelines/GUIDELINE-RULES-001.md

@@ -0,0 +1,30 @@
+---
+id: GUIDELINE-RULES-001
+type: guideline
+maturity: draft
+tags: [rules, governance, context]
+applicable_phases: [analysis, plan, implement, review]
+source_references:
+  - docs/doc/1.md
+last_referenced:
+contributors:
+  - codex
+---
+
+# 规则必须短入口、深文档、可验证
+
+## Context
+
+根规则过长会消耗指令预算，孤立深文档又容易不被发现。当前仓库已经有 `AGENTS.md`、`docs/harness/*`、`.codex/rules/*` 和 `.codex/prompts/*` 多层规则面，需要明确分层。
+
+## Guidance
+
+- `AGENTS.md` 只保留每次会话必须遵守的硬约束和深文档索引。
+- 复杂流程写入 `docs/harness/*` 或 `.codex/rules/*`。
+- 执行时必须注入的行为写入 `.codex/prompts/*`。
+- 禁令必须包含替代方案。
+- 能自动检查的规则应进入脚本、schema 或 hook，而不是只靠文字约束。
+
+## Evidence
+
+本条来自 `docs/doc/1.md` 的规则工程分析，初始成熟度为 `draft`。

package/package-source/docs/codex-harness-engineering/templates/knowledge/knowledge-catalog.md

@@ -0,0 +1,41 @@
+# Knowledge Catalog
+
+本目录保存当前项目的可复用知识。Codex 会话应先读本文件，再按需读取 `catalog.md` 和具体条目。
+
+## 查询顺序
+
+1. 当前任务涉及 harness、规则、driver、trace、模板或 prompt 时，先读 `docs/harness/knowledge-architecture.md`。
+2. 需要查找已有经验时，读 `docs/knowledge/catalog.md`。
+3. 只读取与当前任务直接相关的完整条目。
+
+## 维护入口
+
+- 冷启动导入：`docs/harness/knowledge-import.md`
+- 健康检查：`docs/harness/knowledge-lint.md`
+- 架构协议：`docs/harness/knowledge-architecture.md`
+
+## 分类
+
+| 分类 | 路径 | 用途 |
+| --- | --- | --- |
+| Models | `docs/knowledge/models/` | 实体、结构、关系 |
+| Decisions | `docs/knowledge/decisions/` | 架构决策、取舍和原因 |
+| Guidelines | `docs/knowledge/guidelines/` | 推荐做法、禁止做法和替代方案 |
+| Pitfalls | `docs/knowledge/pitfalls/` | 已知风险、失败模式、排查步骤 |
+| Processes | `docs/knowledge/processes/` | 可重复工作流和操作步骤 |
+| Archive | `docs/knowledge/archive/` | 过时、低置信或待合并条目 |
+
+## 阶段推荐
+
+| 阶段 | 优先知识类型 |
+| --- | --- |
+| analysis | `model`、`process`、`pitfall` |
+| design | `decision`、`guideline`、`model` |
+| plan | `decision`、`process`、`pitfall` |
+| implement | `guideline`、`pitfall` |
+| review | `guideline`、`pitfall`、`decision` |
+| archive | 所有类型 |
+
+## 当前状态
+
+当前知识库处于 cold start。新增条目默认 maturity 为 `draft`，需要通过 trace 引用和验证证据逐步提升。

package/package-source/docs/codex-harness-engineering/templates/package-assets/.specify/memory/constitution.md

@@ -0,0 +1,72 @@
+# Hermes Agent Spec Constitution
+
+## Core Principles
+
+### I. Truth Sources Before Implementation
+
+Every feature MUST define the product and design truth sources required by its task kind before implementation starts. Product truth sources include PRD-Lite, page inventory, state matrix, and acceptance criteria. Design truth sources include design brief, component map, screen states, and design tokens. If a required truth source is missing, the task MUST be marked BLOCKED instead of letting an implementation agent infer behavior.
+
+### II. Scope Boundary Is Mandatory
+
+Every feature spec MUST document goals, non-goals, in-scope behavior, out-of-scope behavior, impacted roles, impacted pages or flows, and open questions. Non-goals are not optional; they prevent uncontrolled scope expansion.
+
+### III. Requirements Must Map To Interfaces
+
+Every P0/P1 requirement MUST map to concrete pages, views, states, UI elements, fields, APIs, and acceptance evidence before design or implementation starts. Every page, modal, drawer, or embedded view MUST have a requirement source. Unmapped requirements and requirement-less UI elements are blocking issues unless explicitly deferred.
+
+### IV. Difficulties Must Be Researched Before Coding
+
+High-risk implementation, design, data, integration, performance, permission, or interaction difficulties MUST be researched before implementation. The research record MUST include alternatives considered, selected approach, rejected approach rationale, validation evidence, and downstream task impact. Implementation agents must not rediscover core strategy during coding.
+
+### V. State Coverage Is Mandatory For UI Work
+
+Every UI-facing page, modal, drawer, or embedded view MUST define default, empty, loading, error, permission_denied, disabled, long_content, and mobile states, or explicitly mark a state as not applicable with a reason. State definitions MUST map to stories, E2E cases, or visual regression checks before frontend implementation can be considered complete.
+
+### VI. AI Image Before Frontend Implementation
+
+For UI-facing frontend work, Design Brief and CSS/token requirements MUST be completed before generating UI images. The workflow is: AI Image Brief -> AI image generation/editing -> UI Image Review -> Image To Frontend Spec -> frontend implementation. Generated images are review evidence, not implementation instructions by themselves. Codex must implement from the approved frontend spec and tokens, not guess hidden behavior from images.
+
+### VII. Contract-First For API Or Data Changes
+
+Any task that changes API behavior, data shape, enums, error semantics, pagination, permissions, or client/server integration MUST update or explicitly exempt `contracts/openapi.yaml` before implementation. Generated clients, mocks, and tests MUST align with the same contract.
+
+### VIII. Verification Evidence Required
+
+No task may be marked complete without fresh verification evidence directly tied to its acceptance criteria. Documentation-only changes MUST at least pass `git diff --check`. UI work SHOULD include story and visual evidence. API or business flow work SHOULD include unit, integration, contract, or E2E evidence.
+
+## Product Requirements Standards
+
+- Requirements MUST be testable and traceable to acceptance criteria.
+- Functional requirements SHOULD use stable IDs such as `FR-001`.
+- Business rules SHOULD use stable IDs such as `BR-001`.
+- Acceptance criteria SHOULD use Given/When/Then or EARS-style wording.
+- Risks, assumptions, and open questions MUST be explicit.
+- Permission differences MUST be represented as a matrix when roles differ.
+- `requirement-interface-matrix.md` MUST map requirements to interfaces and states.
+- `difficulty-research.md` MUST be completed for all high-risk difficulties.
+
+## Design Standards
+
+- Design Brief MUST define visual direction, information architecture, layout rules, interaction rules, responsive behavior, and accessibility expectations.
+- Component Map MUST identify reuse source, responsibility, data inputs, event outputs, required states, and test method for each component.
+- Screen States MUST define trigger, data condition, UI behavior, user actions, and verification mapping for each required state.
+- Design tokens MUST be structured and parseable; colors, typography, spacing, radius, and status colors are the minimum baseline.
+- AI Image Brief MUST include CSS/token requirements, target page states, and generation/edit prompts.
+- UI Image Review MUST compare generated images against requirements, state coverage, CSS rules, and forbidden extra functionality.
+- Image To Frontend Spec MUST translate approved images into layout, component, CSS/token, mock data, state, and test mappings.
+- When visual details conflict, the precedence is: design artifact > Design Brief > Product Spec. Functional behavior remains governed by Product Spec.
+
+## Workflow Gates
+
+- `feature_spec` tasks require repository context and a completed feature specification.
+- `feature_design` tasks require product truth sources.
+- `feature_plan` tasks require product and design truth sources.
+- `feature_impl` tasks require product, design, and plan truth sources.
+- `contract_required` tasks additionally require `contracts/openapi.yaml`.
+- Missing truth sources in non-lightweight gates are blocking issues.
+
+## Governance
+
+This constitution supersedes workflow convenience and prompt shortcuts. If the constitution conflicts with a task description, the task must be clarified or blocked. Amendments require updating this file and any affected templates or workflow docs in the same change.
+
+**Version**: 1.0.0 | **Ratified**: 2026-04-26 | **Last Amended**: 2026-04-26

package/package-source/docs/codex-harness-engineering/templates/package-assets/.specify/scripts/powershell/check-prerequisites.ps1

@@ -0,0 +1,148 @@
+#!/usr/bin/env pwsh
+
+# Consolidated prerequisite checking script (PowerShell)
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.ps1 [OPTIONS]
+#
+# OPTIONS:
+#   -Json               Output in JSON format
+#   -RequireTasks       Require tasks.md to exist (for implementation phase)
+#   -IncludeTasks       Include tasks.md in AVAILABLE_DOCS list
+#   -PathsOnly          Only output path variables (no validation)
+#   -Help, -h           Show help message
+
+[CmdletBinding()]
+param(
+    [switch]$Json,
+    [switch]$RequireTasks,
+    [switch]$IncludeTasks,
+    [switch]$PathsOnly,
+    [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Show help if requested
+if ($Help) {
+    Write-Output @"
+Usage: check-prerequisites.ps1 [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  -Json               Output in JSON format
+  -RequireTasks       Require tasks.md to exist (for implementation phase)
+  -IncludeTasks       Include tasks.md in AVAILABLE_DOCS list
+  -PathsOnly          Only output path variables (no prerequisite validation)
+  -Help, -h           Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  .\check-prerequisites.ps1 -Json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  .\check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
+  
+  # Get feature paths only (no validation)
+  .\check-prerequisites.ps1 -PathsOnly
+
+"@
+    exit 0
+}
+
+# Source common functions
+. "$PSScriptRoot/common.ps1"
+
+# Get feature paths and validate branch
+$paths = Get-FeaturePathsEnv
+
+if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) { 
+    exit 1 
+}
+
+# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
+if ($PathsOnly) {
+    if ($Json) {
+        [PSCustomObject]@{
+            REPO_ROOT    = $paths.REPO_ROOT
+            BRANCH       = $paths.CURRENT_BRANCH
+            FEATURE_DIR  = $paths.FEATURE_DIR
+            FEATURE_SPEC = $paths.FEATURE_SPEC
+            IMPL_PLAN    = $paths.IMPL_PLAN
+            TASKS        = $paths.TASKS
+        } | ConvertTo-Json -Compress
+    } else {
+        Write-Output "REPO_ROOT: $($paths.REPO_ROOT)"
+        Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"
+        Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)"
+        Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)"
+        Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)"
+        Write-Output "TASKS: $($paths.TASKS)"
+    }
+    exit 0
+}
+
+# Validate required directories and files
+if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
+    Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.specify first to create the feature structure."
+    exit 1
+}
+
+if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
+    Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.plan first to create the implementation plan."
+    exit 1
+}
+
+# Check for tasks.md if required
+if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
+    Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
+    Write-Output "Run /speckit.tasks first to create the task list."
+    exit 1
+}
+
+# Build list of available documents
+$docs = @()
+
+# Always check these optional docs
+if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
+if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }
+
+# Check contracts directory (only if it exists and has files)
+if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) { 
+    $docs += 'contracts/' 
+}
+
+if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
+
+# Include tasks.md if requested and it exists
+if ($IncludeTasks -and (Test-Path $paths.TASKS)) { 
+    $docs += 'tasks.md' 
+}
+
+# Output results
+if ($Json) {
+    # JSON output
+    [PSCustomObject]@{ 
+        FEATURE_DIR = $paths.FEATURE_DIR
+        AVAILABLE_DOCS = $docs 
+    } | ConvertTo-Json -Compress
+} else {
+    # Text output
+    Write-Output "FEATURE_DIR:$($paths.FEATURE_DIR)"
+    Write-Output "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    Test-FileExists -Path $paths.RESEARCH -Description 'research.md' | Out-Null
+    Test-FileExists -Path $paths.DATA_MODEL -Description 'data-model.md' | Out-Null
+    Test-DirHasFiles -Path $paths.CONTRACTS_DIR -Description 'contracts/' | Out-Null
+    Test-FileExists -Path $paths.QUICKSTART -Description 'quickstart.md' | Out-Null
+    
+    if ($IncludeTasks) {
+        Test-FileExists -Path $paths.TASKS -Description 'tasks.md' | Out-Null
+    }
+}

package/package-source/docs/codex-harness-engineering/templates/package-assets/.specify/scripts/powershell/common.ps1

@@ -0,0 +1,137 @@
+#!/usr/bin/env pwsh
+# Common PowerShell functions analogous to common.sh
+
+function Get-RepoRoot {
+    try {
+        $result = git rev-parse --show-toplevel 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            return $result
+        }
+    } catch {
+        # Git command failed
+    }
+    
+    # Fall back to script location for non-git repos
+    return (Resolve-Path (Join-Path $PSScriptRoot "../../..")).Path
+}
+
+function Get-CurrentBranch {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if ($env:SPECIFY_FEATURE) {
+        return $env:SPECIFY_FEATURE
+    }
+    
+    # Then check git if available
+    try {
+        $result = git rev-parse --abbrev-ref HEAD 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            return $result
+        }
+    } catch {
+        # Git command failed
+    }
+    
+    # For non-git repos, try to find the latest feature directory
+    $repoRoot = Get-RepoRoot
+    $specsDir = Join-Path $repoRoot "specs"
+    
+    if (Test-Path $specsDir) {
+        $latestFeature = ""
+        $highest = 0
+        
+        Get-ChildItem -Path $specsDir -Directory | ForEach-Object {
+            if ($_.Name -match '^(\d{3})-') {
+                $num = [int]$matches[1]
+                if ($num -gt $highest) {
+                    $highest = $num
+                    $latestFeature = $_.Name
+                }
+            }
+        }
+        
+        if ($latestFeature) {
+            return $latestFeature
+        }
+    }
+    
+    # Final fallback
+    return "main"
+}
+
+function Test-HasGit {
+    try {
+        git rev-parse --show-toplevel 2>$null | Out-Null
+        return ($LASTEXITCODE -eq 0)
+    } catch {
+        return $false
+    }
+}
+
+function Test-FeatureBranch {
+    param(
+        [string]$Branch,
+        [bool]$HasGit = $true
+    )
+    
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if (-not $HasGit) {
+        Write-Warning "[specify] Warning: Git repository not detected; skipped branch validation"
+        return $true
+    }
+    
+    if ($Branch -notmatch '^[0-9]{3}-') {
+        Write-Output "ERROR: Not on a feature branch. Current branch: $Branch"
+        Write-Output "Feature branches should be named like: 001-feature-name"
+        return $false
+    }
+    return $true
+}
+
+function Get-FeatureDir {
+    param([string]$RepoRoot, [string]$Branch)
+    Join-Path $RepoRoot "specs/$Branch"
+}
+
+function Get-FeaturePathsEnv {
+    $repoRoot = Get-RepoRoot
+    $currentBranch = Get-CurrentBranch
+    $hasGit = Test-HasGit
+    $featureDir = Get-FeatureDir -RepoRoot $repoRoot -Branch $currentBranch
+    
+    [PSCustomObject]@{
+        REPO_ROOT     = $repoRoot
+        CURRENT_BRANCH = $currentBranch
+        HAS_GIT       = $hasGit
+        FEATURE_DIR   = $featureDir
+        FEATURE_SPEC  = Join-Path $featureDir 'spec.md'
+        IMPL_PLAN     = Join-Path $featureDir 'plan.md'
+        TASKS         = Join-Path $featureDir 'tasks.md'
+        RESEARCH      = Join-Path $featureDir 'research.md'
+        DATA_MODEL    = Join-Path $featureDir 'data-model.md'
+        QUICKSTART    = Join-Path $featureDir 'quickstart.md'
+        CONTRACTS_DIR = Join-Path $featureDir 'contracts'
+    }
+}
+
+function Test-FileExists {
+    param([string]$Path, [string]$Description)
+    if (Test-Path -Path $Path -PathType Leaf) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+
+function Test-DirHasFiles {
+    param([string]$Path, [string]$Description)
+    if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Where-Object { -not $_.PSIsContainer } | Select-Object -First 1)) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+