devcontour-harness 0.0.0-stage → 0.1.0-alpha.6

package/examples/files-only/graph.json

@@ -0,0 +1,23 @@
+{
+  "apiVersion": "devcontour-harness/v1alpha1",
+  "id": "notes",
+  "source": { "connector": "files", "ref": "graph.json", "revision": "1" },
+  "orders": [
+    {
+      "apiVersion": "devcontour-harness/v1alpha1",
+      "id": "add-tags",
+      "source": { "connector": "files", "ref": "add-tags", "revision": "1" },
+      "title": "Add tags to notes",
+      "goal": "Notes accept a list of tags; tags are trimmed and deduplicated.",
+      "acceptance": [
+        "createNote({ tags: [' a', 'a', 'b'] }) stores ['a', 'b']",
+        "npm test passes with a JUnit report"
+      ],
+      "role": "developer",
+      "repositoryId": "app",
+      "writeScope": ["src", "test"],
+      "gates": ["unit"],
+      "context": ["norms"]
+    }
+  ]
+}

package/examples/files-only/policy.json

@@ -0,0 +1,30 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["npm", "test"],
+          "timeoutMs": 240000,
+          "report": { "type": "junit", "path": ".reports/junit.xml" }
+        }
+      ],
+      "protectedPaths": [".github/", "package-lock.json", "policy.json", "graph.json"]
+    }
+  ],
+  "roles": {
+    "developer": { "writer": { "runtime": "claude" }, "writePaths": ["src", "test"] }
+  },
+  "review": {
+    "code": { "reviewer": { "runtime": "codex" } },
+    "plan": { "reviewer": { "runtime": "codex" }, "alternates": [{ "runtime": "claude" }] },
+    "contract": { "reviewer": { "runtime": "codex" }, "alternates": [{ "runtime": "claude" }] }
+  },
+  "maxAttempts": 3,
+  "budgets": { "work": { "usd": 5 }, "total": { "usd": 50 }, "onUnknown": "stop" }
+}

package/examples/one-vendor/README.md

@@ -0,0 +1,19 @@
+# Один вендор
+
+Writer и reviewer — claude. Это разрешено только потому, что каждое правило
+ревью явно говорит `"vendor": "same-vendor-allowed"`. Без этой строки
+`harness validate` отклоняет политику (`REVIEWER_SAME_VENDOR`).
+
+Что сохраняется и при одном вендоре:
+
+- reviewer — отдельная роль и отдельный вызов со свежей сессией: в его запросе
+  нет разговора, отчёта и идентификатора сессии writer;
+- reviewer получает исходные критерии приёмки, закреплённый контекст, diff,
+  evidence проверенного SHA и прежние находки;
+- reviewer работает только на чтение: правка дерева или HEAD делает его
+  ответ недействительным;
+- приёмка требует тех же gates и ревью обеих фаз; разные модели не нужны.
+
+Тот же эффект для одного runtime без смены вендора по умолчанию даёт
+`alternates`: reviewer `codex`, запасной `claude` — для автора codex будет
+выбран claude только при `same-vendor-allowed`.

package/examples/one-vendor/policy.json

@@ -0,0 +1,27 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["npm", "test"],
+          "report": { "type": "junit", "path": ".reports/junit.xml" }
+        }
+      ],
+      "protectedPaths": [".github/", "package-lock.json", "policy.json", "graph.json"]
+    }
+  ],
+  "roles": {
+    "developer": { "writer": { "runtime": "claude" } }
+  },
+  "review": {
+    "code": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" },
+    "plan": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" },
+    "contract": { "reviewer": { "runtime": "claude" }, "vendor": "same-vendor-allowed" }
+  }
+}

package/examples/single-task/README.md

@@ -0,0 +1,18 @@
+# Пример: одна задача
+
+Вымышленный репозиторий с одним поручением: добавить `greet(name)` в
+`src/greet.js`. Проверка — `node test/run.js`, она пишет JUnit-отчёт в путь из
+`DEVCONTOUR_REPORT_PATH`.
+
+```sh
+cp -R node_modules/devcontour-harness/examples/single-task greeting && cd greeting
+git init -q && git add -A && git commit -qm init
+npx harness validate --graph graph.json --policy policy.json
+npx harness run --graph graph.json --policy policy.json --state ../greeting-state --author external --sink file:../greeting-results
+npx harness result --state ../greeting-state --work add-greeting
+git rev-parse refs/heads/harness/accepted   # совпадает с result.shas.result
+```
+
+`policy.json` — writer claude, reviewer codex (разные вендоры).
+`policy-same-vendor.json` — reviewer того же вендора, разрешённый явно.
+Для запуска нужны установленные и авторизованные CLI `codex` и `claude`.

package/examples/single-task/graph.json

@@ -0,0 +1,27 @@
+{
+  "apiVersion": "devcontour-harness/v1alpha1",
+  "id": "greeting",
+  "source": {
+    "connector": "files",
+    "ref": "graph.json",
+    "revision": "1"
+  },
+  "orders": [
+    {
+      "apiVersion": "devcontour-harness/v1alpha1",
+      "id": "add-greeting",
+      "source": {
+        "connector": "files",
+        "ref": "add-greeting",
+        "revision": "1"
+      },
+      "title": "Add a greeting function",
+      "goal": "Add greet(name) to src/greet.js returning 'Hello, <name>!'.",
+      "acceptance": ["greet('Ada') returns 'Hello, Ada!'", "npm test passes with a JUnit report"],
+      "role": "developer",
+      "repositoryId": "app",
+      "writeScope": ["src"],
+      "gates": ["unit"]
+    }
+  ]
+}

package/examples/single-task/policy-same-vendor.json

@@ -0,0 +1,55 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["node", "test/run.js"],
+          "report": {
+            "type": "junit",
+            "path": "test-results/junit.xml"
+          }
+        }
+      ],
+      "protectedPaths": [
+        ".github/",
+        "test/",
+        "policy.json",
+        "policy-same-vendor.json",
+        "graph.json"
+      ]
+    }
+  ],
+  "roles": {
+    "developer": {
+      "writer": {
+        "runtime": "claude"
+      }
+    }
+  },
+  "review": {
+    "code": {
+      "reviewer": {
+        "runtime": "claude"
+      },
+      "vendor": "same-vendor-allowed"
+    },
+    "plan": {
+      "reviewer": {
+        "runtime": "claude"
+      },
+      "vendor": "same-vendor-allowed"
+    },
+    "contract": {
+      "reviewer": {
+        "runtime": "claude"
+      },
+      "vendor": "same-vendor-allowed"
+    }
+  }
+}

package/examples/single-task/policy.json

@@ -0,0 +1,52 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": ".",
+      "targetRef": "refs/heads/harness/accepted",
+      "gates": [
+        {
+          "id": "unit",
+          "kind": "test",
+          "command": ["node", "test/run.js"],
+          "report": {
+            "type": "junit",
+            "path": "test-results/junit.xml"
+          }
+        }
+      ],
+      "protectedPaths": [
+        ".github/",
+        "test/",
+        "policy.json",
+        "policy-same-vendor.json",
+        "graph.json"
+      ]
+    }
+  ],
+  "roles": {
+    "developer": {
+      "writer": {
+        "runtime": "claude"
+      }
+    }
+  },
+  "review": {
+    "code": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "plan": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "contract": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    }
+  }
+}

package/examples/single-task/test/run.js

@@ -0,0 +1,19 @@
+// Тест примера: проверяет src/greet.js и пишет JUnit в путь, который задаёт harness.
+const fs = require('fs');
+let ok = false;
+let message = '';
+try {
+  const { greet } = require(process.cwd() + '/src/greet.js');
+  ok = greet('Ada') === 'Hello, Ada!';
+  message = 'greet("Ada") = ' + greet('Ada');
+} catch (error) {
+  message = String(error.message);
+}
+const report = process.env.DEVCONTOUR_REPORT_PATH || 'test-results/junit.xml';
+fs.mkdirSync(require('path').dirname(report), { recursive: true });
+const failure = ok ? '' : '<failure message="' + message.replace(/[<&"]/g, '') + '"/>';
+fs.writeFileSync(
+  report,
+  '<testsuite><testcase classname="greet" name="greets">' + failure + '</testcase></testsuite>',
+);
+console.log(ok ? 'greet: ok' : 'greet: ' + message);

package/examples/toolchains/README.md

@@ -0,0 +1,32 @@
+# Toolchains: семь вариантов target-проекта
+
+Каждый каталог — маленький target-проект с детерминированной функцией `label(n)` и поручением
+дополнять номер нулями до трёх знаков (`item-007`). Тесты проекта уже описывают новое
+поведение и защищены от записи.
+
+| Каталог        | Проект                                                            | Установка                        | Проверки                                                    |
+| -------------- | ----------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| `npm`          | Node + npm                                                        | `npm ci`                         | `npm run check`, `npm run test` (node --test, JUnit)        |
+| `pnpm`         | pnpm workspace, локальный бинарник `fx-check`                     | `pnpm install --frozen-lockfile` | `pnpm run check`, `pnpm run test` (фильтр `@fx/label`)      |
+| `turbo`        | pnpm + Turborepo 2.11.10                                          | `pnpm install --frozen-lockfile` | `turbo run check/test --filter=@fx/label`, test — `--force` |
+| `go`           | Go-модуль без package.json                                        | `go mod download`                | `go vet`, `gotestsum … -- -count=1`                         |
+| `python`       | uv-проект без package.json                                        | `uv sync --locked`               | `ruff check`, `pytest --junitxml`                           |
+| `mixed-go`     | один Git root: pnpm `frontend/` + Go `backend/` + `contract/`     | оба рецепта                      | gates с `cwd`, проверка контракта                           |
+| `mixed-python` | один Git root: pnpm `frontend/` + Python `backend/` + `contract/` | оба рецепта                      | gates с `cwd`, проверка контракта                           |
+
+Состав каталога: `repo/` — target-проект (`_gitignore` при подготовке становится
+`.gitignore`), `policy.json` — политика (`path: "repo"`), `task.json` — поручение и требования
+с `testId`, `good/` и `bad/` — файлы, которые пишет fixture writer в положительном и
+отрицательном прогоне.
+
+<!-- repo-only -->
+
+В репозитории harness (не входит в пакет). Сквозной прогон через обычный путь harness (нужны npm, pnpm, go + gotestsum, uv):
+
+```sh
+node --import tsx scripts/acceptance/t01.mjs
+```
+
+<!-- /repo-only -->
+
+Подробности — `docs/toolchains.md`.

package/examples/toolchains/go/bad/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Неверная реализация для отрицательного прогона: два знака.
+func Label(n int) string {
+	return fmt.Sprintf("item-%02d", n)
+}

package/examples/toolchains/go/good/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Label возвращает метку позиции: номер дополняется нулями до трёх знаков.
+func Label(n int) string {
+	return fmt.Sprintf("item-%03d", n)
+}

package/examples/toolchains/go/policy.json

@@ -0,0 +1,79 @@
+{
+  "policyVersion": 1,
+  "repositories": [
+    {
+      "id": "app",
+      "path": "repo",
+      "targetRef": "refs/heads/harness/accepted",
+      "prepare": [
+        {
+          "id": "install",
+          "command": ["go", "mod", "download"],
+          "timeoutMs": 600000
+        }
+      ],
+      "gates": [
+        {
+          "id": "vet",
+          "kind": "check",
+          "command": ["go", "vet", "./..."],
+          "timeoutMs": 240000
+        },
+        {
+          "id": "acceptance",
+          "kind": "test",
+          "command": ["gotestsum", "--junitfile", ".reports/junit.xml", "--", "-count=1", "./..."],
+          "timeoutMs": 240000,
+          "dependsOn": ["vet"],
+          "report": {
+            "type": "junit",
+            "path": ".reports/junit.xml"
+          }
+        }
+      ],
+      "toolchain": {
+        "tools": {
+          "gotestsum": "1.12.3"
+        }
+      },
+      "protectedPaths": [
+        ".github/",
+        ".githooks/",
+        "go.mod",
+        "go.sum",
+        "label/label_test.go",
+        "REQUIREMENTS.md"
+      ]
+    }
+  ],
+  "roles": {
+    "developer": {
+      "writer": {
+        "runtime": "claude"
+      }
+    }
+  },
+  "review": {
+    "code": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "plan": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    },
+    "contract": {
+      "reviewer": {
+        "runtime": "codex"
+      }
+    }
+  },
+  "isolation": {
+    "mode": "none",
+    "domains": []
+  },
+  "maxAttempts": 2,
+  "runTimeoutMs": 900000
+}

package/examples/toolchains/go/repo/REQUIREMENTS.md

@@ -0,0 +1,9 @@
+# Requirements
+
+## REQ-LABEL-PAD
+
+label(n) pads the number to three digits: label(7) is "item-007", label(42) is "item-042".
+
+## REQ-LABEL-LONG
+
+label(n) keeps numbers longer than three digits unchanged: label(1234) is "item-1234".

package/examples/toolchains/go/repo/_gitignore

@@ -0,0 +1 @@
+.reports/

package/examples/toolchains/go/repo/go.mod

@@ -0,0 +1,5 @@
+module example.com/fxlabel
+
+go 1.24
+
+require golang.org/x/mod v0.25.0

package/examples/toolchains/go/repo/go.sum

@@ -0,0 +1,2 @@
+golang.org/x/mod v0.25.0 h1:n7a+ZbQKQA/Ysbyb0/6IbB1H/X41mKgbhfv7AfG/44w=
+golang.org/x/mod v0.25.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=

package/examples/toolchains/go/repo/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Label возвращает метку позиции.
+func Label(n int) string {
+	return fmt.Sprintf("item-%d", n)
+}

package/examples/toolchains/go/repo/label/label_test.go

@@ -0,0 +1,27 @@
+package label
+
+import "testing"
+
+func TestLabelPadsOneDigit(t *testing.T) {
+	if got := Label(7); got != "item-007" {
+		t.Fatalf("Label(7) = %q, want item-007", got)
+	}
+}
+
+func TestLabelPadsTwoDigits(t *testing.T) {
+	if got := Label(42); got != "item-042" {
+		t.Fatalf("Label(42) = %q, want item-042", got)
+	}
+}
+
+func TestLabelKeepsLong(t *testing.T) {
+	if got := Label(1234); got != "item-1234" {
+		t.Fatalf("Label(1234) = %q, want item-1234", got)
+	}
+}
+
+func TestFormatVersion(t *testing.T) {
+	if !ValidFormat() {
+		t.Fatal("format version is not semver")
+	}
+}

package/examples/toolchains/go/repo/label/version.go

@@ -0,0 +1,9 @@
+package label
+
+import "golang.org/x/mod/semver"
+
+// FormatVersion — версия формата меток (внешняя зависимость модуля проверяется go.sum).
+const FormatVersion = "v1.0.0"
+
+// ValidFormat сообщает, что версия формата — корректная semver.
+func ValidFormat() bool { return semver.IsValid(FormatVersion) }

package/examples/toolchains/go/task.json

@@ -0,0 +1,25 @@
+{
+  "title": "Pad item labels to three digits",
+  "goal": "Change label(n) in label/label.go so the number is zero-padded to three digits (item-007), keeping longer numbers unchanged.",
+  "acceptance": [
+    "label(7) is item-007 and label(42) is item-042",
+    "label(1234) is item-1234",
+    "All gates pass with fresh JUnit reports"
+  ],
+  "writeScope": ["label"],
+  "gates": ["vet", "acceptance"],
+  "requirements": [
+    {
+      "id": "REQ-LABEL-PAD",
+      "gate": "acceptance",
+      "testId": "example.com/fxlabel/label.TestLabelPadsOneDigit",
+      "scenario": "example.com/fxlabel/label.TestLabelPadsOneDigit runs and passes on the accepted SHA"
+    },
+    {
+      "id": "REQ-LABEL-LONG",
+      "gate": "acceptance",
+      "testId": "example.com/fxlabel/label.TestLabelKeepsLong",
+      "scenario": "example.com/fxlabel/label.TestLabelKeepsLong runs and passes on the accepted SHA"
+    }
+  ]
+}

package/examples/toolchains/mixed-go/bad/backend/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Неверная реализация для отрицательного прогона: два знака.
+func Label(n int) string {
+	return fmt.Sprintf("item-%02d", n)
+}

package/examples/toolchains/mixed-go/bad/frontend/src/label.js

@@ -0,0 +1,4 @@
+// Метка позиции заказа: номер дополняется нулями до трёх знаков.
+export function label(n) {
+  return `item-${String(n).padStart(3, '0')}`;
+}

package/examples/toolchains/mixed-go/good/backend/label/label.go

@@ -0,0 +1,9 @@
+// Package label форматирует метки позиций заказа.
+package label
+
+import "fmt"
+
+// Label возвращает метку позиции: номер дополняется нулями до трёх знаков.
+func Label(n int) string {
+	return fmt.Sprintf("item-%03d", n)
+}

package/examples/toolchains/mixed-go/good/frontend/src/label.js

@@ -0,0 +1,4 @@
+// Метка позиции заказа: номер дополняется нулями до трёх знаков.
+export function label(n) {
+  return `item-${String(n).padStart(3, '0')}`;
+}