hally-harness-engineering 0.1.6

Installer CLI for Harness Engineering runtime assets

HallyHarnessEngineering

Languages: 中文 | English

中文版

HallyHarnessEngineering 是一个用于学习、验证和演进 Harness Engineering 工程标准的仓库。它把 Agent 工作流拆成可审计、可恢复、可验证的工程工件：规则由文档说明，结构由 JSON Schema 约束，状态写入由脚本网关控制，运行态数据集中落在 work/。

本仓库不是一个普通业务项目模板。它的核心交付是 Harness runtime framework、安装器生命周期、项目接入规则和可回归测试。

当前状态

• .harness/ 已承载运行时框架资产：schema、template、rules、skills、scripts 和 tests。
• work/ 承载当前仓库运行态：workflow state、active/archived plan package、backlog 和 session audit。
• installer/ 定义外部安装器生命周期；安装器不属于 .harness/ 运行时 gate。
• pyproject.toml 和 src/harness_engineering_installer/ 承载当前 Python 包边界、固定资产 manifest、安装器引擎和 CLI 命令入口；当前包/命令标识是 hally-harness-engineering。
• pipx install hally-harness-engineering / pipx upgrade hally-harness-engineering 与 uv tool install hally-harness-engineering / uv tool upgrade hally-harness-engineering 是目标分发路径；PyPI 发布通过手动 release workflow 执行。

权威入口

文件	用途
AGENTS.md	Agent 入口与事实来源。进入仓库后先读它，再按读取顺序核对规则、schema、脚本和测试。
.harness/ARCHITECTURE.md	Harness 框架架构：目录分层、关键文件职责和核心不变量。
.harness/rules/task-level.md	L0/L1/L2/L3 任务等级判断。
.harness/rules/workflow-lifecycle.md	workflow-state、task status、ownerRole、phase 的生命周期语义。
.harness/rules/session-start.md	会话启动、首次 state bootstrap 和 session audit 边界。
.harness/rules/handoff-rules.md	L2/L3 active plan 的 handoff.md 恢复摘要规则。
.harness/rules/llm-script-boundary.md	脚本与 LLM 的职责边界。
.harness/rules/workflow-gates.md	tasks.json 与 testing/review gate 的边界。
.harness/rules/backlog-rules.md	backlog intake、preempt 信号和 consumption audit 边界。
.harness/rules/archive-rules.md	L2/L3 plan 归档与 L0/L1 direct workflow completion 规则。
installer/install-lifecycle.md	外部安装器安装、更新、自检和移交到 project-init 的生命周期。
learning-notes/	设计学习笔记，不作为运行态真相源。

目录边界

路径	职责	是否运行态
.harness/schemas/	JSON Schema 2020-12 机器契约。	否
.harness/templates/	初始化模板和 Markdown 结构模板。	否
.harness/rules/	schema 无法表达的语义规则。	否
.harness/skills/	repo-local Agent 工作流技能。	否
.harness/scripts/	确定性脚本网关和统一 CLI。	否
.harness/tests/	Harness schema、script、template 和规则回归测试。	否
.harness/contracts/	项目接入契约，如 project contracts 和 entrypoint metadata。	否
installer/	安装器生命周期文档和安装器自身测试。	否
src/harness_engineering_installer/	Python 安装器包源码和固定资产 manifest。	否
work/	当前 workflow、plan、backlog、session audit 等运行态。	是
harness-design/	历史设计材料；不作为目标项目运行时资产。	否
learning-notes/	原理说明和学习笔记。	否

核心不变量：.harness/ 只存契约、模板、规则、技能和工具；运行态数据属于 work/。workflow-state.json 不保存任务列表、历史流水或 plan 正文。

真相源与网关

• work/workflow-state.json 是 workflow 级运行态真相源。
• work/plans/active/<PLAN-ID>/plan.md 是 L2/L3 plan 契约。
• work/plans/active/<PLAN-ID>/tasks.json 是 task 级执行真相源。
• work/plans/active/<PLAN-ID>/handoff.md 是恢复摘要，不覆盖 JSON 真相源。
• work/sessions/YYYY-MM-DD/session-<id>.md 是会话审计证据，不驱动状态。
• work/backlog/backlogs.json 是 pending backlog 队列；work/backlog/consumed.jsonl 是消费审计。
• .harness/contracts/project-contracts.json 是目标项目环境检查契约。
• .harness/contracts/project-entrypoints.json 是目标项目 Agent 入口元数据契约。

写入边界必须保持清晰：

• workflow-state.json 只能由 state-write.py 写入；首次 bootstrap 仅允许 session-start.py 在 state 缺失且没有 active plan 时创建。
• tasks.json 只能由 update-task.py 写入 task 状态、验证结果和 review gate 摘要。
• backlogs.json 只能由 backlog-intake.py 追加 pending item。
• consumed.jsonl 只能由 backlog-consume.py 在下游 ownership evidence 已存在时写入。
• testing 和 review 是 workflow gate，不是独立 task。

工作流模型

任务等级按执行控制复杂度划分：

等级	含义	Plan
L0 / direct-patch	局部、低风险、无需正式规划的直接修补。	不创建
L1 / verified-fix	范围有限但必须定向验证的修复。	不创建
L2 / planned-task	需要先规划再执行的任务。	必须创建
L3 / decomposed-epic	必须拆成多个 task 或阶段性 plan 的复杂工作。	必须创建

workflow phase 与责任角色必须对齐：

Phase	ownerRole
planning	planner
implementing	developer
testing	tester
reviewing	reviewer
archiving	developer

L2/L3 在 implementing、testing、reviewing 阶段必须有且仅有一个 active task。task 进入 done 前必须有 acceptance、验证依据和结构化 review 依据，且 verification 与 review gate 都通过。

常用命令

从现有 workflow 恢复或启动会话：

python3 .harness/scripts/harness --root . session-start

运行 Harness 结构巡检和 workflow state 校验：

python3 .harness/scripts/harness --root . lint
python3 .harness/scripts/harness --root . validate-state

从终态开启新的 direct workflow：

python3 .harness/scripts/harness --root . start-workflow \
  --level L1 \
  --workflow-id workflow-adhoc-YYYYMMDD-001 \
  --next-action 执行第一个可验证修改

记录进入 backlog 的新工作：

python3 .harness/scripts/harness --root . backlog-intake \
  --title "Short title" \
  --summary "Auditable summary of incoming work" \
  --source-ref "chat:YYYY-MM-DD-001" \
  --dispatch queue

运行项目环境契约检查：

python3 .harness/scripts/harness --root . check-project-env

运行回归测试：

python3 -m unittest discover -s .harness/tests -p 'test_*.py'
python3 -m unittest discover -s installer/tests -p 'test_*.py'

安装器边界

安装器的职责是把固定 .harness/ 资产复制或更新到目标仓库，并保留目标仓库自己的运行态和项目文档。它必须保留 work/ 和 .harness/contracts/，不得复制本仓库的 root AGENTS.md、README.md 或业务 ARCHITECTURE.md 到目标仓库。

目标包分发路径是：

pipx install hally-harness-engineering
pipx upgrade hally-harness-engineering
uv tool install hally-harness-engineering
uv tool upgrade hally-harness-engineering

CLI 命令形态是：

hally-harness-engineering --version
hally-harness-engineering install <target> --dry-run
hally-harness-engineering install <target>
hally-harness-engineering update <target>
hally-harness-engineering check <target>

发布到 TestPyPI 或 PyPI 前，必须先在本地构建并执行 artifact inspection 作为 pre-publish release gate：

python3 -m build
python3 installer/release/check_artifacts.py dist
python3 installer/release/smoke_install.py dist

该检查只验证本地 dist/ 中的 wheel、sdist、metadata、console script、依赖、.harness/ payload 和安装后的 CLI 行为，不发布包、不读取 registry credentials。

手动发布入口是 .github/workflows/publish-python-package.yml。完整 registry 操作、TestPyPI 验证、PyPI promotion、安装/升级命令和 yank/rollback 指南见 docs/release/package-registry-release.md。

本仓库内的运行时工作仍以 .harness/scripts/harness 为稳定入口；安装器 CLI 只负责复制、更新和检查固定 Harness 资产。

贡献和修改原则

• 修改前先看 git status --short --branch，不要覆盖已有用户改动。
• 改规则时同步检查 schema、template、script 和 test 是否需要更新。
• 能由 schema 表达的约束必须进入 .harness/schemas/，不要只写文档口号。
• 脚本负责确定性、可回归、可审计的操作；LLM 负责语义判断、计划、handoff、closure 和异常分析。
• 完成前说明实际执行过的验证；不要只说“应该可以”。

English Version

RallyHarnessEngineering is a repository for learning, validating, and evolving Harness Engineering standards. It turns Agent workflows into auditable, recoverable, and verifiable engineering artifacts: rules are documented, structure is constrained by JSON Schema, state writes go through deterministic script gateways, and runtime data lives under work/.

This is not a normal application template. Its core deliverables are the Harness runtime framework, installer lifecycle, project onboarding rules, and regression tests.

Current Status

• .harness/ contains runtime framework assets: schemas, templates, rules, skills, scripts, and tests.
• work/ contains this repository's runtime state: workflow state, active/archived plan packages, backlog, and session audit.
• installer/ defines the external installer lifecycle; the installer is not a .harness/ runtime gate.
• pyproject.toml and src/harness_engineering_installer/ define the current Python package boundary, fixed asset manifest, installer engine, and CLI entrypoint; the current package/command identifier is hally-harness-engineering.
• pipx install hally-harness-engineering / pipx upgrade hally-harness-engineering and uv tool install hally-harness-engineering / uv tool upgrade hally-harness-engineering are the target distribution paths. PyPI publication runs through the manual release workflow.

Authoritative Entry Points

File	Purpose
AGENTS.md	Agent entrypoint and source of truth. Read it first, then follow its ordered references.
.harness/ARCHITECTURE.md	Harness framework architecture: layers, file responsibilities, and invariants.
.harness/rules/task-level.md	L0/L1/L2/L3 task level classification.
.harness/rules/workflow-lifecycle.md	Lifecycle semantics for workflow state, task status, ownerRole, and phase.
.harness/rules/session-start.md	Session startup, first state bootstrap, and session audit boundaries.
.harness/rules/handoff-rules.md	Recovery summary rules for L2/L3 active plan handoff.md.
.harness/rules/llm-script-boundary.md	Responsibility boundary between deterministic scripts and LLM semantic judgment.
.harness/rules/workflow-gates.md	Boundary between tasks.json and testing/review workflow gates.
.harness/rules/backlog-rules.md	Backlog intake, preempt signals, and consumption audit boundaries.
.harness/rules/archive-rules.md	L2/L3 plan archiving and L0/L1 direct workflow completion.
installer/install-lifecycle.md	External installer install, update, self-check, and project-init handoff lifecycle.
learning-notes/	Design notes and learning material, not runtime truth sources.

Directory Boundaries

Path	Responsibility	Runtime state
.harness/schemas/	JSON Schema 2020-12 machine contracts.	No
.harness/templates/	Initialization templates and Markdown structure templates.	No
.harness/rules/	Semantic rules that schemas cannot express.	No
.harness/skills/	Repo-local Agent workflow skills.	No
.harness/scripts/	Deterministic script gateways and unified CLI.	No
.harness/tests/	Regression tests for Harness schemas, scripts, templates, and rules.	No
.harness/contracts/	Project onboarding contracts, such as project contracts and entrypoint metadata.	No
installer/	Installer lifecycle docs and installer tests.	No
src/harness_engineering_installer/	Python installer package source and fixed asset manifest.	No
work/	Current workflow, plan, backlog, and session audit data.	Yes
harness-design/	Historical design material; not a target project runtime asset.	No
learning-notes/	Principles and learning notes.	No

Core invariant: .harness/ stores contracts, templates, rules, skills, and tools only; runtime data belongs under work/. workflow-state.json must not store task lists, history streams, or plan prose.

Truth Sources And Gateways

• work/workflow-state.json is the workflow-level runtime truth source.
• work/plans/active/<PLAN-ID>/plan.md is the L2/L3 plan contract.
• work/plans/active/<PLAN-ID>/tasks.json is the task-level execution truth source.
• work/plans/active/<PLAN-ID>/handoff.md is a recovery summary, not an override for JSON truth sources.
• work/sessions/YYYY-MM-DD/session-<id>.md is session audit evidence, not state.
• work/backlog/backlogs.json is the pending backlog queue; work/backlog/consumed.jsonl is the consumption audit log.
• .harness/contracts/project-contracts.json is the target project environment check contract.
• .harness/contracts/project-entrypoints.json is the target project Agent entrypoint metadata contract.

Write boundaries must stay explicit:

• workflow-state.json can only be written by state-write.py; the only bootstrap exception is session-start.py when state is missing and no active plan exists.
• tasks.json can only be updated by update-task.py.
• backlogs.json can only be appended by backlog-intake.py.
• consumed.jsonl can only be written by backlog-consume.py after downstream ownership evidence exists.
• Testing and review are workflow gates, not standalone tasks.

Workflow Model

Task levels are based on execution control complexity:

Level	Meaning	Plan
L0 / direct-patch	Local, low-risk direct patch.	Not created
L1 / verified-fix	Limited fix that requires targeted verification.	Not created
L2 / planned-task	Work that must be planned before execution.	Required
L3 / decomposed-epic	Complex work that must be split into tasks or staged plans.	Required

Workflow phase and owner role must align:

Phase	ownerRole
planning	planner
implementing	developer
testing	tester
reviewing	reviewer
archiving	developer

L2/L3 workflows must have exactly one active task during implementing, testing, and reviewing. A task cannot enter done until its acceptance criteria, verification evidence, and structured review evidence are present and both verification and review gates have passed.

Common Commands

Start or resume a Harness session:

python3 .harness/scripts/harness --root . session-start

Run Harness structure lint and workflow state validation:

python3 .harness/scripts/harness --root . lint
python3 .harness/scripts/harness --root . validate-state

Start a new direct workflow from a terminal state:

python3 .harness/scripts/harness --root . start-workflow \
  --level L1 \
  --workflow-id workflow-adhoc-YYYYMMDD-001 \
  --next-action "Apply the first verifiable change"

Record incoming work in backlog:

python3 .harness/scripts/harness --root . backlog-intake \
  --title "Short title" \
  --summary "Auditable summary of incoming work" \
  --source-ref "chat:YYYY-MM-DD-001" \
  --dispatch queue

Run the project environment contract checks:

python3 .harness/scripts/harness --root . check-project-env

Run regression tests:

python3 -m unittest discover -s .harness/tests -p 'test_*.py'
python3 -m unittest discover -s installer/tests -p 'test_*.py'

Installer Boundary

The installer copies or updates fixed .harness/ assets into a target repository while preserving the target repository's runtime data and project-owned documents. It must preserve work/ and .harness/contracts/, and it must not copy this source repository's root AGENTS.md, README.md, or business ARCHITECTURE.md into the target repository.

The target package distribution paths are:

pipx install hally-harness-engineering
pipx upgrade hally-harness-engineering
uv tool install hally-harness-engineering
uv tool upgrade hally-harness-engineering

The CLI command shape is:

hally-harness-engineering --version
hally-harness-engineering install <target> --dry-run
hally-harness-engineering install <target>
hally-harness-engineering update <target>
hally-harness-engineering check <target>

Before publishing to TestPyPI or PyPI, build locally and run artifact inspection as the pre-publish release gate:

python3 -m build
python3 installer/release/check_artifacts.py dist
python3 installer/release/smoke_install.py dist

This check only validates the local dist/ wheel, sdist, metadata, console script, dependency declaration, bundled .harness/ payload, and installed CLI behavior. It does not publish a package or read registry credentials.

The manual publish entrypoint is .github/workflows/publish-python-package.yml. Full registry operation, TestPyPI validation, PyPI promotion, install/upgrade commands, and yank/rollback guidance live in docs/release/package-registry-release.md.

.harness/scripts/harness remains the stable runtime entrypoint inside this repository. The installer CLI is responsible only for copying, updating, and checking fixed Harness assets.

Contribution And Change Rules

• Check git status --short --branch before editing, and do not overwrite existing user changes.
• When changing a rule, also check whether schemas, templates, scripts, and tests must change.
• Constraints that can be expressed by schema belong in .harness/schemas/, not only in prose.
• Scripts handle deterministic, repeatable, auditable operations; LLMs handle semantic judgment, planning, handoff, closure, and exception analysis.
• Before completion, report the verification commands that actually ran. Do not claim “should work” without evidence.