autobuild-factory 0.2.2__tar.gz

autobuild_factory-0.2.2/.gitattributes

@@ -0,0 +1,11 @@
+# LF everywhere; union merge on the tracker's event log.
+* text=auto eol=lf
+*.jsonl text eol=lf merge=union
+.ergon/** text eol=lf
+*.py text eol=lf
+*.md text eol=lf
+*.js text eol=lf
+*.mjs text eol=lf
+*.sh text eol=lf
+*.toml text eol=lf
+*.json text eol=lf

autobuild_factory-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Publish release assets to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: GitHub release tag containing the reviewed package artifacts
+        required: true
+        default: autobuild-factory-0.2.2
+        type: string
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/autobuild-factory/
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download the GitHub release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          case "$RELEASE_TAG" in
+            autobuild-factory-[0-9]*.[0-9]*.[0-9]*) ;;
+            *)
+              echo "release_tag must use the form autobuild-factory-X.Y.Z" >&2
+              exit 1
+              ;;
+          esac
+
+          mkdir -p release-assets dist
+          gh release download "$RELEASE_TAG" \
+            --repo "$REPOSITORY" \
+            --dir release-assets \
+            --pattern "autobuild_factory-*.whl" \
+            --pattern "autobuild_factory-*.tar.gz" \
+            --pattern "SHA256SUMS"
+
+      - name: Verify the release assets
+        shell: bash
+        run: |
+          set -euo pipefail
+          cd release-assets
+
+          test -f SHA256SUMS
+          mapfile -t packages < <(
+            find . -maxdepth 1 -type f \
+              \( -name "autobuild_factory-*.whl" -o -name "autobuild_factory-*.tar.gz" \) \
+              -printf "%f\n" | sort
+          )
+          test "${#packages[@]}" -eq 2
+          sha256sum --check --strict SHA256SUMS
+
+          cp -- "${packages[@]}" ../dist/
+
+      - name: Publish the verified distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist
+          verify-metadata: true
+          skip-existing: false
+          attestations: true
+          print-hash: true

autobuild_factory-0.2.2/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.uv/
+
+# Runtime and scratch
+.autobuild-run/
+*.log
+/tmp/
+_norton_/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+
+# Local tool settings
+.claude/settings.local.json
+.claude/*.lock
+.claude/worktrees/

autobuild_factory-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Georgios Antikatzidis
+
+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.

autobuild_factory-0.2.2/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: autobuild-factory
+Version: 0.2.2
+Summary: The software factory's build cycle, harness-neutral: logic once, mechanisms behind adapters.
+Project-URL: Repository, https://github.com/antikas/autobuild-factory
+Project-URL: Issues, https://github.com/antikas/autobuild-factory/issues
+Author: Georgios Antikatzidis
+License: MIT License
+        
+        Copyright (c) 2026 Georgios Antikatzidis
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# AutoBuild
+
+Coding assistants can work through a backlog, but the result becomes hard to trust when each assistant carries a different build process in its prompt. AutoBuild puts the campaign in one Python application so the same sequence, checks and delivery rules apply whichever supported assistant runs it.
+
+A fresh builder changes one ready item from the project's tracked queue in an isolated Git worktree. The queue can be [Pinax](https://github.com/antikas/pinax-tracker) or a supported `BACKLOG.md` table. A fresh reviewer sees the approved request, changed files and test evidence without the builder transcript. The application accepts, parks or stops the item, then records enough evidence to judge the outcome without reconstructing a chat session.
+
+The workflow is harness-neutral. Claude Code, Codex and GitHub Copilot sit behind adapters selected at startup; the campaign sequence does not change with the assistant, operating system or shell.
+
+## Run sequence
+
+1. Check the selected harness, repository and project test command before claiming work.
+2. Build and review one ready item in an isolated worktree.
+3. Deliver accepted product and tracker commits to the remote default branch.
+4. Continue until the queue is dry, the item limit is reached or required evidence fails.
+
+## Repository contents
+
+- `src/autobuild/`: the cycle and its adapter interfaces
+- `src/autobuild/adapters/`: the adapters, one per mechanism
+- `src/autobuild/enforcement/`: gates, validators and schemas
+- `skills/autobuild-plan/`: plans, reviews and registers an end-to-end queue, then stops before launch
+- `skills/autobuild/`: configures and launches the Python workflow against a ready queue
+- `tests/`: the test lane
+
+## Start here
+
+The [setup and run guide](docs/running-autobuild.md) explains installation, harness authentication, item briefs, Pinax and `BACKLOG.md`, the project profile, campaign results, refill and failure handling from a standing start.
+
+AutoBuild has two stages. Use `autobuild-plan` for research, planning, independent review and tracker registration. After the owner approves that result, use `autobuild` to run the queue. [The operating guide starts with the planning stage](docs/running-autobuild.md#stage-1-plan-and-register-the-work).
+
+Release 0.2.2 is available from PyPI as [`autobuild-factory`](https://pypi.org/project/autobuild-factory/) and as a Python wheel and source archive on the [GitHub release page](https://github.com/antikas/autobuild-factory/releases/tag/v0.2.2). The guide also has a [macOS setup path](docs/running-autobuild.md#set-up-autobuild-on-macos) and [GitHub Copilot setup](docs/running-autobuild.md#github-copilot-cli).
+
+Platform and coding assistant are separate choices. You can use Codex on macOS, GitHub Copilot on Windows, or any other supported combination.
+
+The [architecture guide](docs/architecture.md) explains the layers, state machines, ports, adapters, evidence chain, Git delivery model and extension points.
+
+Run the test lane with `uv run --native-tls python -m pytest tests -q`.
+
+The [harness adapter guide](docs/harness-adapters.md) explains how one builder and reviewer contract runs through Claude Code, Codex and GitHub Copilot.
+
+## Delivery checks
+
+AutoBuild probes its adapters before claiming work, confines changes to an isolated worktree, runs only the declared validator and verifies the remote revision after delivery. An accepted result must carry matching diff, validator, review, product-commit and tracker-commit evidence.
+
+## Scope and limits
+
+Product decisions, public releases and production deployments stay outside AutoBuild. An optional queue-refill plan records proposed work and unresolved questions. It cannot make a proposal runnable.

autobuild_factory-0.2.2/README.md

@@ -0,0 +1,47 @@
+# AutoBuild
+
+Coding assistants can work through a backlog, but the result becomes hard to trust when each assistant carries a different build process in its prompt. AutoBuild puts the campaign in one Python application so the same sequence, checks and delivery rules apply whichever supported assistant runs it.
+
+A fresh builder changes one ready item from the project's tracked queue in an isolated Git worktree. The queue can be [Pinax](https://github.com/antikas/pinax-tracker) or a supported `BACKLOG.md` table. A fresh reviewer sees the approved request, changed files and test evidence without the builder transcript. The application accepts, parks or stops the item, then records enough evidence to judge the outcome without reconstructing a chat session.
+
+The workflow is harness-neutral. Claude Code, Codex and GitHub Copilot sit behind adapters selected at startup; the campaign sequence does not change with the assistant, operating system or shell.
+
+## Run sequence
+
+1. Check the selected harness, repository and project test command before claiming work.
+2. Build and review one ready item in an isolated worktree.
+3. Deliver accepted product and tracker commits to the remote default branch.
+4. Continue until the queue is dry, the item limit is reached or required evidence fails.
+
+## Repository contents
+
+- `src/autobuild/`: the cycle and its adapter interfaces
+- `src/autobuild/adapters/`: the adapters, one per mechanism
+- `src/autobuild/enforcement/`: gates, validators and schemas
+- `skills/autobuild-plan/`: plans, reviews and registers an end-to-end queue, then stops before launch
+- `skills/autobuild/`: configures and launches the Python workflow against a ready queue
+- `tests/`: the test lane
+
+## Start here
+
+The [setup and run guide](docs/running-autobuild.md) explains installation, harness authentication, item briefs, Pinax and `BACKLOG.md`, the project profile, campaign results, refill and failure handling from a standing start.
+
+AutoBuild has two stages. Use `autobuild-plan` for research, planning, independent review and tracker registration. After the owner approves that result, use `autobuild` to run the queue. [The operating guide starts with the planning stage](docs/running-autobuild.md#stage-1-plan-and-register-the-work).
+
+Release 0.2.2 is available from PyPI as [`autobuild-factory`](https://pypi.org/project/autobuild-factory/) and as a Python wheel and source archive on the [GitHub release page](https://github.com/antikas/autobuild-factory/releases/tag/v0.2.2). The guide also has a [macOS setup path](docs/running-autobuild.md#set-up-autobuild-on-macos) and [GitHub Copilot setup](docs/running-autobuild.md#github-copilot-cli).
+
+Platform and coding assistant are separate choices. You can use Codex on macOS, GitHub Copilot on Windows, or any other supported combination.
+
+The [architecture guide](docs/architecture.md) explains the layers, state machines, ports, adapters, evidence chain, Git delivery model and extension points.
+
+Run the test lane with `uv run --native-tls python -m pytest tests -q`.
+
+The [harness adapter guide](docs/harness-adapters.md) explains how one builder and reviewer contract runs through Claude Code, Codex and GitHub Copilot.
+
+## Delivery checks
+
+AutoBuild probes its adapters before claiming work, confines changes to an isolated worktree, runs only the declared validator and verifies the remote revision after delivery. An accepted result must carry matching diff, validator, review, product-commit and tracker-commit evidence.
+
+## Scope and limits
+
+Product decisions, public releases and production deployments stay outside AutoBuild. An optional queue-refill plan records proposed work and unresolved questions. It cannot make a proposal runnable.

autobuild_factory-0.2.2/docs/architecture.md

@@ -0,0 +1,272 @@
+# AutoBuild architecture
+
+This guide explains how AutoBuild keeps one build process across different coding assistants, operating systems, and trackers. It is written for readers who want to inspect, extend, or review the implementation.
+
+The [setup and run guide](running-autobuild.md) covers installation and operation.
+
+## Design goal
+
+AutoBuild has one campaign sequence and one item sequence. External mechanisms sit behind typed Python interfaces called ports. Adapters implement those ports for Git, trackers, operating systems, and coding assistant commands.
+
+The application decides what happens next. The policy layer decides whether an action is allowed. An adapter decides how to perform an allowed action.
+
+This split keeps harness flags, shell quoting, tracker commands, and host process rules out of the workflow.
+
+## Dependency direction
+
+```mermaid
+flowchart TD
+    CLI[CLI] --> Bootstrap[Bootstrap and runtime composition]
+    Bootstrap --> Application[Campaign and item workflows]
+    Bootstrap --> Policy[Policy gateway]
+    Bootstrap --> Adapters[Mechanism adapters]
+    Application --> Domain[Domain types and state]
+    Application --> Ports[Typed ports]
+    Policy --> Domain
+    Policy --> Ports
+    Adapters --> Domain
+    Adapters --> Ports
+```
+
+Dependencies point toward domain types and port contracts. The application layer does not import an adapter, a vendor package, `subprocess`, or platform detection.
+
+The bootstrap package is the composition root. It is the only part that selects concrete adapters and knows which host command implementation is active.
+
+## Package map
+
+| Path | Responsibility |
+|---|---|
+| `src/autobuild/domain/` | Immutable requests, results, states, dispositions, and evidence types |
+| `src/autobuild/ports/` | Protocols for each external boundary |
+| `src/autobuild/application/` | Campaign loop, item workflow, prompts, and state transitions |
+| `src/autobuild/enforcement/` | Deterministic policy checks around port calls |
+| `src/autobuild/adapters/` | Git, tracker, harness, process, record, and knowledge mechanisms |
+| `src/autobuild/bootstrap/` | Profile loading, discovery, adapter selection, and composition |
+| `src/autobuild/cli.py` | Thin command-line entry point |
+| `skills/autobuild-plan/` | Optional planning entry that researches, reviews and registers a queue, then stops before execution |
+| `skills/autobuild/` | Optional execution entry that configures and launches the Python command |
+| `tests/architecture/` | Dependency and entry-shim tripwires |
+| `tests/contract/` | Shared adapter registration and result contracts |
+| `tests/unit/` | Workflow and policy decisions against fakes |
+| `tests/integration/` | Real processes, Git repositories, trackers, and delivery paths |
+
+## Entry skills and executable
+
+The Python application is the sequencing source. The `autobuild` skill supplies project facts to the command and launches it. The skill does not implement a second campaign or item workflow.
+
+The `autobuild-plan` skill sits before execution. It researches the requested outcome, writes and reviews an end-to-end plan, and registers the resulting queue. It stops before launch unless the owner has already authorised execution.
+
+The repository and source archive contain both skills. The wheel contains the Python application and its `autobuild` command. Skill installation remains with the coding assistant because each host owns its skill directory and loading rules.
+
+## Runtime composition
+
+The CLI loads `.autobuild.toml` and applies explicit command-line overrides. Bootstrap then performs these steps:
+
+1. Choose the Windows or POSIX command adapter from the current Python host.
+2. Select [Pinax](https://github.com/antikas/pinax-tracker) or the Markdown backlog adapter from `[tracker]` and startup probes.
+3. Configure the Git workspace adapter with the selected tracker's paths.
+4. Resolve the selected harness through the adapter registry.
+5. Choose the no-refill or Koine knowledge adapter from the refill plan.
+6. Probe every selected adapter before a claim.
+7. Record adapter identities and versions in the run manifest.
+8. Wrap the adapters with policy-enforced port implementations.
+9. Start the campaign runner with one immutable `WorkflowPorts` object.
+
+Explicit tracker and harness settings take precedence over discovery. Auto tracker selection prefers Pinax when it is usable, then checks the supported backlog path.
+
+## Port contracts
+
+The workflow calls six semantic ports.
+
+| Port | Workflow request | Included adapters |
+|---|---|---|
+| `TrackerPort` | Select, claim, close, park, and record a non-runnable proposal | Pinax and Markdown backlog |
+| `WorkspacePort` | Identify a repository, create a worktree, calculate a diff, commit, deliver, and release | Git worktree adapter |
+| `HarnessPort` | Probe, invoke a fresh seat, cancel it, and collect usage | Claude Code, Codex, and GitHub Copilot CLI |
+| `CommandPort` | Run the approved validator with captured output and process-tree control | Windows and POSIX process adapters |
+| `RunRecordPort` | Create a run, append events, write evidence, and complete a report | Local filesystem records |
+| `KnowledgePort` | Retrieve durable context and record unresolved directions | Koine or no-refill adapter |
+
+Ports exchange dataclasses and enums. Vendor JSON, command flags, and shell strings remain inside adapters.
+
+## Campaign state
+
+The campaign runner owns the queue loop:
+
+```mermaid
+flowchart LR
+    Start[Create run record] --> Select[Select next ready item]
+    Select -->|Item found| Item[Run item workflow]
+    Item -->|Accepted or parked| Bound{Item limit reached?}
+    Bound -->|No| Select
+    Bound -->|Yes| StopBound[Stop: item bound]
+    Select -->|Queue dry| Refill{Refill supplied?}
+    Refill -->|Yes| Propose[Record proposals and fog]
+    Refill -->|No| StopDry[Stop: queue dry]
+    Propose --> StopDry
+    Item -->|Structural failure| StopFailure[Stop: structural failure]
+```
+
+Refill runs only after the live queue is dry. `ProposalRef` rejects a runnable value, so an adapter cannot feed its own proposal back into the campaign as approved work.
+
+## Item state
+
+One item moves through a fixed state machine:
+
+```text
+ready
+  -> verified
+  -> claimed
+  -> isolated
+  -> built
+  -> validated
+  -> reviewed
+  -> correcting or escalated when evidence requires it
+  -> finalised or parked
+  -> released
+```
+
+The reviewer can return `pass`, `correct`, `escalate`, or `park`.
+
+A correction starts another fresh builder and reviewer pair. The default ceiling is two correction rounds. An escalation starts a specialist seat for the named specialist boundary. Any final result other than `pass` parks the item.
+
+## Evidence chain
+
+The acceptance path binds each decision to the same workspace state.
+
+1. `WorkspacePort.diff()` calculates changed paths, content digests, a binary patch reference, and a workspace revision digest.
+2. `CommandPort.run()` executes the declared validator in that worktree.
+3. `ValidationEvidence` binds the validator result and changed paths to the workspace revision.
+4. The reviewer receives the brief, patch reference, and validator output reference.
+5. `commit_item()` recalculates the diff and rejects a changed workspace.
+6. The product commit contains only the reviewed product paths.
+7. The tracker adapter writes the close state after the product commit.
+8. The tracker commit must sit immediately after the product commit.
+9. Delivery merges the item branch, pushes the default branch, and checks the remote revision.
+
+The application accepts a result only when this chain remains intact. A successful model process cannot substitute for missing validator or review evidence.
+
+## Builder and reviewer isolation
+
+Each harness adapter starts a new command invocation with a fresh session identifier. The builder receives write-capable tools allowed by the project profile.
+
+The reviewer receives read-only tools and a read-only sandbox when the harness supports one. Its evidence pack excludes the builder transcript.
+
+The shared harness result contracts contain a builder summary or a review decision with concrete findings. Harness adapters normalise vendor output into these contracts.
+
+## Git delivery model
+
+Tracker state and product state use separate commits.
+
+For an accepted item:
+
+1. The tracker adapter records and pushes the claim from the primary checkout.
+2. The workspace adapter creates an item branch and worktree from that claimed revision.
+3. The builder changes product files in the worktree.
+4. The workspace adapter excludes the selected tracker paths from the product diff.
+5. It creates the product commit from the reviewed path set.
+6. The tracker adapter writes the done state in the worktree.
+7. The workspace adapter creates the tracker commit.
+8. It merges the item branch into the default branch with `--no-ff`.
+9. It pushes the default branch and verifies the remote commit.
+
+For a parked item, AutoBuild writes and delivers a tracker-only commit. It releases the worktree without merging the unaccepted product changes.
+
+The primary checkout must be clean before a claim and before delivery. This rule prevents AutoBuild from mixing a user's uncommitted work into a campaign.
+
+## Tracker adapters
+
+### Pinax
+
+The Pinax adapter delegates ordering, readiness, dependencies, gates, and event folding to the `pinax` command. It requires `.ergon/` and an approved note reference for each selected item.
+
+Claim, park, close, and proposal events are committed under `.ergon/`. A refill proposal receives a Pinax proposal gate and stays outside the ready queue.
+
+### Markdown backlog
+
+The backlog adapter parses one Markdown table with `Item`, `Title`, `Status`, and `Brief` columns. Table order is queue order.
+
+It updates only the selected row for claim, done, and park operations. Refill adds a `Proposed` row. The Git workspace adapter treats the configured backlog file as tracker state, so it cannot enter the product commit.
+
+Auto mode chooses a tracker once during preflight. A campaign does not move from one operational record to another after work starts.
+
+## Policy enforcement
+
+The policy gateway wraps every port used by the workflow. It checks:
+
+- repository, worktree, brief, and evidence paths against approved roots
+- semantic tool permissions for every harness seat
+- exact validator identity and argument vector
+- command and seat timeouts against configured ceilings
+- reviewer read-only access
+- evidence freshness before close
+- separate product and tracker commits before delivery
+- protected-branch gates for claim, park, proposal, and merge operations
+
+The public workflow does not request deployment, publication, destructive actions, or force pushes.
+
+## Host and temporary work
+
+The Windows and POSIX command adapters accept argument vectors. The workflow does not build shell command strings.
+
+Each adapter captures standard output and standard error in files. Timeout and cancellation stop the process tree started for that request.
+
+Bootstrap chooses the operating system temporary directory by default. An operator can supply another scratch root. Child processes receive temporary and package cache environment variables below that root.
+
+## Run records
+
+The local record adapter writes one directory per campaign:
+
+```text
+runs/<run-id>/
+  manifest.json
+  events.jsonl
+  evidence/
+  report.txt
+```
+
+The manifest records the workflow version, repository, harness, model names, validator, refill counts, and selected adapter identities.
+
+Events record the item lifecycle and point to evidence files. The run record keeps decision evidence and diagnostic references. It does not place a full builder transcript in the review pack.
+
+## Failure handling
+
+Preflight failures stop before a claim.
+
+After a claim, the item workflow tries to park any builder, validator, reviewer, evidence, or adapter failure. A successful park writes the reason to the tracker and releases the worktree.
+
+Evidence type failures mark the item as a structural failure and stop the campaign after the park. Other parked outcomes allow the campaign result to report the item honestly.
+
+A hard process kill can interrupt cleanup. AutoBuild preserves any remaining Git branch or worktree for inspection but does not attach a new campaign to it automatically.
+
+## Extension points
+
+### Add a harness
+
+Implement `HarnessPort`, use the shared result contracts, and register the adapter through the `autobuild.adapters` Python entry-point group. Add it to the shared contract and process integration tests.
+
+The application and policy layers require no provider switch.
+
+### Add a tracker
+
+Implement `TrackerPort` with durable claim, close, park, and non-runnable proposal operations. Register its configuration and tracker paths in bootstrap. Reuse `GitWorkspaceAdapter` for separate product and tracker commits.
+
+The campaign and item workflows remain unchanged.
+
+### Add a host process adapter
+
+Implement `CommandPort` with argument-vector execution, captured output, timeout, cancellation, and process-tree teardown. Bind it in bootstrap for the new host capability.
+
+### Add a knowledge adapter
+
+Implement `KnowledgePort`. Keep operational queue state in the tracker. The knowledge adapter handles durable context and unresolved directions only.
+
+## Architecture tests
+
+Architecture tests parse imports and fail when domain, ports, application, or enforcement point toward a forbidden outer layer. They also reject provider and host words in application logic.
+
+Unit tests run the campaign and item state machines against fake ports. They cover acceptance, corrections, specialist escalation, park, structural failure, run bounds, and proposal-only refill.
+
+Contract tests prove that an additional harness can register without an application change.
+
+Integration tests use real temporary Git repositories, bare remotes, Pinax, Markdown backlog files, fake harness processes, and platform command adapters. They verify claim, separate commits, merge, push, remote revision, cancellation, path handling, and automatic backlog fallback.

autobuild_factory-0.2.2/docs/harness-adapters.md

@@ -0,0 +1,92 @@
+# Harness adapters
+
+Coding assistants expose different commands, permission controls, output formats and authentication checks. An automated build becomes hard to trust when those differences change the build process itself.
+
+AutoBuild sends the same typed seat request to every coding assistant. A small adapter translates that request into one command and converts the result back into the same builder or reviewer record. The build sequence does not know which command handled the work.
+
+## Adapter sequence
+
+1. AutoBuild creates a fresh builder request for one tracked item and its isolated workspace.
+2. The selected adapter starts its command with the approved model, tools, paths and timeout.
+3. The builder leaves its product changes uncommitted so validation can inspect the final workspace state.
+4. AutoBuild creates a fresh reviewer request containing the brief, diff and validator evidence. It does not include the builder transcript.
+5. The adapter returns the same typed verdict and usage record whichever command ran the seat.
+
+## Request and result flow
+
+The operator approves the item, model classes and tool policy before the campaign starts. The policy is readable in the runtime profile and can be changed before a run. AutoBuild freezes the selected adapters after their executable, version and authentication probes pass.
+
+The workflow renders the builder instructions once. They name the approved brief, acceptance criteria, workspace and result contract. The adapter receives those finished instructions through a typed request (`SeatRequest`).
+
+The adapter maps the abstract model class to the command's model name. It also maps semantic tools such as `read`, `write`, `python` and `git` to the command's permission flags. An unknown tool fails before the command starts.
+
+The host command adapter starts the process and captures both output streams under the active temporary work root. It owns quoting, environment inheritance, timeout, cancellation and process tree termination. The harness adapter never creates a second process runner.
+
+The command must return one of two small JSON contracts. A builder returns a summary. A reviewer returns a disposition and concrete findings. AutoBuild writes a normalised JSON record and keeps the raw command output as diagnostic evidence.
+
+## Seat safeguards
+
+- Every seat receives a new session identifier and cannot resume a previous conversation.
+- Review seats receive read-only tools and a read-only sandbox where the command supports one.
+- The reviewer receives the brief, diff and validation evidence. Builder transcripts stay outside the review pack.
+- The policy gateway rejects undeclared tools, paths outside the workspace and timeouts above the approved ceiling.
+- Every child process receives `TMPDIR`, `TEMP`, `TMP` and package caches under the active temporary work root. The standard system temporary directory is the default. An operator can supply another root for a machine that needs it.
+- A successful process with missing or malformed result JSON is an evidence failure.
+- Usage is reported when the command supplies it. Missing usage remains explicitly unavailable.
+
+AutoBuild accepts a seat only when these checks pass. A command name or a successful exit code is not enough.
+
+## Responsibility boundaries
+
+The adapters do not choose work, decide acceptance, run validators, merge branches or update the tracker. Those responsibilities remain in the shared workflow and the other ports.
+
+An adapter reports unavailable when its executable or authentication probe fails.
+
+## Implementation details
+
+### Shared result contracts
+
+Builder result:
+
+```json
+{
+  "summary": "What changed and why",
+  "report_ref": "Reference supplied by the command, or an empty string"
+}
+```
+
+Reviewer result:
+
+```json
+{
+  "decision": "pass",
+  "findings": [],
+  "evidence_ref": "Reference supplied by the command, or an empty string"
+}
+```
+
+Blocking decisions use `correct`, `escalate` or `park` and require at least one finding. Each finding carries a code, concrete consequence and evidence reference. A specialist boundary is optional.
+
+### Command mappings
+
+| Adapter | Programmatic command | Fresh context and permissions | Result handling |
+|---|---|---|---|
+| Claude Code | `claude --print` | New session id, no persistence, safe mode, explicit tools, `dontAsk` permission mode | `--output-format json` with `--json-schema` |
+| Codex | `codex ... exec` | Ephemeral session, ignored project rules, `never` approval policy, workspace-write builder or read-only reviewer sandbox | JSONL events, `--output-schema`, and `--output-last-message` |
+| GitHub Copilot | `copilot --prompt` | New session id, explicit available and allowed tools, no user questions, no remote export, no custom instructions | `--output-format json` JSONL normalised to the shared contract |
+
+The GitHub Copilot command also uses `--disallow-temp-dir`. The child environment points every temporary and cache path at the active temporary work root.
+
+### Runtime registration
+
+The built-in adapter names are `claude-code`, `codex` and `github-copilot`. Each factory receives the bound host command port, an output directory, an optional command override and a model map. A fourth adapter can register through the same Python entry-point surface without editing the workflow.
+
+### Version compatibility
+
+The executable help text and official command documentation define the supported flags. AutoBuild records the observed CLI version in each run manifest. Install each coding assistant through its vendor's official tooling so its command and supporting runtime stay together.
+
+Official references:
+
+- [Claude Code command-line reference](https://code.claude.com/docs/en/cli-reference)
+- [Codex CLI repository](https://github.com/openai/codex)
+- [GitHub Copilot CLI programmatic reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)