devcontour-harness 0.1.0-alpha.5 → 0.1.0-alpha.7

package/templates/controller-mode/AGENTS.controller.md

@@ -0,0 +1,58 @@
+<!-- devcontour-harness controller-mode overlay v1. Pinned as a context source; do not edit per project. -->
+
+# Controller mode (devcontour-harness overlay v1)
+
+This attempt runs under devcontour-harness in controller mode. The overlay adds
+to the repository's own AGENTS.md files. It does not replace them. Where this
+overlay and a product rule disagree about who does an operation, this overlay
+decides. Every other product rule still applies.
+
+## Who owns what
+
+| Operation                                                                                       | Owner in this attempt            |
+| ----------------------------------------------------------------------------------------------- | -------------------------------- |
+| Creating, entering, tearing down and removing Git worktrees                                     | harness controller               |
+| Branches, commits, merges, rebases, tags and pushes                                             | harness controller               |
+| Running acceptance gates and recording evidence                                                 | harness controller               |
+| Moving the task, sessions, checkpoints and work history in Relay or any other tracker           | harness controller               |
+| Starting, stopping and cleaning up per-attempt environments (Docker projects, ports, env files) | harness controller via lifecycle |
+| Editing files inside the issued write scope                                                     | worker (you)                     |
+
+The worker edits files only inside the write scope that the harness issued for
+this work order. When the edits are complete, the worker stops and reports. The
+worker leaves every change uncommitted in the given worktree. The controller
+stages, commits, verifies, reviews and integrates the change.
+
+## Product rules delegated to the controller
+
+The product AGENTS.md files can tell an agent to do the operations below. In
+this mode the controller does them instead, so the worker does not:
+
+1. Create or remove worktrees (`pnpm worktree:create`, `worktree:up`,
+   `worktree:down`, `worktree:remove`, or any other worktree registry).
+2. Commit, merge into the main branch, or move the task to review.
+3. Open Relay sessions or intents, write checkpoints or history, or use the
+   `.artifacts/relay/` fallback. The controller keeps the Relay history.
+4. Run `pnpm run setup` or any other unpinned skill or agent bootstrap.
+5. Start another orchestrator, scheduler or agent, or run `harness` from
+   inside the attempt.
+
+## Product rules that still apply
+
+- Code style, architecture, review and naming rules of the touched packages.
+  Read the AGENTS.md files on the paths you change before you edit, for
+  example `apps/nest-backend/AGENTS.md` and `apps/next-web-app/AGENTS.md`.
+- Never hand-edit generated code. To change generated outputs that are in the
+  write scope, change the inputs and run the project's pinned generator
+  command. In Turbo Starter that command is `pnpm rest-api-sdk:generate`. A
+  harness gate regenerates the outputs and rejects any difference.
+- Do not change lockfiles, dependencies, generator configuration or harness
+  files. The harness protects these paths.
+- Do not add tests or test infrastructure where the product forbids it. The
+  harness supplies its acceptance checks outside the product code.
+
+## When you cannot proceed
+
+If a product rule cannot be satisfied inside the issued scope, stop. Report the
+rule and the reason, and return `completed=false`. Do not widen the scope
+yourself.

package/templates/controller-mode/README.md

@@ -0,0 +1,44 @@
+# Controller mode (opt-in, v1)
+
+`AGENTS.controller.md` is an overlay for projects whose own AGENTS.md tells an
+agent to manage worktrees, commits, merges or Relay history itself. Turbo
+Starter is one such project. Under devcontour-harness the controller does
+those operations, and the worker only edits files in the scope it was issued.
+
+## How to enable it without deleting product rules
+
+The overlay is delivered to the attempt as a **pinned context source**. It is
+not a file committed to the target repository. Some projects forbid new
+`.md` files, and their own AGENTS.md files stay unchanged and keep applying.
+
+1. Next to the graph, create the context source directory
+   `context/controller-mode/` and copy `AGENTS.controller.md` into it
+   unchanged.
+2. Put copies of the product AGENTS.md files under
+   `context/controller-mode/references/`. Keep their repository paths, for
+   example `references/AGENTS.md` and `references/apps/nest-backend/AGENTS.md`.
+   Files under `references/` are pinned by SHA-256 and recorded in the
+   attempt's provenance, but they are not inlined into the prompt. The worker
+   reads the live copies in its worktree.
+3. Add `provenance.json` with the overlay version and digest, plus the
+   repository path and baseline blob of each referenced AGENTS.md.
+   `examples/turbo-starter/setup.mjs` (`controllerContext`) writes this
+   layout.
+4. Add `"context": ["controller-mode"]` to every order of the graph. Writer
+   and reviewers then see the same pinned bytes, and a changed overlay
+   requires a new plan approval.
+5. Protect the product AGENTS.md files and the harness setup through the
+   policy's `protectedPaths`. The worker cannot change the rules it runs
+   under.
+
+## What the harness enforces regardless of the text
+
+- A worker commit, a changed HEAD or a write outside `writeScope` makes the
+  attempt fail with `scope-violation`. A change to a protected path fails the
+  same way.
+- The harness creates the attempt worktree. Nothing in the attempt runs the
+  project's own `worktree:create`.
+- Gates, the independent review and acceptance happen only in the harness.
+
+The overlay is versioned. A new version is a new file, `AGENTS.controller.v2.md`,
+with a new `provenance.json` version. Existing pins never change silently.