harness-flow 4.1.1__tar.gz

harness_flow-4.1.1/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Configure git for tests
+        run: |
+          git config --global user.name "CI"
+          git config --global user.email "ci@test"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify wheel contents
+        run: |
+          python -c "
+          import zipfile, sys
+          whl = next(p for p in __import__('pathlib').Path('dist').iterdir() if p.suffix == '.whl')
+          with zipfile.ZipFile(whl) as z:
+              names = z.namelist()
+              templates = [n for n in names if 'templates/' in n]
+              py_files = [n for n in names if n.endswith('.py')]
+              print(f'Templates: {len(templates)}, Python: {len(py_files)}, Total: {len(names)}')
+              assert len(templates) >= 20, f'Expected >=20 template files, got {len(templates)}'
+              assert len(py_files) >= 15, f'Expected >=15 Python files, got {len(py_files)}'
+              print('Wheel contents verified.')
+          "
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/

harness_flow-4.1.1/.github/workflows/release.yml

@@ -0,0 +1,181 @@
+name: CD — Release to PyPI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      publish_only:
+        description: 'Publish current version without bumping (for retry after failed publish)'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  cd:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/harness-flow
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Detect release intent from merged PR
+        id: intent
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ "${{ inputs.publish_only }}" = "true" ]; then
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "publish_only=true" >> "$GITHUB_OUTPUT"
+            echo "Manual publish-only mode — skipping bump"
+            exit 0
+          fi
+
+          COMMIT_MSG=$(git log -1 --format='%B')
+
+          if echo "$COMMIT_MSG" | grep -qi '\[skip release\]'; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Commit message contains [skip release] — skipping"
+            exit 0
+          fi
+
+          PR_NUMBER=$(gh api "repos/${{ github.repository }}/commits/${{ github.sha }}/pulls" -q '.[0].number' 2>/dev/null || echo "")
+
+          BUMP_LEVEL="patch"
+          if [ -n "$PR_NUMBER" ]; then
+            LABELS=$(gh pr view "$PR_NUMBER" --json labels -q '.labels[].name' 2>/dev/null || echo "")
+            if echo "$LABELS" | grep -q 'no-release'; then
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              echo "PR #$PR_NUMBER has no-release label — skipping"
+              exit 0
+            fi
+            if echo "$LABELS" | grep -q 'release:major'; then
+              BUMP_LEVEL="major"
+            elif echo "$LABELS" | grep -q 'release:minor'; then
+              BUMP_LEVEL="minor"
+            fi
+          fi
+
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+          echo "publish_only=false" >> "$GITHUB_OUTPUT"
+          echo "bump_level=$BUMP_LEVEL" >> "$GITHUB_OUTPUT"
+          echo "Release intent: bump=$BUMP_LEVEL (PR #${PR_NUMBER:-none})"
+
+      - name: Set up Python
+        if: steps.intent.outputs.skip != 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Configure git identity
+        if: steps.intent.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        if: steps.intent.outputs.skip != 'true' && steps.intent.outputs.publish_only != 'true'
+        id: bump
+        run: |
+          git pull --rebase origin main
+          chmod +x scripts/release.sh
+          ./scripts/release.sh bump ${{ steps.intent.outputs.bump_level }}
+          VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              m = re.search(r'version\s*=\s*\"([^\"]+)\"', f.read())
+              print(m.group(1))
+          ")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Read current version (publish-only mode)
+        if: steps.intent.outputs.publish_only == 'true'
+        id: current
+        run: |
+          VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              m = re.search(r'version\s*=\s*\"([^\"]+)\"', f.read())
+              print(m.group(1))
+          ")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Publish-only: version=$VERSION"
+
+      - name: Resolve version outputs
+        if: steps.intent.outputs.skip != 'true'
+        id: ver
+        run: |
+          if [ "${{ steps.intent.outputs.publish_only }}" = "true" ]; then
+            echo "version=${{ steps.current.outputs.version }}" >> "$GITHUB_OUTPUT"
+            echo "tag=${{ steps.current.outputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=${{ steps.bump.outputs.version }}" >> "$GITHUB_OUTPUT"
+            echo "tag=${{ steps.bump.outputs.tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check if already released
+        if: steps.intent.outputs.skip != 'true'
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          if gh release view "$TAG" --json tagName &>/dev/null; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Release $TAG already exists — skipping"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "Will release $TAG"
+          fi
+
+      - name: Commit version bump
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true' && steps.intent.outputs.publish_only != 'true'
+        run: |
+          git add pyproject.toml
+          git commit -m "chore: bump version to ${{ steps.ver.outputs.version }}"
+          git push origin main
+
+      - name: Create and push tag
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true' && steps.intent.outputs.publish_only != 'true'
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          if git rev-parse "$TAG" &>/dev/null; then
+            echo "Tag $TAG already exists — skipping"
+          else
+            git tag "$TAG"
+            git push origin "$TAG"
+          fi
+
+      - name: Install build tools
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        run: pip install build
+
+      - name: Build package
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        run: python -m build
+
+      - name: Publish to PyPI
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        if: steps.intent.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.ver.outputs.tag }}
+          generate_release_notes: true
+          files: dist/*

harness_flow-4.1.1/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+*.so
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+*.log
+.DS_Store
+.idea/
+.cursor/
+
+# harness — .agents/ 是本地运行时目录，不纳入版本控制
+# 包含 state.json、.stop、tasks/、archive/ 等运行时产物
+# config.toml 和 vision.md 如需团队共享，可通过 git add -f 手动添加
+.agents/
+
+# harness — do not track runtime state
+.agents/state.json
+.agents/.stop

harness_flow-4.1.1/ARCHITECTURE.md

@@ -0,0 +1,221 @@
+# Architecture (v4.0.0 — native-only)
+
+This document explains **why** harness-flow is structured the way it is after the native-only refactor. Execution lives in **Cursor**: the Python package bootstraps configuration, generates IDE artifacts, and maintains local state—not an external orchestration loop.
+
+For module-level behavior, read the code and docstrings. For day-to-day usage, see `README.md`.
+
+## System overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  harness CLI (Typer)                                             │
+│  init · install · status · update                                │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         ▼                   ▼                   ▼
+   .agents/*            core/*              native/skill_gen
+   config, vision,      config, state,      Jinja2 → .cursor/
+   state, progress      scanner, ui, …      skills, agents, rules
+                             │
+                             ▼
+                    integrations/
+                    git_ops, memverse
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Cursor IDE — skills, subagents, rules execute the workflow      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Principle:** Cursor is the execution engine. Harness generates and refreshes the artifacts Cursor runs; there is no separate process supervisor or IDE driver layer in this package.
+
+---
+
+## CLI layer (`src/harness/cli.py`)
+
+Built with **Typer**. Four commands:
+
+| Command   | Purpose |
+|-----------|---------|
+| `init`    | Interactive project bootstrap (see below). |
+| `install` | Regenerate `.cursor/` native artifacts from current config. |
+| `status`  | Load session state and render a Rich dashboard. |
+| `update`  | Check PyPI, optional pip upgrade, reinstall artifacts, config migration hints. |
+
+---
+
+## Commands (`src/harness/commands/`)
+
+### `init.py`
+
+Wizard (interactive by default; `--non-interactive` / `-y` for defaults):
+
+1. **Language** — `en` or `zh`; drives i18n for the session.
+2. **Project info** — name and description.
+3. **Trunk branch** — detected from git when possible, user-confirmed.
+4. **CI** — project scan (`scanner`) suggests commands; user picks or enters a custom gate command.
+5. **Memverse** — enable/disable and domain prefix for the Memverse MCP integration.
+6. **Vision** — optional immediate vision flow vs. deferred (placeholder file still created when skipped).
+
+**Writes:** `.agents/config.toml` (from `templates/config.toml.j2`), `.agents/vision.md` when appropriate, then calls `generate_native_artifacts()` so `.cursor/` is populated. Updates `.gitignore` for harness-local files (e.g. `.agents/state.json`, `.agents/.stop`).
+
+### `install.py`
+
+Resolves language (CLI flag or project config), loads `HarnessConfig`, calls **`generate_native_artifacts()`** with optional `--force` to overwrite generated files.
+
+### `status.py`
+
+Loads **`SessionState`** from `.agents/state.json` and renders progress via **Rich** (`core/ui.py` patterns).
+
+### `update.py`
+
+Queries PyPI for newer versions, runs **`pip install --upgrade harness-flow`** when requested, reinstalls native artifacts, and runs lightweight **config migration** checks with user-visible warnings.
+
+---
+
+## Core (`src/harness/core/`)
+
+### `config.py`
+
+**Pydantic** models: `ProjectConfig`, `CIConfig`, `ModelsConfig`, `NativeModeConfig`, `WorkflowConfig`, `HarnessConfig`, plus nested integration config (e.g. Memverse).
+
+- **`HarnessConfig` uses `ConfigDict(extra="ignore")`** so older TOML keys do not break loading.
+- **`HarnessConfig.load()`** builds the effective config by deep-merging, then validates:
+  - Start from **project** `.agents/config.toml` (if present).
+  - Merge **`~/.harness/config.toml`** under it so **project wins** on conflicts.
+  - Merge **`HARNESS_*` environment variables** on top (highest precedence).
+  - Missing keys fall back to **model defaults**.
+
+`ModelsConfig` carries `default`, `role_overrides`, and `role_configs`; unknown keys under `[models]` are ignored. Native workflows primarily use `native.*` and project/CI/workflow fields.
+
+### `roles.py`
+
+Minimal constants only:
+
+- **`ALL_ROLES`** — empty `frozenset` (no routed roles in native-only mode).
+- **`NATIVE_REVIEW_ROLES`** — the five native review roles: `architect`, `product_owner`, `engineer`, `qa`, `project_manager`.
+- **`SCORING_DIMENSIONS`** — evaluation dimension labels (used by tests for validation).
+- **`DEFAULT_RUNTIME`** — default runtime label (`"cursor"`) for registry/events/tracker.
+
+### `state.py`
+
+**`SessionState`**, **`TaskRecord`**, **`CompletedTask`** (and related types) with **JSON** persistence under `.agents/state.json` for resume-friendly dashboards.
+
+### `progress.py`
+
+**`suggest_next_action`** and **`update_progress`** helpers for markdown progress narratives (e.g. `.agents/progress.md`) aligned with native workflows.
+
+### `scanner.py`
+
+Scans the repository layout to **suggest CI commands** during `init`.
+
+### `ui.py`
+
+**Rich** helpers for terminal output (tables, panels, styling) used by status and other commands.
+
+### `events.py`
+
+Structured **JSONL** event logging for observability of harness-adjacent activity.
+
+### `registry.py`
+
+**SQLite**-backed registry for agent run metadata (local audit trail).
+
+### `context.py`
+
+**Task execution context** shared by code paths that still need a unified “where is the task root / config” view.
+
+---
+
+## Native mode generator (`src/harness/native/`)
+
+### `skill_gen.py`
+
+- Loads **Jinja2** templates from `src/harness/templates/native/`.
+- Builds a **template context** from `HarnessConfig` (CI command, trunk branch, native gates, hooks, per-role model hints, etc.) plus small static principle blocks where templates expect them.
+- **`generate_native_artifacts()`** writes:
+  - **10 skills** under `.cursor/skills/harness/<skill-name>/SKILL.md`
+  - **5 agents** under `.cursor/agents/*.md`
+  - **4 rules** under `.cursor/rules/*.mdc`
+  - **Eval resources** (checklist and specialist docs) under `.cursor/skills/harness/harness-eval/`
+  - **`.cursor/worktrees.json`** for parallel worktree setup (skipped if the file already exists unless `force`)
+
+Idempotent by default for `worktrees.json`; skills/agents/rules are regenerated according to `install`/`force` behavior.
+
+---
+
+## Templates (`src/harness/templates/`)
+
+- **`config.toml.j2`** — project config emitted by `init`.
+- **`native/`** — Jinja2 sources for skills, agents, rules, and shared **sections** (e.g. plan/review gates, trust boundary, CI verification).
+- **`vision.md.j2` / `vision.zh.md.j2`** — initial vision stubs.
+
+All user-visible harness **behavior** in the IDE is intended to flow from these templates plus `HarnessConfig`, so upgrades can refresh prompts without forking business logic across Python files.
+
+---
+
+## Integrations (`src/harness/integrations/`)
+
+- **`git_ops.py`** — git helpers (rebase, merge, cleanup) used where the workflow still touches branches.
+- **`memverse.py`** — Memverse MCP integration for learnings and memory sync aligned with skills.
+
+---
+
+## Design principles
+
+1. **Cursor IDE is the execution engine** — Harness generates **skills, agents, and rules** that Cursor’s agent runtime executes. No in-package external CLI orchestration of other IDEs.
+2. **Five-role adversarial review** — The five native roles review **plans and code** in parallel; templates encode how dispatch and aggregation behave.
+3. **Fix-First auto-remediation** — Review output is classified into **AUTO-FIX** vs **ASK** before presentation (encoded in generated rules/skills, not in a Python state machine).
+4. **Config cascade** — **Project** and **global** TOML merge with **project overriding global**; **`HARNESS_*` env vars** override both; Pydantic validates the result.
+5. **Backward compatibility** — **`extra="ignore"`** on `HarnessConfig` allows stale keys from older installs to load safely.
+6. **Template-driven generation** — Native artifacts are rendered from **Jinja2**; Python supplies context and file placement only.
+7. **Local-first** — State, config, registry, and logs are **on disk**; PyPI is only needed for **package updates**, not for routine development.
+
+---
+
+## Artifact layout (high level)
+
+**Project (`.agents/`)**
+
+- `config.toml` — harness configuration.
+- `vision.md` — product/engineering vision for skills.
+- `state.json` — session state (typically gitignored).
+- `progress.md` — human-readable progress log.
+- `.stop` — optional graceful stop flag (typically gitignored).
+- `tasks/`, `archive/` — task artifacts and history (convention from harness workflow docs).
+
+**Generated IDE (`.cursor/`)**
+
+- `skills/harness/**` — generated skills and eval resources.
+- `agents/*.md` — five review agents plus any future template outputs.
+- `rules/*.mdc` — always-on rules (workflow, trust boundary, Fix-First, safety).
+- `worktrees.json` — optional parallel-agent worktree bootstrap commands.
+
+---
+
+## Internationalization
+
+Module-level catalogs (`i18n/en.py`, `i18n/zh.py`) expose `t(key, **kwargs)`. Missing keys fall back to English. CLI and generator user-facing strings go through this layer when applicable.
+
+---
+
+## Testing orientation
+
+Tests are organized around **fast, local behavior**: configuration loading (including env overrides), state/progress, scanner suggestions, skill generation output, install/update flows, git helpers, registry, and UI pieces—without requiring a live Cursor session. Template and config drift is caught by tests that assert on generated files or loaded models.
+
+---
+
+## Design decisions (native era)
+
+### Why generate `.cursor/` instead of shipping static files?
+
+Project-specific **CI command**, **trunk branch**, **review gates**, and **hooks** must flow into prompts. Templating from `HarnessConfig` keeps one SSOT and allows `harness install` to refresh IDE assets after config edits.
+
+### Why keep `ALL_ROLES` empty?
+
+Older configs and code paths referenced a unified role set for model validation. An empty `ALL_ROLES` preserves **compatibility** while native mode keys off **`NATIVE_REVIEW_ROLES`** only.
+
+### Why SQLite for the registry?
+
+A **local, queryable** history of runs supports debugging and audit without a hosted service—consistent with the local-first stance.

harness_flow-4.1.1/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 4.1.0
+
+### Breaking Changes
+
+- **Project renamed** from `harness-orchestrator` to `harness-flow`. Install with `pip install harness-flow`. The Python package name (`harness`) and CLI command (`harness`) are unchanged.
+- **Migration:** If upgrading from `harness-orchestrator`, run `pip uninstall harness-orchestrator && pip install harness-flow`.
+
+## 4.0.0 (2026-04-02)
+
+### Breaking Changes
+
+- **Removed orchestrator mode** — The external CLI-driven orchestrator (`harness run`, `harness auto`, `harness stop`, `harness vision`) has been removed. Harness now operates exclusively in cursor-native mode.
+- **Removed CLI commands**: `run`, `auto`, `stop`, `vision`
+- **Removed modules**: `harness.orchestrator`, `harness.drivers`, `harness.methodology`, `harness.agents` (packaged agent definitions)
+- **Removed config fields**: `workflow.mode`, `workflow.profile`, `workflow.dual_evaluation`, `[drivers]` section, `integrations.memverse.driver`
+- **Removed role registry**: Orchestrator roles (planner, builder, evaluator, alignment_evaluator, strategist, reflector) removed from `harness.core.roles`
+
+### Migration
+
+- **Old configs are safe**: `HarnessConfig` now uses `extra="ignore"`, so `.agents/config.toml` files with `[drivers]` or removed `[workflow]` fields will load without errors.
+- **Use Cursor skills instead of CLI**: `/harness-plan`, `/harness-vision`, `/harness-brainstorm` replace the removed CLI commands.
+- **Run `harness install --force`** after upgrading to regenerate native artifacts.
+
+### What's kept
+
+- Full cursor-native mode: skill generation, 5-role review system, Fix-First auto-remediation
+- CLI commands: `init`, `install`, `status`, `update`
+- Core infrastructure: config, state, UI, events, registry, git ops, scanner
+- All native templates and generated artifacts
+
+### Simplified
+
+- `harness init` wizard: 6 steps (was 9) — no IDE probing, no mode selection
+- `harness install`: only generates native artifacts (no IDE agent copying)
+- `config.py`: cleaner model without driver configs
+- `roles.py`: minimal exports (NATIVE_REVIEW_ROLES, SCORING_DIMENSIONS)
+- `state.py`: data models only (StateMachine removed)
+- i18n catalogs: ~72 keys each (was ~270+)

harness_flow-4.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthas Zeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.