diff --git a/.githooks/commit-msg b/.githooks/commit-msg index e280d8a..72dac25 100755 --- a/.githooks/commit-msg +++ b/.githooks/commit-msg @@ -4,6 +4,12 @@ set -euo pipefail root="$(git rev-parse --show-toplevel)" +if [[ -n "${NEW_PROJECT_SEED_REQUEST:-}" ]]; then + [[ $# == 1 ]] || exit 1 + python3 -B "$root/.governance/seed_baseline.py" hook-check --root "$root" \ + --request "$NEW_PROJECT_SEED_REQUEST" --message-file "$1" + exit $? +fi policy_runner="$root/.governance/repository_policy.py" [[ -f "$policy_runner" ]] || policy_runner="$root/scripts/repository_policy.py" if [[ -f "$policy_runner" ]]; then diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 9bd795f..bf69c0b 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -8,6 +8,26 @@ set -euo pipefail root="$(git rev-parse --show-toplevel)" branch="$(git symbolic-ref --short HEAD 2>/dev/null || true)" +# A seed request can authorize only the allocator's exact prepared root commit. +# Existing history, product files and an unprepared request fail closed here. +if [[ -n "${NEW_PROJECT_SEED_REQUEST:-}" ]]; then + python3 -B "$root/.governance/seed_baseline.py" hook-check --root "$root" \ + --request "$NEW_PROJECT_SEED_REQUEST" + exit $? +fi + +# Run before every profile/status success path. Identity is supplied by the +# session launcher; the hook must never infer it from the lease holder. +if [[ "$branch" =~ (^|/)ticket[-/][0-9]{3,} ]]; then + writer_runner="$root/.governance/change_lease_check.py" + [[ -f "$writer_runner" ]] || writer_runner="$root/scripts/change_lease_check.py" + if [[ ! -f "$writer_runner" ]]; then + echo "GOV-CHANGE-LEASE-001: writer-lease checker is missing; restore the managed installation." >&2 + exit 1 + fi + python3 -B "$writer_runner" writer-check --root "$root" --operation commit --ref "refs/heads/$branch" +fi + run_worktree_guard() { local runner="$root/.governance/worktree_guard.py" if [[ -f "$runner" ]]; then @@ -70,13 +90,13 @@ if [[ -z "$branch" || "$branch" == "HEAD" ]]; then exit 1 fi -if [[ ! "$branch" =~ ticket[-/]([0-9]{3,}) ]]; then +if [[ ! "$branch" =~ (^|/)ticket[-/]([0-9]{3,}) ]]; then echo "GOV-AGENT-HOST-001: branch '$branch' is not bound to ticket-NNN." >&2 echo " Allocate with ./project/new-ticket.sh and commit on a ticket branch." >&2 exit 1 fi -ticket="ticket-${BASH_REMATCH[1]}" +ticket="ticket-${BASH_REMATCH[2]}" readme_rel="project/$ticket/README.md" ticket_storage="$(git config --local --get new-project.ticketStorage 2>/dev/null || true)" @@ -98,6 +118,36 @@ else exit 1 fi +# A carrier-only follow-up commit (for example the delivery contract that the +# gate asks for after the material change) is admitted only when the ticket +# branch already delivers a material change relative to its target branch. +# A branch without one still needs a material first commit; CI re-checks the +# whole range (GOV-MATERIAL-001). +branch_has_material_delivery() { + local target base path + target="$(PYTHONDONTWRITEBYTECODE=1 python3 - "$root/project/$ticket/intent.json" 2>/dev/null <<'PYTARGET' +import json +import sys +try: + delivery = json.load(open(sys.argv[1], encoding="utf-8")).get("delivery") + value = delivery.get("targetBranch") if isinstance(delivery, dict) else None +except (OSError, ValueError, AttributeError): + value = None +ok = isinstance(value, str) and value and not any(c.isspace() for c in value) and ".." not in value +print(value if ok else "main") +PYTARGET +)" || return 1 + base="$(git merge-base HEAD "refs/remotes/origin/$target" 2>/dev/null)" || return 1 + [[ -n "$base" ]] || return 1 + while IFS= read -r -d '' path; do + case "$path" in + project/ticket-*/*|TODO.md|project/TICKETS.md|config/artifact-registry.json) ;; + *) return 0 ;; + esac + done < <(git diff --no-renames --name-only -z "$base" HEAD --) + return 1 +} + governance_only_transition() { # SQLite transitions never require a Git carrier commit. [[ "${ticket_storage:-files}" == files ]] || return 1 @@ -124,14 +174,25 @@ if grep -Eiq '^-[[:space:]]+\*\*Status\*\*:[[:space:]]*IN_PROGRESS([[:space:]]|$ exit 0 fi + # NUL-framed rename records carry both paths. Moving a material file into + # tracking storage still changes the material source at its previous path. material=false - while IFS= read -r -d '' path; do - case "$path" in - project/ticket-*/*|TODO.md|project/TICKETS.md|config/artifact-registry.json) ;; - *) material=true; break ;; - esac - done < <(git diff --cached --name-only -z --diff-filter=AM --) - if [[ "$material" != true ]]; then + while IFS= read -r -d '' change; do + IFS= read -r -d '' path || break + change_paths=("$path") + if [[ "$change" == R* ]]; then + IFS= read -r -d '' path || break + change_paths+=("$path") + fi + for path in "${change_paths[@]}"; do + case "$path" in + project/ticket-*/*|TODO.md|project/TICKETS.md|config/artifact-registry.json) ;; + *) material=true; break ;; + esac + done + if [[ "$material" == true ]]; then break; fi + done < <(git diff --cached --name-status -z --diff-filter=AMR --) + if [[ "$material" != true ]] && ! branch_has_material_delivery; then echo "GOV-AGENT-HOST-007: staged change contains only ticket tracking carriers." >&2 echo " Add a material deliverable, or emit an external no-change receipt without committing." >&2 exit 1 diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100755 index 0000000..dfb5777 --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,76 @@ +#!/usr/bin/env bash +# Git invokes this before a push. Delivery reaches the declared target branch only +# through a reviewed pull request merged by the validator; a direct push skips +# review, required checks and CI (GOV-PUSH-001). Repositories whose delivery +# profile is main-only or local-audit commit on the target branch by design. +set -euo pipefail + +root="$(git rev-parse --show-toplevel)" +allow_target=false +policy_runner="$root/.governance/repository_policy.py" +[[ -f "$policy_runner" ]] || policy_runner="$root/scripts/repository_policy.py" +if [[ -f "$policy_runner" ]]; then + profile="$(PYTHONDONTWRITEBYTECODE=1 python3 "$policy_runner" --root "$root" --profile 2>/dev/null || true)" + case "$profile" in + local-audit|main-only-planfile|main-only-files) allow_target=true ;; + esac +fi + +if ! targets="$(PYTHONDONTWRITEBYTECODE=1 python3 - "$root" <<'PY' +import json, sys +from pathlib import Path +root = Path(sys.argv[1]) +try: + for rel in (".governance/manifest.json", ".governance/manifest.base.json", "governance/manifest.hub.json"): + path = root / rel + if not path.exists(): + continue + manifest = json.loads(path.read_text(encoding="utf-8")) + if not isinstance(manifest, dict): + raise ValueError("manifest must be an object") + delivery = manifest.get("delivery", {}) + if not isinstance(delivery, dict): + raise ValueError("delivery must be an object") + if "targetBranches" not in delivery: + continue + branches = delivery["targetBranches"] + if not isinstance(branches, list) or not branches or not all(isinstance(b, str) and b and not any(c.isspace() for c in b) for b in branches): + raise ValueError("target branches must be a nonempty list of branch names") + print("\n".join(branches)) + break + else: + print("main") +except (OSError, UnicodeError, ValueError): + print("GOV-PUSH-001: invalid or unreadable target-branch policy; restore the declared manifest before pushing.", file=sys.stderr) + sys.exit(1) +PY +)"; then + exit 1 +fi + +refused=0 +while read -r local_ref local_sha remote_ref remote_sha; do + [[ -n "${remote_ref:-}" ]] || continue + for ref in "$local_ref" "$remote_ref"; do + if [[ "$ref" =~ ^refs/heads/(.*/)?ticket[-/][0-9]{3,} ]]; then + writer_runner="$root/.governance/change_lease_check.py" + [[ -f "$writer_runner" ]] || writer_runner="$root/scripts/change_lease_check.py" + if [[ ! -f "$writer_runner" ]]; then + echo "GOV-CHANGE-LEASE-001: writer-lease checker is missing; restore the managed installation." >&2 + refused=1 + elif ! python3 -B "$writer_runner" writer-check --root "$root" --operation push --ref "$ref"; then + refused=1 + fi + fi + done + [[ "$allow_target" == true ]] && continue + while IFS= read -r target; do + if [[ "$remote_ref" == "refs/heads/$target" ]]; then + echo "GOV-PUSH-001: direct push to '$target' refused ($local_ref -> $remote_ref)." >&2 + echo " Push the ticket branch and open a pull request; the validator merges it." >&2 + refused=1 + fi + done <<< "$targets" +done + +exit "$refused" diff --git a/.github/workflows/new-project-branch-hygiene.yml b/.github/workflows/new-project-branch-hygiene.yml index d010978..8a010e9 100644 --- a/.github/workflows/new-project-branch-hygiene.yml +++ b/.github/workflows/new-project-branch-hygiene.yml @@ -1,16 +1,8 @@ name: new-project-branch-hygiene -# `delete_branch_on_merge` covers the merge exit. This workflow covers the -# other one: a branch whose pull request was closed without merging. Nothing -# in the toolchain removes those, and `GOV-BRANCH-LIFECYCLE-002` validates the -# repository as a whole rather than the diff under review, so a single left -# behind branch fails `governance / remote lifecycle` on *every* later pull -# request, indefinitely and through no fault of its own. -# -# Closing a pull request without merging is the explicit owner decision to -# discard the branch that the check's own remediation asks for, and GitHub -# keeps the branch restorable from the pull request page afterwards. - +# GitHub's delete_branch_on_merge setting handles successfully merged branches. +# Closing an unmerged pull request does not authorize discarding its work. +# Explicit discard requires a separate owner decision and intent reconciliation. on: pull_request: types: [closed] @@ -19,54 +11,17 @@ permissions: contents: read jobs: - discard-unmerged-head: - # Forks cannot be written to, and the default branch is never a head to - # discard. Both guards are cheap and keep the job from ever running where - # deleting would be wrong. - if: >- - github.event.pull_request.merged == false && - github.event.pull_request.head.repo.full_name == github.repository && - github.event.pull_request.head.ref != github.event.repository.default_branch + preserve-unmerged-head: + if: github.event.pull_request.merged == false runs-on: ${{ vars.NEW_PROJECT_RUNNER_LABEL || 'ubuntu-latest' }} - permissions: - contents: write steps: - - name: Delete the closed pull request's head branch + - name: Report preserved pull request branch uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: script: | const ref = context.payload.pull_request.head.ref; - - // Several pull requests may share one head branch. Deleting it - // while another is still open would break that one instead. - const owners = await github.paginate(github.rest.pulls.list, { - owner: context.repo.owner, - repo: context.repo.repo, - state: 'open', - head: `${context.repo.owner}:${ref}`, - per_page: 100, - }); - if (owners.length > 0) { - const numbers = owners.map(pull => `#${pull.number}`).join(', '); - core.info(`Kept ${ref}: still owned by ${numbers}.`); - return; - } - - try { - await github.rest.git.deleteRef({ - owner: context.repo.owner, - repo: context.repo.repo, - ref: `heads/${ref}`, - }); - core.info( - `Deleted ${ref}. GitHub keeps it restorable from the pull request page.`, - ); - } catch (error) { - // The branch is commonly gone already, because the person - // closing the pull request ticked "delete branch". - if (error.status === 404 || error.status === 422) { - core.info(`${ref} was already deleted.`); - return; - } - throw error; - } + core.notice( + `Preserved ${JSON.stringify(ref)}. Closing a pull request does not ` + + 'authorize branch deletion. Reconcile remaining intent and obtain ' + + 'an explicit owner discard decision before a separate deletion.', + ); diff --git a/.github/workflows/new-project-governance.yml b/.github/workflows/new-project-governance.yml index 975f449..6a60d46 100644 --- a/.github/workflows/new-project-governance.yml +++ b/.github/workflows/new-project-governance.yml @@ -103,12 +103,114 @@ jobs: python3 -c 'import sys; assert sys.version_info >= (3, 11), sys.version' - name: Install wellman governance runtime shell: bash + env: + PROTECTED_RUNTIME_SHA: ${{ vars.NEW_PROJECT_RUNTIME_SHA }} + BASE_SHA: ${{ github.event.pull_request.base.sha }} + BASE_REF: ${{ github.event.pull_request.base.ref }} + EVENT_NAME: ${{ github.event_name }} + EVENT_SHA: ${{ github.sha }} + EVENT_REF: ${{ github.ref }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GOVERNANCE_ROOT: . run: | set -euo pipefail - standard_version="$(python3 -c 'import json; print(json.load(open(".governance/manifest.json", encoding="utf-8"))["standard"]["version"])')" - runtime_ref="v${standard_version}" - python3 -m pip install --disable-pip-version-check "git+https://github.com/wellmanifest/new-project.git@${runtime_ref}#subdirectory=packages/wellman" - wellman --version + # Repository variable is protected configuration; candidate manifests are not. + runtime_ref="$(python3 -I - <<'PY_RUNTIME' + import json + import os + import re + import subprocess + from pathlib import PurePosixPath + + def reject(message): + raise SystemExit("Trusted governance runtime pin: " + message) + + def sha(value): + if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{40}", value): + reject("a full lowercase commit SHA is required") + return value + + def unique(pairs): + result = {} + for key, value in pairs: + if key in result: + reject("duplicate lock key") + result[key] = value + return result + + protected = os.environ.get("PROTECTED_RUNTIME_SHA", "") + if protected: + print(sha(protected)) + else: + if os.environ.get("EVENT_NAME") == "pull_request": + branch = os.environ.get("DEFAULT_BRANCH", "") + if not branch or os.environ.get("BASE_REF") != branch: + reject("PR base must be the default branch or use a protected SHA") + base = sha(os.environ.get("BASE_SHA", "")) + else: + branch = os.environ.get("DEFAULT_BRANCH", "") + if not branch or os.environ.get("EVENT_REF") != "refs/heads/" + branch: + reject("non-PR runs require the default branch or a protected SHA") + base = sha(os.environ.get("EVENT_SHA", "")) + target = os.path.relpath(os.path.abspath(os.environ.get("GOVERNANCE_ROOT", ".")), os.getcwd()) + if ".." in PurePosixPath(target).parts or "\\" in target: + reject("target-root must stay inside the repository") + lock_path = str(PurePosixPath(target) / ".governance/manifest.lock.json") + observed = subprocess.run(["git", "show", base + ":" + lock_path], + capture_output=True, text=True) + if observed.returncode: + reject("trusted base lock unavailable; configure protected NEW_PROJECT_RUNTIME_SHA for initial adoption") + try: + lock = json.loads(observed.stdout, object_pairs_hook=unique) + standard = lock["standard"] + if (lock["schema"] != "new-project.lock/v1" + or standard["id"] != "wellmanifest/new-project" + or standard["sourceRepository"] != "wellmanifest/new-project" + or standard["publicationStatus"] != "published"): + reject("unsupported or unpublished trusted adoption") + print(sha(standard["sourceRevision"])) + except (ValueError, KeyError, TypeError): + reject("malformed trusted base lock") + PY_RUNTIME + )" + runtime_venv="$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/wellman-governance.XXXXXX")" + python3 -I -m venv "$runtime_venv" + "$runtime_venv/bin/python" -I -m pip install --disable-pip-version-check "git+https://github.com/wellmanifest/new-project.git@${runtime_ref}#subdirectory=packages/wellman" + # Accept only a recognized console entrypoint from this isolated runtime. + runtime_command="$("$runtime_venv/bin/python" -I - <<'PY_RUNTIME_COMMAND' + import os + import sys + from importlib.metadata import distributions + from pathlib import Path + + if sys.prefix == sys.base_prefix: + raise SystemExit("Governance runtime requires its isolated environment") + found = [] + for name, command, module in ( + ("wellmanifest-governance", "wellman-governance", "wellmanifest_governance_runtime"), + ("wellman", "wellman", "wellman"), + ): + matches = list(distributions(name=name)) + if not matches: + continue + if len(matches) != 1: + raise SystemExit("Ambiguous governance runtime distribution: " + name) + installed = matches[0] + entries = [entry.value for entry in installed.entry_points + if entry.group == "console_scripts" and entry.name == command] + launcher = Path(sys.executable).parent / command + if (entries != [module + ".check:main"] + or not Path(installed.locate_file("")).resolve().is_relative_to(Path(sys.prefix).resolve()) + or launcher.is_symlink() or not launcher.is_file() or not os.access(launcher, os.X_OK)): + raise SystemExit("Unsupported governance runtime identity: " + name) + found.append(command) + if len(found) != 1: + raise SystemExit("Expected exactly one supported governance runtime") + print(found[0]) + PY_RUNTIME_COMMAND + )" + "$runtime_venv/bin/$runtime_command" --version + printf '%s\n' "$runtime_venv/bin" >> "$GITHUB_PATH" - name: Run the managed governance gate shell: bash env: @@ -126,7 +228,35 @@ jobs: fi range_arguments=(--base "$BASE_SHA" --head "$HEAD_SHA") fi - wellman check --root . --actor ci --json "${range_arguments[@]}" + # Resolve only the runtime installed from the independently selected pin. + runtime_module="$(python -I - <<'PY_GATE_RUNTIME' + import sys + from importlib.metadata import PackageNotFoundError, distribution + from pathlib import Path + + if sys.prefix == sys.base_prefix: + raise SystemExit("Governance runtime requires its isolated environment") + for name, command, module in ( + ("wellmanifest-governance", "wellman-governance", "wellmanifest_governance_runtime"), + ("wellman", "wellman", "wellman"), + ): + try: + installed = distribution(name) + except PackageNotFoundError: + continue + expected = module + ".check:main" + entries = [entry.value for entry in installed.entry_points + if entry.group == "console_scripts" and entry.name == command] + if (entries != [expected] + or not Path(installed.locate_file("")).resolve().is_relative_to(Path(sys.prefix).resolve())): + raise SystemExit("Unsupported governance runtime identity: " + name) + print(module) + break + else: + raise SystemExit("Governance runtime is not installed") + PY_GATE_RUNTIME + )" + python -I -m "$runtime_module" check --root . --actor ci --json "${range_arguments[@]}" # The adopter's standard-adoption.json mode decides: "enforce" fails on # missing packs, "audit" reports them without failing the gate. python3 .governance/standard_pack_check.py --root . --format json diff --git a/.governance/AGENT_DECISIONS.md b/.governance/AGENT_DECISIONS.md index 6836002..1a1e560 100644 --- a/.governance/AGENT_DECISIONS.md +++ b/.governance/AGENT_DECISIONS.md @@ -48,6 +48,15 @@ both HEADs is inherited context. Two actual dirty writers remain contested; unresolved ancestry retains conservative checking. Intent ownership remains a separate check even when Git can merge file contents. +For a non-primary detached checkout with no commits ahead of the observed +target, a staged path already identical to that target is not an outstanding +contribution. The query verifies exact target blob and mode, stage-zero index +entry, and raw filesystem blob and mode. Different or unknown evidence remains +pending. Named branches and active intent retain their reservations. All dirty +paths remain visible, and the observation digest binds index entries as well +as filesystem content. This does not classify the checkout as disposable or +authorize its cleanup, lease transfer, source writes or publication. + `wellmanifest/git-lifecycle` still owns cleanup effects; `ticket-lifecycle` owns reservations, and protected merge/publication controllers own external effects. Fix an incorrect checker at its HOME with a failing regression and diff --git a/.governance/agent-hosts.json b/.governance/agent-hosts.json index 13dc33e..7455c3b 100644 --- a/.governance/agent-hosts.json +++ b/.governance/agent-hosts.json @@ -4,10 +4,12 @@ "hook": { "path": ".githooks/pre-commit", "hooksPathConfig": ".githooks", - "additionalHooks": [".githooks/commit-msg"], + "additionalHooks": [".githooks/commit-msg", ".githooks/pre-push"], "runtimeFiles": [ ".governance/worktree_guard.py", ".governance/worktree_overlap_check.py", + ".governance/change_lease_check.py", + ".governance/change-lease.schema.json", "worktree-guard.yaml" ] }, diff --git a/.governance/agent-hosts.schema.json b/.governance/agent-hosts.schema.json index 2fca5b7..762f7e0 100644 --- a/.governance/agent-hosts.schema.json +++ b/.governance/agent-hosts.schema.json @@ -18,7 +18,7 @@ "hooksPathConfig": { "type": "string", "minLength": 1 }, "additionalHooks": { "type": "array", "uniqueItems": true, - "items": { "type": "string", "enum": [".githooks/commit-msg", ".githooks/prepare-commit-msg"] } + "items": { "type": "string", "enum": [".githooks/commit-msg", ".githooks/prepare-commit-msg", ".githooks/pre-push"] } }, "runtimeFiles": { "type": "array", diff --git a/.governance/agent_host_check.py b/.governance/agent_host_check.py index 1a6804a..59604a9 100644 --- a/.governance/agent_host_check.py +++ b/.governance/agent_host_check.py @@ -290,7 +290,7 @@ def check_hook(root: Path, contract: dict[str, Any], actor: str) -> list[Finding additional = contract["hook"].get("additionalHooks", []) if (not isinstance(additional, list) or any(not isinstance(path, str) or path not in { - ".githooks/commit-msg", ".githooks/prepare-commit-msg", + ".githooks/commit-msg", ".githooks/prepare-commit-msg", ".githooks/pre-push", } for path in additional) or len(additional) != len(set(additional))): findings.append(Finding( @@ -342,7 +342,10 @@ def python_declaration(marker: Path) -> tuple[dict[str, Any] | None, dict[str, A document = tomllib.loads(marker.read_text(encoding="utf-8")) except (OSError, tomllib.TOMLDecodeError): return None, {} - declaration = document.get("tool", {}).get("wellmanifest") + if not isinstance(document, dict): + return None, {} + tool = document.get("tool") + declaration = tool.get("wellmanifest") if isinstance(tool, dict) else None return (declaration if isinstance(declaration, dict) else None), document @@ -358,11 +361,15 @@ def node_declaration(marker: Path) -> tuple[dict[str, Any] | None, dict[str, Any def lifecycle_value(kind: str, document: dict[str, Any]) -> str: + if not isinstance(document, dict): + return "" if kind == "npm-script": scripts = document.get("scripts") value = scripts.get("prepare") if isinstance(scripts, dict) else None else: - options = document.get("tool", {}).get("pytest", {}).get("ini_options", {}) + tool = document.get("tool") + pytest = tool.get("pytest") if isinstance(tool, dict) else None + options = pytest.get("ini_options") if isinstance(pytest, dict) else None value = options.get("addopts") if isinstance(options, dict) else None if isinstance(value, list): return " ".join(str(item) for item in value) @@ -461,7 +468,7 @@ def check_declaration( return findings -def workflow_job_names(path: Path) -> list[str]: +def required_checks_validator(): """Use the adjacent managed validator for the offline workflow contract. Load by the package path, never by a target-controlled import search path. @@ -476,7 +483,11 @@ def workflow_job_names(path: Path) -> list[str]: raise ImportError("managed required-checks validator is missing") checker = importlib.util.module_from_spec(spec) spec.loader.exec_module(checker) - return checker.workflow_job_names(path) + return checker + + +def workflow_job_names(path: Path) -> list[str]: + return required_checks_validator().workflow_job_names(path) def check_guidance_anomalies(root: Path, contract: dict[str, Any]) -> list[Finding]: @@ -587,6 +598,12 @@ def check_guidance_anomalies(root: Path, contract: dict[str, Any]) -> list[Findi )) return findings if not isinstance(declaration, dict): + findings.append(Finding( + "GOV-AGENT-HOST-004", + "CI required-checks declaration must be a JSON object.", + "Restore a valid managed required-checks declaration.", + [str(checks_path.relative_to(root))], + )) return findings pairs: list[tuple[str, str]] = [] bound = declaration.get("requiredChecks") @@ -598,6 +615,18 @@ def check_guidance_anomalies(root: Path, contract: dict[str, Any]) -> list[Findi pairs = [(str(name), declaration["workflowFile"]) for name in declaration["requiredCheckNames"] if isinstance(name, str)] + if "externalChecks" in declaration: + try: + external = required_checks_validator().external_check_names(declaration) + except (OSError, UnicodeDecodeError, ImportError, AttributeError, ValueError, SystemExit): + findings.append(Finding( + "GOV-AGENT-HOST-004", + "CI external required-check declaration cannot be resolved.", + "Restore the managed validator and an explicit supported producer binding; run check_required_checks.py for the precise refusal.", + [str(checks_path.relative_to(root))], + )) + return findings + pairs = [(name, workflow) for name, workflow in pairs if name not in external] if not pairs: findings.append(Finding( "GOV-AGENT-HOST-004", diff --git a/.governance/bootstrap_packaging_scope.py b/.governance/bootstrap_packaging_scope.py new file mode 100755 index 0000000..b5c09cc --- /dev/null +++ b/.governance/bootstrap_packaging_scope.py @@ -0,0 +1,267 @@ +#!/usr/bin/env python3 +"""Explicit current-owner scope correction for first native packaging adoption. + +Only unchanged, existing packaging markers in the installed published contract +may be added. The controller changes the intent and fenced reservation, never +packaging source, expiry, owner, publication state or another checkout. +""" +from contextlib import nullcontext +from datetime import datetime, timezone +import argparse +import base64 +import importlib.util +import json +from pathlib import Path +import re +import sys + + +def sibling(name): + path = Path(__file__).parent + sys.path.insert(0, str(path)) + try: + spec = importlib.util.spec_from_file_location('_packaging_scope_' + name, path / (name + '.py')) + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + finally: + sys.path.pop(0) + + +store = sibling('terminal_lease_release') +start = sibling('work_start_check') +allocation = sibling('snapshot_allocation') +FIELDS = {'schema', 'requestId', 'ticket', 'headSha', 'paths', 'leaseRevision', + 'fencingToken', 'leaseSha256', 'intentSha256', 'bootstrapReceiptSha256'} +# Closed capability of this published controller. A target-owned contract and +# its rewritten hashes cannot introduce another executable source path. +SUPPORTED_MARKERS = frozenset({'pyproject.toml', 'package.json'}) +require, sha, encoded = store.require, store.sha, store.encoded + + +def raw(path): + with store.directory(path.parent) as (fd, verify): + value = store.read_at(fd, path.name, private=True) + verify() + return value + + +def request_value(path, primary): + path = path.absolute() + require(not path.is_relative_to(primary), 'request_must_be_external') + request = store.decode(raw(path)) + require(isinstance(request, dict) and set(request) == FIELDS + and request['schema'] == 'new-project.bootstrap-packaging-scope/v1', 'invalid_request') + require(isinstance(request['requestId'], str) + and re.fullmatch('[a-z0-9][a-z0-9.-]{0,95}', request['requestId']), 'invalid_request_id') + require(isinstance(request['ticket'], str) and re.fullmatch('ticket-[0-9]{3,}', request['ticket']), 'invalid_ticket') + for key in ('leaseSha256', 'intentSha256', 'bootstrapReceiptSha256'): + require(isinstance(request[key], str) and re.fullmatch('[0-9a-f]{64}', request[key]), 'invalid_digest') + require(isinstance(request['headSha'], str) and re.fullmatch('[0-9a-f]{40}', request['headSha']), 'invalid_head') + require(all(type(request[k]) is int and request[k] > 0 for k in ('leaseRevision', 'fencingToken')), 'invalid_cas') + paths = request['paths'] + require(isinstance(paths, list) and 0 < len(paths) <= 8 + and all(isinstance(p, str) and re.fullmatch('[A-Za-z0-9_.-]+', p) + and p not in {'.', '..'} for p in paths) + and len(paths) == len(set(paths)), 'literal_unique_packaging_markers_required') + return request + + +def pinned_packaging(root, primary, request): + receipt_path = root / '.subactor/receipts/bootstrap-adoption.json' + receipt_raw = raw(receipt_path) + require(sha(receipt_raw) == request['bootstrapReceiptSha256'], 'bootstrap_receipt_changed') + receipt = store.decode(receipt_raw) + lock_raw = raw(root / '.governance/manifest.lock.json') + lock = store.decode(lock_raw) + standard = lock.get('standard', {}) + require(receipt.get('schema') == 'new-project.bootstrap-adoption/v1' + and receipt.get('bootstrapKind') in {'legacy-scaffold', 'fresh'} + and receipt.get('baseSha') == request['headSha'] + and receipt.get('commonGitDir') == store.git(root, 'rev-parse', '--path-format=absolute', '--git-common-dir') + and receipt.get('sourceRevision') == standard.get('sourceRevision') + and standard.get('sourceRepository') == 'wellmanifest/new-project' + and standard.get('publicationStatus') == 'published' + and re.fullmatch('[0-9a-f]{40}', str(standard.get('sourceRevision', ''))), 'published_bootstrap_required') + files = receipt.get('files', {}) + require(isinstance(files, dict) and files.get('.governance/manifest.lock.json') == sha(lock_raw), 'bootstrap_lock_changed') + managed = lock.get('managedFiles') + require(isinstance(managed, dict) and managed, 'managed_pin_required') + for name, digest in managed.items(): + require(isinstance(name, str) and not Path(name).is_absolute() + and '..' not in Path(name).parts, 'unsafe_managed_path') + require(sha(raw(root / name)) == digest, 'managed_pin_drift') + contract_path = '.governance/agent-hosts.json' + contract_raw = raw(root / contract_path) + require(files.get(contract_path) == sha(contract_raw) + and managed.get(contract_path) == sha(contract_raw), 'packaging_contract_unbound') + contract = store.decode(contract_raw).get('packaging', {}) + require(isinstance(contract, dict), 'packaging_contract_invalid') + markers = {row.get('marker') for row in contract.values() if isinstance(row, dict)} + require(set(request['paths']) <= markers & SUPPORTED_MARKERS, 'path_is_not_published_packaging_marker') + if receipt['bootstrapKind'] == 'legacy-scaffold': + start.bootstrap_scaffold_at_head(root, request['headSha']) + else: + require(not store.git(root, 'ls-tree', request['headSha'], '--', '.governance'), 'fresh_base_has_governance') + for name in request['paths']: + content = raw(root / name) + row = store.git(root, 'ls-tree', request['headSha'], '--', name) + require(row.startswith(('100644 blob ', '100755 blob ')) and row.endswith('\t' + name), 'committed_regular_marker_required') + require(store.git(root, 'hash-object', '--no-filters', '--', name) + == row.split()[2], 'packaging_source_changed') + require(store.git(root, 'diff', 'HEAD', '--', name) == '', 'packaging_index_or_mode_changed') + require(content == raw(root / name), 'packaging_observation_changed') + return standard['sourceRevision'] + + +def transaction(root, primary, request, lease_raw, intent_raw, actor, session, stamp): + lease, intent = store.decode(lease_raw), store.decode(intent_raw) + require(sha(lease_raw) == request['leaseSha256'] and sha(intent_raw) == request['intentSha256'], 'scope_cas_changed') + require(not store.canonical.validate_lease(lease), 'invalid_canonical_lease') + require((lease['ownerActor'], lease['ownerSession']) == (actor, session), 'current_owner_required') + require((lease['leaseRevision'], lease['fencingToken']) + == (request['leaseRevision'], request['fencingToken']), 'stale_fencing') + require(lease['phase'] in {'claimed', 'editing', 'validating'} and not lease['publicationFrozen'], 'inactive_or_frozen_lease') + now = datetime.now(timezone.utc) + issued, heartbeat, expiry = (datetime.fromisoformat(lease[k].replace('Z', '+00:00')) + for k in ('issuedAt', 'heartbeatAt', 'expiresAt')) + require(issued <= heartbeat <= now < expiry, 'live_owner_required') + require(root.name == lease['worktreeId'] and lease['ticketId'] == request['ticket'] + and lease['workstream'] == intent.get('workstream') == 'governance' + and intent.get('ticket') == request['ticket'] + and intent.get('schema') == 'new-project.intent/v3', 'ticket_scope_mismatch') + match = store.WORKTREE_ID_RE.fullmatch(root.name) + require(match is not None and match[1] == request['ticket'], 'canonical_worktree_required') + branch = 'refs/heads/ticket/' + match[2] + '-' + match[3] + require(lease['headSha'] == request['headSha'] and lease['branchRef'] == branch + and store.git(root, 'symbolic-ref', 'HEAD') == branch + and store.git(root, 'rev-parse', 'HEAD') == request['headSha'], 'branch_or_head_changed') + accepted = store._accepted_repositories(primary) + require(lease['repositoryRef'] in accepted, 'repository_binding_mismatch') + old_paths = intent.get('allowedPaths') + require(isinstance(old_paths, list) and start.digest(old_paths) == lease['scopeHash'], 'intent_scope_unbound') + require(not set(request['paths']) & set(old_paths) + and not any(start.path_ignored(p, tuple(intent.get('forbiddenPaths', []))) for p in request['paths']), 'path_already_owned_or_forbidden') + revision = pinned_packaging(root, primary, request) + delivery = intent.get('delivery', {}) + require(delivery.get('acceptedBaseSha') == request['headSha'] + and delivery.get('targetBranch') == lease['targetBranch'] + and delivery.get('standardAdoption') == {'sourceRepository': 'wellmanifest/new-project', + 'fromRevision': None, 'toRevision': revision}, 'initial_adoption_intent_required') + report = start.inspect(root, 'governance', request['paths']) + require(not report.get('diagnostic') and all( + b['path'] == str(root) and b['ticket'] == request['ticket'] and b['reason'] == 'scope-reservation' + for b in report['blockers']), 'packaging_scope_contested') + intent['allowedPaths'] = [*old_paths, *request['paths']] + command = {'schema': store.canonical.REQUEST_SCHEMA, 'requestId': request['requestId'] + '-scope', + 'leaseId': lease['leaseId'], 'action': 'heartbeat', 'expectedRevision': lease['leaseRevision'], + 'expectedFencingToken': lease['fencingToken'], 'expectedPhase': lease['phase'], + 'requestedBy': actor, 'idempotencyKey': request['requestId'] + ':scope', + 'targetHeadSha': request['headSha'], 'replacementReceiptRef': None, + 'authorityRef': 'policy:explicit-bootstrap-packaging-scope', 'requestedAt': stamp} + receipt, errors = store.canonical.evaluate_transition(lease, command) + require(not errors, 'scope_transition_refused') + lease.update(scopeHash=start.digest(intent['allowedPaths']), leaseRevision=receipt['leaseRevision'], + fencingToken=receipt['fencingToken'], heartbeatAt=stamp, + previousReceiptRef=receipt['receiptRef'], eventSequence=lease['eventSequence'] + 1) + require(not store.canonical.validate_lease(lease), 'invalid_amended_lease') + return encoded(lease), encoded(intent), receipt + + +def amend(root, request_path, actor, session, *, apply=False): + root = Path(root).absolute() + registrations = start.worktrees(root) + _, primary, common = allocation.context(root) + require(root == root.resolve() == primary / '.worktrees' / root.name + and any(row['worktree'] == str(root) for row in registrations), 'canonical_registered_checkout_required') + request = request_value(Path(request_path), primary) + request_digest = sha(encoded({'request': request, 'actor': actor, 'session': session})) + journal_dir = primary / '.subactor/receipts/bootstrap-packaging-scope' + journal_name = request['requestId'] + '.json' + lease_name = root.name + '.json' + intent_dir = root / 'project' / request['ticket'] + with (allocation.allocation_lock(common) if apply else nullcontext()), \ + store.directory(primary / '.subactor/leases') as (lfd, verify_lease), \ + store.directory(intent_dir) as (ifd, verify_intent): + with (store.lease_lock(lfd, lease_name, verify_lease) if apply else nullcontext(verify_lease)) as verify: + current_lease = store.read_at(lfd, lease_name, private=True) + current_intent = store.read_at(ifd, 'intent.json', private=True) + saved = None + try: + saved = store.decode(raw(journal_dir / (journal_name + '.prepared'))) + except FileNotFoundError: + pass + if saved is not None: + require(saved.get('requestSha256') == request_digest, 'request_identity_reused') + before_lease = base64.b64decode(saved['beforeLease'], validate=True) + before_intent = base64.b64decode(saved['beforeIntent'], validate=True) + stamp = saved['stamp'] + else: + before_lease, before_intent = current_lease, current_intent + stamp = datetime.now(timezone.utc).isoformat(timespec='microseconds').replace('+00:00', 'Z') + after_lease, after_intent, transition = transaction( + root, primary, request, before_lease, before_intent, actor, session, stamp) + record = {'schema': 'new-project.bootstrap-packaging-scope-receipt/v1', + 'requestSha256': request_digest, 'stamp': stamp, + 'beforeLease': base64.b64encode(before_lease).decode(), + 'beforeIntent': base64.b64encode(before_intent).decode(), + 'afterLeaseSha256': sha(after_lease), 'afterIntentSha256': sha(after_intent), + 'paths': request['paths'], 'transition': transition} + require(saved is None or saved == record, 'prepared_transaction_changed') + require((current_lease, current_intent) in ((before_lease, before_intent), + (after_lease, before_intent), (after_lease, after_intent)), 'partial_transaction_changed') + if not apply: + return {'status': 'planned', 'paths': request['paths'], 'grantsAuthority': False} + with store.directory(journal_dir, create=True) as (jfd, verify_journal): + if saved is None: + store.atomic_at(jfd, journal_name + '.prepared', encoded(record), exclusive=True) + # Re-observe pins, packaging bytes and competing reservations at + # the effect boundary; the durable preparation is not authority. + require(transaction(root, primary, request, before_lease, before_intent, + actor, session, stamp) == (after_lease, after_intent, transition), + 'scope_observation_changed') + verify(); verify_intent(); verify_journal() + require(store.read_at(lfd, lease_name, private=True) == current_lease + and store.read_at(ifd, 'intent.json', private=True) == current_intent, 'scope_cas_changed') + require(store.git(root, 'rev-parse', 'HEAD') == request['headSha'], 'head_changed_before_apply') + # Fence the prior reservation before exposing its expanded intent. + if current_lease == before_lease: + store.atomic_at(lfd, lease_name, after_lease) + if current_intent == before_intent: + store.atomic_at(ifd, 'intent.json', after_intent) + require(store.read_at(lfd, lease_name, private=True) == after_lease + and store.read_at(ifd, 'intent.json', private=True) == after_intent, 'applied_scope_changed') + verify(); verify_intent(); verify_journal() + try: + require(store.read_at(jfd, journal_name) == encoded(record), 'completed_receipt_changed') + except FileNotFoundError: + store.atomic_at(jfd, journal_name, encoded(record), exclusive=True) + lease = store.decode(after_lease) + return {'status': 'amended', 'ticket': request['ticket'], 'worktreePath': str(root), + 'receipt': str(journal_dir / journal_name), 'paths': request['paths'], + 'leaseRevision': lease['leaseRevision'], 'fencingToken': lease['fencingToken'], + 'expiresAt': lease['expiresAt'], 'grantsEditAuthority': False, 'grantsMergeAuthority': False, + 'writerEnvironment': {'NEW_PROJECT_WRITER_ACTOR': actor, 'NEW_PROJECT_WRITER_SESSION': session, + 'NEW_PROJECT_LEASE_REVISION': str(lease['leaseRevision']), + 'NEW_PROJECT_FENCING_TOKEN': str(lease['fencingToken'])}} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', type=Path, required=True) + parser.add_argument('--request', type=Path, required=True) + parser.add_argument('--actor', required=True) + parser.add_argument('--session', required=True) + parser.add_argument('--apply', action='store_true') + args = parser.parse_args() + try: + print(json.dumps(amend(args.root, args.request, args.actor, args.session, apply=args.apply), sort_keys=True)) + except (OSError, ValueError, TypeError, KeyError, PermissionError, start.ObservationError) as error: + print('GOV-BOOTSTRAP-PACKAGING: ' + str(error), file=sys.stderr) + return 1 + return 0 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/.governance/branch_intent_reconciliation.py b/.governance/branch_intent_reconciliation.py index a15f92c..574211e 100644 --- a/.governance/branch_intent_reconciliation.py +++ b/.governance/branch_intent_reconciliation.py @@ -157,6 +157,7 @@ def reconcile_criterion_disposition(row, criteria, proof, decision, follow, unre elif row["outcome"] in ("partial", "missing"): require(decision is None or decision["facts"]["disposition"] == "discard", "remaining work has contradictory decision") + require(decision is None or follow is None, "remaining work cannot both discard and defer") require(follow is not None or (decision is not None and decision["facts"]["disposition"] == "discard"), "remaining work needs a follow-up or explicit discard decision") elif row["outcome"] == "unknown": diff --git a/.governance/branch_lifecycle_check.py b/.governance/branch_lifecycle_check.py index 20b46c0..3b20052 100755 --- a/.governance/branch_lifecycle_check.py +++ b/.governance/branch_lifecycle_check.py @@ -47,13 +47,21 @@ def require_repository(value: Any, label: str, *, nullable: bool = False) -> str def require_ref(value: Any, label: str) -> str: + # Snapshot fields are literal branch names. Validate Git's branch syntax + # offline; invoking --branch here could expand revision shorthand (@{-1}). if ( not isinstance(value, str) or not value or len(value) > 255 - or any(ord(character) < 32 or ord(character) == 127 for character in value) + or value in {"HEAD", "@"} + or value.startswith(("/", "-")) + or value.endswith(("/", ".")) + or any(token in value for token in ("..", "//", "@{")) + or any(part.startswith(".") or part.endswith(".lock") for part in value.split("/")) + or any(ord(character) <= 32 or ord(character) == 127 or character in "~^:?*[\\" + for character in value) ): - raise SnapshotError(f"{label} must be a non-empty bounded Git ref name") + raise SnapshotError(f"{label} must be a non-empty bounded literal Git branch name") return value diff --git a/.governance/change-evaluation.schema.json b/.governance/change-evaluation.schema.json index 1ea7abd..03d0111 100644 --- a/.governance/change-evaluation.schema.json +++ b/.governance/change-evaluation.schema.json @@ -38,7 +38,7 @@ "allOf": [ { "if": { - "properties": { "event": { "enum": ["pull_request", "merge_group"] } }, + "properties": { "event": { "const": "pull_request" } }, "required": ["event"] }, "then": { "required": ["pullRequest"] } diff --git a/.governance/change-lease.schema.json b/.governance/change-lease.schema.json index ed14b28..f67ee9a 100644 --- a/.governance/change-lease.schema.json +++ b/.governance/change-lease.schema.json @@ -9,7 +9,7 @@ ], "$defs": { "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, - "gitSha": {"type": "string", "pattern": "^[0-9a-f]{40,64}$"}, + "gitSha": {"type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})(?![\\s\\S])"}, "phase": {"enum": ["claimed", "editing", "validating", "publication_frozen", "dispatching", "approved", "merged", "closed", "cancelled", "expired", "released"]}, "action": {"enum": ["heartbeat", "begin-edit", "begin-validation", "freeze-publication", "dispatch-validation", "approve", "record-merge", "close", "cancel", "expire", "release", "supersede"]}, "lease": { diff --git a/.governance/change_lease_check.py b/.governance/change_lease_check.py index 42811bb..bd0d828 100755 --- a/.governance/change_lease_check.py +++ b/.governance/change_lease_check.py @@ -5,21 +5,32 @@ import argparse import json +import hashlib +import os +import stat +import subprocess import re import sys -from datetime import datetime +from datetime import datetime, timezone from functools import lru_cache from pathlib import Path from typing import Any +from urllib.parse import urlparse LEASE_SCHEMA = "wellmanifest.change-lease/v1" REQUEST_SCHEMA = "wellmanifest.change-lease-transition/v1" RECEIPT_SCHEMA = "wellmanifest.change-lease-receipt/v1" SHA256_RE = re.compile(r"^[0-9a-f]{64}$") -GIT_SHA_RE = re.compile(r"^[0-9a-f]{40,64}$") +# JSON Schema patterns search strings; unlike $, this assertion cannot match +# just before a final line terminator and is portable to ECMAScript engines. +GIT_SHA_RE = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})(?![\s\S])") PHASES = {"claimed", "editing", "validating", "publication_frozen", "dispatching", "approved", "merged", "closed", "cancelled", "expired", "released"} FROZEN_PHASES = {"publication_frozen", "dispatching", "approved"} TERMINAL_REPLACEMENT_PHASES = {"merged", "closed", "cancelled", "released"} +# wellmanifest/worktrees v5 layout: the single source for every lease and worktree reader. +WORKTREES_ROOT = ".worktrees" +LEASE_ROOT = ".subactor/leases" +MAX_LEASE_BYTES = 65536 TRANSITIONS = { "heartbeat": {phase: phase for phase in PHASES - {"released"}}, "begin-edit": {"claimed": "editing"}, @@ -343,6 +354,144 @@ def print_findings(findings: list[dict[str, Any]], output_format: str) -> None: for item in findings: print(f"{item['code']} ERROR: {item['message']}") +TICKET_REF = re.compile(r"^refs/heads/ticket[-/]([0-9]{3,})-[a-z0-9]+(?:-[a-z0-9]+)*$") + + +def read_writer_lease(path: Path) -> dict[str, Any]: + """Open bounded regular data without following any symlink component.""" + if os.name == "nt": + if path.is_symlink() or any(p.is_symlink() for p in path.parents): + raise ValueError("Lease path contains symlinks") + if not path.is_file(): + raise ValueError("Lease must be a regular file") + raw = path.read_bytes() + if len(raw) > MAX_LEASE_BYTES: + raise ValueError("Lease exceeds bounded size") + value = json.loads(raw.decode("utf-8")) + if not isinstance(value, dict): + raise ValueError("Lease must be an object") + return value + flags = os.O_RDONLY | os.O_NOFOLLOW + descriptor = os.open(path.anchor, flags | os.O_DIRECTORY) + try: + for component in path.parts[1:-1]: + child = os.open(component, flags | os.O_DIRECTORY, dir_fd=descriptor) + os.close(descriptor) + descriptor = child + leaf = os.open(path.name, flags | os.O_NONBLOCK, dir_fd=descriptor) + with os.fdopen(leaf, "rb") as stream: + if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode): + raise ValueError("Lease must be a regular file") + raw = stream.read(MAX_LEASE_BYTES + 1) + if len(raw) > MAX_LEASE_BYTES: + raise ValueError("Lease exceeds bounded size") + value = json.loads(raw) + if not isinstance(value, dict): + raise ValueError("Lease must be an object") + return value + finally: + os.close(descriptor) + + +def canonical_owner_repository(url: str) -> str | None: + """Return the ``owner/name`` repository identity an origin URL carries. + + Mirrors the allocator's canonical repository URI reduction so a lease can + bind either the canonical identity or the legacy ``local/`` label. + """ + value = (url or "").strip() + if not value: + return None + match = re.fullmatch(r"git@([^:]+):(.+?)(?:\.git)?", value) + if match: + value = f"ssh://git@{match.group(1)}/{match.group(2)}" + try: + parsed = urlparse(value) + except ValueError: + return None + parts = [part for part in parsed.path.strip("/").split("/") if part] + if parts: + parts[-1] = parts[-1].removesuffix(".git") + if len(parts) == 2 and parsed.netloc and all(part not in {"", ".", ".."} for part in parts): + return "/".join(parts) + return None + + +def check_writer(root: Path, ref: str, operation: str, actor: str, session: str, + revision: str, fencing: str) -> list[dict[str, Any]]: + """Read the canonical controller projection; never renew or accept handoffs. + + Identity and CAS values must come from the invoking session, not this file. + Local hooks defend against accidental competing writers, not a hostile OS user. + """ + match = TICKET_REF.fullmatch(ref) + if not match: + return [finding("GOV-CHANGE-LEASE-001", "Writer check requires an exact ticket branch ref.")] + if (not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,159}", actor) + or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,254}", session) + or not re.fullmatch(r"[1-9][0-9]{0,18}", revision) + or not re.fullmatch(r"[1-9][0-9]{0,18}", fencing)): + return [finding("GOV-CHANGE-LEASE-001", "Supply writer actor/session and current lease revision/fencing from the controller.")] + try: + # Git hook variables may name another checkout's index/git-dir. Discovery + # must be relative to the explicitly supplied root. + env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} + def git(*args: str) -> str: + return subprocess.run(["git", "-C", str(root), *args], env=env, + check=True, capture_output=True, text=True).stdout.strip() + rows = git("worktree", "list", "--porcelain", "-z").split("\0\0") + records = [dict(field.split(" ", 1) for field in row.split("\0") if " " in field) + for row in rows if row] + primary = Path(records[0]["worktree"]).resolve() + owners = [row for row in records if row.get("branch") == ref] + if len(owners) != 1: + raise ValueError("Ticket ref needs exactly one registered canonical worktree") + ticket = "ticket-" + match[1] + slug = ref.split(match[1] + "-", 1)[1] + worktree_id = ticket + "--" + slug + expected = primary / WORKTREES_ROOT / worktree_id + owner_worktree = Path(owners[0]["worktree"]) + if os.name == "nt": + if owner_worktree.resolve() != expected.resolve() or expected.is_symlink(): + raise ValueError("Ticket worktree is not canonical") + if operation == "commit" and root.resolve() != expected.resolve(): + raise ValueError("Commit must run in the owned worktree") + else: + if owner_worktree != expected or expected.resolve() != expected: + raise ValueError("Ticket worktree is not canonical") + if operation == "commit" and root.resolve() != expected: + raise ValueError("Commit must run in the owned worktree") + lease = read_writer_lease(primary / LEASE_ROOT / (worktree_id + ".json")) + errors = validate_lease(lease) + if errors: + return errors + repository = "local/" + hashlib.sha256(str(primary).encode("utf-8")).hexdigest() + accepted_repositories = {repository} + try: + canonical = canonical_owner_repository(git("config", "--get", "remote.origin.url")) + except subprocess.SubprocessError: + canonical = None + if canonical: + accepted_repositories.add(canonical) + if (lease["branchRef"] != ref or lease["ticketId"] != ticket + or lease["worktreeId"] != worktree_id + or lease["repositoryRef"] not in accepted_repositories): + raise ValueError("Lease repository, ticket, branch or worktree binding differs") + if (lease["ownerActor"] != actor or lease["ownerSession"] != session + or lease["leaseRevision"] != int(revision) or lease["fencingToken"] != int(fencing)): + return [finding("GOV-CHANGE-LEASE-002", "Writer/session or controller fencing differs; use GOV-WORK-START accepted handoff, never copy the holder identity.")] + now = datetime.now(timezone.utc) + times = [datetime.fromisoformat(lease[key].replace("Z", "+00:00").replace("z", "+00:00")) + for key in ("issuedAt", "heartbeatAt", "expiresAt")] + if not times[0] <= times[1] <= now < times[2]: + return [finding("GOV-CHANGE-LEASE-002", "Lease is expired or its clock bounds are invalid; timeout is not a handoff.")] + if lease["phase"] not in {"claimed", "editing", "validating"} or lease["publicationFrozen"]: + return [finding("GOV-CHANGE-LEASE-003", "Lease phase forbids Git mutation; preserve the frozen or released writer state.")] + except (OSError, ValueError, KeyError, IndexError, AttributeError, subprocess.SubprocessError): + return [finding("GOV-CHANGE-LEASE-001", "Cannot verify canonical writer lease; restore controller evidence without taking ownership.")] + return [] + + def parse_args(argv: list[str]) -> argparse.Namespace: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--format", choices=("text", "json"), default="text") @@ -351,12 +500,23 @@ def parse_args(argv: list[str]) -> argparse.Namespace: transition = sub.add_parser("transition"); transition.add_argument("--lease", type=Path, required=True); transition.add_argument("--request", type=Path, required=True); transition.add_argument("--replacement-receipt", type=Path) trace = sub.add_parser("trace"); trace.add_argument("document", type=Path) repository = sub.add_parser("repository"); repository.add_argument("root", type=Path) + writer = sub.add_parser("writer-check") + writer.add_argument("--root", type=Path, required=True) + writer.add_argument("--ref", required=True) + writer.add_argument("--operation", choices=("commit", "push"), required=True) + for name in ("actor", "session", "revision", "fencing"): + variable = {"actor": "WRITER_ACTOR", "session": "WRITER_SESSION", + "revision": "LEASE_REVISION", "fencing": "FENCING_TOKEN"}[name] + writer.add_argument("--" + name, default=os.environ.get("NEW_PROJECT_" + variable, "")) return parser.parse_args(argv) def main(argv: list[str] | None = None) -> int: args = parse_args(argv or sys.argv[1:]) - if args.command == "validate": findings = validate_document(args.document) + if args.command == "writer-check": + findings = check_writer(args.root, args.ref, args.operation, args.actor, args.session, + args.revision, args.fencing) + elif args.command == "validate": findings = validate_document(args.document) elif args.command == "trace": findings = validate_trace(args.document) elif args.command == "repository": findings = validate_repository(args.root.resolve()) else: diff --git a/.governance/check_required_checks.py b/.governance/check_required_checks.py index 570a200..a5de359 100755 --- a/.governance/check_required_checks.py +++ b/.governance/check_required_checks.py @@ -101,11 +101,35 @@ def declared_checks(data: dict) -> list[tuple[str, str]]: return [(name, workflow) for name in names] +def external_check_names(data: dict) -> list[str]: + """Declare the existing OneDev producer; never infer or execute a check. + + Keep this vocabulary closed so a hosted job cannot be moved outside the + workflow comparison by adding arbitrary provider metadata. + """ + bindings = data.get("externalChecks", []) + if not isinstance(bindings, list): + raise SystemExit("externalChecks must be a list") + if bindings and "requiredChecks" in data: + raise SystemExit("externalChecks requires workflowFile+requiredCheckNames") + names: list[str] = [] + required = [name for name, _workflow in declared_checks(data)] + for binding in bindings: + if binding != {"name": "onedev/local-verify", "provider": "onedev"}: + raise SystemExit("unsupported external check binding; expected the protected OneDev context") + name = binding["name"] + if name in names or required.count(name) != 1: + raise SystemExit("external check must be declared exactly once in requiredCheckNames and externalChecks") + names.append(name) + return names + + def load_source(path: Path) -> dict: data = json.loads(path.read_text(encoding="utf-8")) if not isinstance(data, dict) or data.get("schema") != SCHEMA: raise SystemExit(f"unsupported required-checks schema in {path}") declared_checks(data) + external_check_names(data) return data @@ -238,13 +262,18 @@ def check_instance_identity(root: Path, data: dict, source_path: Path) -> list[s declared = data.get("repository") if not isinstance(declared, str) or not declared: return [] + own = own_identity(root) if declared == UNRESOLVED_ADOPTER: + # The managed updater is the only writer of the adoption lock, so the + # remedy is a rerun that binds the detected name, never a manual edit. + detected = (f"detected {own!r}; rerun" if own else + "no origin remote detected; add it or pass --repository OWNER/NAME and rerun") return [ f"{source_path} still carries the unadapted template identity " - f"{UNRESOLVED_ADOPTER!r}; set repository, workflowFile and the check " - "names this repository's own workflows publish" + f"{UNRESOLVED_ADOPTER!r}; {detected} the managed updater " + "(create_adoption_lock.py --target-root . --source-revision --upgrade) to bind it to the repository's own workflow checks" ] - own = own_identity(root) if own is None or declared.casefold() == own.casefold(): return [] return [ @@ -278,7 +307,7 @@ def source_for_check(root: Path, source_override: Path | None) -> Path | None: return source_path -def print_check_success(root, source_path, required_names, published_names) -> None: +def print_check_success(root, source_path, required_names, published_names, external_names=()) -> None: try: source_label = source_path.relative_to(root) except ValueError: @@ -287,6 +316,8 @@ def print_check_success(root, source_path, required_names, published_names) -> N "required-checks gate OK: " f"source={source_label} " f"required={required_names} published={published_names}" + + (f" external_declared={list(external_names)} external_execution=not-observed" + if external_names else "") ) @@ -322,7 +353,11 @@ def main(argv: list[str] | None = None) -> int: for message in identity_errors: print(f" - {message}", file=sys.stderr) return 1 - pairs = declared_checks(data) + all_pairs = declared_checks(data) + external_names = external_check_names(data) + pairs = [(name, workflow) for name, workflow in all_pairs if name not in external_names] + if not pairs: + raise SystemExit("workflowFile declaration must retain its hosted check names") if args.workflow is not None: workflow_path = args.workflow if not workflow_path.is_file(): @@ -351,9 +386,9 @@ def main(argv: list[str] | None = None) -> int: for err in errors: print(f" - {err}", file=sys.stderr) return 1 - required_names = [name for name, _workflow in pairs] + required_names = [name for name, _workflow in all_pairs] if __name__ == "__main__": - print_check_success(root, source_path, required_names, published_names) + print_check_success(root, source_path, required_names, published_names, external_names) return 0 diff --git a/.governance/continuity_namespace.py b/.governance/continuity_namespace.py new file mode 100644 index 0000000..dd76717 --- /dev/null +++ b/.governance/continuity_namespace.py @@ -0,0 +1,175 @@ +"""Explicit isolated advisory stores; never repository aliases or authority.""" +from __future__ import annotations + +import hashlib +import json +import os +from pathlib import Path +import secrets +import tempfile + +SCHEMA = "new-project.continuity-namespace/v1" +MAX_BYTES = 16384 +FIELDS = {"schema", "authority", "repositoryRef", "legacyRepositoryRef", + "legacyEventSha256", "legacyEventCount", "recordedAt"} + + +def locations(root, repository): + key = hashlib.sha256(repository.encode("utf-8")).hexdigest() + return (root / ".subactor/recovery/continuity-namespaces" / (key + ".json"), + root / ".subactor/sessions/continuity-namespaces" / key / "events.jsonl", + root / ".subactor/recovery/continuity-namespaces" / key / "checkpoint-index.json") + + +def read_selector(path, repository, api): + try: + with api._stream_descriptor(path, False) as descriptor: + with os.fdopen(descriptor, "rb", closefd=False) as stream: + raw = stream.read(MAX_BYTES + 1) + except FileNotFoundError: + return None + if len(raw) > MAX_BYTES: + api.fail("GOV-CONTINUITY-001", "continuity namespace selector is too large") + + def unique(pairs): + value = {} + for key, item in pairs: + if key in value: + raise ValueError("duplicate namespace field") + value[key] = item + return value + + try: + value = api.exact_object(json.loads(raw.decode("utf-8"), object_pairs_hook=unique), + FIELDS, "continuity namespace selector") + except (ValueError, UnicodeError) as error: + raise api.ContinuityError("GOV-CONTINUITY-001", "invalid continuity namespace selector") from error + if (value["schema"] != SCHEMA or value["authority"] != "advisory-projection" + or value["repositoryRef"] != repository + or value["legacyRepositoryRef"] == repository + or type(value["legacyEventCount"]) is not int or value["legacyEventCount"] < 1): + api.fail("GOV-CONTINUITY-002", "continuity namespace selector binding differs") + api.validate_repository(value["legacyRepositoryRef"], "legacy repository") + api.sha(value["legacyEventSha256"], "legacy stream digest", api.SHA256_RE) + api.timestamp(value["recordedAt"], "namespace timestamp") + return value + + +def select(root, repository, legacy, api): + marker, events, index = locations(root, repository) + if read_selector(marker, repository, api) is None: + return legacy + return events, index, legacy[2], legacy[3] + + +def stream_digest(path, api): + digest = hashlib.sha256() + with api._stream_descriptor(path, False) as descriptor: + with os.fdopen(descriptor, "rb", closefd=False) as stream: + while chunk := stream.read(65536): + digest.update(chunk) + return digest.hexdigest() + + +def legacy_observation(path, repository, expected_digest, api): + try: + before = stream_digest(path, api) + if before != expected_digest: + api.fail("GOV-CONTINUITY-002", "legacy stream digest changed") + events, _ = api.event_state(api.iter_events(path), repository) + if not events or stream_digest(path, api) != before: + api.fail("GOV-CONTINUITY-002", "legacy stream is empty or changed during observation") + except FileNotFoundError as error: + raise api.ContinuityError("GOV-CONTINUITY-002", "expected legacy journal is unavailable") from error + return len(events) + + +def require_unoccupied(paths, api): + for path in paths: + try: + with api._stream_descriptor(path, False): + api.fail("GOV-CONTINUITY-002", "new namespace already contains unselected storage") + except FileNotFoundError: + pass + + +def publish_selector(path, value, api): + """Reuse anchored storage and serialization, with no-clobber publication. + + The index writer replaces an owned cache. This immutable selector instead + links an exclusively created private file, preserving any concurrent file. + """ + payload = api.index_payload(value, MAX_BYTES) + with api._parent_directory(path, True) as (directory, verify): + temporary = "namespace." + secrets.token_hex(16) + ".pending" + if os.name == "posix": + descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, + 0o600, dir_fd=directory) + remove = lambda: os.unlink(temporary, dir_fd=directory) + else: + descriptor, temporary = tempfile.mkstemp(prefix="namespace.", dir=path.parent) + remove = lambda: os.unlink(temporary) + try: + with os.fdopen(descriptor, "wb") as stream: + stream.write(payload) + stream.flush() + os.fsync(stream.fileno()) + verify() + if os.name == "posix": + os.link(temporary, path.name, src_dir_fd=directory, dst_dir_fd=directory, + follow_symlinks=False) + else: + os.link(temporary, path) + verify() + finally: + remove() + if os.name == "posix": + try: + os.fsync(directory) + except OSError: + pass # Same directory-fsync portability boundary as index writes. + + +def initialize(args, api): + root = args.root.resolve() + repository = api.repository_ref(root) + old_repository = api.validate_repository(args.expected_legacy_repository, "legacy repository") + api.sha(args.expected_legacy_sha256, "legacy stream digest", api.SHA256_RE) + if old_repository == repository: + api.fail("GOV-CONTINUITY-002", "legacy repository already matches; preserve its existing chain") + settings = api.load_local_manifest(root)["continuity"] + legacy = root / settings["eventStreamPath"] + legacy_index = root / settings["checkpointIndexPath"] + marker, events, index = locations(root, repository) + + def result(status): + return {"status": status, "repositoryRef": repository, "grantsAuthority": False, + "legacyModified": False, "legacyRepositoryRef": old_repository, + "legacyEventSha256": args.expected_legacy_sha256, + "selectorPath": marker.relative_to(root).as_posix(), + "eventStreamPath": events.relative_to(root).as_posix(), + "checkpointIndexPath": index.relative_to(root).as_posix()} + + def inspect(): + if api.repository_ref(root) != repository: + api.fail("GOV-CONTINUITY-002", "repository changed during namespace initialization") + existing = read_selector(marker, repository, api) + if existing is not None: + if (existing["legacyRepositoryRef"] != old_repository + or existing["legacyEventSha256"] != args.expected_legacy_sha256): + api.fail("GOV-CONTINUITY-002", "namespace initialization request differs") + return None + count = legacy_observation(legacy, old_repository, args.expected_legacy_sha256, api) + require_unoccupied((events, index), api) + return {"schema": SCHEMA, "authority": "advisory-projection", "repositoryRef": repository, + "legacyRepositoryRef": old_repository, "legacyEventSha256": args.expected_legacy_sha256, + "legacyEventCount": count, "recordedAt": api.utc_now()} + + if not args.apply: + return result("already-enabled" if inspect() is None else "planned") + with api.storage_transaction(legacy, legacy_index, marker, events, index): + value = inspect() + if value is None: + return result("already-enabled") + publish_selector(marker, value, api) + return result("enabled") diff --git a/.governance/controller_store_compaction.py b/.governance/controller_store_compaction.py new file mode 100755 index 0000000..ccee34c --- /dev/null +++ b/.governance/controller_store_compaction.py @@ -0,0 +1,614 @@ +#!/usr/bin/env python3 +"""Bounded retention and archive-preserving compaction for external controller lease stores. + +Plan mode is strictly read-only and grants no writer, takeover, or publication +authority. Apply mode requires an explicit operator actor and exact SHA-256 CAS +on state.json, acquires the store's exclusive flock (.lock), writes pruned +historical records to an append-only private archive before replacing state.json, +and preserves nextFencingToken monotonicity, active ownership, non-terminal/expired +leases, expiry previousReceiptRef receipts, and recent idempotency keys. +""" +from __future__ import annotations + +import argparse +from contextlib import contextmanager +from datetime import datetime, timedelta, timezone +import hashlib +import json +import os +from pathlib import Path +import re +import secrets +import stat +import subprocess +import sys + +sys.dont_write_bytecode = True + +STORE_SCHEMA = "subactor.repository-change-lease-store/v1" +REPORT_SCHEMA = "new-project.controller-store-compaction-report/v1" +ARCHIVE_SCHEMA = "new-project.controller-store-compaction-archive/v1" +CODE = "GOV-CHANGE-LEASE-002" +ALLOWED_TOP_KEYS = { + "schema", "nextFencingToken", "leases", "active", + "acquisitions", "requests", "evidence", "identities", +} +REQUIRED_TOP_KEYS = {"schema", "leases", "active"} +ALL_PHASES = { + "claimed", "editing", "validating", "publication_frozen", "dispatching", + "approved", "merged", "closed", "cancelled", "expired", "released", +} +PRUNABLE_TERMINAL_PHASES = {"closed", "cancelled", "released"} +MIN_RETENTION_SECONDS = 3600 +DEFAULT_RETENTION_SECONDS = 7 * 86400 +MAX_STORE_BYTES = 128 * 1024 * 1024 +CHUNK_BYTES = 65536 +ACTOR_RE = re.compile(r"^[A-Za-z0-9._:@/-]{1,128}$") +SHA256_RE = re.compile(r"^[0-9a-f]{64}$") + + +class CompactionError(ValueError): + """Fixed safe diagnostic code without leaking secret session tokens.""" + + +def require(condition: bool, message: str) -> None: + if not condition: + raise CompactionError(message) + + +def _unique_pairs(pairs): + result = {} + for key, value in pairs: + require(key not in result, "duplicate_json_key") + result[key] = value + return result + + +def _parse_iso(value) -> datetime: + require(isinstance(value, str) and bool(value), "invalid_timestamp") + try: + parsed = datetime.fromisoformat(value.replace("Z", "+00:00").replace("z", "+00:00")) + except ValueError as error: + raise CompactionError("invalid_timestamp") from error + require(parsed.tzinfo is not None and parsed.utcoffset() is not None, "invalid_timestamp") + return parsed.astimezone(timezone.utc) + + +def _encode(document: dict) -> bytes: + return (json.dumps(document, indent=2, sort_keys=True) + "\n").encode("utf-8") + + +def _verify_external_store(root: Path, store: Path) -> None: + root = Path(os.path.abspath(root)) + require(all(not p.is_symlink() for p in (root, *root.parents)), "symlinked_repository_root") + env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")} + top = subprocess.run( + ["git", "-C", str(root), "rev-parse", "--show-toplevel"], + env=env, capture_output=True, text=True, timeout=20, check=False, + ) + common = subprocess.run( + ["git", "-C", str(root), "rev-parse", "--path-format=absolute", "--git-common-dir"], + env=env, capture_output=True, text=True, timeout=20, check=False, + ) + wt = subprocess.run( + ["git", "-C", str(root), "worktree", "list", "--porcelain", "-z"], + env=env, capture_output=True, text=True, timeout=20, check=False, + ) + require(top.returncode == 0 and common.returncode == 0 and wt.returncode == 0, + "repository_observation_unavailable") + common_path = Path(os.path.abspath(common.stdout.strip())) + require(not store.is_relative_to(common_path), "store_inside_git_metadata") + for token in wt.stdout.split("\0"): + if token.startswith("worktree "): + checkout = Path(os.path.abspath(token.split(" ", 1)[1])) + require(not store.is_relative_to(checkout), "store_inside_candidate_checkout") + + +@contextmanager +def _anchored_directory(path: Path): + require(os.name == "posix" and hasattr(os, "O_NOFOLLOW"), "posix_controller_required") + resolved = Path(os.path.abspath(path)) + require(".." not in resolved.parts, "unsafe_store_path") + require(all(not p.is_symlink() for p in (resolved, *resolved.parents)), "symlinked_store_path") + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + descriptors = [os.open(resolved.anchor, flags)] + try: + for part in resolved.parts[1:]: + descriptors.append(os.open(part, flags, dir_fd=descriptors[-1])) + store_info = os.fstat(descriptors[-1]) + require(store_info.st_uid == os.geteuid(), "store_owner_mismatch") + + def verify() -> None: + for parent_fd, child_fd, part in zip(descriptors, descriptors[1:], resolved.parts[1:]): + named = os.stat(part, dir_fd=parent_fd, follow_symlinks=False) + held = os.fstat(child_fd) + require( + stat.S_ISDIR(named.st_mode) + and (named.st_dev, named.st_ino) == (held.st_dev, held.st_ino), + "store_directory_identity_changed", + ) + + verify() + yield resolved, descriptors[-1], verify + finally: + for fd in reversed(descriptors): + os.close(fd) + + +def _read_state_at(store_fd: int) -> tuple[dict, str, int]: + try: + fd = os.open("state.json", os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=store_fd) + except FileNotFoundError as error: + raise CompactionError("controller_state_missing") from error + chunks = [] + total = 0 + hasher = hashlib.sha256() + with os.fdopen(fd, "rb") as stream: + info = os.fstat(stream.fileno()) + require(stat.S_ISREG(info.st_mode), "controller_state_not_regular") + require(info.st_uid == os.geteuid(), "controller_state_owner_mismatch") + while True: + chunk = stream.read(CHUNK_BYTES) + if not chunk: + break + total += len(chunk) + require(total <= MAX_STORE_BYTES, "controller_state_exceeds_bound") + hasher.update(chunk) + chunks.append(chunk) + raw = b"".join(chunks) + try: + decoded = json.loads(raw.decode("utf-8"), object_pairs_hook=_unique_pairs) + except (UnicodeDecodeError, json.JSONDecodeError) as error: + raise CompactionError("controller_state_invalid_json") from error + require(isinstance(decoded, dict), "controller_state_invalid_root") + return decoded, hasher.hexdigest(), total + + +@contextmanager +def _exclusive_store_lock(store_fd: int, verify): + import fcntl + + fd = os.open(".lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600, dir_fd=store_fd) + try: + info = os.fstat(fd) + require(stat.S_ISREG(info.st_mode) and info.st_nlink == 1 and info.st_uid == os.geteuid(), + "unsafe_controller_lock") + try: + fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError as error: + raise CompactionError("controller_lock_busy") from error + verify() + named = os.stat(".lock", dir_fd=store_fd, follow_symlinks=False) + require( + stat.S_ISREG(named.st_mode) + and named.st_nlink == 1 + and (named.st_dev, named.st_ino) == (info.st_dev, info.st_ino), + "controller_lock_identity_changed", + ) + yield + finally: + os.close(fd) + + +def _lease_timestamp(lease: dict) -> datetime: + stamps = [] + for key in ("heartbeatAt", "expiresAt", "issuedAt"): + if lease.get(key) is not None: + stamps.append(_parse_iso(lease[key])) + require(bool(stamps), "lease_timestamp_missing") + return max(stamps) + + +def _compute_compaction( + state: dict, + *, + cutoff: datetime, + min_recent_leases: int, + min_recent_acquisitions: int, + min_recent_requests: int, +) -> tuple[dict, dict]: + require(state.get("schema") == STORE_SCHEMA, "unsupported_controller_schema") + require(REQUIRED_TOP_KEYS.issubset(state) and set(state).issubset(ALLOWED_TOP_KEYS), + "invalid_controller_top_level_keys") + leases = state["leases"] + active = state["active"] + require(isinstance(leases, dict) and isinstance(active, dict), "invalid_controller_maps") + + active_lease_ids = set() + for res_key, holder_id in active.items(): + require(isinstance(res_key, str) and bool(res_key), "invalid_active_resource") + if holder_id is not None: + require(isinstance(holder_id, str) and holder_id in leases, "dangling_active_lease") + active_lease_ids.add(holder_id) + + max_token = 0 + lease_times: dict[str, datetime] = {} + terminal_candidates: list[tuple[datetime, str]] = [] + retained_lease_ids: set[str] = set() + + for lid, lease in leases.items(): + require(isinstance(lid, str) and isinstance(lease, dict), "invalid_lease_entry") + require(lease.get("leaseId") in (None, lid), "lease_id_key_mismatch") + phase = lease.get("phase") + require(isinstance(phase, str) and phase in ALL_PHASES, "invalid_lease_phase") + token = lease.get("fencingToken") + if token is not None: + require(type(token) is int and token >= 1, "invalid_fencing_token") + if token > max_token: + max_token = token + stamp = _lease_timestamp(lease) + lease_times[lid] = stamp + if lid in active_lease_ids or phase not in PRUNABLE_TERMINAL_PHASES: + retained_lease_ids.add(lid) + else: + terminal_candidates.append((stamp, lid)) + + if "nextFencingToken" in state: + next_token = state["nextFencingToken"] + require(type(next_token) is int and next_token >= max(1, max_token), + "non_monotonic_next_fencing_token") + + terminal_candidates.sort(key=lambda item: (item[0], item[1]), reverse=True) + for index, (stamp, lid) in enumerate(terminal_candidates): + if index < min_recent_leases or stamp >= cutoff: + retained_lease_ids.add(lid) + + retained_leases = {lid: leases[lid] for lid in leases if lid in retained_lease_ids} + pruned_leases = {lid: leases[lid] for lid in leases if lid not in retained_lease_ids} + + compacted: dict = {"schema": STORE_SCHEMA} + if "nextFencingToken" in state: + compacted["nextFencingToken"] = state["nextFencingToken"] + compacted["leases"] = retained_leases + compacted["active"] = dict(active) + + pruned: dict = { + "leases": pruned_leases, + "identities": {}, + "acquisitions": {}, + "requests": {}, + "evidence": {}, + } + + if "identities" in state: + identities = state["identities"] + require(isinstance(identities, dict), "invalid_identities_map") + compacted["identities"] = { + lid: val for lid, val in identities.items() if lid in retained_lease_ids + } + pruned["identities"] = { + lid: val for lid, val in identities.items() if lid not in retained_lease_ids + } + + if "acquisitions" in state: + acquisitions = state["acquisitions"] + require(isinstance(acquisitions, dict), "invalid_acquisitions_map") + acq_candidates: list[tuple[datetime, str]] = [] + retained_acq_keys: set[str] = set() + epoch = datetime.fromtimestamp(0, tz=timezone.utc) + for req_key, entry in acquisitions.items(): + require(isinstance(req_key, str) and isinstance(entry, dict), "invalid_acquisition_entry") + lid = entry.get("leaseId") + require(isinstance(lid, str) and bool(lid), "invalid_acquisition_lease_ref") + if lid in retained_lease_ids: + retained_acq_keys.add(req_key) + else: + acq_candidates.append((lease_times.get(lid, epoch), req_key)) + acq_candidates.sort(key=lambda item: (item[0], item[1]), reverse=True) + for index, (stamp, req_key) in enumerate(acq_candidates): + if index < min_recent_acquisitions or stamp >= cutoff: + retained_acq_keys.add(req_key) + compacted["acquisitions"] = { + k: v for k, v in acquisitions.items() if k in retained_acq_keys + } + pruned["acquisitions"] = { + k: v for k, v in acquisitions.items() if k not in retained_acq_keys + } + + referenced_prev_receipts = { + lease["previousReceiptRef"] + for lease in retained_leases.values() + if isinstance(lease.get("previousReceiptRef"), str) and lease["previousReceiptRef"] + } + + if "requests" in state: + requests = state["requests"] + require(isinstance(requests, dict), "invalid_requests_map") + req_candidates: list[tuple[datetime, str]] = [] + retained_req_keys: set[str] = set() + for idem_key, receipt in requests.items(): + require(isinstance(idem_key, str) and isinstance(receipt, dict), "invalid_request_receipt") + occurred = _parse_iso(receipt["occurredAt"]) if "occurredAt" in receipt else cutoff + if (receipt.get("leaseId") in retained_lease_ids + or receipt.get("receiptRef") in referenced_prev_receipts + or occurred >= cutoff): + retained_req_keys.add(idem_key) + else: + req_candidates.append((occurred, idem_key)) + req_candidates.sort(key=lambda item: (item[0], item[1]), reverse=True) + for index, (_stamp, idem_key) in enumerate(req_candidates): + if index < min_recent_requests: + retained_req_keys.add(idem_key) + compacted["requests"] = { + k: v for k, v in requests.items() if k in retained_req_keys + } + pruned["requests"] = { + k: v for k, v in requests.items() if k not in retained_req_keys + } + + if "evidence" in state: + evidence = state["evidence"] + require(isinstance(evidence, dict), "invalid_evidence_map") + retained_ev_keys: set[str] = set() + for ev_key, item in evidence.items(): + require(isinstance(ev_key, str) and isinstance(item, dict), "invalid_evidence_entry") + recorded = _parse_iso(item["recordedAt"]) if "recordedAt" in item else cutoff + if item.get("leaseId") in retained_lease_ids or recorded >= cutoff: + retained_ev_keys.add(ev_key) + compacted["evidence"] = { + k: v for k, v in evidence.items() if k in retained_ev_keys + } + pruned["evidence"] = { + k: v for k, v in evidence.items() if k not in retained_ev_keys + } + + return compacted, pruned + + +def _write_archive(store_fd: int, archive_name: str, archive_bytes: bytes) -> str: + try: + os.mkdir("archive", 0o700, dir_fd=store_fd) + except FileExistsError: + pass + archive_dir_fd = os.open("archive", os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=store_fd) + try: + dir_info = os.fstat(archive_dir_fd) + require(dir_info.st_uid == os.geteuid(), "archive_owner_mismatch") + temp_name = f".archive-{secrets.token_hex(12)}.tmp" + fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=archive_dir_fd) + try: + with os.fdopen(fd, "wb") as stream: + stream.write(archive_bytes) + stream.flush() + os.fsync(stream.fileno()) + try: + os.link(temp_name, archive_name, src_dir_fd=archive_dir_fd, dst_dir_fd=archive_dir_fd, + follow_symlinks=False) + except FileExistsError: + existing_fd = os.open(archive_name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, + dir_fd=archive_dir_fd) + existing_hasher = hashlib.sha256() + existing_total = 0 + with os.fdopen(existing_fd, "rb") as existing_stream: + require(stat.S_ISREG(os.fstat(existing_stream.fileno()).st_mode), + "archive_not_regular") + while True: + chunk = existing_stream.read(CHUNK_BYTES) + if not chunk: + break + existing_total += len(chunk) + require(existing_total <= MAX_STORE_BYTES, "archive_exceeds_bound") + existing_hasher.update(chunk) + require(existing_hasher.hexdigest() == hashlib.sha256(archive_bytes).hexdigest(), + "archive_collision_mismatch") + finally: + try: + os.unlink(temp_name, dir_fd=archive_dir_fd) + except FileNotFoundError: + pass + os.fsync(archive_dir_fd) + except Exception: + try: + os.unlink(temp_name, dir_fd=archive_dir_fd) + except FileNotFoundError: + pass + raise + finally: + os.close(archive_dir_fd) + os.fsync(store_fd) + return f"archive/{archive_name}" + + +def _atomic_replace_state(store_fd: int, raw: bytes) -> None: + temp_name = f".state-compact-{secrets.token_hex(12)}.tmp" + fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=store_fd) + try: + with os.fdopen(fd, "wb") as stream: + stream.write(raw) + stream.flush() + os.fsync(stream.fileno()) + os.replace(temp_name, "state.json", src_dir_fd=store_fd, dst_dir_fd=store_fd) + os.fsync(store_fd) + except Exception: + try: + os.unlink(temp_name, dir_fd=store_fd) + except FileNotFoundError: + pass + raise + + +def compact_store( + store: Path, + *, + apply: bool = False, + operator_actor: str | None = None, + expected_state_sha256: str | None = None, + retention_seconds: int = DEFAULT_RETENTION_SECONDS, + min_recent_leases: int = 64, + min_recent_acquisitions: int = 256, + min_recent_requests: int = 512, + now: datetime | None = None, + root: Path | None = None, +) -> dict: + require(type(retention_seconds) is int and retention_seconds >= MIN_RETENTION_SECONDS, + "retention_below_minimum") + for count in (min_recent_leases, min_recent_acquisitions, min_recent_requests): + require(type(count) is int and count >= 0, "invalid_minimum_retention_count") + if expected_state_sha256 is not None: + require(isinstance(expected_state_sha256, str) and bool(SHA256_RE.fullmatch(expected_state_sha256)), + "invalid_expected_state_sha256") + if apply: + require(expected_state_sha256 is not None, "apply_requires_expected_state_sha256") + require(isinstance(operator_actor, str) and bool(ACTOR_RE.fullmatch(operator_actor)), + "apply_requires_operator_actor") + elif operator_actor is not None: + require(isinstance(operator_actor, str) and bool(ACTOR_RE.fullmatch(operator_actor)), + "invalid_operator_actor") + + current_time = (now or datetime.now(timezone.utc)).astimezone(timezone.utc) + cutoff = current_time - timedelta(seconds=retention_seconds) + + with _anchored_directory(Path(store)) as (resolved_store, store_fd, verify): + if root is not None: + _verify_external_store(Path(root), resolved_store) + if not apply: + state, pre_sha, pre_bytes = _read_state_at(store_fd) + verify() + if expected_state_sha256 is not None: + require(pre_sha == expected_state_sha256, "controller_state_cas_mismatch") + compacted, pruned = _compute_compaction( + state, + cutoff=cutoff, + min_recent_leases=min_recent_leases, + min_recent_acquisitions=min_recent_acquisitions, + min_recent_requests=min_recent_requests, + ) + pruned_total = sum(len(items) for items in pruned.values()) + post_raw = _encode(compacted) if pruned_total else None + post_sha = hashlib.sha256(post_raw).hexdigest() if post_raw is not None else pre_sha + post_bytes = len(post_raw) if post_raw is not None else pre_bytes + return { + "schema": REPORT_SCHEMA, + "mode": "plan", + "applied": False, + "grantsAuthority": False, + "store": str(resolved_store), + "preStateSha256": pre_sha, + "postStateSha256": post_sha, + "preBytes": pre_bytes, + "postBytes": post_bytes, + "nextFencingToken": compacted.get("nextFencingToken"), + "activeResourceCount": len(compacted["active"]), + "retainedCounts": { + "leases": len(compacted["leases"]), + "identities": len(compacted.get("identities", {})), + "acquisitions": len(compacted.get("acquisitions", {})), + "requests": len(compacted.get("requests", {})), + "evidence": len(compacted.get("evidence", {})), + }, + "prunedCounts": {key: len(val) for key, val in pruned.items()}, + "archiveRelPath": None, + "archiveSha256": None, + } + + with _exclusive_store_lock(store_fd, verify): + state, pre_sha, pre_bytes = _read_state_at(store_fd) + verify() + require(pre_sha == expected_state_sha256, "controller_state_cas_mismatch") + compacted, pruned = _compute_compaction( + state, + cutoff=cutoff, + min_recent_leases=min_recent_leases, + min_recent_acquisitions=min_recent_acquisitions, + min_recent_requests=min_recent_requests, + ) + pruned_total = sum(len(items) for items in pruned.values()) + archive_rel = None + archive_sha = None + if pruned_total > 0: + post_raw = _encode(compacted) + post_sha = hashlib.sha256(post_raw).hexdigest() + post_bytes = len(post_raw) + archive_payload = { + "schema": ARCHIVE_SCHEMA, + "compactedAt": current_time.isoformat(), + "operatorActor": operator_actor, + "retentionSeconds": retention_seconds, + "preStateSha256": pre_sha, + "postStateSha256": post_sha, + "nextFencingToken": compacted.get("nextFencingToken"), + "pruned": pruned, + } + archive_bytes = _encode(archive_payload) + archive_sha = hashlib.sha256(archive_bytes).hexdigest() + archive_name = f"compaction-{archive_sha}.json" + archive_rel = _write_archive(store_fd, archive_name, archive_bytes) + verify() + _atomic_replace_state(store_fd, post_raw) + else: + post_sha = pre_sha + post_bytes = pre_bytes + + return { + "schema": REPORT_SCHEMA, + "mode": "apply", + "applied": pruned_total > 0, + "grantsAuthority": False, + "operatorActor": operator_actor, + "store": str(resolved_store), + "preStateSha256": pre_sha, + "postStateSha256": post_sha, + "preBytes": pre_bytes, + "postBytes": post_bytes, + "nextFencingToken": compacted.get("nextFencingToken"), + "activeResourceCount": len(compacted["active"]), + "retainedCounts": { + "leases": len(compacted["leases"]), + "identities": len(compacted.get("identities", {})), + "acquisitions": len(compacted.get("acquisitions", {})), + "requests": len(compacted.get("requests", {})), + "evidence": len(compacted.get("evidence", {})), + }, + "prunedCounts": {key: len(val) for key, val in pruned.items()}, + "archiveRelPath": archive_rel, + "archiveSha256": archive_sha, + } + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--store", type=Path, required=True, + help="External controller lease store directory containing state.json") + parser.add_argument("--root", type=Path, + help="Optional repository root to verify store resides outside candidate checkouts") + parser.add_argument("--retention-seconds", type=int, default=DEFAULT_RETENTION_SECONDS, + help="Minimum age in seconds before terminal closed/cancelled/released entries can be archived") + parser.add_argument("--min-recent-leases", type=int, default=64) + parser.add_argument("--min-recent-acquisitions", type=int, default=256) + parser.add_argument("--min-recent-requests", type=int, default=512) + parser.add_argument("--expected-state-sha256", metavar="SHA256", + help="Exact SHA-256 of state.json (required with --apply)") + parser.add_argument("--operator-actor", metavar="ACTOR", + help="Explicit operator/controller actor identity (required with --apply)") + parser.add_argument("--apply", action="store_true", + help="Acquire .lock, write content-addressed archive, and atomically replace state.json") + args = parser.parse_args(argv) + try: + report = compact_store( + args.store, + apply=args.apply, + operator_actor=args.operator_actor, + expected_state_sha256=args.expected_state_sha256, + retention_seconds=args.retention_seconds, + min_recent_leases=args.min_recent_leases, + min_recent_acquisitions=args.min_recent_acquisitions, + min_recent_requests=args.min_recent_requests, + root=args.root, + ) + except (CompactionError, OSError, subprocess.SubprocessError) as error: + reason = error.args[0] if isinstance(error, CompactionError) and error.args else "controller_compaction_failed" + print(json.dumps({ + "schema": REPORT_SCHEMA, + "mode": "apply" if args.apply else "plan", + "applied": False, + "grantsAuthority": False, + "diagnostic": CODE, + "reason": reason, + }, sort_keys=True)) + return 1 + print(json.dumps(report, sort_keys=True)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.governance/decision_record.py b/.governance/decision_record.py index 3363e7d..ff83e94 100755 --- a/.governance/decision_record.py +++ b/.governance/decision_record.py @@ -53,13 +53,18 @@ def classify_action(action: str) -> dict[str, Any]: DECISION_START = re.compile(r"^DECISION\s+(D-\d{3}-\d{4,})\s*$") FIELD = re.compile(r"^([A-Z][A-Z0-9_]*)\s+(.+)$") -INPUT_LINE = re.compile(r"^INPUT\s+([A-Za-z0-9_]+)\s*=\s*(.+)$") +JSON_STRING_PATTERN = r'"(?:[^"\\]|\\.)*"' +INPUT_LINE = re.compile(rf"^INPUT\s+({JSON_STRING_PATTERN}|[A-Za-z0-9_]+)\s*=\s*(.+)$") VERDICT_LINE = re.compile( r"^VERDICT\s+(\S+)\s+AUTHORITY\s+(DETERMINISTIC|ADVISORY)\s*$" ) REJECTED_LINE = re.compile(r"^REJECTED\s+(\S+)\s+BECAUSE\s+(.+)$") +# The explicit JSON marker avoids reinterpreting legacy bare alternatives +# such as '"quoted"' or 'JSON'. Only previously unrepresentable names need it. +REJECTED_JSON_LINE = re.compile(rf"^REJECTED\s+JSON\s+({JSON_STRING_PATTERN})\s+BECAUSE\s+(.+)$") ADVISORY_LINE = re.compile( - r'^ADVISORY\s+llm_verdict\s*=\s*"([^"]*)"\s+MODEL\s+"([^"]*)"\s*$' + r'^ADVISORY\s+llm_verdict\s*=\s*("(?:[^"\\]|\\.)*")\s+' + r'MODEL\s+("(?:[^"\\]|\\.)*")\s*$' ) ASSERT_LINE = re.compile(r"^ASSERT\s+(.+)$") @@ -79,7 +84,7 @@ def format_value(value: Any) -> str: def decision_body(text: str) -> str: body = text.strip() if body.startswith("```"): - lines = body.splitlines() + lines = body.split("\n") if lines[0].startswith("```"): lines = lines[1:] if lines and lines[-1].strip() == "```": @@ -110,13 +115,32 @@ def apply_decision_line(record: dict[str, Any], line: str) -> bool: return True match = INPUT_LINE.match(line) if match: - record["inputs"][match.group(1)] = parse_value(match.group(2)) + name = match.group(1) + if name.startswith('"'): + try: + name = json.loads(name) + except json.JSONDecodeError: + return False + record["inputs"][name] = parse_value(match.group(2)) return True match = VERDICT_LINE.match(line) if match: record["verdict"] = match.group(1) record["verdictAuthority"] = match.group(2) return True + match = REJECTED_JSON_LINE.match(line) + if match: + try: + alternative = json.loads(match.group(1)) + except json.JSONDecodeError: + return False + if not alternative: + return False + record["rejected"] = { + "alternative": alternative, + "because": match.group(2).strip(), + } + return True match = REJECTED_LINE.match(line) if match: record["rejected"] = { @@ -126,10 +150,14 @@ def apply_decision_line(record: dict[str, Any], line: str) -> bool: return True match = ADVISORY_LINE.match(line) if match: - record["advisory"] = { - "llmVerdict": match.group(1), - "model": match.group(2), - } + try: + advisory = { + "llmVerdict": json.loads(match.group(1)), + "model": json.loads(match.group(2)), + } + except json.JSONDecodeError: + return False + record["advisory"] = advisory return True match = ASSERT_LINE.match(line) if match: @@ -168,7 +196,9 @@ def parse_dsl_record(text: str) -> dict[str, Any]: "advisory": None, "derivedFrom": None, } - for line in decision_body(text).splitlines(): + # JSON strings may contain Unicode line separators. DSL records are + # separated by physical LF (with optional CR), not those string values. + for line in decision_body(text).split("\n"): line = line.rstrip() if not line or line.startswith("#"): continue @@ -188,22 +218,28 @@ def to_dsl(record: dict[str, Any]) -> str: f"APPLIED_RULE {record['appliedRule']}", ] for key in sorted(record["inputs"]): - lines.append(f"INPUT {key} = {format_value(record['inputs'][key])}") + name = key if re.fullmatch(r"[A-Za-z0-9_]+", key) else format_value(key) + lines.append(f"INPUT {name} = {format_value(record['inputs'][key])}") lines.append( f"VERDICT {record['verdict']} AUTHORITY {record['verdictAuthority']}" ) rejected = record["rejected"] + because = " ".join(str(rejected["because"]).splitlines()).strip() + alternative = rejected["alternative"] + if not re.fullmatch(r"\S+", alternative): + alternative = f"JSON {format_value(alternative)}" lines.append( - f"REJECTED {rejected['alternative']} BECAUSE {rejected['because']}" + f"REJECTED {alternative} BECAUSE {because}" ) adv = record.get("advisory") if adv: lines.append( - f'ADVISORY llm_verdict = "{adv.get("llmVerdict", "")}" ' - f'MODEL "{adv.get("model", "")}"' + f'ADVISORY llm_verdict = {format_value(adv.get("llmVerdict", ""))} ' + f'MODEL {format_value(adv.get("model", ""))}' ) for assertion in record.get("assertions") or []: - lines.append(f"ASSERT {assertion}") + assert_text = " ".join(str(assertion).splitlines()).strip() + lines.append(f"ASSERT {assert_text}") return "\n".join(lines) + "\n" @@ -313,21 +349,24 @@ def validate_record(record: dict[str, Any]) -> list[str]: def split_decision_blocks(markdown: str) -> list[str]: - """Extract fenced ```dsl DECISION ... blocks or bare DECISION sequences.""" + """Extract bare and fenced DSL decisions once, in document order.""" + def decisions(text: str) -> list[str]: + parts = re.split(r"(?=^DECISION\s+D-)", text.strip(), flags=re.MULTILINE) + return [part.strip() for part in parts if part.strip().startswith("DECISION ")] + blocks: list[str] = [] - fence = re.findall(r"```dsl\n(.*?)```", markdown, flags=re.DOTALL) - for body in fence: - if "DECISION " in body: - # may contain multiple DECISION records - parts = re.split(r"(?=^DECISION\s+D-)", body.strip(), flags=re.MULTILINE) - for part in parts: - part = part.strip() - if part.startswith("DECISION "): - blocks.append(part) - if blocks: - return blocks - parts = re.split(r"(?=^DECISION\s+D-)", markdown.strip(), flags=re.MULTILINE) - return [p.strip() for p in parts if p.strip().startswith("DECISION ")] + cursor = 0 + fences = re.finditer( + r"^[ \t]{0,3}```([^\n]*)\n(.*?)^[ \t]{0,3}```[ \t]*(?:\n|$)", + markdown, flags=re.MULTILINE | re.DOTALL, + ) + for fence in fences: + blocks.extend(decisions(markdown[cursor:fence.start()])) + if fence.group(1).strip() == "dsl": + blocks.extend(decisions(fence.group(2))) + cursor = fence.end() + blocks.extend(decisions(markdown[cursor:])) + return blocks def check_append_only(previous_markdown: str, current_markdown: str) -> list[str]: diff --git a/.governance/diagnostics.json b/.governance/diagnostics.json index d64de8f..84d09d6 100644 --- a/.governance/diagnostics.json +++ b/.governance/diagnostics.json @@ -106,6 +106,16 @@ "remediation": "Reduce the slice or obtain fresh authorization for a larger bounded intent.", "documentation": null }, + "GOV-IDLE-TAKEOVER-001": { + "message": "Idle takeover was refused: the ticket is active, frozen, integrated, noncanonical, disabled by policy or its lease changed concurrently.", + "remediation": "Read the reported state on .subactor/cache/autonomy-board.md; continue only an IDLE_TAKEOVER_ELIGIBLE ticket, otherwise assist, reconcile or request an accepted handoff.", + "documentation": "error/GOV-IDLE-TAKEOVER.md" + }, + "GOV-IDLE-TAKEOVER-002": { + "message": "Idle takeover could not observe the repository or write its snapshot, receipt, lease or board.", + "remediation": "Preserve the worktree, fix the reported read or write failure and re-run observe before any takeover.", + "documentation": "error/GOV-IDLE-TAKEOVER.md" + }, "GOV-CHANGE-LEASE-001": { "message": "A change lease, transition request or receipt is malformed or not closed.", "remediation": "Rebuild the document from the managed change-lease schema without undeclared fields.", @@ -113,7 +123,7 @@ }, "GOV-CHANGE-LEASE-002": { "message": "Change authority is stale or its receipt trace is not monotonic.", - "remediation": "Read the authoritative lease and retry with its exact revision, fencing token and phase.", + "remediation": "Have the controller verify the calling writer/session and supply current revision, fencing token and phase. A different writer requires the accepted handoff described in error/GOV-WORK-START.md; never copy the holder identity.", "documentation": "error/GOV-CHANGE-LEASE.md" }, "GOV-CHANGE-LEASE-003": { @@ -231,6 +241,11 @@ "remediation": "Route the shared path through the manifest-declared integration workstream without transferring path ownership.", "documentation": null }, + "GOV-HOST-MERGE-001": { + "message": "Host instructions carry the superseded autonomous-merge block that allows agents to merge on green or bypass review.", + "remediation": "Preview and apply scripts/host_publication_policy.py from the standard in an owned ticket; only the independent Validator may approve and merge.", + "documentation": "error/GOV-HOST-MERGE.md" + }, "GOV-INTENT-001": { "message": "Implementation changed before the ticket entered an implementation state.", "remediation": "Record authorization and move the active ticket to EDIT, VALIDATION or PUBLICATION before changing implementation.", @@ -301,6 +316,11 @@ "remediation": "Re-acquire the pull request through the GitHub API and retry the workflow; do not skip open-PR ticket, scope or approval enforcement.", "documentation": null }, + "GOV-PUSH-001": { + "message": "A push would update a declared target branch directly.", + "remediation": "Push the ticket branch and open a pull request; the validator merges it into the target branch.", + "documentation": "error/GOV-PUSH.md" + }, "GOV-REMEDIATION-001": { "message": "A diagnostic remediation intent is malformed, unresolved or semantically unsafe.", "remediation": "Correct the target-owned remediation-intent DSL and pass deterministic schema and semantic validation before LLM planning.", diff --git a/.governance/docs/information/continuity-namespaces.md b/.governance/docs/information/continuity-namespaces.md new file mode 100644 index 0000000..8688073 --- /dev/null +++ b/.governance/docs/information/continuity-namespaces.md @@ -0,0 +1,92 @@ +--- +{ + "schema": "wellmanifest.docs/document/v1", + "id": "continuity-namespaces", + "kind": "information", + "version": 1, + "title": "Preserve continuity history in explicit repository namespaces", + "status": "proposed", + "owner": "wellmanifest/new-project", + "scope": "repository", + "created": "2026-11-12", + "updated": "2026-11-12", + "review_after": "2026-12-12", + "source_revision": "511eb0ab1c0f9f8697c44f5748ba93b25da5e0d9", + "affected_repositories": ["wellmanifest/new-project"], + "evidence": [ + "https://github.com/wellmanifest/new-project/issues/604", + "repo://wellmanifest/new-project@511eb0ab1c0f9f8697c44f5748ba93b25da5e0d9/scripts/work_continuity.py", + "repo://wellmanifest/new-project/scripts/continuity_namespace.py", + "repo://wellmanifest/new-project/tests/continuity_namespace_test.py" + ] +} +--- + +# Explicit repository continuity namespaces + + +## Purpose + +A canonical origin change can leave the legacy journal bound to its former +repository reference. The baseline revision in the metadata correctly refuses +that foreign binding. This changeset adds an explicit isolated advisory store +while preserving the complete old journal, index and original receipt identities. + + +## Scope + +`work_continuity.py init-namespace` plans by default. Initialization creates a +selector keyed by SHA-256 of the current canonical repository reference under +`.subactor/recovery/continuity-namespaces/`. Its selected journal and index are +confined to the corresponding ignored repository namespace directories. +Existing matching journals keep their original behavior without initialization. + + +## Evidence + +`tests/continuity_namespace_test.py` reproduces the refusal with real Git +origins and CLI commands. It checks planning, capture/resolve/verify, complete +chain validation, original-byte preservation, foreign event rejection, exact +replay, idempotency, occupied stores, links, process contention and interrupted +publication. `tests/work-continuity.test.sh` includes it in the existing gate. +These fixture results establish source behavior, not consumer deployment. + + +## Procedure and contract + +Observe Git, accepted intent, current owner/fencing, PR and terminal receipts +first. Record the actual former repository reference and SHA-256 of the entire +legacy stream. With the published runtime, inspect the read-only plan: + +```bash +python3 .governance/work_continuity.py init-namespace --root . \ + --expected-legacy-repository repository:github.com/example/former-name \ + --expected-legacy-sha256 "$OBSERVED_LEGACY_SHA256" +``` + +Add `--apply` only for the already authorized initialization. It holds the +existing native storage transaction, revalidates the complete legacy chain and +digest, refuses occupied unselected storage and publishes the selector without +replacing any concurrent file. An exact repeat returns `already-enabled`. +All ordinary capture, record, resolve and index operations then use that store. + +The new namespace starts empty. Restore only a complete chain already bound to +the current repository through `record`; retain its original digests and order. +Never rewrite old event repository fields or manufacture predecessor receipts. +Historical events remain recoverable under their original identity. A new +canonical origin needs its own explicit initialization; selectors are not aliases. + + +## Limits and authority + +This operation does not prove two repository references identify the same +project. A controller handling a rename must separately verify stable repository +identity before treating the histories as related. It neither rebinds old +events nor changes tickets, leases, approvals, protected checks or source scope. +Its result always states `grantsAuthority: false`. + +Storage locks serialize cooperating writers. Required identity, digest and +anchored-path checks remain conservative on concurrent changes. Unsupported +filesystem hard links fail initialization while retaining the old store. +Preserve selectors and both histories for recovery; rollback is not deletion. +Published source, qualified consumer support and target activation are separate. diff --git a/.governance/error/GOV-AGENT-HOST.md b/.governance/error/GOV-AGENT-HOST.md index d3aeb44..2f6cbba 100644 --- a/.governance/error/GOV-AGENT-HOST.md +++ b/.governance/error/GOV-AGENT-HOST.md @@ -4,7 +4,7 @@ Kody: `GOV-AGENT-HOST-001`, `GOV-AGENT-HOST-002`, `GOV-AGENT-HOST-003`, `GOV-AGENT-HOST-007` emitowane przez `.githooks/pre-commit`, oraz `GOV-AGENT-HOST-004`, `GOV-AGENT-HOST-005`, `GOV-AGENT-HOST-006` emitowane przez -`scripts/agent_host_check.py`. Wszystkie siedem jest zarejestrowanych w +`.governance/agent_host_check.py`. Wszystkie siedem jest zarejestrowanych w `governance/diagnostics.json`; `scripts/audit_diagnostics.py` skanuje teraz również `.githooks`, więc kod emitowany przez hooka nie może już wypaść z katalogu niezauważony. @@ -14,6 +14,12 @@ hosta, tracą `checkpoint`/`handoff`/`stop`, zawierają skonfigurowaną sprzeczn albo deklarują required check, którego workflow nie publikuje. To są blokery przed rozpoczęciem długiej sesji, a nie sygnały do kolejnych ślepych retry. +W repozytorium adoptującym standard checker jest instalowany jako +`.governance/agent_host_check.py`; poniższe polecenia dotyczą tego układu. +W źródłowym hubie `wellmanifest/new-project` użyj zamiast tego +`python3 scripts/agent_host_check.py --root .` (z opcją `--format json` +przy weryfikacji JSON). + ## Situation `001`–`003` oraz `007` pojawiają się przy commicie: branch nie jest związany z ticketem @@ -47,13 +53,13 @@ rzeczywistości sprawdzany. i dołącz materialną zmianę poza katalogiem ticketu, TODO, indeksem i registry. Dla `003` nie twórz commita: chroniony kontroler dostawy zapisuje terminalny receipt poza checkoutem autora. -4. Potwierdź stan: `python3 scripts/agent_host_check.py --root .`. +4. Potwierdź stan: `python3 .governance/agent_host_check.py --root .`. Przy findingu anomalii napraw źródłowy kontrakt/projekcję lub CI, a potem uruchom audyt ponownie; nie obchodź go przez `--no-verify`. ## Verification -- `python3 scripts/agent_host_check.py --root .` kończy się kodem 0. +- `python3 .governance/agent_host_check.py --root .` kończy się kodem 0. - `git config --get core.hooksPath` zwraca wartość z `agent-hosts.json`. - Próbny commit na branchu bez ticketu jest odrzucony przez hook. - `./project/governance-check.sh` nie zgłasza kodów `GOV-AGENT-HOST-*`. diff --git a/.governance/error/GOV-ARCHITECTURE-001.md b/.governance/error/GOV-ARCHITECTURE-001.md index 49cf403..d258c52 100644 --- a/.governance/error/GOV-ARCHITECTURE-001.md +++ b/.governance/error/GOV-ARCHITECTURE-001.md @@ -30,7 +30,8 @@ approval. Observe the actual diff and existing execution authorization first. `integrationTicket` alone does not transfer path ownership. 5. If another writer owns the same files, preserve its work. Prepare a patch and isolated regression tests; apply it only after an accepted handoff or - serialization. Unknown ownership is not inferred from idle time. + serialization. Unknown ownership is not inferred from idle time; only the + measured `GOV-IDLE-TAKEOVER` policy may move a known lease to a new writer. 6. Revalidate intent and lease before writes. Validate the full delivery diff with the exact observed base and head before publication; a check of an empty worktree does not validate the PR. Keep protected review unchanged. diff --git a/.governance/error/GOV-CHANGE-LEASE.md b/.governance/error/GOV-CHANGE-LEASE.md index c0abe32..e4d38c9 100644 --- a/.governance/error/GOV-CHANGE-LEASE.md +++ b/.governance/error/GOV-CHANGE-LEASE.md @@ -14,6 +14,56 @@ cannot be established from a closed, monotonic change lease. ## Safe resolution +For a completed delivery under `local-single-clone`, the current owner may +explicitly hand off its valid lease through the managed POSIX controller: + +```sh +python .governance/terminal_lease_release.py --root . --request /absolute/request.json +python .governance/terminal_lease_release.py --root . --request /absolute/request.json --apply +``` + +The closed request has `schema: new-project.terminal-owner-release/v1`, +`requestId`, canonical `worktreeId`, current `ownerActor` and `ownerSession`, +`ownerHandoff: true`, `expectedRevision`, `expectedFencingToken`, the exact +`expectedLeaseSha256` and `terminalReceiptRef`. The receipt must already be in +the configured registry. Actor/session identify the invoking owner; never copy +another session's identity from its lease. The merged receipt must verify in +the configured Git-common terminal registry and bind this ticket's merged +HEAD against its current target. This is a resource handoff, not publication +approval. A dry run grants no authority. +The invoking session supplies `NEW_PROJECT_WRITER_ACTOR` and +`NEW_PROJECT_WRITER_SESSION`; applying requires them to match the request and +the current lease. The controller API takes that caller context separately. + +When the original writer session has already exited after verified terminal +delivery (`releasesReservation: true`), the local-single-clone controller may +settle eligible leases (`claimed`, `editing`, `validating`, `approved`, +`merged`, `closed`) without impersonating the former writer session: + +```sh +python .governance/terminal_lease_release.py --root . --settle-verified +python .governance/terminal_lease_release.py --root . --settle-verified --apply +python .governance/terminal_lease_release.py --root . --settle-verified --ticket ticket-123 --apply +``` + +Controller settlement requires an unambiguous verified terminal receipt on +`targetBranch`, clean or already-removed checkout ancestry, and exclusive lease +CAS, writing an immutable receipt under `.subactor/receipts/terminal-owner-release/` +with `"settledBy": "controller:verified-terminal-receipt"`. + +The controller rechecks owner, bytes, fencing, clean delivery checkout and +source ancestry, uses canonical transitions and increments fencing. An active +local claim is explicitly cancelled before release; an already approved or +merged lease follows its existing terminal transitions. No approval phase is +invented. A write-ahead receipt makes an interrupted request replayable with +the same request, without repeated transitions. Re-observe after any CAS loss. + +This adapter preserves every worktree and branch. Registered controllers, +frozen publication still awaiting reconciliation, unknown/foreign owners, +expired phases and invalid states such as `completed` need their existing +controller. An expired timestamp alone never permits taking ownership or +normalizing the record. Unsupported platforms refuse before controller effects. + 1. Stop the writer; never retry with guessed counters. 2. Read the authoritative lease from the repository change controller. 3. Use its exact revision, fencing token, phase and HEAD. diff --git a/.governance/error/GOV-HOST-MERGE.md b/.governance/error/GOV-HOST-MERGE.md new file mode 100644 index 0000000..d7f5e3a --- /dev/null +++ b/.governance/error/GOV-HOST-MERGE.md @@ -0,0 +1,43 @@ +# GOV-HOST-MERGE: przestarzały blok autonomicznego scalania w instrukcjach hosta + +Kod: `GOV-HOST-MERGE-001` (ostrzeżenie) emitowany przez `governance_check.py` +i zarejestrowany w `governance/diagnostics.json`. + +## Situation + +`AGENTS.md`, `CLAUDE.md` lub `GEMINI.md` w katalogu głównym repozytorium zawiera +blok `` w starej treści, powołującej +się na `wellmanifest/merge@ticket-008` („Prymat Zielonych Testów”). + +## Meaning + +Stary blok pozwala agentowi scalać PR po zielonych testach, rotować konta +recenzentów, używać `gh pr merge --admin` i luzować limity WIP. Obowiązujący +standard dopuszcza wyłącznie niezależnego Validatora do zatwierdzania i +scalania; agent czeka na limity API i nie omija reguł. Agenci czytający stary +blok scalali PR samodzielnie (issue #507). + +## Safe resolution + +1. Przydziel ticket w repozytorium, którego plik dotyczy; nie edytuj pliku na `main`. +2. Podgląd: `python3 /scripts/host_publication_policy.py --path + --expected-sha256 ` (bez `--apply`); sprawdź `changed`. +3. Zastosuj z kopią zapasową (`--apply --backup-directory `) + w worktree ticketu, zatwierdź i opublikuj przez zwykły PR i Validatora. +4. Plik hosta spoza Git (np. `~/github/subactor/AGENTS.md`) uzgadnia jego właściciel + z kopią zapasową; nie twórz w tym celu repozytorium. + +## Verification + +`./project/governance-check.sh` nie zgłasza `GOV-HOST-MERGE-001`, a plik zawiera +zdanie „Only the independent Validator may approve and merge.”. + +## Do not + +- Nie usuwaj znaczników bloku ani nie przepisuj go ręcznie poza narzędziem. +- Nie scalaj PR samodzielnie, nie używaj `--admin` i nie zmieniaj kont recenzentów. +- Nie stosuj zmiany do wielu repozytoriów jednym commitem ani bez ticketu. + +## Related rules + +`GOV-HOST-MERGE-001`, `GOV-AGENT-HOST-001`, `GOV-PUSH-001`; issue #507. diff --git a/.governance/error/GOV-IDLE-TAKEOVER.md b/.governance/error/GOV-IDLE-TAKEOVER.md new file mode 100644 index 0000000..b119d17 --- /dev/null +++ b/.governance/error/GOV-IDLE-TAKEOVER.md @@ -0,0 +1,192 @@ +# GOV-IDLE-TAKEOVER + +## Situation + +Another agent's ticket blocks the next task, but its writer has stopped. The +idle takeover policy (`new-project.idle-takeover/v1`) lets an autonomous agent +continue that ticket after `coordination.idleTakeover.idleMinutes` without +observed activity, and keeps a board of every ticket's state for the next agent. + +## Meaning + +- `GOV-IDLE-TAKEOVER-001`: the takeover was refused by policy or state. +- `GOV-IDLE-TAKEOVER-002`: the observation or a snapshot, receipt, lease or + board write failed. + +### Explicit local lease continuation + +Standard0.20.149 adds two explicit controller operations. Ordinary `observe` +and `takeover` keep their existing refusal states. A timeout or a metadata +snapshot alone never transfers ownership. + +`idle_takeover.py --root PRIMARY recover-reservation --request FILE --actor ID +--session ID` accepts a closed `new-project.expired-reservation-recovery/v1` +request with `requestId`, `workstream`, and `restoration`. The latter is the +existing `new-project.local-ticket-restoration-request/v1` object, including +the exact old reservation SHA-256, owner, revision/fence, metadata snapshot +path/digest and optional exact restoration HEAD. Both input files must be +outside checkouts. The caller supplies a fresh identity, never the old holder's +identity. Recovery requires enabled manifest idle policy, an expired idle lease, +no registered checkout or branch, no integrated metadata and no observable +process in the missing path (including Linux deleted-cwd processes). +Released and frozen/publication-owned leases refuse. This operation requires +Linux process observation; it is not a multi-node controller. + +The pinned canonical `expire`/`release` transitions and a fresh claim advance +revision and fencing. The result names the canonical worktree/branch, its new +`writerEnvironment`, and `restorationRequest` for the existing native +`new-ticket.sh --restore-local-request` route. It restores no source bytes, +reserves no new number and grants neither editing nor publication. After +restoration, run the normal work-start/governance gates before writing. + +`idle_takeover.py --root OWNED_CHECKOUT checkpoint-owner --request FILE --actor +ID --session ID` accepts `new-project.owner-lease-checkpoint/v1` with +`requestId`, `ticket`, `reservationSha256`, `leaseRevision` and `fencingToken`. +It requires the same current live owner and canonical branch, captures its +actual Git HEAD through a canonical heartbeat, and does not extend expiry or +change scope/owner. Frozen, expired and released leases refuse. Use the returned +fencing values; old tokens no longer authorize a write. This POSIX operation +does not establish review, merge or release provenance. + +Both operations hold the existing per-lease lock, revalidate state after +preparation, and use anchored atomic storage. Prepare/result records in +`.subactor/receipts/lease-continuation/` bind request identity and both lease +hashes. An interrupted final receipt can replay the same claim; it cannot +renew a lease or apply a changed request. Retain divergent preparations for +reconciliation rather than overwriting a current owner. + +### Policy (single source: the governance manifest) + +```json +"coordination": { + "idleTakeover": { "enabled": true, "idleMinutes": 15, "leaseMinutes": 120 } +} +``` + +The default and hub manifests carry these values; the manifest schema bounds +them (`idleMinutes` 5–240, `leaseMinutes` 15–480 and greater than +`idleMinutes`). The script has no built-in threshold and no validator of its +own: it applies the pinned `governance_check.idle_takeover_policy_valid`, so a +missing or malformed policy (non-boolean `enabled`, a boolean, zero, negative or +out-of-range duration) reports `POLICY_DISABLED` and nothing is taken over. + +### Activity + +A ticket is idle only when the newest of these is older than `idleMinutes`: + +- the lease `heartbeatAt`; +- the ticket branch commit; +- the newest modification of a dirty or untracked file in the ticket worktree; +- the ticket's latest checkpoint in the stream that `.subactor/manifest.json` + declares as `continuity.eventStreamPath`. + +A live process whose working directory is inside the ticket worktree always +makes the ticket `ACTIVE` (observed through `/proc`; other platforms rely on the +four timestamps). + +### Worktree layout (wellmanifest/worktrees v5) + +Layout roots come from the pinned `change_lease_check.py` (`WORKTREES_ROOT`, +`LEASE_ROOT`); nothing else defines them. The primary checkout is the first +entry of Git's worktree registry, also when the command runs inside a linked +worktree. A ticket is a takeover candidate only when one delivery unit matches: + +- worktree `/.worktrees/--`; +- lease `/.subactor/leases/--.json`; +- branch `ticket/NNN-` and the lease's `ticketId`; +- no symlink in the canonical worktree path. + +Anything else is `NONCANONICAL_LAYOUT` with the failing parts in +`layoutProblems`. Request an adoption upgrade; do not move or recreate it by hand. + +### States + +| State | Meaning | Action | +| --- | --- | --- | +| `ACTIVE` | Activity within `idleMinutes` or a live process. | Assist read-only or choose other work. | +| `IDLE_TAKEOVER_ELIGIBLE` | Idle, canonical, takeable phase (`claimed`, `editing`, `validating`, `expired`), worktree present. | `idle_takeover.py takeover`. | +| `IDLE_FROZEN` | Publication frozen, dispatching or approved. | Never taken over; follow the PR's validator outcome. | +| `IDLE_INTEGRATED` | Clean worktree whose HEAD is already in the target branch. | Release the lease; nothing to continue. | +| `IDLE_NO_WORKTREE` | Lease without a registered ticket worktree. | Reconcile; never taken over. | +| `IDLE_NOT_TAKEABLE` | Idle in a phase the lease contract cannot expire or release. | Reconcile through the controller. | +| `POLICY_DISABLED` | No enabled manifest policy, so idleness is not measured (a live process still reads `ACTIVE`). | Accepted handoff only. | +| `NONCANONICAL_LAYOUT` | Worktree, lease or branch outside the v5 layout. | Adoption upgrade; never by hand. | +| `INVALID_LEASE` | The repository's pinned lease contract rejects the lease. | Restore controller evidence. | + +Phase sets are derived from the pinned contract's transitions, not listed here. + +## Safe resolution + +### Takeover + +```sh +python3 .governance/idle_takeover.py observe # rewrite and print the board +python3 .governance/idle_takeover.py takeover --ticket ticket-NNN \ + --actor agent: --session +``` + +`takeover` takes an exclusive, non-waiting lock on +`.json.lock` (a held lock refuses), re-observes under it and refuses +anything that is not `IDLE_TAKEOVER_ELIGIBLE` or already held by the same +session. Still under the lock it: + +1. stores dirty work as a content-addressed tar (tracked diff plus every dirty + or untracked file) in `.subactor/snapshots/idle-takeover//.tar`; + the worktree is not reset, so the new owner continues from the same files; +2. moves the lease through the pinned change-lease CAS: `expire` (unless already + expired), `release`, then a new `claimed` lease for the new actor and session + with revision and fencing token one above the release receipt and + `leaseMinutes` until expiry; +3. compares the lease bytes and file identity immediately before the receipt and + the replacement and refuses on any concurrent change; a writer that bypassed + the lock still fails the fencing token at its next commit; +4. appends the record to `.subactor/receipts/idle-takeover/.jsonl`; +5. rewrites the board and prints the record as JSON. + +The JSON result names `ticket`, `branch`, `worktreePath`, `leasePath` and +`writerEnvironment` (`NEW_PROJECT_WRITER_ACTOR`, `NEW_PROJECT_WRITER_SESSION`, +`NEW_PROJECT_LEASE_REVISION`, `NEW_PROJECT_FENCING_TOKEN` for the writer hook). +Take these only from the result (worktrees rules 9–10), export the environment, +and work only inside `worktreePath`. A non-zero exit ends the attempt. + +The authority reference is +`policy:new-project.idle-takeover/v1;idleMinutes=…;limit=…;lastActivity=…`. +It authorizes continuing the ticket's existing intent and scope only. It never +grants review, approval, merge, a scope change or a takeover of a frozen +publication; the independent Validator remains required. + +### Autonomy board + +Every `observe`, `takeover` and `work_start_check.py` run rewrites +`.subactor/cache/autonomy-board.json` and `.md` in the primary checkout (the +root-ignored cache namespace). The header names the worktree and lease roots +and links the repository, its pull requests and its issue list. Each ticket +lists state, owner, phase, idle minutes, the newest activity source, dirty file +count, its worktree path and links to the branch, README and pull request. Read +it before choosing the next task. The board is an observation and grants no +authority. + +## Verification + +```sh +python3 tests/idle_takeover_test.py +``` + +## Do not + +- Do not take over a ticket that is not `IDLE_TAKEOVER_ELIGIBLE`, or treat lease + expiry, an old commit or a missing heartbeat alone as a handoff. +- Do not reset, clean, move or recreate the previous writer's worktree; the + snapshot is evidence, not a replacement for the files. +- Do not hand-write a lease, reuse a revision or fencing token, or copy the + previous holder's actor or session. +- Do not take paths from a directory listing; use only the JSON result. +- Do not treat the takeover as review, approval, merge or scope authority. + +## Related rules + +- `GOV-WORK-START`: routes and accepted handoff. +- `GOV-CHANGE-LEASE`: CAS transitions, fencing and receipts. +- `wellmanifest/worktrees` v5: canonical worktree and lease layout, rules 1–13. +- `wellmanifest/nohardcode` and `wellmanifest/ssot`: the policy lives in the + manifest and the layout in the lease contract; the script repeats neither. diff --git a/.governance/error/GOV-INTENT.md b/.governance/error/GOV-INTENT.md index cf7059f..278d9a6 100644 --- a/.governance/error/GOV-INTENT.md +++ b/.governance/error/GOV-INTENT.md @@ -34,11 +34,27 @@ idealnie zgodny z `allowedPaths`, a mandat i tak nie powstał na czas. 3. Gdy kod został zacommitowany przed intentem, przebuduj nieopublikowaną gałąź atomowo. Nie przepisuj opublikowanej, zaufanej historii. +4. Gdy błąd `delivery ... incomplete` lub `bounded-delivery fields` zawiera + `move X to PATH`, przenieś pole dokładnie do wskazanej ścieżki zamiast + przepisywać intent. Pola architektury (`interfaceChanges`, `dataChanges`, + `components`, `ui`, `rollback`, `status`, `decision`, + `responsibilityChanges`) należą do `delivery.architecture`, limity `max*` do + `delivery.budgets`, a pozostałe pola kontraktu bezpośrednio do `delivery`. + Przeniesione pole nie jest akceptowane jako synonim; nieznane pola pozostają + odrzucone bez podpowiedzi położenia. + ## Verification -`./project/governance-check.sh` bez argumentów bada **drzewo robocze**, nie -historię commitów. Chroniona bramka zakresowa potwierdza, że intent istnieje w -pierwszym materialnym commicie. +`./project/governance-check.sh` bez `--base` na gałęzi `ticket/NNN-*` sam +wyznacza bazę jako `git merge-base HEAD origin/` (target z +`delivery.targetBranches` manifestu, a przy kilku z `delivery.targetBranch` +ticketu) i bada zacommitowany zakres, więc brak kontraktu `delivery` jest +wykrywany lokalnie. Brak `origin/` kończy się `GOV-BASE-001` zamiast +pustego `GOV-PASS`; wykonaj `git fetch origin ` albo podaj `--base`. +Jawne `--base` lub `--changed-file` zawsze wygrywa. Na innych gałęziach i przy +odłączonym HEAD wywołanie bez argumentów nadal bada tylko drzewo robocze. +Chroniona bramka zakresowa potwierdza, że intent istnieje w pierwszym +materialnym commicie. Dowodem jest wyłącznie tryb zakresowy: @@ -47,7 +63,7 @@ Dowodem jest wyłącznie tryb zakresowy: ``` Uruchom go przed każdym pushem gałęzi ticketowej. Wynik `GOV-PASS` z gołego -wywołania nie jest wystarczającym dowodem. +wywołania poza gałęzią `ticket/NNN-*` nie jest wystarczającym dowodem. ## Do not diff --git a/.governance/error/GOV-PACKAGING.md b/.governance/error/GOV-PACKAGING.md index 5bf798c..358de40 100644 --- a/.governance/error/GOV-PACKAGING.md +++ b/.governance/error/GOV-PACKAGING.md @@ -1,7 +1,13 @@ # GOV-PACKAGING: metadane paczki nie egzekwują standardu Kody: `GOV-PACKAGING-001`, `GOV-PACKAGING-002`, `GOV-PACKAGING-003` -(emitowane przez `scripts/agent_host_check.py`). +(emitowane przez `.governance/agent_host_check.py`). + +W repozytorium adoptującym standard checker jest instalowany jako +`.governance/agent_host_check.py`; poniższe polecenia dotyczą tego układu. +W źródłowym hubie `wellmanifest/new-project` użyj zamiast tego +`python3 scripts/agent_host_check.py --root .` (z opcją `--format json` +przy weryfikacji JSON). ## Situation @@ -46,11 +52,11 @@ egzekucji. 3. Po każdym upgrade standardu zaktualizuj blok razem z lockiem — rozjazd jest wykrywany deterministycznie. -4. Potwierdź: `python3 scripts/agent_host_check.py --root .`. +4. Potwierdź: `python3 .governance/agent_host_check.py --root .`. ## Verification -- `python3 scripts/agent_host_check.py --root . --format json` zwraca `ok: true`. +- `python3 .governance/agent_host_check.py --root . --format json` zwraca `ok: true`. - `npm install` w czystym klonie ustawia `core.hooksPath` bez ręcznej komendy. - Zmiana wersji w locku bez zmiany metadanych paczki daje `GOV-PACKAGING-002`. diff --git a/.governance/error/GOV-PHYS.md b/.governance/error/GOV-PHYS.md index 5441404..b1ccbdf 100644 --- a/.governance/error/GOV-PHYS.md +++ b/.governance/error/GOV-PHYS.md @@ -44,4 +44,4 @@ Expected result: no `GOV-PHYS-*` finding. ## Related rules - `P-PHYS-001`, `P-PHYS-002`, `P-PHYS-003` in `POLICY.md`. -- [Physical interface contracts](../docs/information/physical-interface-contracts.md). +- [Physical interface contracts](https://github.com/wellmanifest/new-project/blob/main/docs/information/physical-interface-contracts.md). diff --git a/.governance/error/GOV-PUSH.md b/.governance/error/GOV-PUSH.md new file mode 100644 index 0000000..28622d6 --- /dev/null +++ b/.governance/error/GOV-PUSH.md @@ -0,0 +1,42 @@ +# GOV-PUSH: bezpośredni push do gałęzi docelowej + +Kod: `GOV-PUSH-001` emitowany przez zarządzany hook `.githooks/pre-push` +i zarejestrowany w `governance/diagnostics.json`. + +## Situation + +`git push` próbuje zaktualizować gałąź zadeklarowaną w +`delivery.targetBranches` (domyślnie `main`): wprost (`git push origin main`), +przez refspec (`HEAD:main`) albo usuwając ją. Repozytoria z profilem dostarczania +`main-only-planfile`, `main-only-files` lub `local-audit` są zwolnione. + +## Meaning + +Gałąź docelowa przyjmuje zmiany wyłącznie przez przejrzany pull request scalany +przez validatora. Bezpośredni push omija review, required checks i CI, które w +wielu repozytoriach uruchamia się tylko dla PR; 19.10.2026 trzynaście takich +commitów w paxlet-com/willmux pogorszyło `main` z 1 do 4 błędów i 32 wyjątków testów. + +## Safe resolution + +1. Zostaw lokalny commit na gałęzi ticketu (`ticket/NNN-...`); nie przenoś go na `main`. +2. Wypchnij gałąź ticketu: `git push -u origin ticket/NNN-...`. +3. Otwórz pull request do gałęzi docelowej i poczekaj na validatora oraz CI. +4. Jeśli commit powstał już na lokalnym `main`, utwórz z niego gałąź ticketu + (`git branch ticket/NNN-... main`) i przywróć `main` do `origin/main` dopiero + po sprawdzeniu, że gałąź ticketu zawiera całą pracę. + +## Verification + +`git push origin ticket/NNN-...` kończy się kodem 0, a pull request pokazuje +uruchomione required checks. `git push origin main` nadal kończy się `GOV-PUSH-001`. + +## Do not + +- Nie omijaj hooka (`--no-verify`, zmiana `core.hooksPath`); agentom nie wolno omijać hooków. +- Nie wymuszaj pusha (`--force`) na gałąź docelową ani nie usuwaj jej. +- Nie zmieniaj `delivery.targetBranches` ani profilu dostarczania, żeby obejść blokadę. + +## Related rules + +`C-HOST-001` (zarządzane hooki są aktywne), zasada hosta „Never commit on main”. diff --git a/.governance/error/GOV-TICKET-ALLOCATION.md b/.governance/error/GOV-TICKET-ALLOCATION.md index cc89f67..e114ae0 100644 --- a/.governance/error/GOV-TICKET-ALLOCATION.md +++ b/.governance/error/GOV-TICKET-ALLOCATION.md @@ -34,6 +34,31 @@ Ręczne `mkdir`, skopiowanie katalogu albo sam `fetch` nie tworzą rezerwacji. exact head. 6. W profilu lokalnym napraw łączność z `origin` i ponów allocator; stale lock usuwaj tylko po potwierdzeniu braku procesu. +7. Gdy zarezerwowany ticket (numer nie większy od high-water, rekord w + `.subactor/leases/`) stracił kanoniczny checkout, branch lub + niezacommitowane metadane, nie alokuj nowego numeru i nie odtwarzaj ich + ręcznie. Uruchom `new-ticket.sh --workstream W --restore-request FILE + --recovery-lease-store DIR`. Request + `new-project.ticket-restoration-request/v1` wiąże ticket, `worktreeId`, + dokładny HEAD (`null` oznacza bazę rezerwacji), snapshot + `new-project.ticket-metadata-snapshot/v1` z jego SHA-256 oraz CAS żywego + leasu kontrolera w fazie `claimed` lub `editing`. Restoration tworzy tylko + brakujący branch, względną rejestrację checkoutu oraz `README.md` i + `intent.json`; ponowienie po przerwaniu kończy brakujące kroki, a gotowy + stan zwraca `ALREADY_RESTORED`. Nie daje prawa do edycji ani merge: dalej + obowiązuje `work_start_check.py --ticket`. +8. Dla istniejącej rezerwacji `local-single-clone` bez zewnętrznego store użyj + jawnego `--restore-local-request FILE`, z własnym writer actor/session oraz + `NEW_PROJECT_LEASE_REVISION` i `NEW_PROJECT_FENCING_TOKEN`. Request ma te same + pola co zewnętrzny, schema `new-project.local-ticket-restoration-request/v1` + i dodatkowe `reservationSha256`: SHA-256 dokładnych bajtów kanonicznego + `.subactor/leases/{worktreeId}.json`. CAS i właściciel odnoszą się do tego + pliku. Kontroler utrzymuje jego blokadę, sprawdza repozytorium i zakres oraz + ponawia kontrolę przed każdym skutkiem. Nie przekazuj `--recovery-lease-store` + w tej ścieżce; odmowa store nigdy nie przełącza automatycznie na local. + Wygasła, zamrożona lub zwolniona rezerwacja jest odrzucana. Najpierw wymagane + jest osobne, uprawnione przejęcie przez kontroler; restoration nie odnawia + lease, nie zwiększa fencing i nie przywraca źródeł ze snapshotu. ## Verification @@ -50,6 +75,8 @@ Ręczne `mkdir`, skopiowanie katalogu albo sam `fetch` nie tworzą rezerwacji. - Nie zmieniaj numeru przez ręczne `mv` i nie kopiuj historii obu branchy. - Nie usuwaj dirty/unreachable worktree ani locka bez identyfikacji procesu. - Nie przydzielaj numeru offline ze starych refów. +- Nie przejmuj cudzej rezerwacji po wygaśnięciu leasu; zmianę właściciela + wykonuje kontroler, a restoration jej wymaga. - Nie traktuj lokalnego high-water, receipt ani samego ERROR jako merge lub execution authority. - Nie zamykaj przegrywającego PR przed zachowaniem delta i utworzeniem diff --git a/.governance/error/GOV-VERSION.md b/.governance/error/GOV-VERSION.md index fd570f3..4b5e7cf 100644 --- a/.governance/error/GOV-VERSION.md +++ b/.governance/error/GOV-VERSION.md @@ -26,7 +26,12 @@ Ponadto w modelach podziału na workstreamy (`manifest.json`), workstream `integ from importlib.metadata import version as _meta_version __version__ = _meta_version("my-package") except Exception: - __version__ = (Path(__file__).resolve().parent / "VERSION").read_text(encoding="utf-8").strip() + from pathlib import Path + _root = Path(__file__).resolve().parent + while _root.parent != _root and not (_root / "VERSION").is_file(): + _root = _root.parent + _version_file = _root / "VERSION" + __version__ = _version_file.read_text(encoding="utf-8").strip() if _version_file.is_file() else "0.0.0" ``` Jeśli w kodzie pozostaje statyczne przypisanie `__version__ = "..."`, jego wartość musi być identyczna z `VERSION`. 4. Uruchom bramkę: `./project/governance-check.sh`. diff --git a/.governance/error/GOV-WORK-CONTINUITY.md b/.governance/error/GOV-WORK-CONTINUITY.md index f9bcede..02e8f6c 100644 --- a/.governance/error/GOV-WORK-CONTINUITY.md +++ b/.governance/error/GOV-WORK-CONTINUITY.md @@ -35,6 +35,13 @@ użycia zapisanego fencing tokenu. ## Verification +Gdy pełny dziennik jest poprawny pod dawnym repositoryRef po zmianie origin, +zachowaj obie tożsamości i wszystkie oryginalne receipty. Opublikowany runtime +z `init-namespace` pozwala jawnie zaplanować osobną przestrzeń po walidacji +całego starego chain i jego zaobserwowanego SHA-256; `--apply` wymaga istniejącej +autoryzacji tej operacji. Patrz [procedura](../docs/information/continuity-namespaces.md). +Nie reinterpretuj tej operacji jako migracji identity, lease lub approval. + ```bash python3 .governance/work_continuity.py validate python3 .governance/work_continuity.py verify --root . --ticket ticket-NNN diff --git a/.governance/error/GOV-WORK-START.md b/.governance/error/GOV-WORK-START.md index 04a5744..eb61a9b 100644 --- a/.governance/error/GOV-WORK-START.md +++ b/.governance/error/GOV-WORK-START.md @@ -20,7 +20,7 @@ keep it in private receipt storage, not a tracked ticket. | --- | --- | --- | | REUSE_EXISTING | Continue the matching canonical ticket checkout. | Revalidate intent, owner and current lease first. | | ASSIST_READ_ONLY | Help an active delivery with analysis or review. | No second writer or trusted self-approval. | -| HANDOFF_REQUIRED | Reconcile pending work from an inactive ticket. | Accepted scope, snapshot and controller CAS; no automatic takeover. | +| HANDOFF_REQUIRED | Reconcile pending work from an inactive ticket. | Accepted scope, snapshot and controller CAS; automatic takeover only through `GOV-IDLE-TAKEOVER` after the configured idle time. | | SERIALIZE | Workstream capacity is occupied. | Queue without another delivery worktree. | | RECONCILE | Owner, ancestry, pending branch or observations are uncertain. | Preserve work and resolve the specific missing evidence. | | NEW_TICKET_CANDIDATE | Scope and WIP capacity permit new allocation. | Planning candidate only; never write authority. | @@ -49,6 +49,15 @@ task -> registered clone observation owner, fencing and the governance gate at the effect boundary. A saved report is evidence, never a replayable admission token. +For an unfinished `released` slot, ordinary owner handoff and checkout +restoration deliberately remain unavailable. A protected host may use the +independently published `resume_released` API only with independently +authenticated original-writer release/stopped evidence, exact lease/Git/intent +CAS, a complete managed terminal registry and a fresh bounded successor. +See [explicit owner handoff](../docs/EXPLICIT_OWNER_HANDOFF.md). Preserve dirty +work and reuse the same ticket; never edit lease JSON, infer release authority +from expiry/PID absence, or allocate a competing implementation. + For a branch without a registered worktree, distinct commit IDs alone are not a competing delta. Admission compares the complete Git tree of **every** commit unique to that branch with target trees strictly after the common @@ -139,6 +148,29 @@ The result explicitly lists PR, checks, approval, protected merge, release and deployment as unobserved stages. Preserve dirty work regardless of remote status. Gather those stages' own exact-head receipts before claiming DONE. +### Optional controller availability + +`--controller-store DIR --controller-repository OWNER/NAME` adds a read-only +`editingResource` observation (`new-project.editing-resource-observation/v1`) +of the controller's exclusive editing resource for that repository and target +branch. Run it before preparing an expiring editing credential or admission. +The route still reports planning eligibility only: disjoint paths can select +`NEW_TICKET_CANDIDATE` or `REUSE_EXISTING` while the resource is +`HELD_BY_OTHER`. `HELD_EXPIRED` still blocks: expiry alone never authorizes a +takeover; the controller must release it, record a protected handoff, or the +ticket must qualify for `GOV-IDLE-TAKEOVER` (no observed activity for +`coordination.idleTakeover.idleMinutes`). +`UNAVAILABLE` carries a reason (`controller-store-missing`, +`controller-state-unreadable`, `controller-state-invalid`, +`controller-state-changed`; runtime clients may report transport, pin or +policy failures) and never implies availability. The holder is a safe +reference (lease, ticket, phase, expiry) without owner session or plan. +`queueSupported` is `false` for the file controller, which has no queue; a +runtime that queues reports `QUEUED`, and a queued request is not a grant. +Follow `nextAction`, bind `stateDigest` and `observedAt` as the observation's +freshness, and re-observe instead of retrying an admission whose window +elapsed. + ## Verification Report `new-project.work-start-report/v1` uses closed schema @@ -181,3 +213,47 @@ retains its separate contract, not a development-gate exemption. P-WORKSPACE-005, P-WORKSPACE-006, C-START-004, C-CONCURRENCY-005, P-CORE-014, P-TICKET-ACTIVITY-001 and P-LEASE-001. + +## Ticket writer fencing + +Allocation requires `--writer-actor` and `--writer-session`, or the explicit +`NEW_PROJECT_WRITER_ACTOR` and `NEW_PROJECT_WRITER_SESSION` environment values. +The agent provider (`--agent`) is display metadata, not a session identity. +The allocator keeps scaffolds in its canonical linked worktree and records the +caller in the existing lease fields. Invalid identity fails before reservation. + +The launcher supplies these same identity values plus `NEW_PROJECT_LEASE_REVISION` +and `NEW_PROJECT_FENCING_TOKEN` from current controller evidence to Git hooks. +`change_lease_check.py writer-check --root . --operation commit --ref +refs/heads/ticket/NNN-slug` performs a read-only check. Push checks resolve each +source and destination ticket ref through Git's registered primary and worktrees, +including when the push originates from another checkout. Missing or unsafe +leases/runtime produce GOV-CHANGE-LEASE-001; identity, expired lease or stale CAS +produce GOV-CHANGE-LEASE-002; released/frozen phases produce GOV-CHANGE-LEASE-003. +The clone-local repository hash matches the allocator's existing lease binding. + +A successor must obtain an independently accepted handoff through the controller: +observe the old owner gone or explicitly handed off, re-observe dirty work and +HEAD, and have the controller publish the successor lease with fresh monotonic +CAS values. Pass that evidence to the successor session. Hooks never consume a +local handoff file, update ownership, renew a timeout, or infer caller identity +from lease contents. Do not copy another session's identity or fencing values. +These local checks do not defend against an OS user who can alter hooks or +impersonate launcher environment, and do not replace protected publication. + +### Explicit owner consent with an expired local lease + +For the registered `local-single-clone` policy, a protected host adapter may +use the public `owner_handoff.handoff` API independently of idle takeover. +It must authenticate the previous owner's explicit consent and bind the full +request to its protected authorization verifier. A request, actor label, FD or +expiry alone never authenticates ownership. The standalone CLI is read-only; +without the protected adapter, preserve the checkpoint and queue the handoff. +See [Explicit local owner handoff](../docs/EXPLICIT_OWNER_HANDOFF.md). + +A successful operation preserves scope, intent and the worktree, archives the +old lease and authorization before replacement, advances fencing and creates a +bounded fresh session. Run work-start and writer checks with its returned +context before editing. Exact replay re-authenticates and never renews the +successor. Later file, Git, policy, authorization or fencing changes require a +new observation and an authenticated handoff; never repair lease JSON manually. diff --git a/.governance/generate_required_checks.py b/.governance/generate_required_checks.py index 03ffd7e..3f367ba 100644 --- a/.governance/generate_required_checks.py +++ b/.governance/generate_required_checks.py @@ -28,7 +28,7 @@ JOB_LINE = re.compile(r"^ ([A-Za-z0-9][A-Za-z0-9_-]*):\s*(?:#.*)?$") JOB_NAME_LINE = re.compile(r"^ name:\s*(.+?)\s*$") TOP_LEVEL_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*:") -REUSABLE_CALL = re.compile(r"^ (?:uses:|['\"]uses['\"]:)") +REUSABLE_CALL = re.compile(r"^ (?:uses:|['\"]uses['\"]:)\s*(.*)$") IMMUTABLE_CALL = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/\.github/workflows/[A-Za-z0-9_.-]+\.ya?ml@[0-9a-f]{40}") CONTRACT_PATH = Path('.github/reusable-workflows.lock.json') CONTRACT_SCHEMA = 'new-project.reusable-workflows/v1' @@ -211,8 +211,8 @@ def resolved_checks_text(text: str, sources: dict[str, str], callers: list[str]) if not unresolved: return names for key, body in literal_jobs(text): - calls = [scalar(line.split('uses:', 1)[1]) for line in body.splitlines() - if REUSABLE_CALL.match(line)] + calls = [scalar(match.group(1)) for line in body.splitlines() + if (match := REUSABLE_CALL.match(line))] if not calls: continue name = literal_name(key, body) @@ -230,22 +230,146 @@ def resolved_checks_text(text: str, sources: dict[str, str], callers: list[str]) return names +def _trigger_line(line: str, *, complete: bool = False) -> str: + """Strip YAML comments while retaining hashes inside quoted scalars.""" + quote = None + containers = [] + index = 0 + while index < len(line): + char = line[index] + if quote == '"' and char == '\\': + index += 2 + continue + if quote == "'" and line[index:index + 2] == "''": + index += 2 + continue + if char == quote: + quote = None + elif quote is None and char in "'\"": + quote = char + elif quote is None and char == '#' and (index == 0 or line[index - 1].isspace()): + line = line[:index] + break + elif complete and quote is None and char in '[{': + containers.append(char) + elif complete and quote is None and char in ']}': + if not containers or containers.pop() != {']': '[', '}': '{'}[char]: + raise SystemExit('unsupported workflow metadata flow value') + index += 1 + if complete and (quote is not None or containers): + raise SystemExit('unsupported multiline workflow metadata value') + return line.rstrip() + + +def _trigger_word(value: str) -> str: + if not re.fullmatch(r'''(?:[a-z][a-z0-9_]*|'[a-z][a-z0-9_]*'|"[a-z][a-z0-9_]*")''', value): + raise SystemExit('unsupported literal workflow trigger scalar') + return value.strip("'\"") + + +def _trigger_sequence(value: str, children: list[str]) -> list[str]: + if value: + combined = ' '.join([value, *(line.strip() for line in children)]) + if not (combined.startswith('[') and combined.endswith(']')): + raise SystemExit('unsupported workflow trigger sequence') + items = combined[1:-1].split(',') + if items[-1].strip() == '': + items.pop() # YAML permits a trailing comma. + else: + items = [] + indentation = None + for line in children: + match = re.fullmatch(r'( *)-\s+(.+)', line) + if match is None or (indentation is not None and len(match[1]) != indentation): + raise SystemExit('unsupported workflow trigger sequence') + indentation = len(match[1]) + items.append(match[2]) + if not items: + raise SystemExit('empty workflow trigger sequence') + return [_trigger_word(item.strip()) for item in items] + + +def _trigger_mapping(lines: list[str], *, indentless_lists: bool = False) -> dict[str, tuple[str, list[str]]]: + """Read literal block fields; reject aliases, merge keys and mixed forms.""" + result: dict[str, tuple[str, list[str]]] = {} + indentation = len(lines[0]) - len(lines[0].lstrip()) if lines else 0 + current = None + for line in lines: + depth = len(line) - len(line.lstrip()) + if '\t' in line[:depth] or depth < indentation: + raise SystemExit('unsupported workflow trigger indentation') + if depth == indentation and not line.lstrip().startswith('- '): + match = re.fullmatch(r'''\s*([a-z][a-z0-9_]*|'[a-z][a-z0-9_]*'|"[a-z][a-z0-9_]*"):\s*(.*)''', line) + if match is None: + raise SystemExit('unsupported workflow trigger mapping') + current = _trigger_word(match[1]) + if current in result: + raise SystemExit('duplicate workflow trigger field') + result[current] = (match[2], []) + elif current is None or (depth == indentation and not indentless_lists): + raise SystemExit('unsupported workflow trigger mapping') + else: + result[current][1].append(line) + return result + + def pull_request_gating(text: str) -> bool: - """Keep after-merge-only callers out of pre-merge declarations.""" - if "pull_request" not in text: - return False # A workflow that never runs on a PR cannot gate one. - # A pull_request trigger with exclusively the 'closed' type publishes - # checks that run after the merge decision, never before. They cannot - # gate a pull request and must not inflate the required-checks declaration. - has_closed_type = bool(re.search(r"\btypes:\s*\[\s*closed\s*\]", text)) or bool( - re.search(r"\btypes:\s*\n\s*-\s*closed\b", text) - ) - has_gating_types = bool( - re.search(r"\btypes:\s*\[.*\b(?:opened|synchronize|reopened|ready_for_review)\b", text) - ) or bool( - re.search(r"\btypes:\s*\n(?:\s*-[^\n]*\n)*\s*-\s*(?:opened|synchronize|reopened|ready_for_review)\b", text) - ) - return not (has_closed_type and not has_gating_types) + """Inspect only literal on.pull_request, never sibling events or payload text. + + Like literal_jobs, this is an offline subset reader, not a general YAML + parser. Ambiguous or unsupported trigger forms must refuse derivation. + """ + lines = [active for line in text.splitlines() if (active := _trigger_line(line)).strip()] + # Establish literal root boundaries before searching for on. A multiline + # quoted/flow metadata value may otherwise contain a line resembling a key. + roots = set() + root_key, root_value = None, '' + for line in lines: + if line.startswith((' ', '\t')) or (line == '---' and not roots): + continue + if line.startswith('- ') and root_key == 'on' and not root_value: + continue + match = re.fullmatch(r'''([A-Za-z_][A-Za-z0-9_-]*|'[A-Za-z_][A-Za-z0-9_-]*'|"[A-Za-z_][A-Za-z0-9_-]*")\s*:\s*(.*)''', line) + if match is None: + raise SystemExit('unsupported literal workflow root mapping') + root_key, root_value = match[1].strip("'\""), match[2] + if root_key in roots: + raise SystemExit('duplicate workflow root field') + roots.add(root_key) + if root_key != 'on': + if root_value.startswith(("'", '"')): + scalar(root_value) + elif root_value.startswith(('[', '{')): + _trigger_line(root_value, complete=True) + triggers = [(index, match[1]) for index, line in enumerate(lines) + if (match := re.fullmatch(r'''(?:on|'on'|"on")\s*:\s*(.*)''', line))] + if not triggers: + return False + if len(triggers) != 1: + raise SystemExit('duplicate workflow on declaration') + index, value = triggers[0] + children = [] + for line in lines[index + 1:]: + if not line.startswith((' ', '\t', '- ')): + break + children.append(line) + if value.startswith('[') or (not value and children and children[0].lstrip().startswith('- ')): + return 'pull_request' in _trigger_sequence(value, children) + if value: + if children: + raise SystemExit('unsupported workflow trigger scalar children') + return _trigger_word(value) == 'pull_request' + events = _trigger_mapping(children) + if 'pull_request' not in events: + return False + value, children = events['pull_request'] + if value not in ('', 'null', '~', '{}') or (value and children): + raise SystemExit('unsupported pull_request trigger mapping') + fields = _trigger_mapping(children, indentless_lists=True) + if 'types' not in fields: + return True + types, children = fields['types'] + return any(activity != 'closed' for activity in _trigger_sequence(types, children)) def published_checks_text(text: str, callers: list[str]) -> list[str]: @@ -309,21 +433,25 @@ def declaration_for( root: Path, ignored: tuple[str, ...] = (), workflow_payloads: dict[str, bytes] | None = None, + repository: str | None = None, ) -> dict[str, Any] | None: - repository = repository_name(root) + repository = repository or repository_name(root) if repository is None: return None directory = root / ".github/workflows" overlays = workflow_payloads or {} + ignored_set = set(ignored) workflows: dict[str, tuple[Path, bytes | None]] = {} if directory.is_dir(): for workflow in sorted(directory.glob("*.y*ml")): relative = workflow.relative_to(root).as_posix() - workflows[relative] = (workflow, None) + if relative not in ignored_set and workflow.name not in ignored_set: + workflows[relative] = (workflow, None) for relative, content in overlays.items(): if not relative.startswith(".github/workflows/") or not relative.endswith((".yml", ".yaml")): continue - workflows[relative] = (root / relative, content) + if relative not in ignored_set and Path(relative).name not in ignored_set: + workflows[relative] = (root / relative, content) if not workflows: return None checks: list[dict[str, str]] = [] diff --git a/.governance/governance_check.py b/.governance/governance_check.py index 4df52dd..2af84f0 100755 --- a/.governance/governance_check.py +++ b/.governance/governance_check.py @@ -35,7 +35,9 @@ sys.dont_write_bytecode = True try: try: - from ticket_activity import ActivityError, delivery_landed, resolve as resolve_ticket_activity + from ticket_activity import (ActivityError, ActivityReadBatch, delivery_landed, + parse_ticket_state_text as _shared_ticket_state, + resolve as resolve_ticket_activity) except ModuleNotFoundError: _activity_spec = importlib.util.spec_from_file_location( "ticket_activity", Path(__file__).with_name("ticket_activity.py") @@ -46,8 +48,10 @@ sys.modules[_activity_spec.name] = _activity_module _activity_spec.loader.exec_module(_activity_module) ActivityError = _activity_module.ActivityError + ActivityReadBatch = _activity_module.ActivityReadBatch delivery_landed = _activity_module.delivery_landed resolve_ticket_activity = _activity_module.resolve + _shared_ticket_state = _activity_module.parse_ticket_state_text finally: sys.dont_write_bytecode = _previous_bytecode_policy @@ -76,18 +80,18 @@ "schema": "new-project.policy-dsl-lock/v1", "dependency": { "id": "wellmanifest/policy-dsl", - "version": "0.1.0-dev", + "version": "0.2.0-dev", "sourceRepository": "wellmanifest/policy-dsl", - "sourceRevision": "daaf7b7b96312a2469de1b4799f2f81c7396de4e", + "sourceRevision": "0ffa41efd903d3e0fc3dbf4431f2771b34c1f70e", "sourcePath": "tests/policy_dsl_check.py", - "sourceSha256": "1ebed8ada3f687bf82de235b352ec1ce94b606887ad2a1657d66bd58f04314e8", + "sourceSha256": "9bc02c1805ef208a5d136c045c6a829b7394bc652208c26942dd2e31561881ac" }, "installation": { "packageSourcePath": "scripts/policy_dsl_check.py", "managedTargetPath": ".governance/policy_dsl_check.py", "lockTargetPath": ".governance/policy-dsl.lock.json", - "networkRequired": False, - }, + "networkRequired": False + } } ACTIVE_DEFAULT = {"IN_PROGRESS"} TICKET_ACTIVITY_ERROR = "GOV-TICKET-ACTIVITY-001" @@ -179,6 +183,9 @@ def payload(self) -> dict[str, Any]: data = { "schema": "new-project.governance-report/v1", "runtimeVersion": RUNTIME_VERSION, + "validation_scope": "static-governance", + "runtime_enforcement": "not_checked", + "grants_execution_authority": False, "root": ".", "status": "passed" if self.errors == 0 else "failed", "summary": { @@ -395,6 +402,37 @@ def load_policy_dsl_module(root: Path) -> Any: return module +HOST_MERGE_START = "" +HOST_MERGE_END = "" +# The superseded block granted merge on green and administrative bypass; every +# observed copy cites this revision of wellmanifest/merge. +STALE_HOST_MERGE_SIGNATURE = "wellmanifest/merge@ticket-008" + + +def check_host_merge_policy(root: Path, report: Report) -> None: + """Warn while host instructions still carry the superseded merge authority.""" + stale = [] + for name in ("AGENTS.md", "CLAUDE.md", "GEMINI.md"): + path = root / name + if not path.is_file() or path.is_symlink(): + continue + text = path.read_text(encoding="utf-8", errors="replace") + begin, end = text.find(HOST_MERGE_START), text.find(HOST_MERGE_END) + block = text[begin:end] if 0 <= begin < end else "" + if STALE_HOST_MERGE_SIGNATURE in block: + stale.append(name) + if stale: + report.add( + "GOV-HOST-MERGE-001", + "Host instructions carry the superseded autonomous-merge block that allows " + "agents to merge on green or bypass review.", + "Preview and apply scripts/host_publication_policy.py from the standard in an owned " + "ticket; only the independent Validator may approve and merge.", + stale, + severity="warning", + ) + + def check_required_checks_declaration(root: Path, report: Report) -> None: script = next( ( @@ -414,7 +452,12 @@ def check_required_checks_declaration(root: Path, report: Report) -> None: if spec is None or spec.loader is None: raise ValueError("required-checks gate cannot be imported") module = importlib.util.module_from_spec(spec) - spec.loader.exec_module(module) + previous_bytecode_policy = sys.dont_write_bytecode + try: + sys.dont_write_bytecode = True + spec.loader.exec_module(module) + finally: + sys.dont_write_bytecode = previous_bytecode_policy code = module.main(["--root", str(root)]) except SystemExit as error: code = error.code if isinstance(error.code, int) else 1 @@ -440,8 +483,12 @@ def check_policy_dsl(root: Path, report: Report) -> None: if not contributing.is_file(): return try: + source = contributing.read_text(encoding="utf-8") + # Only a document that opts into the Policy DSL with a dsl fence is validated. + if not any(line.strip() == "```dsl" for line in source.splitlines()): + return policy_dsl = load_policy_dsl_module(root) - policy_dsl.parse_markdown(contributing.read_text(encoding="utf-8")) + policy_dsl.parse_markdown(source) except Exception as error: report.add( "GOV-POLICY-DSL-001", @@ -547,7 +594,7 @@ def delivery_classes_valid(value: Any) -> bool: def delivery_profiles_valid(value: dict[str, Any], classes_valid: bool) -> bool: profiles = value.get("profiles") - return profiles is None or ( + return "profiles" not in value or ( classes_valid and isinstance(profiles, dict) and set(profiles) == set(value["allowedComplexityClasses"]) @@ -596,7 +643,20 @@ def effective_delivery_policy(policy: dict[str, Any], complexity: str) -> dict[s return policy if profile is None else {**policy, **profile} -def field_set_hint(value: Any, required: set[str], optional: set[str] = frozenset()) -> str: +# Where each recognized delivery field belongs, so a misplaced one names its required path. +DELIVERY_FIELD_PATHS = { + **{name: f"delivery.{name}" for name in ( + "acceptedBaseSha", "targetBranch", "outcome", "nonGoals", "complexity", "estimatedMinutes", + "budgets", "architecture", "runtimeDependencies", "validation")}, + **{name: f"delivery.budgets.{name}" for name in ( + "maxImplementationFiles", "maxAffectedComponents", "maxPublicInterfaceChanges", "maxRuntimeDependencies")}, + **{name: f"delivery.architecture.{name}" for name in ( + "status", "decision", "components", "responsibilityChanges", "interfaceChanges", "dataChanges", "ui", "rollback")}, +} + + +def field_set_hint(value: Any, required: set[str], optional: set[str] = frozenset(), + located: dict[str, str] | None = None) -> str: """Name the missing and unexpected keys so an agent can repair an intent in one edit.""" if not isinstance(value, dict): return f" (expected an object with {', '.join(sorted(required))}; got {type(value).__name__})" @@ -605,6 +665,7 @@ def field_set_hint(value: Any, required: set[str], optional: set[str] = frozense parts = [f"missing: {', '.join(missing)}"] if missing else [] if unexpected: parts.append(f"unexpected: {', '.join(unexpected)}") + parts.extend(f"move {name} to {located[name]}" for name in unexpected if name in (located or {})) return f" ({'; '.join(parts)})" if parts else "" @@ -631,7 +692,7 @@ def delivery_budgets_error(budgets: Any) -> str | None: "maxPublicInterfaceChanges", "maxRuntimeDependencies", } if not isinstance(budgets, dict) or set(budgets) != fields: - return "delivery budgets are incomplete" + field_set_hint(budgets, fields) + return "delivery budgets are incomplete" + field_set_hint(budgets, fields, located=DELIVERY_FIELD_PATHS) if not integer_fields_valid(budgets, fields): return "delivery budgets must be integers" if budgets["maxImplementationFiles"] < 1 or budgets["maxAffectedComponents"] < 1: @@ -730,7 +791,8 @@ def delivery_architecture_error(architecture: Any) -> str | None: "interfaceChanges", "dataChanges", "ui", "rollback", } if not isinstance(architecture, dict) or set(architecture) != fields: - return "delivery architecture decision is incomplete" + field_set_hint(architecture, fields) + return "delivery architecture decision is incomplete" + field_set_hint( + architecture, fields, located=DELIVERY_FIELD_PATHS) if architecture.get("status") != "accepted": return f"delivery architecture status must be accepted before implementation (got {architecture.get('status')!r})" for name in ("decision", "rollback"): @@ -913,7 +975,7 @@ def check_physical_contract_changes( ) -PLACEMENT_HOMES = {"wellmanifest", "subactor", "semcod"} +PLACEMENT_HOMES = {"wellmanifest", "subactor", "semcod", "paxlet-com", "dockuri"} PLACEMENT_SHAPES = {"domain_pack", "runtime_service", "both"} PLACEMENT_ADOPT = re.compile(r"^wellmanifest/[a-z0-9][a-z0-9-]*$") @@ -923,15 +985,15 @@ def placement_error(value: Any) -> str | None: allowed = required | {"runtimeOwner", "adopt"} if not isinstance(value, dict) or not required <= set(value) <= allowed: return "placement must contain home and shape" - if value["home"] not in PLACEMENT_HOMES: + if not isinstance(value.get("home"), str) or value["home"] not in PLACEMENT_HOMES: return "placement home is invalid" - if value["shape"] not in PLACEMENT_SHAPES: + if not isinstance(value.get("shape"), str) or value["shape"] not in PLACEMENT_SHAPES: return "placement shape is invalid" runtime_owner = value.get("runtimeOwner") - if runtime_owner is not None and runtime_owner not in PLACEMENT_HOMES: + if runtime_owner is not None and (not isinstance(runtime_owner, str) or runtime_owner not in PLACEMENT_HOMES): return "placement runtimeOwner is invalid" if value["home"] == "wellmanifest" and value["shape"] == "runtime_service": - return "runtime_service must not HOME wellmanifest; ADOPT packs from subactor or semcod" + return "runtime_service must not HOME wellmanifest; HOME in a product organization and ADOPT wellmanifest packs" adopt = value.get("adopt") if adopt is not None and ( not string_list(adopt) or not all(PLACEMENT_ADOPT.fullmatch(item) for item in adopt) @@ -1125,7 +1187,8 @@ def delivery_intent_error(value: Any) -> str | None: } optional_fields = {"standardAdoption", "snapshotMigration"} if not isinstance(value, dict) or not required_fields <= set(value) <= required_fields | optional_fields: - return "delivery must contain exactly the bounded-delivery fields" + field_set_hint(value, required_fields, optional_fields) + return "delivery must contain exactly the bounded-delivery fields" + field_set_hint( + value, required_fields, optional_fields, located=DELIVERY_FIELD_PATHS) if "snapshotMigration" in value: try: migration_error = snapshot_migration_runtime().contract_error(value["snapshotMigration"]) @@ -1326,7 +1389,7 @@ def check_history_order( if not base: return try: - arguments = ["rev-list", "--reverse", f"{base}..{head}"] + arguments = ["rev-list", "--reverse", "--topo-order", f"{base}..{head}"] migration = report.snapshot_migrations.get(ticket_name) if migration: arguments.append("^" + migration["sourceSha"]) @@ -1341,31 +1404,52 @@ def check_history_order( first_implementation: tuple[int, str] | None = None for index, commit in enumerate(commits): try: - raw = git_output(root, ["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", commit]) - except subprocess.CalledProcessError: + parents = git_output(root, ["rev-list", "--parents", "--max-count=1", commit]).decode().split() + tree_diff = ["diff-tree", "--no-commit-id", "--name-only", "--no-renames", + "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "-r", "-z"] + # Diff merge resolutions against the first parent explicitly; + # diff-tree's default omits merges, while -m includes every parent. + previous = [parents[1], commit] if len(parents) > 1 else ["--root", commit] + raw = git_output(root, [*tree_diff, *previous]) + paths = [path for path in raw.decode("utf-8", "surrogateescape").split("\0") if path] + material = {path for path in paths if not matches(path, governance_patterns)} + if not material: + continue + # A historical commit that only sets these entries to their exact + # baseline state introduces no new implementation for this ticket. + # Tree diffs retain modes, types and deletions; do not filter by the + # final HEAD diff, which could conceal transient unapproved code. + # Verified migrations define their own imported baseline. A repair + # that reverts imported material to the ordinary base still counts + # there and must not receive this inherited-history exemption. + if not migration: + relative = git_output(root, [*tree_diff, base, commit]) + different_from_base = set(relative.decode("utf-8", "surrogateescape").split("\0")) + if not material.intersection(different_from_base): + continue + except (subprocess.CalledProcessError, FileNotFoundError): report.add( "GOV-DIFF-001", f"Git could not inspect commit {commit}.", "Fetch complete commit objects and rerun the governance gate.", evidence={"commit": commit}, ) return - paths = [path for path in raw.decode("utf-8", "surrogateescape").split("\0") if path] - if any(not matches(path, governance_patterns) for path in paths): - first_implementation = (index, commit) - break + first_implementation = (index, commit) + break if first_implementation is None: return _, commit = first_implementation ticket_intent = f"{ticket_root.rstrip('/')}/{ticket_name}/{intent_path}" try: - subprocess.run( - ["git", "cat-file", "-e", f"{commit}:{ticket_intent}"], cwd=root, - check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, - ) - except subprocess.CalledProcessError: + raw_blob = git_output(root, ["cat-file", "-p", f"{commit}:{ticket_intent}"]) + parsed_intent = json.loads(raw_blob.decode("utf-8")) + _, intent_error = validate_intent_value(parsed_intent, ticket_name) + if intent_error is not None: + raise ValueError(intent_error) + except (subprocess.CalledProcessError, ValueError, UnicodeDecodeError): report.add( "GOV-INTENT-003", - f"{ticket_intent} was absent from the first material implementation commit.", + f"{ticket_intent} was absent or invalid in the first material implementation commit.", "Include the validated intent atomically with the first material commit; do not create a separate plan-only commit.", [ticket_intent], {"firstImplementationCommit": commit}, ) @@ -1492,12 +1576,27 @@ def integration_policy_valid(integration: Any, workstreams: dict[str, Any]) -> b ) +def idle_takeover_policy_valid(policy: Any) -> bool: + def bounded(value: Any, low: int, high: int) -> bool: + return isinstance(value, int) and not isinstance(value, bool) and low <= value <= high + return ( + isinstance(policy, dict) + and set(policy) == {"enabled", "idleMinutes", "leaseMinutes"} + and isinstance(policy["enabled"], bool) + and bounded(policy["idleMinutes"], 5, 240) + and bounded(policy["leaseMinutes"], 15, 480) + and policy["leaseMinutes"] > policy["idleMinutes"] + ) + + def coordination_policy_valid(coordination: Any) -> bool: fields = { "mode", "maxActiveTicketsPerWorkstream", "rejectActiveScopeOverlap", "workstreams", "integration", } - if not isinstance(coordination, dict) or set(coordination) != fields: + if not isinstance(coordination, dict) or set(coordination) - {"idleTakeover"} != fields: + return False + if "idleTakeover" in coordination and not idle_takeover_policy_valid(coordination["idleTakeover"]): return False limit = coordination.get("maxActiveTicketsPerWorkstream") settings_valid = ( @@ -1575,6 +1674,8 @@ def lock_standard_valid(standard: Any, expected_version: str) -> bool: def load_managed_lock(lock_path: Path, manifest: dict[str, Any]) -> dict[str, str]: lock = load_json(lock_path) + if not isinstance(lock, dict): + raise ValueError("lock must be an object") managed = lock["managedFiles"] if ( lock.get("schema") != "new-project.lock/v1" @@ -1700,12 +1801,7 @@ def parse_ticket_state(readme: Path) -> tuple[str | None, str | None]: def parse_ticket_state_text(text: str) -> tuple[str | None, str | None]: - status_match = re.search(r"(?mi)^-[ \t]+\*\*Status\*\*:[ \t]*([A-Z_]+)[ \t]*$", text) - state_match = re.search(r"(?mi)^-[ \t]+\*\*Workflow state\*\*:[ \t]*([A-Z_]+)[ \t]*$", text) - return ( - status_match.group(1).upper() if status_match else None, - state_match.group(1).upper() if state_match else None, - ) + return _shared_ticket_state(text) def ticket_directories(root: Path, config: dict[str, Any]) -> list[Path]: @@ -1872,8 +1968,9 @@ def load_repository_policy_ticket( "integrationTicket": None, "classification": {"kind": "SERVICE", "priority": "P2", "origin": "requested"}, } + ticket_root = policy.get("tickets", {}).get("root", "project") return TicketRecord( - root / str(raw_path), + root / str(ticket_root) / adapter["ticket"], adapter["status"], adapter["workflow"], intent, @@ -1936,6 +2033,38 @@ def active_ticket_records( report: Report | None = None, ) -> list[TicketRecord]: """Return live reservations from the shared status/receipt resolver.""" + active_statuses = set(config.get("activeStatuses", ACTIVE_DEFAULT)) + projected = [record for record in records if record.status in active_statuses] + if not projected: + return [] + try: + with ActivityReadBatch(root): + return _resolve_active_ticket_records(root, config, projected, report) + except ActivityError as error: + # Inactivity is accepted only after the whole batch revalidates. A + # changed input invalidates every terminal result from this inspection. + _report_activity_error(root, projected[0], error, report) + return projected + + +def _report_activity_error( + root: Path, record: TicketRecord, error: ActivityError, report: Report | None, +) -> None: + if report is not None and not any( + finding.code == TICKET_ACTIVITY_ERROR for finding in report.findings + ): + report.add( + TICKET_ACTIVITY_ERROR, + f"Ticket activity could not be resolved safely: {error}", + "Reconcile or quarantine the clone-external registry from protected evidence; follow error/GOV-TICKET-ACTIVITY.md.", + [rel(root, record.directory / "README.md")], + {"ticket": record.directory.name, "fallback": "remain-active"}, + ) + + +def _resolve_active_ticket_records( + root: Path, config: dict[str, Any], records: list[TicketRecord], report: Report | None, +) -> list[TicketRecord]: active_statuses = set(config.get("activeStatuses", ACTIVE_DEFAULT)) active: list[TicketRecord] = [] for record in records: @@ -1948,16 +2077,7 @@ def active_ticket_records( # A broken optional cache must never fabricate terminal authority. # Keep the projection active and expose one stable, recoverable error. active.append(record) - if report is not None and not any( - finding.code == TICKET_ACTIVITY_ERROR for finding in report.findings - ): - report.add( - TICKET_ACTIVITY_ERROR, - f"Ticket activity could not be resolved safely: {error}", - "Reconcile or quarantine the clone-external registry from protected evidence; follow error/GOV-TICKET-ACTIVITY.md.", - [rel(root, record.directory / "README.md")], - {"ticket": record.directory.name, "fallback": "remain-active"}, - ) + _report_activity_error(root, record, error, report) continue if resolution.active: active.append(record) @@ -2094,13 +2214,13 @@ def adoption_path_list_valid(paths: Any, pattern: str) -> bool: return ( isinstance(paths, list) and bool(paths) - and len(paths) == len(set(paths)) and all( isinstance(path, str) and re.fullmatch(pattern, path) is not None and relative_pattern(path) for path in paths ) + and len(paths) == len(set(paths)) ) @@ -2122,6 +2242,8 @@ def adoption_binding_registry(root: Path) -> tuple[list[str], list[str]] | None: registry = load_json(registry_path) except (OSError, UnicodeError, json.JSONDecodeError, TypeError, ValueError): return None + if not isinstance(registry, dict): + return None workflow_paths = registry.get("revisionBoundWorkflowPaths") target_patterns = registry.get("digestBoundTargetPatterns") valid = ( @@ -2194,6 +2316,78 @@ def add_adoption_docker_bindings(root: Path, manifest: dict[str, Any], bindings: ) +WELLMAN_SCAFFOLD_PROFILES = frozenset({ + "wellmanifest/new-project", + "profile:baseline", + "profile:domain-pack", + "profile:runtime-service", + "profile:agent-executor", + "profile:deployment", + "profile:embedded-fleet", + "profile:full", +}) +WELLMAN_SCAFFOLD_VERSION_RE = re.compile( + r"\A(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)" + r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)" + r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?" + r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\Z" +) + + +def initial_adoption_seed_paths(root: Path, base: str, revision: str, + manifest: dict[str, Any]) -> set[str]: + """Closed required seeds; neither existing ownership nor writer authority.""" + if not isinstance(base, str) or re.fullmatch(r"[a-f0-9]{40}", base) is None: + return set() + root = root.resolve() + # ls-tree distinguishes proven absence from missing objects/Git failures. + native = [".governance/manifest.lock.json", ".governance/package-manifest.json", + ".governance/manifest.base.json"] + if git_output(root, ["ls-tree", "-z", base, "--", *native]): + return set() + legacy = git_output(root, ["ls-tree", "-z", base, "--", ".governance/manifest.json"]) + if legacy: + if legacy.split(b" ", 1)[0] not in {b"100644", b"100755"}: + return set() + original = json.loads(git_output(root, ["show", base + ":.governance/manifest.json"])) + standard = original.get("standard", {}) if isinstance(original, dict) else {} + if (not isinstance(original, dict) or set(original) != {"schema", "standard"} + or original.get("schema") != "wellmanifest.manifest/v1" + or not isinstance(standard, dict) or set(standard) != {"id", "version"} + or standard.get("id") not in WELLMAN_SCAFFOLD_PROFILES + or not isinstance(standard.get("version"), str) + or WELLMAN_SCAFFOLD_VERSION_RE.fullmatch(standard["version"]) is None): + return set() + for name in native: + path = root / name + if any(p.is_symlink() for p in (path, *path.parents)) or not path.is_file(): + return set() + lock = load_json(safe_repo_path(root, ".governance/manifest.lock.json")) + if (lock.get("standard", {}).get("sourceRevision") != revision + or lock.get("standard", {}).get("publicationStatus") != "published"): + return set() + base_path = safe_repo_path(root, ".governance/manifest.base.json") + if content_digest(base_path.read_bytes()) != lock.get("managedFiles", {}).get( + ".governance/manifest.base.json"): + return set() + published = load_json(base_path) + package = load_json(safe_repo_path(root, ".governance/package-manifest.json")) + targets = {item["target"] for item in package["files"]} + shared = manifest["coordination"]["integration"]["requiredForPaths"] + seeds = set() + for name in published["requiredFiles"]: + if (not isinstance(name, str) or not relative_pattern(name) + or any(c in name for c in "*?[\\") or name in targets or matches(name, shared)): + continue + path = root / name + if (any(p.is_symlink() for p in (path, *path.parents)) or not path.is_file() + or path.suffix.lower() in EXECUTABLE_SUFFIXES or path.stat().st_mode & 0o111 + or git_output(root, ["ls-tree", "-z", base, "--", name])): + continue + seeds.add(name) + return seeds + + def atomic_adoption_binding_paths( root: Path, manifest: dict[str, Any], @@ -2212,6 +2406,13 @@ def atomic_adoption_binding_paths( add_adoption_workflow_bindings(root, revision, registry, bindings) add_adoption_packaging_bindings(root, bindings) add_adoption_docker_bindings(root, manifest, bindings) + if (intent.get("workstream") == "governance" and adoption.get("fromRevision") is None + and standard_adoption_error(adoption) is None): + try: + bindings.update(initial_adoption_seed_paths( + root, delivery.get("acceptedBaseSha"), revision, manifest)) + except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError): + pass # Incomplete seed evidence grants no cross-workstream scope. return bindings @@ -2375,17 +2576,33 @@ def check_scope_overlaps( governance_patterns: list[str], report: Report, ) -> None: + if len(valid_active) < 2: + return + # Match each ticket against repository paths once, rather than repeating + # that work for every pair. Positions retain duplicate counts and the + # original first-20 selection before Report canonicalizes the paths. + candidates = [(index, path) for index, path in enumerate(files) + if not matches(path, governance_patterns)] + matching_positions: list[set[int]] = [] + for record in valid_active: + assert record.intent is not None + matching_positions.append({ + index for index, path in candidates + if matches(path, record.intent["allowedPaths"]) + and not matches(path, record.intent["forbiddenPaths"]) + }) for index, first in enumerate(valid_active): - for second in valid_active[index + 1:]: - shared_files = ticket_shared_files(first, second, files, governance_patterns) + for second_index in range(index + 1, len(valid_active)): + second = valid_active[second_index] + shared_positions = matching_positions[index] & matching_positions[second_index] overlapping_patterns = ticket_overlapping_patterns(first, second, governance_patterns) - if shared_files or overlapping_patterns: + if shared_positions or overlapping_patterns: report.add( "GOV-WORKSTREAM-004", f"Active ticket scopes overlap: {first.directory.name} and {second.directory.name}.", "Narrow one allowedPaths declaration, serialize the work, or route the shared contract through integration.", - shared_files[:20], - {"tickets": [first.directory.name, second.directory.name], "overlappingPatterns": overlapping_patterns, "concretePathCount": len(shared_files)}, + [files[position] for position in sorted(shared_positions)[:20]], + {"tickets": [first.directory.name, second.directory.name], "overlappingPatterns": overlapping_patterns, "concretePathCount": len(shared_positions)}, ) @@ -2720,12 +2937,19 @@ def validate_domain_errors(root: Path, errors: dict[str, Any], domain: str, comm {"code", "documentation", "retryability", "status", "rejectionEvent"}, "errors", ) + command_for_code = { + code: [cmd_name for cmd_name, cmd in commands.items() if code in cmd["rejects"]] + for code in error_index + } for error in error_index.values(): contract_document( root, error["documentation"], f"error/{error['code']}.md", "error", ) if error["rejectionEvent"] not in event_index: raise ValueError("error rejection event is unknown") + emitter = event_index[error["rejectionEvent"]]["emittedBy"] + if emitter not in command_for_code.get(error["code"], []): + raise ValueError("error rejection event emitter does not match rejecting command") if error["retryability"] not in { "never", "after-correction", "after-new-evidence", }: @@ -2803,6 +3027,22 @@ def first_repo_file(names: list[str]) -> str | None: ) +def _section_aware_toml_version(content: str, section_names: tuple[str, ...]) -> str | None: + current_section = None + for line in content.splitlines(): + line = line.strip() + if not line or line.startswith("#"): + continue + if line.startswith("[") and line.endswith("]"): + current_section = line.strip("[]").strip() + continue + if current_section in section_names: + m = re.match(r'^version\s*=\s*["\']([^"\']+)["\']', line) + if m: + return m.group(1).strip() + return None + + def _extract_pyproject_version(content: str) -> str | None: if tomllib is not None: try: @@ -2818,8 +3058,7 @@ def _extract_pyproject_version(content: str) -> str | None: return flit["version"].strip() except Exception: pass - m = re.search(r'^\s*version\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE) - return m.group(1).strip() if m else None + return _section_aware_toml_version(content, ("project", "tool.poetry", "tool.flit.metadata")) def _extract_setup_py_version(content: str) -> str | None: @@ -2839,8 +3078,87 @@ def _extract_cargo_version(content: str) -> str | None: return pkg["version"].strip() except Exception: pass - m = re.search(r'^\s*version\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE) - return m.group(1).strip() if m else None + return _section_aware_toml_version(content, ("package",)) + + +def _read_bounded_regular_utf8(path: Path, resolved_root: Path, max_bytes: int) -> str | None: + resolved_path = path.resolve() + resolved_path.relative_to(resolved_root) + open_flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0) + fd = os.open(path, open_flags) + try: + st = os.fstat(fd) + if not stat.S_ISREG(st.st_mode) or st.st_size > max_bytes: + return None + chunks: list[bytes] = [] + total = 0 + while total <= max_bytes: + chunk = os.read(fd, min(65536, max_bytes + 1 - total)) + if not chunk: + break + chunks.append(chunk) + total += len(chunk) + if total > max_bytes: + return None + return b"".join(chunks).decode("utf-8") + finally: + os.close(fd) + + +def _enclosing_subpackage_version( + root: Path, + resolved_root: Path, + init_file: Path, + max_bytes: int, + report: Report, +) -> tuple[str | None, str | None, bool]: + anc = init_file.parent + while anc != root: + for manifest_name in ("pyproject.toml", "setup.py"): + candidate = anc / manifest_name + if candidate.is_symlink(): + rel_c = rel(root, candidate) + report.add( + "GOV-VERSION-001", + f"Symlinked nested package manifest {rel_c} is forbidden in version parity scan.", + "Replace symlinked nested package manifest with a regular repository-contained file.", + [rel_c], + ) + return None, None, True + if not os.path.lexists(candidate): + continue + rel_c = rel(root, candidate) + try: + content = _read_bounded_regular_utf8(candidate, resolved_root, max_bytes) + except (OSError, UnicodeDecodeError, ValueError): + content = None + if content is None: + report.add( + "GOV-VERSION-001", + f"Nested package manifest {rel_c} is unreadable, non-regular, or oversized in version parity scan.", + "Ensure nested package manifests are regular UTF-8 files within size bounds.", + [rel_c], + ) + return None, None, True + if manifest_name == "pyproject.toml": + if tomllib is not None: + try: + tomllib.loads(content) + except Exception: + report.add( + "GOV-VERSION-001", + f"Nested pyproject.toml {rel_c} contains invalid TOML syntax.", + "Fix TOML syntax in the nested pyproject.toml.", + [rel_c], + ) + return None, None, True + sub_v = _extract_pyproject_version(content) + else: + sub_v = _extract_setup_py_version(content) + if sub_v: + return sub_v, rel_c, False + anc = anc.parent + return None, None, False def check_version_parity(root: Path, manifest: dict[str, Any], report: Report) -> None: @@ -2942,16 +3260,50 @@ def check_version_parity(root: Path, manifest: dict[str, Any], report: Report) - "tests", "test", "build", "dist", "node_modules", "fixtures", "__pycache__", ".tox", ".nox", ".pytest_cache" } - for init_file in root.glob("**/__init__.py"): + resolved_root = root.resolve() + max_init_bytes = 1024 * 1024 + for init_file in version_scan_initializers(root): rel_parts = init_file.relative_to(root).parts if any(part in skip_dirs for part in rel_parts): continue + cur = init_file + has_symlink = False + while cur != root: + if cur.is_symlink(): + has_symlink = True + break + cur = cur.parent + if has_symlink: + rel_p = rel(root, init_file) + report.add( + "GOV-VERSION-001", + f"Symlinked Python package initializer {rel_p} is forbidden in version parity scan.", + "Replace symlinked __init__.py or package directory with a regular repository-contained file.", + [rel_p], + ) + continue try: - text = init_file.read_text(encoding="utf-8") + text = _read_bounded_regular_utf8(init_file, resolved_root, max_init_bytes) + if text is None: + continue m = re.search(r'^__version__\s*=\s*["\']([^"\']+)["\']', text, re.MULTILINE) if m: found_v = m.group(1).strip() - if found_v != raw_version: + sub_v, sub_source, failed = _enclosing_subpackage_version( + root, resolved_root, init_file, max_init_bytes, report + ) + if failed: + continue + if sub_v is not None and sub_source is not None: + if found_v != sub_v: + rel_p = rel(root, init_file) + report.add( + "GOV-VERSION-001", + f"Static __version__ '{found_v}' in {rel_p} does not match enclosing {sub_source} version '{sub_v}'.", + f"Synchronize __version__ in {rel_p} with {sub_source} or use dynamic version discovery.", + [rel_p, sub_source], + ) + elif found_v != raw_version: rel_p = rel(root, init_file) report.add( "GOV-VERSION-001", @@ -2959,10 +3311,29 @@ def check_version_parity(root: Path, manifest: dict[str, Any], report: Report) - "Use dynamic version discovery (importlib.metadata / VERSION) or synchronize __version__ with VERSION.", [rel_p, "VERSION"], ) - except (OSError, UnicodeDecodeError): + except (OSError, UnicodeDecodeError, ValueError): pass +def version_scan_initializers(root: Path) -> list[Path]: + """Return package initializers owned by this repository. + + Local runtime directories (``.run``, virtualenvs, build caches) are not + repository state even when they are absent from the static skip set. Git + owns the ignore rules, so honor .gitignore/.git/info/exclude here; a + non-Git checkout keeps the previous full scan. + """ + try: + raw = git_output(root, ["ls-files", "-co", "--exclude-standard", "-z"]) + except (subprocess.CalledProcessError, FileNotFoundError): + return list(root.glob("**/__init__.py")) + names = raw.decode("utf-8", "surrogateescape").split("\0") + return [candidate for name in names + if name == "__init__.py" or name.endswith("/__init__.py") + for candidate in (root / name,) + if candidate.is_file()] + + def immutable_image_reference(reference: str) -> bool: return reference == "scratch" or IMMUTABLE_IMAGE_RE.fullmatch(reference) is not None @@ -3122,21 +3493,30 @@ def add_field(name: str) -> None: if m: fields.append(m.group(1)) + def assigned_literal(target: ast.AST, value: ast.AST) -> None: + if isinstance(target, (ast.Tuple, ast.List)): + if isinstance(value, (ast.Tuple, ast.List)) and len(target.elts) == len(value.elts): + for item, literal in zip(target.elts, value.elts): + assigned_literal(item, literal) + return + if not is_secret_literal(value): + return + if isinstance(target, ast.Name): + add_field(target.id) + elif isinstance(target, ast.Attribute): + add_field(target.attr) + elif isinstance(target, ast.Subscript): + key = extract_constant_string(target.slice) + if key is not None: + add_field(key) + for node in ast.walk(tree): if isinstance(node, ast.Assign): for target in node.targets: - if isinstance(target, ast.Name) and SECRET_FIELD_NAME_RE.search(target.id): - if is_secret_literal(node.value): - add_field(target.id) - elif isinstance(target, (ast.Tuple, ast.List)): - if isinstance(node.value, (ast.Tuple, ast.List)) and len(target.elts) == len(node.value.elts): - for t, v in zip(target.elts, node.value.elts): - if isinstance(t, ast.Name) and SECRET_FIELD_NAME_RE.search(t.id) and is_secret_literal(v): - add_field(t.id) + assigned_literal(target, node.value) elif isinstance(node, ast.AnnAssign): - if isinstance(node.target, ast.Name) and SECRET_FIELD_NAME_RE.search(node.target.id): - if node.value is not None and is_secret_literal(node.value): - add_field(node.target.id) + if node.value is not None: + assigned_literal(node.target, node.value) elif isinstance(node, ast.Call): for kw in node.keywords: if kw.arg and SECRET_FIELD_NAME_RE.search(kw.arg): @@ -3148,12 +3528,13 @@ def add_field(name: str) -> None: if is_secret_literal(v): add_field(k.value) elif isinstance(node, ast.Compare): - if isinstance(node.left, ast.Name) and SECRET_FIELD_NAME_RE.search(node.left.id): - for comp in node.comparators: - if is_secret_literal(comp): - add_field(node.left.id) - elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): - pos_args = node.args.args + operands = [node.left, *node.comparators] + literal = next((value for value in operands if is_secret_literal(value)), None) + if literal is not None: + for target in operands: + assigned_literal(target, literal) + elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)): + pos_args = [*node.args.posonlyargs, *node.args.args] defaults = node.args.defaults for arg, default in zip(pos_args[-len(defaults):], defaults): if SECRET_FIELD_NAME_RE.search(arg.arg) and is_secret_literal(default): @@ -3427,20 +3808,24 @@ def observe_delivery_bases(root, delivery, accepted_sha, intent_path, base, repo return observed +def _is_git_ancestor(root: Path, ancestor_sha: str, descendant_sha: str) -> bool: + result = subprocess.run( + ["git", "merge-base", "--is-ancestor", ancestor_sha, descendant_sha], + cwd=root, + check=False, + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + return result.returncode == 0 + + def check_observed_delivery_bases(root, accepted_commit, observed, component_patterns, record, intent_path, report) -> None: checked: set[str] = set() for source, observed_sha in observed: if observed_sha in checked or observed_sha == accepted_commit: continue checked.add(observed_sha) - ancestor = subprocess.run( - ["git", "merge-base", "--is-ancestor", accepted_commit, observed_sha], - cwd=root, - check=False, - stdout=subprocess.DEVNULL, - stderr=subprocess.DEVNULL, - ) - if ancestor.returncode != 0: + if not _is_git_ancestor(root, accepted_commit, observed_sha): report.add( "GOV-BASE-001", f"Ticket {record.directory.name} accepted base is not an ancestor of the observed target.", @@ -4242,6 +4627,61 @@ def standard_adoption_records(active: list[TicketRecord]) -> list[TicketRecord]: ] +def _record_ticket_dir_and_prefix(root: Path, record: Any) -> tuple[Path | None, str | None]: + ticket_dir = getattr(record, "directory", None) + if not isinstance(ticket_dir, Path): + return None, None + resolved_dir = ticket_dir if ticket_dir.is_absolute() else root / ticket_dir + try: + rel_dir = resolved_dir.resolve().relative_to(root.resolve()).as_posix().rstrip("/") + except ValueError: + rel_dir = ticket_dir.as_posix().rstrip("/") if not ticket_dir.is_absolute() else None + return resolved_dir, (f"{rel_dir}/" if rel_dir else None) + + +def _is_clean_target_head(root: Path, target_ref: str, head: str) -> bool: + try: + target_sha = git_output(root, ["rev-parse", "--verify", f"{target_ref}^{{commit}}"]).decode().strip() + head_sha = git_output(root, ["rev-parse", "--verify", f"{head}^{{commit}}"]).decode().strip() + if not target_sha or head_sha != target_sha: + return False + return not git_output(root, ["status", "--porcelain", "--untracked-files=all"]).strip() + except (subprocess.CalledProcessError, FileNotFoundError): + return False + + +def unlanded_standard_adoption_records( + root: Path, + active: list[TicketRecord], + changed: list[str] | None = None, + *, + require_clean_target_head: bool = False, + head: str = "HEAD", +) -> list[TicketRecord]: + unlanded: list[TicketRecord] = [] + for record in standard_adoption_records(active): + if record.intent is None: + continue + delivery = record.intent.get("delivery") + if not isinstance(delivery, dict): + continue + ticket_dir, prefix = _record_ticket_dir_and_prefix(root, record) + if changed and prefix and any(path.startswith(prefix) for path in changed): + unlanded.append(record) + continue + target_branch = delivery.get("targetBranch") + if ticket_dir is not None and isinstance(target_branch, str) and target_branch: + target_ref = f"refs/remotes/origin/{target_branch}" + if not require_clean_target_head or _is_clean_target_head(root, target_ref, head): + try: + if delivery_landed(root, ticket_dir, target_ref): + continue + except Exception: + pass + unlanded.append(record) + return unlanded + + def load_standard_adoption_evidence( root: Path, base: str, @@ -4280,7 +4720,7 @@ def load_standard_adoption_evidence( head_hashes = adoption_lock(head_lock_path.read_bytes(), adoption["toRevision"]) base_managed = {path for path, strategy in base_strategies.items() if strategy == "managed"} head_managed = {path for path, strategy in head_strategies.items() if strategy == "managed"} - legacy_base = not base_strategies or (set(base_hashes) <= set(base_strategies)) + legacy_base = base_package_content is None if ( frozenset(base_hashes) not in {frozenset(base_strategies), frozenset(base_managed)} and not legacy_base @@ -4417,8 +4857,11 @@ def atomic_standard_adoption_paths( changed: list[str], active: list[TicketRecord], report: Report, + head: str = "HEAD", ) -> set[str]: - records = standard_adoption_records(active) + records = unlanded_standard_adoption_records( + root, active, changed, require_clean_target_head=(base is None), head=head, + ) if not records: return set() evidence_paths = [".governance/manifest.lock.json", ".governance/package-manifest.json"] @@ -4609,6 +5052,8 @@ def parse_args(argv: list[str]) -> argparse.Namespace: default=".governance/work-classification.dsl.json", ) parser.add_argument("--base") + parser.add_argument("--infer-ticket-base", action="store_true", + help="On a ticket/NNN-* branch without --base, validate from its merge-base with origin/") parser.add_argument("--head", default="HEAD") parser.add_argument("--changed-file", action="append", default=[]) parser.add_argument("--actor", choices=["agent", "human", "ci"], default="agent") @@ -4717,27 +5162,10 @@ def resolve_validation_base( if supplied_base is not None: return supplied_base active = active_records if active_records is not None else active_ticket_records(root, config, records) - adoption_records = standard_adoption_records(active) # If an adoption ticket's delivery is already landed on its target branch, # its prose status remains active only because terminal receipts were not recorded. # Exclude landed adoptions so subsequent tickets do not have their validation base poisoned. - unlanded_adoptions = [] - for record in adoption_records: - if record.intent is None: - continue - delivery = record.intent.get("delivery") - if not isinstance(delivery, dict): - continue - ticket_dir = getattr(record, "directory", None) - target_branch = delivery.get("targetBranch") - if ticket_dir is not None and target_branch: - target_ref = f"refs/remotes/origin/{target_branch}" - try: - if delivery_landed(root, ticket_dir, target_ref): - continue - except Exception: - pass - unlanded_adoptions.append(record) + unlanded_adoptions = unlanded_standard_adoption_records(root, active) deliveries = [record.intent["delivery"] for record in unlanded_adoptions if record.intent is not None] if not deliveries: return None @@ -4754,28 +5182,35 @@ def resolve_validation_base( def check_change_lease(root: Path, report: Report) -> None: - candidates = [ - root / "scripts" / "change_lease_check.py", - root / ".governance" / "change_lease_check.py", - ] - checker = next((path for path in candidates if path.is_file()), None) - if checker is None: + # The inspected repository is data, not a source of executable validator + # code. Use the helper shipped with this particular validator instead. + checker = Path(__file__).resolve().with_name("change_lease_check.py") + if checker.is_symlink() or not checker.is_file(): + report.add( + "GOV-CHANGE-LEASE-001", "The validator's change-lease checker is missing or not a regular file.", + "Restore the complete trusted new-project validator package.", + ) return spec = importlib.util.spec_from_file_location("new_project_change_lease_check", checker) if spec is None or spec.loader is None: report.add( "GOV-CHANGE-LEASE-001", "Could not load the managed change-lease checker.", - "Restore the managed checker from the pinned new-project package.", [rel(root, checker)], + "Restore the managed checker from the pinned new-project package.", ) return module = importlib.util.module_from_spec(spec) try: - spec.loader.exec_module(module) + previous_bytecode_policy = sys.dont_write_bytecode + try: + sys.dont_write_bytecode = True + spec.loader.exec_module(module) + finally: + sys.dont_write_bytecode = previous_bytecode_policy findings = module.validate_repository(root) except Exception as error: report.add( "GOV-CHANGE-LEASE-001", f"Change-lease validation failed closed: {error}", - "Repair the managed checker or lease evidence before continuing.", [rel(root, checker)], + "Repair the managed checker or lease evidence before continuing.", ) return for item in findings: @@ -4812,29 +5247,36 @@ def compute_git_dirty_digest(root: Path) -> str: if not raw: return "clean" - fields = iter(raw.split(b"\0")) + if not raw.endswith(b"\0"): + return "git-status-failed" + fields = iter(raw[:-1].split(b"\0")) dirty_files: list[str] = [] for field in fields: if not field: - continue - path_bytes = field[3:] - try: - rel_path = path_bytes.decode("utf-8") - except UnicodeDecodeError: - rel_path = path_bytes.decode("utf-8", errors="replace") - dirty_files.append(rel_path) - if field[:2] in (b"R ", b"C "): - try: - dest = next(fields).decode("utf-8", errors="replace") - dirty_files.append(dest) - except StopIteration: - pass + return "git-status-failed" + if len(field) < 4 or field[2:3] != b" ": + return "git-status-failed" + dirty_files.append(field[3:].decode("utf-8", errors="surrogateescape")) + # Porcelain -z has one additional source pathname for a rename/copy + # in either column, including RM, MR and unstaged rename/copy states. + if b"R" in field[:2] or b"C" in field[:2]: + source = next(fields, b"") + if not source: + return "git-status-failed" + dirty_files.append(source.decode("utf-8", errors="surrogateescape")) file_hashes: dict[str, str] = {} for rel_path in sorted(set(dirty_files)): + relative = Path(rel_path) + if not relative.parts or relative.anchor or ".." in relative.parts: + return "git-status-failed" if rel_path.startswith(".subactor/cache/"): continue - p = root / rel_path + # A tracked child may remain in status after its parent directory was + # replaced by a link. Disable caching rather than hash its external target. + if any((root / parent).is_symlink() for parent in relative.parents if parent != Path(".")): + return "git-status-failed" + p = root / relative if p.is_symlink(): try: target = os.readlink(p) @@ -4856,7 +5298,7 @@ def compute_git_dirty_digest(root: Path) -> str: hasher = hashlib.sha256() hasher.update(raw) for k in sorted(file_hashes.keys()): - hasher.update(f"\n{k}:{file_hashes[k]}".encode("utf-8")) + hasher.update(f"\n{k}:{file_hashes[k]}".encode("utf-8", errors="surrogateescape")) return hasher.hexdigest() @@ -4873,6 +5315,50 @@ def file_sha256_or_none(path: Path | None) -> str | None: return "read-error" +def infer_ticket_branch_base(root: Path, manifest_path: Path | None, head: str, report: Report) -> str | None: + """Bind a bare local run on a ticket branch to the range its PR will be validated on. + + Without a base, only adoption tickets infer one, so an ordinary ticket's + committed implementation is invisible and a missing delivery contract + passes. A branch that cannot be bound fails closed instead. + """ + branch = subprocess.run(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], + cwd=root, capture_output=True, text=True, check=False).stdout.strip() + match = re.fullmatch(r"ticket/([0-9]+)-[^/]+", branch) + if match is None: + return None + try: + targets = load_json(manifest_path)["delivery"]["targetBranches"] if manifest_path else None + except (OSError, ValueError, KeyError, TypeError): + targets = None + try: + declared = load_json(root / f"project/ticket-{match.group(1)}/intent.json")["delivery"]["targetBranch"] + except (OSError, ValueError, KeyError, TypeError): + declared = None + if isinstance(targets, list) and len(targets) == 1: + target = targets[0] + else: + # Several or no policy targets: only the ticket's own declaration may choose. + target = declared if not isinstance(targets, list) or declared in targets else None + target = target if branch_name(target) else None + remote = f"refs/remotes/origin/{target}" + base = (subprocess.run(["git", "merge-base", head, remote], cwd=root, + capture_output=True, text=True, check=False).stdout.strip() if target else "") + if re.fullmatch(r"[0-9a-f]{40,64}", base) is None: + report.add( + "GOV-BASE-001", + f"Ticket branch {branch} has no validation base: " + + (f"{remote} is missing or unrelated to {head}." if target + else "the manifest names no single delivery target branch for it."), + f"Run git fetch origin {target or ''} or pass --base explicitly; " + "a bare run never validates a ticket branch without a range.", + [], {"branch": branch, "targetBranch": target}, + ) + return None + print(f"governance-check: --base {base} (merge-base of {branch} and origin/{target})", file=sys.stderr) + return base + + def git_rev_parse(root: Path, ref: str) -> str: try: proc = subprocess.run( @@ -4895,8 +5381,25 @@ def compute_preflight_cache_key( profiles_path: Path | None, work_classification_path: Path | None, ) -> str | None: + # A Git dirty digest cannot bind external ticket input, including SQLite WAL. + # Let the ordinary reader recheck its current contents and snapshot pins. + if not args.base or any((args.ticket_database, args.ticket_snapshot, args.ticket_snapshot_sha256)): + return None + try: + storage = git_output(root, ["config", "--local", "--get", "new-project.ticketStorage"]).decode().strip() + except subprocess.CalledProcessError as error: + if error.returncode != 1: + return None + storage = "files" + except (OSError, UnicodeError): + return None + if storage != "files": + return None + head_sha = git_rev_parse(root, args.head or "HEAD") - base_sha = git_rev_parse(root, args.base) if args.base else "inferred" + base_sha = git_rev_parse(root, args.base) + if head_sha.startswith("unresolved:") or base_sha.startswith("unresolved:"): + return None dirty_digest = compute_git_dirty_digest(root) if dirty_digest == "git-status-failed": return None @@ -5048,11 +5551,12 @@ def run_governance_checks( if any(path.startswith(f"{rel(root, record.directory).rstrip('/')}/") for path in changed) ] adoption_paths = atomic_standard_adoption_paths( - root, base, changed, changed_active or active, report, + root, base, changed, changed_active or active, report, args.head, ) timed_step(report, "load_work_classification", load_work_classification, root, report, args.work_classification) timed_step(report, "check_lock", check_lock, root, lock_path, manifest, report) timed_step(report, "check_policy_dsl", check_policy_dsl, root, report) + timed_step(report, "check_host_merge_policy", check_host_merge_policy, root, report) timed_step(report, "check_required_checks_declaration", check_required_checks_declaration, root, report) timed_step(report, "check_agent_hosts", check_agent_hosts, root, args.actor, report) timed_step(report, "check_required_files", check_required_files, root, manifest, report) @@ -5147,6 +5651,9 @@ def main(argv: list[str] | None = None) -> int: except ValueError: pass + if args.infer_ticket_base and args.base is None and not args.changed_file: + args.base = infer_ticket_branch_base(root, manifest_path, args.head, report) + if cache_allowed and manifest_path and manifest_path.is_file(): cache_key = compute_preflight_cache_key( root, args, manifest_path, lock_path, profiles_path, work_class_path diff --git a/.governance/idle_takeover.py b/.governance/idle_takeover.py new file mode 100755 index 0000000..7b887ab --- /dev/null +++ b/.governance/idle_takeover.py @@ -0,0 +1,880 @@ +#!/usr/bin/env python3 +"""Idle ticket takeover and the autonomy state board (new-project.idle-takeover/v1). + +A ticket whose writer shows no activity for ``coordination.idleTakeover.idleMinutes`` +may be taken over by another agent through the change-lease CAS: +``expire`` -> ``release`` -> a fresh ``claimed`` lease with a higher fencing token. +The policy lives only in the governance manifest; without it takeover is disabled. + +Activity is the newest of the lease heartbeat, the branch commit, any dirty file +in the ticket worktree and the ticket's continuity events. A live process whose +working directory is inside the worktree always counts as activity. Dirty work is +stored as a content-addressed snapshot before ownership moves; the worktree itself +is never reset. Frozen publication phases, integrated tickets, worktrees outside +the wellmanifest/worktrees v5 layout and invalid leases are reported, never taken +over. + +Every observation rewrites the board ``.subactor/cache/autonomy-board.{json,md}`` +in the primary checkout: owner, idle time, state, the canonical worktree and lease +paths and links to the project, branch, README, pull request and issue list, so +the next agent can pick work without reconstructing the state from chat. +""" +from __future__ import annotations + +import argparse +import hashlib +import importlib.util +import io +import json +import os +import re +import stat +import subprocess +import sys +import tarfile +from contextlib import contextmanager +from datetime import datetime, timedelta, timezone +from pathlib import Path +from typing import Any + +try: # Exclusive lease transition lock: fcntl on POSIX, msvcrt on Windows. + import fcntl +except ImportError: # pragma: no cover - Windows + fcntl = None + import msvcrt + +SCHEMA = "new-project.idle-takeover/v1" +BOARD_SCHEMA = "new-project.autonomy-board/v1" +# Runtime namespaces this module owns; all lie under the root-ignored +# wellmanifest/worktrees operational directories (cache, snapshots, receipts). +BOARD_DIR = ".subactor/cache" +SNAPSHOT_DIR = ".subactor/snapshots/idle-takeover" +RECEIPT_DIR = ".subactor/receipts/idle-takeover" +CONTINUITY_MANIFEST = ".subactor/manifest.json" +POLICY_MANIFESTS = (".governance/manifest.json", "governance/manifest.hub.json") +POLICY_FIELDS = ("enabled", "idleMinutes", "leaseMinutes") +# Bounded inputs: a snapshot larger than this needs a human handoff, and only the +# newest part of the append-only continuity stream is read. +MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024 +MAX_CONTINUITY_BYTES = 8 * 1024 * 1024 +# Layout fallbacks for pinned lease contracts older than new-project 0.20.120, +# which do not export the wellmanifest/worktrees v5 roots yet. +LEGACY_LAYOUT = {"WORKTREES_ROOT": ".worktrees", "LEASE_ROOT": ".subactor/leases", "MAX_LEASE_BYTES": 65536} +TICKET_RE = re.compile(r"ticket-[0-9]{3,}") +IDENTITY_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,159}") +# Forge URL shapes for the board; the host comes from the origin remote. +FORGE_PATHS = {"branch": "tree/{branch}", "readme": "blob/{branch}/project/{ticket}/README.md", + "pull": "pull/{number}", "pullSearch": "pulls?q=head%3A{branch}", + "pulls": "pulls", "issues": "issues"} + + +def pinned_module(primary: Path | None, name: str): + """Load the repository's own pinned .governance copy; fall back to the sibling script.""" + pinned = primary / ".governance" / name if primary else None + source = pinned if pinned and pinned.is_file() else Path(__file__).resolve().parent / name + module_name = f"idle_takeover_{Path(name).stem}" + spec = importlib.util.spec_from_file_location(module_name, source) + module = importlib.util.module_from_spec(spec) + sys.modules[module_name] = module + spec.loader.exec_module(module) + return module + + +def lease_runtime(primary: Path | None = None): + """Validate leases with the repository's own pinned contract.""" + return pinned_module(primary, "change_lease_check.py") + + +def contract(runtime) -> dict[str, Any]: + """Layout and phase vocabulary come from the pinned change-lease contract (SSOT).""" + layout = {key: getattr(runtime, key, value) for key, value in LEGACY_LAYOUT.items()} + frozen, expirable = set(runtime.FROZEN_PHASES), set(runtime.TRANSITIONS["expire"]) + released_from = set(runtime.TRANSITIONS["release"]) + terminal = set(runtime.PHASES) - expirable - released_from | (released_from - {"expired"} - expirable) + return dict(layout, frozen=frozen, terminal=terminal, + takeover=(expirable - frozen) | (released_from - terminal)) + + +def git(root: Path, *args: str, check: bool = True) -> str: + env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} + result = subprocess.run(["git", "-C", str(root), *args], env=env, capture_output=True, text=True, check=check) + return result.stdout.strip() + + +def utc(value: str | None) -> datetime | None: + if not isinstance(value, str): + return None + try: + moment = datetime.fromisoformat(value.replace("Z", "+00:00").replace("z", "+00:00")) + except ValueError: + return None + return moment if moment.utcoffset() is not None else None + + +def stamp(moment: datetime) -> str: + return moment.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def read_json(path: Path) -> Any: + try: + return json.loads(path.read_text(encoding="utf-8")) if path.is_file() else None + except (OSError, json.JSONDecodeError): + return None + + +def primary_checkout(root: Path) -> Path: + """wellmanifest/worktrees rule 1: the primary is the first registered worktree, never a linked one.""" + rows = git(root, "worktree", "list", "--porcelain").split("\n\n") + return Path(rows[0].splitlines()[0].split(" ", 1)[1]).resolve() + + +def manifest_policy(primary: Path) -> dict[str, Any]: + """The governance manifest is the only source of the policy; absent or malformed means disabled. + + Validity is decided by the pinned governance_check.idle_takeover_policy_valid, + the same closed check the manifest gate applies (exact bool, bounded positive + integers, lease longer than the idle threshold).""" + valid = getattr(pinned_module(primary, "governance_check.py"), "idle_takeover_policy_valid", None) + for relative in POLICY_MANIFESTS: + manifest = read_json(primary / relative) + if manifest is None: + continue + configured = manifest.get("coordination", {}).get("idleTakeover") if isinstance(manifest, dict) else None + if valid is not None and valid(configured) and configured["enabled"] is True: + return {key: configured[key] for key in POLICY_FIELDS} | {"source": relative} + return {"enabled": False, "idleMinutes": None, "leaseMinutes": None, "source": relative} + return {"enabled": False, "idleMinutes": None, "leaseMinutes": None, "source": None} + + +def worktrees(primary: Path) -> dict[str, dict[str, str]]: + found = {} + for row in git(primary, "worktree", "list", "--porcelain").split("\n\n"): + fields = dict(line.split(" ", 1) for line in row.splitlines() if " " in line) + branch = fields.get("branch", "") + if "/ticket/" in branch: + found[branch] = {"path": fields["worktree"], "head": fields.get("HEAD", "")} + return found + + +def leases(primary: Path, layout: dict[str, Any]) -> list[tuple[Path, dict[str, Any]]]: + directory = primary / layout["LEASE_ROOT"] + loaded = [] + for path in sorted(directory.glob("*.json")) if directory.is_dir() else []: + try: + if path.is_symlink() or not path.is_file() or path.stat().st_size > layout["MAX_LEASE_BYTES"]: + raise ValueError("Lease must be a bounded regular file") + value = json.loads(path.read_text(encoding="utf-8")) + loaded.append((path, value if isinstance(value, dict) else {})) + except (OSError, ValueError): + loaded.append((path, {})) + return loaded + + +def canonical_layout(primary: Path, lease_path: Path, lease: dict[str, Any], tree: dict[str, str] | None, + layout: dict[str, Any]) -> dict[str, Any]: + """wellmanifest/worktrees v5 rules 2, 3 and 7: path, lease stem and branch name one delivery unit.""" + worktree_id = str(lease.get("worktreeId", "")) + ticket, _, slug = worktree_id.partition("--") + expected_path = primary / layout["WORKTREES_ROOT"] / worktree_id + expected_lease = primary / layout["LEASE_ROOT"] / f"{worktree_id}.json" + expected_branch = f"refs/heads/ticket/{ticket.removeprefix('ticket-')}-{slug}" + problems = [] + if not TICKET_RE.fullmatch(ticket) or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", slug): + problems.append("worktreeId") + if lease_path != expected_lease: + problems.append("leasePath") + if lease.get("branchRef") != expected_branch or lease.get("ticketId") != ticket: + problems.append("branch") + if tree and Path(tree["path"]) != expected_path: + problems.append("worktreePath") + if any(part.is_symlink() for part in (expected_path, *expected_path.parents) if part != part.parent and part.is_relative_to(primary)): + problems.append("symlink") + return {"worktreePath": str(expected_path), "leasePath": str(expected_lease), + "branch": expected_branch.removeprefix("refs/heads/"), "problems": problems} + + +def continuity_times(primary: Path) -> dict[str, datetime]: + """Newest checkpoint per ticket from the stream the continuity manifest declares.""" + manifest = read_json(primary / CONTINUITY_MANIFEST) + relative = manifest.get("continuity", {}).get("eventStreamPath") if isinstance(manifest, dict) else None + latest: dict[str, datetime] = {} + stream = primary / relative if isinstance(relative, str) else None + if stream is None or not stream.is_file(): + return latest + with stream.open("rb") as handle: + size = handle.seek(0, os.SEEK_END) + handle.seek(max(0, size - MAX_CONTINUITY_BYTES)) + lines = handle.read().decode("utf-8", "replace").splitlines() + for line in lines: + try: + event = json.loads(line) + except json.JSONDecodeError: + continue + checkpoint = event.get("checkpoint") if isinstance(event, dict) else None + if isinstance(checkpoint, dict): + ticket, moment = checkpoint.get("ticket"), utc(checkpoint.get("recordedAt")) + if isinstance(ticket, str) and moment and moment > latest.get(ticket, moment - timedelta(seconds=1)): + latest[ticket] = moment + return latest + + +def live_processes(path: Path, *, include_callers: bool = False) -> list[int]: + """Processes whose cwd is inside the worktree (Linux /proc only; elsewhere none are observed).""" + proc, own, pids = Path("/proc"), set() if include_callers else {os.getpid(), os.getppid()}, [] + if not proc.is_dir(): + return pids + target = str(path.resolve()) + for entry in proc.iterdir(): + if not entry.name.isdigit() or int(entry.name) in own: + continue + try: + cwd = os.readlink(entry / "cwd") + except OSError: + continue + cwd = cwd.removesuffix(" (deleted)") + if cwd == target or cwd.startswith(target + os.sep): + pids.append(int(entry.name)) + return sorted(pids) + + +def dirty_paths(worktree: Path) -> list[str]: + raw = subprocess.run(["git", "-C", str(worktree), "status", "--porcelain", "-z", "--untracked-files=all"], + capture_output=True, check=True).stdout.decode("utf-8", "surrogateescape") + paths, entries = [], raw.split("\0") + index = 0 + while index < len(entries): + entry = entries[index] + if len(entry) > 3: + paths.append(entry[3:]) + # Porcelain -z: a rename or copy in either status column is followed + # by its source path as a separate record. + if set(entry[:2]) & {"R", "C"}: + index += 1 + if index < len(entries) and entries[index]: + paths.append(entries[index]) + index += 1 + return sorted(set(paths)) + + +def integrated(primary: Path, head: str, target: str) -> bool: + """A ticket HEAD already contained in the target branch needs release, not takeover.""" + if not re.fullmatch(r"[0-9a-f]{40}", head or ""): + return False + env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} + # Any target ref that contains HEAD is enough; a stale remote ref must not hide a local merge. + return any( + git(primary, "rev-parse", "-q", "--verify", ref, check=False) + and subprocess.run(["git", "-C", str(primary), "merge-base", "--is-ancestor", head, ref], env=env).returncode == 0 + for ref in (f"refs/remotes/origin/{target}", f"refs/heads/{target}")) + + +def web_url(primary: Path) -> str | None: + remote = git(primary, "remote", "get-url", "origin", check=False) + match = re.fullmatch(r"(?:https?://|ssh://)?(?:[^@/]+@)?([^/:]+)[:/](.+?)(?:\.git)?/?", remote) + return f"https://{match[1]}/{match[2]}" if match else None + + +def links(base: str | None, branch: str | None, ticket: str, pull_request: Any) -> dict[str, str | None]: + if not base: + return {"project": None, "branch": None, "readme": None, "pullRequest": None, "issues": None} + name = branch.removeprefix("refs/heads/") if branch else None + number = re.search(r"([0-9]+)$", str(pull_request)) if pull_request else None + url = lambda key, **values: f"{base}/{FORGE_PATHS[key].format(**values)}" # noqa: E731 + return { + "project": base, + "branch": url("branch", branch=name) if name else None, + "readme": url("readme", branch=name, ticket=ticket) if name else None, + "pullRequest": url("pull", number=number[1]) if number else (url("pullSearch", branch=name) if name else None), + "issues": url("issues"), + } + + +def classify(lease, phase, invalid, layout_record, tree, dirty, pids, last, now, policy, rules, primary) -> str: + if invalid: + return "INVALID_LEASE" + if layout_record["problems"]: + return "NONCANONICAL_LAYOUT" + if pids or (last and policy["enabled"] and now - last < timedelta(minutes=policy["idleMinutes"])): + return "ACTIVE" + if not policy["enabled"]: + return "POLICY_DISABLED" + if phase in rules["frozen"] or lease.get("publicationFrozen"): + return "IDLE_FROZEN" + if not tree: + return "IDLE_NO_WORKTREE" + if not dirty and integrated(primary, tree["head"], str(lease.get("targetBranch", "main"))): + return "IDLE_INTEGRATED" + if phase not in rules["takeover"]: + return "IDLE_NOT_TAKEABLE" + return "IDLE_TAKEOVER_ELIGIBLE" + + +def observe(root: Path, now: datetime | None = None, runtime=None) -> dict[str, Any]: + now = now or datetime.now(timezone.utc) + primary = primary_checkout(root) + runtime = runtime or lease_runtime(primary) + rules, policy = contract(runtime), manifest_policy(primary) + trees, continuity, base = worktrees(primary), continuity_times(primary), web_url(primary) + entries = [] + for path, lease in leases(primary, rules): + ticket = str(lease.get("ticketId", path.stem.split("--")[0])) + phase = str(lease.get("phase", "unknown")) + if phase in rules["terminal"]: + continue + tree = trees.get(str(lease.get("branchRef"))) + record = canonical_layout(primary, path, lease, tree, rules) + activity = {"heartbeat": utc(lease.get("heartbeatAt")), "continuity": continuity.get(ticket)} + dirty, pids = [], [] + if tree and Path(tree["path"]).is_dir(): + worktree = Path(tree["path"]) + activity["commit"] = utc(git(worktree, "log", "-1", "--format=%cI", check=False)) + dirty = dirty_paths(worktree) + times = [(worktree / item).stat().st_mtime for item in dirty if (worktree / item).is_file()] + activity["dirtyFile"] = datetime.fromtimestamp(max(times), timezone.utc) if times else None + pids = live_processes(worktree) + known = {key: value for key, value in activity.items() if value} + source, last = max(known.items(), key=lambda item: item[1]) if known else (None, None) + invalid = bool(runtime.validate_lease(lease)) if lease else True + entries.append({ + "ticket": ticket, + "state": classify(lease, phase, invalid, record, tree, dirty, pids, last, now, policy, rules, primary), + "ownerActor": lease.get("ownerActor"), "ownerSession": lease.get("ownerSession"), "phase": phase, + "leaseRevision": lease.get("leaseRevision"), "fencingToken": lease.get("fencingToken"), + "leasePath": str(path), "worktree": tree["path"] if tree else None, + "canonicalWorktree": record["worktreePath"], "layoutProblems": record["problems"], + "branchRef": lease.get("branchRef"), "lastActivityAt": stamp(last) if last else None, + "lastActivitySource": source, "idleMinutes": int((now - last).total_seconds() // 60) if last else None, + "livePids": pids, "dirtyPaths": dirty[:50], "dirtyCount": len(dirty), + "links": links(base, lease.get("branchRef"), ticket, lease.get("pullRequest")), + }) + entries.sort(key=lambda item: (item["state"], item["idleMinutes"] if item["idleMinutes"] is not None else -1)) + return {"schema": BOARD_SCHEMA, "observedAt": stamp(now), "primaryCheckout": str(primary), + "worktreesRoot": str(primary / rules["WORKTREES_ROOT"]), "leaseRoot": str(primary / rules["LEASE_ROOT"]), + "project": base, "issues": f"{base}/{FORGE_PATHS['issues']}" if base else None, + "pullRequests": f"{base}/{FORGE_PATHS['pulls']}" if base else None, "policy": policy, + "grantsAuthority": False, "tickets": entries} + + +BACKGROUND_STATES = {"IDLE_NO_WORKTREE", "INVALID_LEASE", "IDLE_INTEGRATED", "NONCANONICAL_LAYOUT"} + + +def board_markdown(board: dict[str, Any]) -> str: + def link(label: str, url: str | None) -> str: + return f"[{label}]({url})" if url else "-" + primary = Path(board["primaryCheckout"]) + def local(path: str | None) -> str: + return f"`{Path(path).relative_to(primary)}`" if path and Path(path).is_relative_to(primary) else (f"`{path}`" if path else "-") + policy = board["policy"] + rule = (f"Idle takeover after {policy['idleMinutes']} min (from `{policy['source']}`)." if policy["enabled"] + else f"Idle takeover disabled (`coordination.idleTakeover` in `{policy['source']}`).") + lines = [ + "# Autonomy board", "", + f"Observed {board['observedAt']} in `{board['primaryCheckout']}`. {rule} Advisory state; it grants no authority.", "", + f"Project: {link('repository', board['project'])} · {link('pull requests', board['pullRequests'])} · {link('issues', board['issues'])}", "", + f"Worktrees: `{board['worktreesRoot']}` · leases: `{board['leaseRoot']}` (wellmanifest/worktrees v5). " + "Work only in the worktree a lease names; never create one by hand.", "", + "| Ticket | State | Owner | Phase | Idle | Last activity | Dirty | Worktree | Links |", + "| --- | --- | --- | --- | --- | --- | --- | --- | --- |", + ] + background = [item for item in board["tickets"] if item["state"] in BACKGROUND_STATES] + for item in (item for item in board["tickets"] if item["state"] not in BACKGROUND_STATES): + idle = "-" if item["idleMinutes"] is None else f"{item['idleMinutes']} min" + refs = " · ".join(link(name, item["links"][key]) for name, key in + (("branch", "branch"), ("README", "readme"), ("PR", "pullRequest"))) + lines.append(f"| {item['ticket']} | {item['state']} | {item['ownerActor']} | {item['phase']} | {idle} " + f"| {item['lastActivitySource'] or '-'} | {item['dirtyCount']} | {local(item['worktree'])} | {refs} |") + if background: + lines += ["", f"{len(background)} further leases are integrated, have no ticket worktree, break the worktree " + "layout or fail the pinned lease contract: " + + ", ".join(f"{item['ticket']} ({item['state']}, {item['ownerActor']})" for item in background[:40]) + + (" …" if len(background) > 40 else "") + ". Reconcile them; they are never taken over automatically."] + eligible = [item for item in board["tickets"] if item["state"] == "IDLE_TAKEOVER_ELIGIBLE"] + if eligible: + lines += ["", "## Takeover candidates", ""] + lines += [f"- `{item['ticket']}` in {local(item['worktree'])}: `python3 .governance/idle_takeover.py takeover " + f"--ticket {item['ticket']} --actor --session `" for item in eligible] + return "\n".join(lines) + "\n" + + +def sync_directory(path: Path) -> None: + """Persist rename/creation ordering where directory fsync is supported.""" + if os.name == "posix": + descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY) + try: + os.fsync(descriptor) + finally: + os.close(descriptor) + + +def write_atomic(path: Path, data: bytes) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp") + created = False + try: + with temporary.open("xb") as handle: + created = True + handle.write(data) + handle.flush() + os.fsync(handle.fileno()) + os.replace(temporary, path) + sync_directory(path.parent) + finally: + # A failed exclusive open must not remove an existing attempt's file. + if created: + try: + temporary.unlink() + except FileNotFoundError: + pass # Successful replacement already consumed the temporary. + + +@contextmanager +def lease_lock(lease_path: Path): + """Serialize every idle-takeover transition of one lease; a held lock refuses, never waits.""" + if any(p.is_symlink() for p in (lease_path, *lease_path.parents)): + raise PermissionError("Symlinked lease path is unsafe; preserve and reconcile.") + lease_path.parent.mkdir(parents=True, exist_ok=True) + lock = lease_path.with_name(lease_path.name + ".lock") + flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) + try: + descriptor = os.open(lock, flags, 0o600) + except OSError as error: + raise PermissionError("Unsafe lease lock file; preserve and reconcile.") from error + try: + info = os.fstat(descriptor) + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1: + raise PermissionError("Unsafe lease lock file; preserve and reconcile.") + try: + if fcntl: + fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) + else: # pragma: no cover - Windows + msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1) + except OSError as error: + raise PermissionError("Another transition holds this lease; re-observe.") from error + named = os.stat(lock, follow_symlinks=False) + if not stat.S_ISREG(named.st_mode) or (named.st_dev, named.st_ino) != (info.st_dev, info.st_ino): + raise PermissionError("Lease lock changed during acquisition; re-observe.") + yield + finally: + os.close(descriptor) + + +def write_board(board: dict[str, Any]) -> Path: + directory = Path(board["primaryCheckout"]) / BOARD_DIR + write_atomic(directory / "autonomy-board.json", (json.dumps(board, indent=2, sort_keys=True) + "\n").encode()) + write_atomic(directory / "autonomy-board.md", board_markdown(board).encode()) + return directory / "autonomy-board.md" + + +def file_identity(path: Path) -> tuple[int, int, int, int]: + status = path.stat() + return status.st_dev, status.st_ino, status.st_size, status.st_mtime_ns + + +def snapshot(primary: Path, entry: dict[str, Any]) -> dict[str, Any] | None: + """Content-addressed tar of the dirty files plus the tracked diff; the worktree stays untouched.""" + if not entry["dirtyCount"]: + return None + worktree = Path(entry["worktree"]) + buffer, total = io.BytesIO(), 0 + with tarfile.open(fileobj=buffer, mode="w", format=tarfile.PAX_FORMAT) as archive: + def add(name: str, data: bytes) -> None: + nonlocal total + total += len(data) + if total > MAX_SNAPSHOT_BYTES: + raise ValueError("Dirty work exceeds the bounded snapshot size; hand off instead.") + info = tarfile.TarInfo(name) + info.size, info.mtime, info.mode = len(data), 0, 0o644 + archive.addfile(info, io.BytesIO(data)) + diff = subprocess.run(["git", "-C", str(worktree), "diff", "--binary", "HEAD"], capture_output=True, check=True).stdout + add("tracked.diff", diff) + for item in dirty_paths(worktree): + path = worktree / item + if path.is_file() and not path.is_symlink(): + data = path.read_bytes() + add("files/" + item, data) + data = buffer.getvalue() + if len(data) > MAX_SNAPSHOT_BYTES: + raise ValueError("Dirty work exceeds the bounded snapshot size; hand off instead.") + digest = hashlib.sha256(data).hexdigest() + target = primary / SNAPSHOT_DIR / entry["ticket"] / f"{digest}.tar" + if not target.exists(): + write_atomic(target, data) + return {"ref": f"snapshot:idle-takeover/{entry['ticket']}/{digest}", "sha256": digest, + "path": str(target), "paths": entry["dirtyPaths"], "headSha": git(worktree, "rev-parse", "HEAD")} + + +def takeover(root: Path, ticket: str, actor: str, session: str, now: datetime | None = None) -> dict[str, Any]: + if not TICKET_RE.fullmatch(ticket) or not IDENTITY_RE.fullmatch(actor) or not IDENTITY_RE.fullmatch(session): + raise ValueError("Exact ticket, actor and session identities are required.") + runtime = lease_runtime(primary_checkout(root)) + now = now or datetime.now(timezone.utc) + board = observe(root, now, runtime) + write_board(board) + entry = next((item for item in board["tickets"] if item["ticket"] == ticket), None) + if entry is None: + raise PermissionError(f"{ticket} is NO_LIVE_LEASE; idle takeover needs IDLE_TAKEOVER_ELIGIBLE.") + with lease_lock(Path(entry["leasePath"])): + # Decide again under the lock: the first observation only located the lease. + return locked_takeover(root, ticket, actor, session, now, runtime, _lock_held=True) + + +def locked_takeover( + root: Path, + ticket: str, + actor: str, + session: str, + now: datetime, + runtime, + *, + _lock_held: bool = False, +) -> dict[str, Any]: + if not _lock_held: + board = observe(root, now, runtime) + entry = next((item for item in board["tickets"] if item["ticket"] == ticket), None) + if entry is None: + raise PermissionError(f"{ticket} is NO_LIVE_LEASE; idle takeover needs IDLE_TAKEOVER_ELIGIBLE.") + with lease_lock(Path(entry["leasePath"])): + return locked_takeover(root, ticket, actor, session, now, runtime, _lock_held=True) + board = observe(root, now, runtime) + entry = next((item for item in board["tickets"] if item["ticket"] == ticket), None) + if entry is None or entry["state"] != "IDLE_TAKEOVER_ELIGIBLE": + state = entry["state"] if entry else "NO_LIVE_LEASE" + raise PermissionError(f"{ticket} is {state}; idle takeover needs IDLE_TAKEOVER_ELIGIBLE.") + if entry["ownerActor"] == actor and entry["ownerSession"] == session: + raise PermissionError(f"{ticket} is already held by this session; heartbeat instead of taking over.") + primary, lease_path = Path(board["primaryCheckout"]), Path(entry["leasePath"]) + original, identity = lease_path.read_bytes(), file_identity(lease_path) + lease = json.loads(original) + snap = snapshot(primary, entry) + authority = (f"policy:{SCHEMA};idleMinutes={entry['idleMinutes']};limit={board['policy']['idleMinutes']};" + f"lastActivity={entry['lastActivityAt']}" + (f";snapshot={snap['sha256']}" if snap else "")) + receipts, current, sequence = [], dict(lease), int(lease.get("eventSequence", 0)) + for action in (["expire"] if current["phase"] != "expired" else []) + ["release"]: + request = {"schema": runtime.REQUEST_SCHEMA, "requestId": f"idle-takeover-{action}-{stamp(now)}", + "leaseId": current["leaseId"], "action": action, "expectedRevision": current["leaseRevision"], + "expectedFencingToken": current["fencingToken"], "expectedPhase": current["phase"], + "requestedBy": actor, "idempotencyKey": f"{ticket}:{current['fencingToken']}:{action}", + "targetHeadSha": None, "replacementReceiptRef": None, "authorityRef": authority, + "requestedAt": stamp(now)} + receipt, errors = runtime.evaluate_transition(current, request) + if errors: + raise PermissionError(f"{action} rejected: {errors[0]['code']} {errors[0]['message']}") + receipts.append(receipt) + sequence += 1 + current.update(phase=receipt["phaseAfter"], leaseRevision=receipt["leaseRevision"], + fencingToken=receipt["fencingToken"], previousReceiptRef=receipt["receiptRef"], eventSequence=sequence) + worktree = Path(entry["worktree"]) + claimed = dict(current, ownerActor=actor, ownerSession=session, phase="claimed", + leaseRevision=current["leaseRevision"] + 1, fencingToken=current["fencingToken"] + 1, + issuedAt=stamp(now), heartbeatAt=stamp(now), + expiresAt=stamp(now + timedelta(minutes=board["policy"]["leaseMinutes"])), + headSha=git(worktree, "rev-parse", "HEAD"), eventSequence=sequence + 1) + errors = runtime.validate_lease(claimed) + if errors: + raise ValueError(f"Claimed lease is invalid: {errors[0]['message']}") + # wellmanifest/worktrees rules 9-10: a machine-readable result names the exact + # ticket, branch, worktree and lease; the agent takes its paths only from here. + record = {"schema": SCHEMA, "ticket": ticket, "takenOverAt": stamp(now), + "branch": entry["branchRef"].removeprefix("refs/heads/"), "worktreePath": str(worktree), + "leasePath": str(lease_path), + "writerEnvironment": {"NEW_PROJECT_WRITER_ACTOR": actor, "NEW_PROJECT_WRITER_SESSION": session, + "NEW_PROJECT_LEASE_REVISION": str(claimed["leaseRevision"]), + "NEW_PROJECT_FENCING_TOKEN": str(claimed["fencingToken"])}, + "previousOwner": {"actor": lease["ownerActor"], "session": lease["ownerSession"], + "leaseRevision": lease["leaseRevision"], "fencingToken": lease["fencingToken"]}, + "newOwner": {"actor": actor, "session": session, "leaseRevision": claimed["leaseRevision"], + "fencingToken": claimed["fencingToken"]}, + "idle": {"minutes": entry["idleMinutes"], "lastActivityAt": entry["lastActivityAt"], + "source": entry["lastActivitySource"]}, + "authorityRef": authority, "snapshot": snap, "receipts": receipts} + # Compare-and-swap under the lease lock, immediately before the receipt and + # the replacement; the fencing token rejects any writer that bypassed the lock. + if lease_path.read_bytes() != original or file_identity(lease_path) != identity: + raise PermissionError("Lease changed during takeover (compare-and-swap lost); re-observe.") + trace = primary / RECEIPT_DIR / f"{ticket}.jsonl" + claimed_bytes = (json.dumps(claimed, indent=2, sort_keys=True) + "\n").encode() + prepared = {"schema": "new-project.idle-takeover-prepare/v1", "state": "prepared", + "grantsAuthority": False, "beforeSha256": hashlib.sha256(original).hexdigest(), + "afterSha256": hashlib.sha256(claimed_bytes).hexdigest(), + "lease": claimed, "record": record} + prepared_bytes = (json.dumps(prepared, sort_keys=True) + "\n").encode() + digest = hashlib.sha256(prepared_bytes).hexdigest() + pending = trace.with_name(f"{ticket}.{digest}.prepared.json") + if pending.exists(): + if pending.read_bytes() != prepared_bytes: + raise PermissionError("Prepared handoff changed; preserve it and reconcile.") + else: + write_atomic(pending, prepared_bytes) + # Preparing recovery data is an I/O boundary: re-verify idle eligibility and + # compare the original lease again under lease_lock immediately before replacement. + # Prepared data grants no authority. + latest_board = observe(root, now, runtime) + latest_entry = next((item for item in latest_board["tickets"] if item["ticket"] == ticket), None) + if ( + latest_entry is None + or latest_entry["state"] != "IDLE_TAKEOVER_ELIGIBLE" + or Path(latest_entry["leasePath"]) != lease_path + or git(worktree, "rev-parse", "HEAD") != claimed["headSha"] + or lease_path.is_symlink() + or lease_path.read_bytes() != original + or file_identity(lease_path) != identity + ): + raise PermissionError("Lease changed while preparing takeover (compare-and-swap lost); re-observe.") + write_atomic(lease_path, claimed_bytes) + if lease_path.read_bytes() != claimed_bytes: + raise PermissionError("Replaced lease changed; preserve prepared recovery data and reconcile.") + # Publish success only after the matching lease is applied. If append fails, + # the prepared record binds both hashes for explicit controller recovery. + with trace.open("a", encoding="utf-8") as handle: + handle.write(json.dumps(record, sort_keys=True) + "\n") + handle.flush() + os.fsync(handle.fileno()) + sync_directory(trace.parent) + try: + pending.unlink() + except OSError: + pass # Final lease and success trace are committed; stale prepare is harmless. + record["board"] = str(write_board(observe(root, now, runtime))) + return record + + +def continue_local_lease(root: Path, request_path: Path, actor: str, session: str, + *, recover: bool, now: datetime | None = None) -> dict[str, Any]: + """Explicit local controller effects; never infer ownership from a snapshot.""" + if not IDENTITY_RE.fullmatch(actor) or not IDENTITY_RE.fullmatch(session): + raise ValueError("Explicit actor and session required") + primary = primary_checkout(root) + restoration = pinned_module(primary, "ticket_restoration.py") + anchored = pinned_module(primary, "terminal_lease_release.py") + runtime = lease_runtime(primary) + now = now or datetime.now(timezone.utc) + moment = now.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + def require(condition, message): + if not condition: + raise PermissionError(message) + def restoration_call(callback, *args, **kwargs): + try: + return callback(*args, **kwargs) + except restoration.recovery.RecoveryError as error: + raise PermissionError(str(error)) from error + request_path = restoration_call(restoration.safe, request_path) + request = anchored.read_path(request_path) + common_fields = {"schema", "requestId"} + fields = common_fields | ({"workstream", "restoration"} if recover else + {"ticket", "reservationSha256", "leaseRevision", "fencingToken"}) + schema = "new-project.expired-reservation-recovery/v1" if recover else "new-project.owner-lease-checkpoint/v1" + require(isinstance(request, dict) and set(request) == fields and request["schema"] == schema, + "Invalid lease continuation request") + require(isinstance(request["requestId"], str) and re.fullmatch(r"[a-z0-9][a-z0-9.-]{0,95}", request["requestId"]), + "Unsafe request identity") + if recover: + subject = request["restoration"] + restoration_call(restoration.validate_request, subject, request["workstream"], local=True) + snapshot_path = restoration_call(restoration.safe, subject["snapshotPath"]) + require(not any(snapshot_path.is_relative_to(Path(e["worktree"]).resolve()) + for e in restoration.start.worktrees(primary)), "Snapshot must be outside checkouts") + files, intent = restoration_call(restoration.load_snapshot, subject, request["workstream"]) + ticket, worktree_id = subject["ticket"], subject["worktreeId"] + else: + ticket, worktree_id = request["ticket"], root.resolve().name + require(isinstance(ticket, str) and TICKET_RE.fullmatch(ticket) + and worktree_id.startswith(ticket + "--"), "Checkpoint must run in the canonical owned checkout") + require(all(type(request[k]) is int and request[k] > 0 for k in ("leaseRevision", "fencingToken")) + and isinstance(request["reservationSha256"], str) + and re.fullmatch(r"[0-9a-f]{64}", request["reservationSha256"]), "Invalid checkpoint CAS") + subject = request + files = intent = None + path = primary / ".subactor/leases" / (worktree_id + ".json") + require(not request_path.is_relative_to(primary), "Request must be outside the repository") + digest = hashlib.sha256(json.dumps({"request": request, "actor": actor, "session": session}, + sort_keys=True).encode()).hexdigest() + receipt_dir = primary / ".subactor/receipts/lease-continuation" + name = request["requestId"] + ".json" + with anchored.directory(path.parent) as (fd, verify): + with anchored.lease_lock(fd, path.name, verify) as verify_lock: + original = anchored.read_at(fd, path.name, private=True) + require(os.stat(path.name, dir_fd=fd, follow_symlinks=False).st_uid == os.geteuid(), + "Lease belongs to another OS owner") + lease = json.loads(original, object_pairs_hook=restoration.unique) + require(not runtime.validate_lease(lease), "Invalid canonical lease") + with anchored.directory(receipt_dir, create=True) as (receipt_fd, verify_receipts): + def read_optional(filename): + try: + return anchored.decode(anchored.read_at(receipt_fd, filename)) + except FileNotFoundError: + return None + saved = read_optional(name) or read_optional(name + ".prepared") + if saved is not None: + require(saved.get("requestSha256") == digest, "Request identity was reused for different inputs") + if hashlib.sha256(original).hexdigest() == saved.get("afterSha256"): + expected_environment = {"NEW_PROJECT_WRITER_ACTOR": actor, "NEW_PROJECT_WRITER_SESSION": session, + "NEW_PROJECT_LEASE_REVISION": str(lease["leaseRevision"]), + "NEW_PROJECT_FENCING_TOKEN": str(lease["fencingToken"])} + require((lease["ownerActor"], lease["ownerSession"]) == (actor, session) + and utc(lease["expiresAt"]) > now and not lease["publicationFrozen"] + and lease["phase"] in {"claimed", "editing", "validating"} + and saved["result"]["writerEnvironment"] == expected_environment + and saved["result"]["leaseRevision"] == lease["leaseRevision"] + and saved["result"]["fencingToken"] == lease["fencingToken"] + and saved["result"]["grantsEditAuthority"] is False + and saved["result"]["grantsMergeAuthority"] is False, + "Saved continuation no longer binds a live owner") + if recover: + expected_request = {**subject, "ownerActor": actor, "ownerSession": session, + "headSha": lease["headSha"], "leaseRevision": lease["leaseRevision"], + "fencingToken": lease["fencingToken"], + "reservationSha256": hashlib.sha256(original).hexdigest()} + require(saved["result"]["restorationRequest"] == expected_request, + "Saved restoration request changed") + if read_optional(name) is None: + verify_lock(); verify_receipts() + anchored.atomic_at(receipt_fd, name, anchored.encoded(saved), exclusive=True) + return saved["result"] + require(hashlib.sha256(original).hexdigest() == saved.get("beforeSha256"), + "Prepared continuation no longer matches current fencing") + + def observe_before_write(): + verify_lock(); verify_receipts() + require(anchored.read_at(fd, path.name, private=True) == original, "Lease CAS changed") + require(hashlib.sha256(original).hexdigest() == subject["reservationSha256"] + and lease["leaseRevision"] == subject["leaseRevision"] + and lease["fencingToken"] == subject["fencingToken"], "Lease digest or CAS mismatch") + require(lease["ticketId"] == ticket and lease["worktreeId"] == worktree_id, + "Reservation identity mismatch") + repo = anchored.canonical.canonical_owner_repository( + git(primary, "config", "--get", "remote.origin.url", check=False)) + legacy = "local/" + hashlib.sha256(str(primary).encode()).hexdigest() + require(lease["repositoryRef"] in {repo, legacy}, "Repository binding mismatch") + phases = {"claimed", "editing", "validating", "expired"} if recover else {"claimed", "editing", "validating"} + require(lease["phase"] in phases + and not lease["publicationFrozen"], "Frozen or inactive lease") + issued, heartbeat, expiry = (utc(lease[key]) for key in ("issuedAt", "heartbeatAt", "expiresAt")) + require(all((issued, heartbeat, expiry)) and issued <= heartbeat < expiry, + "Invalid lease clock bounds") + if recover: + require(os.name == "posix" and Path("/proc/self/cwd").is_symlink(), + "Missing-checkout recovery requires observable Linux processes") + board = observe(primary, now, runtime) + entry = next((e for e in board["tickets"] if e["ticket"] == ticket), None) + require(entry is not None and entry["state"] == "IDLE_NO_WORKTREE" + and board["policy"]["enabled"] and expiry <= now, + "Recovery requires an expired, idle, missing reservation under enabled policy") + require((actor, session) != (lease["ownerActor"], lease["ownerSession"]), + "A fresh handoff identity is required") + common = Path(git(primary, "rev-parse", "--path-format=absolute", "--git-common-dir")) + record = restoration_call(restoration.reservation, primary, common, subject, request["workstream"]) + require(record == lease and lease["leaseId"] == subject["leaseId"] + and lease["scopeHash"] == restoration.start.digest(intent["allowedPaths"]), + "Snapshot scope or reservation changed") + state = restoration_call(restoration.observe, primary, subject, record, files, intent) + require(not state["registered"] and state["branchHead"] is None and not state["committed"], + "Recovery does not replace existing branches, checkouts or integrated metadata") + require(not live_processes(state["canonical"], include_callers=True), + "A live writer still uses the missing checkout") + require(lease["pullRequest"] is None and lease["validatorRunId"] is None, + "Publication ownership requires its protected controller") + return state["target"], board["policy"]["leaseMinutes"] + require((actor, session) == (lease["ownerActor"], lease["ownerSession"]) + and heartbeat <= now < expiry, "Current live owner required") + expected = primary / ".worktrees" / worktree_id + require(root.resolve() == expected and not root.is_symlink() + and git(root, "symbolic-ref", "--quiet", "HEAD") == lease["branchRef"], + "Checkpoint must bind the canonical owned branch") + return git(root, "rev-parse", "HEAD"), None + + head, minutes = observe_before_write() + current, receipts = dict(lease), [] + actions = (["expire"] if lease["phase"] != "expired" else []) + ["release"] if recover else ["heartbeat"] + for action in actions: + transition = {"schema": runtime.REQUEST_SCHEMA, "requestId": request["requestId"] + "-" + action, + "leaseId": current["leaseId"], "action": action, + "expectedRevision": current["leaseRevision"], "expectedFencingToken": current["fencingToken"], + "expectedPhase": current["phase"], "requestedBy": actor, + "idempotencyKey": request["requestId"] + ":" + action, + "targetHeadSha": head if not recover else None, "replacementReceiptRef": None, + "authorityRef": "policy:explicit-local-lease-continuation;request=" + digest, + "requestedAt": moment} + receipt, errors = runtime.evaluate_transition(current, transition) + require(not errors, "Canonical lease transition refused") + receipts.append(receipt) + current.update(phase=receipt["phaseAfter"], leaseRevision=receipt["leaseRevision"], + fencingToken=receipt["fencingToken"], previousReceiptRef=receipt["receiptRef"], + eventSequence=current["eventSequence"] + 1) + current.update(headSha=head, heartbeatAt=moment) + if recover: + current.update(ownerActor=actor, ownerSession=session, phase="claimed", issuedAt=moment, + expiresAt=(now + timedelta(minutes=minutes)).isoformat().replace("+00:00", "Z"), + leaseRevision=current["leaseRevision"] + 1, fencingToken=current["fencingToken"] + 1, + eventSequence=current["eventSequence"] + 1) + require(not runtime.validate_lease(current), "Invalid continued lease") + replacement = anchored.encoded(current) + result = {"schema": "new-project.lease-continuation/v1", "ticket": ticket, + "branch": lease["branchRef"].removeprefix("refs/heads/"), + "worktreePath": str(primary / ".worktrees" / worktree_id), "leasePath": str(path), + "headSha": head, "leaseRevision": current["leaseRevision"], "fencingToken": current["fencingToken"], + "writerEnvironment": {"NEW_PROJECT_WRITER_ACTOR": actor, "NEW_PROJECT_WRITER_SESSION": session, + "NEW_PROJECT_LEASE_REVISION": str(current["leaseRevision"]), + "NEW_PROJECT_FENCING_TOKEN": str(current["fencingToken"])}, + "grantsEditAuthority": False, "grantsMergeAuthority": False, "receipts": receipts} + if recover: + result["restorationRequest"] = {**subject, "ownerActor": actor, "ownerSession": session, + "headSha": head, "leaseRevision": current["leaseRevision"], + "fencingToken": current["fencingToken"], + "reservationSha256": hashlib.sha256(replacement).hexdigest()} + prepared = {"schema": "new-project.lease-continuation-prepare/v1", "requestSha256": digest, + "beforeSha256": hashlib.sha256(original).hexdigest(), + "afterSha256": hashlib.sha256(replacement).hexdigest(), "result": result} + raw = anchored.encoded(prepared) + if saved is None: + anchored.atomic_at(receipt_fd, name + ".prepared", raw, exclusive=True) + else: + require(saved == prepared, "Prepared result diverged") + require(observe_before_write()[0] == head, "HEAD changed while preparing continuation") + anchored.atomic_at(fd, path.name, replacement) + require(anchored.read_at(fd, path.name, private=True) == replacement, "Applied continuation changed") + verify_receipts(); verify_lock() + anchored.atomic_at(receipt_fd, name, raw, exclusive=True) + return result + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + parser.add_argument("--root", type=Path, default=Path(".")) + commands = parser.add_subparsers(dest="command", required=True) + show = commands.add_parser("observe", help="classify ticket leases and rewrite the autonomy board") + show.add_argument("--format", choices=("json", "md"), default="md") + show.add_argument("--no-write", action="store_true", help="print only; do not rewrite the board") + take = commands.add_parser("takeover", help="take over an IDLE_TAKEOVER_ELIGIBLE ticket") + take.add_argument("--ticket", required=True) + take.add_argument("--actor", required=True) + take.add_argument("--session", required=True) + for command in ("recover-reservation", "checkpoint-owner"): + operation = commands.add_parser(command, help="explicit CAS-bound local lease continuation") + operation.add_argument("--request", type=Path, required=True) + operation.add_argument("--actor", required=True) + operation.add_argument("--session", required=True) + args = parser.parse_args(argv) + try: + if args.command == "observe": + board = observe(args.root) + if not args.no_write: + write_board(board) + sys.stdout.write(json.dumps(board, indent=2) + "\n" if args.format == "json" else board_markdown(board)) + return 0 + if args.command == "takeover": + record = takeover(args.root, args.ticket, args.actor, args.session) + else: + record = continue_local_lease(args.root, args.request, args.actor, args.session, + recover=args.command == "recover-reservation") + sys.stdout.write(json.dumps(record, indent=2, sort_keys=True) + "\n") + return 0 + except PermissionError as error: + sys.stderr.write(f"GOV-IDLE-TAKEOVER-001: {error}\n") + return 1 + except (OSError, ValueError, RuntimeError, KeyError, TypeError, subprocess.CalledProcessError) as error: + sys.stderr.write(f"GOV-IDLE-TAKEOVER-002: {error}\n") + return 2 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.governance/intent.schema.json b/.governance/intent.schema.json index 9bee41c..cfa6a09 100644 --- a/.governance/intent.schema.json +++ b/.governance/intent.schema.json @@ -71,11 +71,11 @@ "description": "Optional HOME vs ADOPT. Fill for SERVICE/FEATURE that create or place a repository. Missing is valid so existing tickets still parse; invalid values reject. runtime_service must not HOME wellmanifest.", "properties": { "home": { - "enum": ["wellmanifest", "subactor", "semcod"], + "enum": ["wellmanifest", "subactor", "semcod", "paxlet-com", "dockuri"], "description": "Org that owns the repository. Not the same as adopt." }, "runtimeOwner": { - "enum": ["wellmanifest", "subactor", "semcod"], + "enum": ["wellmanifest", "subactor", "semcod", "paxlet-com", "dockuri"], "description": "Org that runs the CLI/daemon. Omit to inherit home. wellmanifest does not host product daemons." }, "shape": { diff --git a/.governance/legacy_terminal_retirement.py b/.governance/legacy_terminal_retirement.py new file mode 100755 index 0000000..facf8a3 --- /dev/null +++ b/.governance/legacy_terminal_retirement.py @@ -0,0 +1,196 @@ +#!/usr/bin/env python3 +"""Retire one expired, owner-bound legacy slot after a verified merge. + +Separate opt-in compatibility adapter. The ordinary lease controllers remain +strict. Plan never writes. Apply archives the exact original bytes before +unlinking only the obsolete lease, never a checkout or branch. A normalized +lease is neither written nor used to grant writer or publication authority. + +The closed request extends the existing terminal-owner-release fields with +schema new-project.legacy-terminal-retirement/v1, legacyRepositoryRef (the bare +old label) and canonicalRepositoryRef (OWNER/REPO). Apply requires the existing +NEW_PROJECT_WRITER_ACTOR and NEW_PROJECT_WRITER_SESSION owner context. +""" +import argparse +import base64 +from datetime import datetime, timezone +import importlib.util +import json +import os +from pathlib import Path +import stat +import sys + + +def _controller(): + spec = importlib.util.spec_from_file_location( + '_legacy_terminal_controller', Path(__file__).with_name('terminal_lease_release.py')) + value = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = value + spec.loader.exec_module(value) + return value + + +release = _controller() +SCHEMA = 'new-project.legacy-terminal-retirement/v1' +FIELDS = release.FIELDS | {'legacyRepositoryRef', 'canonicalRepositoryRef'} +JOURNAL_FIELDS = {'schema', 'request', 'original', 'identity', 'terminal', 'stamp'} +PHASES = {'claimed', 'editing', 'validating', 'merged', 'closed'} + + +def _request(request): + release.require(isinstance(request, dict) and set(request) == FIELDS + and request['schema'] == SCHEMA, 'invalid_legacy_request') + projected = {k: request[k] for k in release.FIELDS} + projected['schema'] = release.REQUEST_SCHEMA + release.request_identity(projected) + return projected + + +def _origin(root, request): + remote = release.git(root, 'config', '--get', 'remote.origin.url') + canonical = release.canonical.canonical_owner_repository(remote) + release.require(canonical is not None and canonical == request['canonicalRepositoryRef'], + 'repository_identity_mismatch') + label = canonical.split('/')[1] + release.require(root.name == request['legacyRepositoryRef'] == label, + 'legacy_repository_label_mismatch') + + +def _original(raw, root, request, projected): + release.require(len(raw) <= release.canonical.MAX_LEASE_BYTES, 'legacy_lease_exceeds_bound') + release.require(release.sha(raw) == request['expectedLeaseSha256'], 'lease_compare_and_swap_lost') + lease = release.decode(raw) + release.require(isinstance(lease, dict) + and lease.get('repositoryRef') == request['legacyRepositoryRef'], + 'legacy_repository_label_mismatch') + # Shape validation only: this temporary view is never a persisted lease. + shape = dict(lease, repositoryRef=request['canonicalRepositoryRef']) + release.require(not release.canonical.validate_lease(shape), 'invalid_legacy_lease') + ticket, branch = release.request_identity(projected) + release.require(lease['ticketId'] == ticket and lease['worktreeId'] == request['worktreeId'] + and lease['branchRef'] == branch, 'lease_scope_mismatch') + release.require(lease['ownerActor'] == request['ownerActor'] + and lease['ownerSession'] == request['ownerSession'], 'current_owner_mismatch') + release.require(lease['leaseRevision'] == request['expectedRevision'] + and lease['fencingToken'] == request['expectedFencingToken'], + 'lease_compare_and_swap_lost') + release.require(lease['phase'] in PHASES and not lease['publicationFrozen'], + 'legacy_phase_not_retireable') + expiry = datetime.fromisoformat(lease['expiresAt'].replace('Z', '+00:00').replace('z', '+00:00')) + release.require(expiry <= datetime.now(timezone.utc), 'legacy_lease_still_live') + receipt = release._verify_terminal(root, projected, lease) + release.require(receipt['outcome'] == 'merged', 'verified_merge_required') + return receipt + + +def _identity(fd, name): + info = os.stat(name, dir_fd=fd, follow_symlinks=False) + release.require(stat.S_ISREG(info.st_mode) and info.st_nlink == 1, 'regular_private_file_required') + # A filesystem can immediately recycle an unlinked inode. Bind the inode's + # change timestamp too, so a recreated byte-identical slot is not replayed. + return {'device': info.st_dev, 'inode': info.st_ino, 'changedAtNs': info.st_ctime_ns} + + +def _read_slot(fd, name): + identity = _identity(fd, name) + raw = release.read_at(fd, name, release.canonical.MAX_LEASE_BYTES, private=True) + release.require(_identity(fd, name) == identity, 'lease_compare_and_swap_lost') + return raw, identity + + +def _unlink_slot(fd, name): + os.unlink(name, dir_fd=fd) + os.fsync(fd) + + +def _execute(root, request, projected, fd, verify, name, apply): + journal_path = (root / '.subactor/receipts/legacy-terminal-retirement' + / (release.sha(release.encoded(request)) + '.json')) + if os.path.lexists(journal_path): + journal = release.read_path(journal_path) + release.require(isinstance(journal, dict) and set(journal) == JOURNAL_FIELDS + and journal['schema'] == SCHEMA and journal['request'] == request, + 'journal_request_mismatch') + original = base64.b64decode(journal['original'], validate=True) + terminal = _original(original, root, request, projected) + release.require(journal['terminal'] == terminal, 'journal_terminal_mismatch') + identity = journal['identity'] + release.require(isinstance(identity, dict) + and set(identity) == {'device', 'inode', 'changedAtNs'} + and all(type(v) is int and v >= 0 for v in identity.values()), + 'journal_identity_mismatch') + try: + raw, observed = _read_slot(fd, name) + except FileNotFoundError: + verify() + return {'status': 'idempotent', 'grantsAuthority': False, 'receipt': str(journal_path)} + release.require(raw == original and observed == identity, 'lease_compare_and_swap_lost') + else: + original, identity = _read_slot(fd, name) + terminal = _original(original, root, request, projected) + journal = {'schema': SCHEMA, 'request': request, + 'original': base64.b64encode(original).decode(), 'identity': identity, + 'terminal': terminal, 'stamp': datetime.now(timezone.utc).isoformat()} + verify() + _origin(root, request) + release.require(_read_slot(fd, name) == (original, identity), 'lease_compare_and_swap_lost') + if not apply: + return {'status': 'planned', 'grantsAuthority': False, + 'actions': ['archive-original', 'retire-expired-slot'], + 'worktreeCleanup': 'separate_controller_required'} + with release.directory(journal_path.parent, create=True) as (journal_fd, verify_journal): + try: + release.atomic_at(journal_fd, journal_path.name, release.encoded(journal), exclusive=True) + except FileExistsError: + release.require(release.read_at(journal_fd, journal_path.name) == release.encoded(journal), + 'journal_changed') + verify_journal() + verify() + _origin(root, request) + release.require(_read_slot(fd, name) == (original, identity), 'lease_compare_and_swap_lost') + _unlink_slot(fd, name) + verify() + return {'status': 'retired', 'grantsAuthority': False, 'receipt': str(journal_path), + 'originalSha256': release.sha(original), 'worktreeCleanup': 'separate_controller_required'} + + +def retire_owner(root, request, *, apply=False, actor=None, session=None): + projected = _request(request) + if apply: + release.require(actor == request['ownerActor'] and session == request['ownerSession'], + 'invoking_owner_context_required') + root, policy, config = release._controller_root(root) + _origin(root, request) + with release.directory(root / '.subactor/leases') as (fd, verify_directory): + def verify(): + verify_directory() + release.require(release.read_path(policy) == config, 'controller_policy_changed') + name = request['worktreeId'] + '.json' + if apply: + with release.lease_lock(fd, name, verify) as verify_lock: + return _execute(root, request, projected, fd, verify_lock, name, True) + return _execute(root, request, projected, fd, verify, name, False) + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', type=Path, default=Path.cwd()) + parser.add_argument('--request', type=Path, required=True) + parser.add_argument('--apply', action='store_true') + args = parser.parse_args(argv) + try: + result = retire_owner(args.root, release.read_path(args.request.absolute()), apply=args.apply, + actor=os.environ.get('NEW_PROJECT_WRITER_ACTOR'), + session=os.environ.get('NEW_PROJECT_WRITER_SESSION')) + print(json.dumps(result)) + return 0 + except (OSError, ValueError, TypeError, KeyError, PermissionError, + release.subprocess.SubprocessError, release.activity.ActivityError): + print('GOV-CHANGE-LEASE-002: legacy terminal retirement refused; preserve the exact ' + 'slot and verify owner, expiry, identity, merged receipt and CAS.', file=sys.stderr) + return 2 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/.governance/managed-copies.json b/.governance/managed-copies.json index 6846100..5fd8b5c 100644 --- a/.governance/managed-copies.json +++ b/.governance/managed-copies.json @@ -1,5 +1,6 @@ { ".governance/docs/BRANCH_INTENT_RECONCILIATION.md": "d17163b016e1ad8cf97408d528bf5a6443e931ea694e97191abc7c1e50586c3b", ".governance/docs/LOCAL_CI_PUBLICATION.md": "001ba246f985ab10d0e4bb70ca18b45a9f3c80b5af70718ec30f6dfecd54bff8", - ".governance/docs/SNAPSHOT_MIGRATION.md": "c73fe642f48e6b1d54b36c9a5f55d2e2a93f8405389533733c26907bd69d6012" + ".governance/docs/SNAPSHOT_MIGRATION.md": "c73fe642f48e6b1d54b36c9a5f55d2e2a93f8405389533733c26907bd69d6012", + ".governance/docs/information/continuity-namespaces.md": "a4dd32fab072d3c609ba6ffb9681425565dca7578e86aa767df4c222e12dac9d" } diff --git a/.governance/manifest.base.json b/.governance/manifest.base.json index 99fde59..c6e097d 100644 --- a/.governance/manifest.base.json +++ b/.governance/manifest.base.json @@ -15,7 +15,6 @@ "integration": { "workstream": "integration" }, - "maxActiveTicketsPerWorkstream": 8, "mode": "workstreams", "rejectActiveScopeOverlap": true }, @@ -133,7 +132,7 @@ "stacks": [], "standard": { "id": "wellmanifest/new-project", - "version": "0.20.92" + "version": "0.20.162" }, "ticket": { "activeStatuses": [ diff --git a/.governance/manifest.json b/.governance/manifest.json index 09a8905..db011b2 100644 --- a/.governance/manifest.json +++ b/.governance/manifest.json @@ -84,7 +84,8 @@ ".gitattributes", "docs/CONTRIBUTING.md", "errors/**", - "pyproject.toml" + "pyproject.toml", + ".github/workflows/new-project-branch-hygiene.yml" ] }, "infrastructure": { @@ -258,7 +259,7 @@ "stacks": [], "standard": { "id": "wellmanifest/new-project", - "version": "0.20.92" + "version": "0.20.162" }, "ticket": { "activeStatuses": [ diff --git a/.governance/manifest.lock.json b/.governance/manifest.lock.json index 201d067..b0f37e6 100644 --- a/.governance/manifest.lock.json +++ b/.governance/manifest.lock.json @@ -2,113 +2,131 @@ "managedFiles": { ".aider.conf.yml": "6de9c74f752e8a879419698531ac575a1f2a3b93efd38a257ac1c48682a26bdd", ".cursor/rules/new-project-standard.mdc": "8884003b3a4470e4677ca5128645f466021432ceb3f018a9f1aa743210f4181d", - ".githooks/commit-msg": "a5479e5960c369b584604b89b3529e8b9fa388f12e1942e873cdf42c4338028e", - ".githooks/pre-commit": "5ff77238cbdc3c09ff6a6d800487a7b01471be7925417eff35fd9eac026996be", + ".githooks/commit-msg": "df3e39f98bfebf971392a66b643163145872ff474d4d7cb01c6e05ed4ceb4199", + ".githooks/pre-commit": "4c68016fe9aa7e2a4ff4f1b7fca6fc1d7382a4e9d3092a1868a2ba1480218f22", + ".githooks/pre-push": "e60a8cfc468c3d3c316e63b5b6f626416716abc718fa221fc2db7ec0a967ef00", ".github/copilot-instructions.md": "08330b67c95c3c175573fe1bec06c21a2f49e6c419164d04980d4f81b4efb8a8", - ".github/workflows/new-project-branch-hygiene.yml": "ee765e68f8a8a2febf468da8301566e0676cffb46fbef0ba96cd756f742a30a2", - ".github/workflows/new-project-governance.yml": "690647944da33aee408b324d7771353f12f9ace9fccc9282e2515f019c09418c", - ".governance/AGENT_DECISIONS.md": "853c5282e44321cd5cd895f41627fc4c5bb98774cd6e726ee1ccf319582f8407", + ".github/workflows/new-project-branch-hygiene.yml": "e51a2dd4b60e79b40a24023310bac50a86b595208eb9502956e7ac5754ba1f7f", + ".github/workflows/new-project-governance.yml": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9", + ".governance/AGENT_DECISIONS.md": "bc511acb758aa7120d06f5f795eae820a02b868adcfef30377312f8c33dbb44a", ".governance/adoption-bindings.json": "9a6015fde26226d4c55764c81c1ab8e8d42fcf64661533a71d90fcc488edaeb3", ".governance/adoption-bindings.schema.json": "0fbad765ca67924b7b3340dcad09f262b62c979740a291da7dacd8e48d28241c", - ".governance/agent-hosts.json": "6204d4c32f11932d7671fad5cd09d8a15b1f38e89e9376145aeb0b32ada8aa51", - ".governance/agent-hosts.schema.json": "2e7ae89edbb4262a5efa43fd52c5a7f0790e0bbb19f5970bc2074e5175c20117", - ".governance/agent_host_check.py": "10abea9ed29e7ffbca6366d4cfb66117ce72793238bb38b32d96f70a47dc295d", + ".governance/agent-hosts.json": "d03e7bd5ed2941311a7917e4b26fd8a5ef38e809611ed2648b0fd3f290dc4d4c", + ".governance/agent-hosts.schema.json": "4cda59d458f774490bada85d1c1b86167e71268cb1a2b8c9bd5126601ddfbb0b", + ".governance/agent_host_check.py": "488e7ad3a65112dc4bb410dcd164d739fff25662621ba6bc166be921e003839e", ".governance/approval-evidence.schema.json": "e0f79eb7bdb534ec17e1a94a56b06a371df14b6f6b9f34db6cf4f8ee059718d5", + ".governance/bootstrap_packaging_scope.py": "614f99feb7ef0e6be5cb6ac3e12ed22c531f6aa6a601266a2cdea1c752f5f706", ".governance/branch-intent-reconciliation.schema.json": "8d770fc7c81884844c3218cc1f18c11ed9c9f7851f2769e040eec676e8ea8006", - ".governance/branch_intent_reconciliation.py": "cf316043eaff77021183d64f5b6f8b291fb0c38b62a9bae7203845a8b35592ca", - ".governance/branch_lifecycle_check.py": "dc562dfad667b809e46aabd7beccf97b30852fa68ee92112f4a8836d8df9802e", - ".governance/change-evaluation.schema.json": "69af6aa537dd3957d9cdc6ff19edb1ac8c8710f798e5255219422547d84fa2d3", - ".governance/change-lease.schema.json": "f9b8eabf4d66ced63fbb1c5d8ae733f88bcf64016c8f9cf101eb4a17533406c6", - ".governance/change_lease_check.py": "5a50656625bf3b606f43afcf2236fb5754ae9de9888c0a248c4cb5f2e328170c", - ".governance/check_required_checks.py": "bcf973ee6221105513feccad98d1dd1c0f9d6c0a92c4303e9c600e3ad15cdec2", + ".governance/branch_intent_reconciliation.py": "752f824d2c4a59d6d30e8c044744ef1d398813519840fe20a97b0fdbefd701bd", + ".governance/branch_lifecycle_check.py": "faf18a9449ed13f805f5442174c3f7b6cf4077e8891670e81800d586b1622daa", + ".governance/change-evaluation.schema.json": "0ac0908b551d0d36ec7007f5b23b888b6d11376ea450aae68068f1b0faa9060b", + ".governance/change-lease.schema.json": "10c65de08424aca0e661ffabd61c3c2877296314f901de583548423650445877", + ".governance/change_lease_check.py": "9c9402194b3ad785f48d7c31b1f9a5cd3257fd97e770ff7442d76e35ea9e0d33", + ".governance/check_required_checks.py": "cb0b3a44b74c7b0fe8888c00ca149c4e680685f605ac7d95992997b6cf12d363", + ".governance/continuity_namespace.py": "79993dbf80dcf55f8804cf24b5b4185de2fafd1320254301d4ca15a63c3351a8", + ".governance/controller_store_compaction.py": "5cad4e84d8fdd2d4998896eff708e9a89477861f5533adebee04d74c0ebcb953", ".governance/decision-record.schema.json": "9300b57ee9c1823adb1b2ddbf0eb86827b270c5ca030a91d69eefbf042e034a9", - ".governance/decision_record.py": "6fccde7e49c5115769a7f94a7c2e10040f1317ac53e322f47a3e68780e73eac1", - ".governance/diagnostics.json": "9c02c12a4f1a01e1745e12e351b35c7c320c077e911b6b98adfdabb85abf4010", + ".governance/decision_record.py": "7127229c4ccb9014fef225ddb94304d1e91f7e041fc7fd7d36fcb568d66c4245", + ".governance/diagnostics.json": "b6781acba2a375ea0909cc339949d4a26e0f675f08a6e3a6874bc3fe99c4bac0", ".governance/diagnostics.schema.json": "5c28e6a54319d106c234e63e1f65933533b5bfd5cdf6509a17b28362b56f86e1", ".governance/docs/BRANCH_INTENT_RECONCILIATION.md": "d17163b016e1ad8cf97408d528bf5a6443e931ea694e97191abc7c1e50586c3b", ".governance/docs/LOCAL_CI_PUBLICATION.md": "001ba246f985ab10d0e4bb70ca18b45a9f3c80b5af70718ec30f6dfecd54bff8", ".governance/docs/SNAPSHOT_MIGRATION.md": "c73fe642f48e6b1d54b36c9a5f55d2e2a93f8405389533733c26907bd69d6012", - ".governance/error/GOV-AGENT-HOST.md": "ba4ad66e68705a9ab0b43a9864ffaaa2399ddaddc91c5f25202803c058e320d9", + ".governance/docs/information/continuity-namespaces.md": "a4dd32fab072d3c609ba6ffb9681425565dca7578e86aa767df4c222e12dac9d", + ".governance/error/GOV-AGENT-HOST.md": "abd836976efcbe048c6a04010ae02f88e3fe469cc3864fe6ae54acea82583a6a", ".governance/error/GOV-APPROVAL.md": "3b508f23491f2ad93e115481699fab84ef3def844f7580736c29c8afafb1ec47", - ".governance/error/GOV-ARCHITECTURE-001.md": "c2b9e480ccb5e15023c1592d9d81a6c8532a87fdd5ab93719fccd2c5d75e7a08", - ".governance/error/GOV-CHANGE-LEASE.md": "30530e7fd7c2eca9f4db0adec575dbc9b1bea139c2a640bfde0ae7c4b2ace116", - ".governance/error/GOV-INTENT.md": "4dc29dbf4c39d18cd11a5ec1eccc257a06d2bea2f95b560aa58085672611d4a9", - ".governance/error/GOV-PACKAGING.md": "4a602c65a655e9b8b631487fa24982df00e0ae874cf5bdb5129f6493bb440c89", - ".governance/error/GOV-PHYS.md": "81224b0b975d1374dd1ad01b013fda0ff716819c7bd57c7614417b7bfbfb269d", + ".governance/error/GOV-ARCHITECTURE-001.md": "33cabd81fbd1bede22a85b0f5c27897f56d8ec8bf3c43ae4ba37d8de145c9b90", + ".governance/error/GOV-CHANGE-LEASE.md": "109798c08bcbd3a4476da27dc16d337cb04e2920eabf9ccbdab334e7afc1ef45", + ".governance/error/GOV-HOST-MERGE.md": "59d4bf531c9d2d461fe23f8c8a3a6c5423a6051c0d6d5e1c9f35fb60f628fba3", + ".governance/error/GOV-IDLE-TAKEOVER.md": "9426a5460368feb4e7c6caac73568709e6186d7abe09a05f27112daded8ac9d3", + ".governance/error/GOV-INTENT.md": "c078852b4ebb868a0f49463e33df4db410e30989856c5cc5e2d3108289024f75", + ".governance/error/GOV-PACKAGING.md": "a5ca878344c86fe9c0f4017aa8220d4dfd493870f5ef8bbdd6980d566f04efc6", + ".governance/error/GOV-PHYS.md": "f10991e7cf35097a1328ed110c86039156e79b650facac8588cc6136b6d82e24", + ".governance/error/GOV-PUSH.md": "d2f685b927ee637d3ac4a0c6a9d80582808627b542452e87f01df5d81400d620", ".governance/error/GOV-REMEDIATION-INTENT.md": "ff0f41bf5112a1808738554b51c13a24ce97f7842304f1aca33e9f9846d73aa3", ".governance/error/GOV-SNAPSHOT-MIGRATION.md": "b82f44800ce8470d7769cef8b4b4c46a70279cc1fffdbd6592cfbe43741b3cb4", ".governance/error/GOV-STANDARD-UPDATE.md": "4a6c83617dc5308d77a1adb1c79f54ec085f280aa3acc33a6e5329a4aa80109c", ".governance/error/GOV-TICKET-001.md": "61e110b93b6111fde243e538e4f34330df36ae29f5a65fb4f90b91d44c1b801e", ".governance/error/GOV-TICKET-ACTIVITY.md": "f1bc9cab86c36028eed449f1c40a229131cb49141cbea35620580e2ef2d2b642", - ".governance/error/GOV-TICKET-ALLOCATION.md": "09f92cac24bbbbe5c2967221497fb6b68b02bcd3bf4f56afe36d36ac7d7b0a58", - ".governance/error/GOV-VERSION.md": "07433f9401e4839e87c2143b8963967d137ea0b8dd1f2fbcb9796fcf1b5e1009", - ".governance/error/GOV-WORK-CONTINUITY.md": "de46a4adc51e8dd5880a83a6d9585ecdbbea4ae30a44ee6506c207ea2e8bc8eb", - ".governance/error/GOV-WORK-START.md": "6dcec8198e98a23c34c1d34cf8fb14c25b973b7f25217a6cb0554959b6fbba3f", + ".governance/error/GOV-TICKET-ALLOCATION.md": "acc7386172dec6015773c179bc7cbe80ba4a84c686102a8a529ddaac15c55a9f", + ".governance/error/GOV-VERSION.md": "b36de34adf8900f39e05ae2f92bfa892971143803fc263821728be587543ce0b", + ".governance/error/GOV-WORK-CONTINUITY.md": "56a5618043492186a1e3b12377c51011dc8518fb69632cc1dfb6390f56c1ae79", + ".governance/error/GOV-WORK-START.md": "423b9d74e3cdd282765a409905c22ed219cf455eeca81987b81651b0bfdcad90", ".governance/error/GOV-WORKSPACE-LIFECYCLE.md": "392b9f484ee26eff04a77d6c24d283413aa25d7e23e0d295ab3d1542f3e1ef3d", ".governance/error/GOV-WORKTREE-OVERLAP.md": "65a2533f13e63d6ebeeb63c07adc0794ea9e04075a91e873eff2d79910239b0e", ".governance/error/README.md": "e8486dd29f52ca3fee96ed6881a62c38141864cde5aa1adea2b16d22b2feefaa", - ".governance/generate_required_checks.py": "2967c7223246a676eaafd7d71fc84702180e7519ef994be729eeee98bf77689c", - ".governance/governance_check.py": "b66ab3434755b43d692d477063d075fc646db1b3c63708226811ff8148f256ae", - ".governance/intent.schema.json": "6fc23c80f2dde00c9aa4d50e2896599a612df179417c65b267c92071647ab252", + ".governance/generate_required_checks.py": "d6c188a1628b1e8b9b884b824d566f0a5fa9d02d0e480339e4d46e2cdcc6dc51", + ".governance/governance_check.py": "a7bfd191ecfb4f4cd160046530c324a1d0b25bd7521bba164e50ac3a56007510", + ".governance/idle_takeover.py": "34314bab61967ae4372385c0437222f7930385d2eace0d4312571c985d407315", + ".governance/intent.schema.json": "b0a75ee7b580425fd453a0bb93bfbd442930dadec625aef48bebae18e8e963a9", + ".governance/legacy_terminal_retirement.py": "835473ce9025ae64448f98eeddb7a4ae481fb12cd6ef82f86b4773812c951ce1", ".governance/lock.schema.json": "ad80c98f800a4a3310870336dcdaf0aa689cc4988f71084d25d76bea2df1242f", - ".governance/managed-copies.json": "c94bb38d048d517d541ac8ad7fc47d3f531471d88c713634b1d5889fd8e871d7", - ".governance/manifest.base.json": "cda04417d0578708773ce234c6314d230cbe6b4b96812a9808343b7d1879b722", - ".governance/manifest.schema.json": "6caeb5295678e15427daacc92c60c2a06d2279964ed965e08207b11a2b846f3e", - ".governance/package-manifest.json": "138acf8f95f5ea09fc05f45f8ee8ea95157f45cbc60f950cb3de081380815f67", + ".governance/managed-copies.json": "e2037c92653ae0c7c886c48cd9ffa22034240cd25391732504ee6c8467db19da", + ".governance/manifest.base.json": "c7b80e5799107096825e0416cc13fef3aeddaae89f4fd052e5f0916d250e4cd9", + ".governance/manifest.schema.json": "2194aa771caa7d84d2f4b5b8bdd5b7c06182ffcd0cb910a86a8228326967a9da", + ".governance/owner_handoff.py": "3eb6d07b96106e8c6042a815a6133bf24aba510dc7b84cb476f6a453241e31d3", + ".governance/package-manifest.json": "84ed5427ed167c5f9040ecfb09241a72fdfad66652637af81ea3f64b69600b01", ".governance/physical-contracts.schema.json": "df69632961d6936d961d9cba21e82e96dac96a8b52d9b3e36ed7e13e5a01b403", + ".governance/policy-dsl.lock.json": "930b9d97998ab912c612872248608d880efa08ef74b6e6c2c4904c9ea0373138", + ".governance/policy_dsl_check.py": "9bc02c1805ef208a5d136c045c6a829b7394bc652208c26942dd2e31561881ac", ".governance/precommit_standard_update.py": "c91e2bf9ae9d6ccc77bce0e61450c818a5961edee5bfde3b60426da88e296b0f", - ".governance/prune_merged_worktrees.py": "1fef90ad396829a1a877832bf35939773fc3596efc1242f8e263ae214bd90d9b", + ".governance/prune_merged_worktrees.py": "67b5dfb1370460a45c1f31ce68be3cdc54a46bd6635b67fe4fc37cf693cc68de", ".governance/remediation-intent.schema.json": "844f834775174b4c0e10f4530f5ac66f918a6f315428d3d70c884b688832d29e", ".governance/remediation-intent.template.dsl.json": "a3eb01c54fe678f3fcebb88103ac4eb02f5dd24016b2ba9552814b5e442dfb34", - ".governance/remediation_intent.py": "6dea0c1394ff42dcf7a223bf1249749f87df845f18ef395f4ecd5283c8bfdade", - ".governance/repository_policy.py": "f52a3cbf99943be747871297c33c115f25e26ceab386fd957923294e32b49800", - ".governance/required-checks.schema.json": "465f004d0e30f21e60e59c8b7860cc33db059e383e272e3caa267df7f24437f5", + ".governance/remediation_intent.py": "351e8c7bc86952ed6e5ebb90076c1627cf1770cda0e25787e46690d6b04dd22c", + ".governance/repository_policy.py": "8c1cdee4250f0c3ce87c9613996c3a69095aa787bad4572d68876fecab31ad05", + ".governance/required-checks.schema.json": "70675a17bf251c4a41a4483e27d76acb7379c6eea1f61abd52177493989c9683", ".governance/reusable-workflows.schema.json": "04c82369e8dff62ae580196ea64d2f8d28c10d4b097dc337a5bf59419a6fa4a1", + ".governance/seed_baseline.py": "072ba0ee47a656e61b746c8c09f768d6264b6d2889c6b46c8537a8c9d3eccab7", ".governance/snapshot-migration.schema.json": "37e97ca683254a66d1a83576e3a4293e37663d38efb0cbc94e9deec1dd58b5ca", ".governance/snapshot_allocation.py": "31c7fa7f94139ab221be61e6f2011a433fe09b5c1712aa5c00ef8cf9b2d7b878", - ".governance/snapshot_migration.py": "5e15b8b9f9835e7f2177e713c30e97545b79dbb9d2e23a22209c7375ec73a034", + ".governance/snapshot_migration.py": "b030abe2d0bd8027f14bcf8182b55a403b0701aac8f24a5ce089c8adfc20cd44", ".governance/stack-profiles.json": "47a3b899553968dfc5e0565c0de525f13aadde5dacae4556614572a731054f0e", + ".governance/standard-adoption-plan.schema.json": "4829ea370409f921eefe2624b40eb7157047e1ac27867a854c498cbf5de2b615", ".governance/standard-adoption.schema.json": "d9c58e86d11ebd23174ed8a5c209c13ae96bd4cd34b7866ac8c61a66de19bc9b", - ".governance/standard-packs.json": "bb18e6aac52e64db36e29ecfddf892a02c07d4197d47974d668d734672bec833", - ".governance/standard_pack_check.py": "9b13bd39b460c6af1117307750cd8cbea27dc0d930d75d70864ba7b1fbdfcae6", + ".governance/standard-packs.json": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d", + ".governance/standard-propagation-request.schema.json": "25b189eb11402137afc67d5a53c426a6b91e083dfa0ca03e720b0bbeebe33beb", + ".governance/standard_pack_check.py": "e5bee4c152ab295125d0ddd069b2a92a08ecee76e117834e3d47d5a1506ffd86", ".governance/templates/conftest-worktree-bootstrap.py": "1901fb6924b844915479d5ef781d6bca16232f6f1d2b93dcf93bb2c70bd9663b", ".governance/terminal-receipt-registry.schema.json": "799dac322e708421a1ff2dbb00408a47cd05f7021c87920d1d37a1e70fe671f9", + ".governance/terminal_lease_release.py": "994ac3f08c4315ed886d093dba92f45c9fa77c92326f4d7ba42e3f001c51593f", ".governance/ticket-activity-override.schema.json": "070f22044fba29e1a09543d7236b3105aa9127b9c22229f3e3d9aa067c6c8d17", ".governance/ticket-activity.json": "b73e881f64f940cd9e670a411713f18c6fe701f46278426bd44e173b8b418599", ".governance/ticket-activity.schema.json": "f11f717702145982716ce16598e94c47e46fe6dfdf3377b7b0fe45efdf932953", - ".governance/ticket-allocation-receipt.schema.json": "e3827eca95cdb833345964f0705a5aa8dc84c54cc369778bfb8b611419b191b2", - ".governance/ticket-allocation-request.schema.json": "b3796ee4670bf78ab088f7a691edafe9630db2aa7a57663c12705ebc8c83df05", - ".governance/ticket-allocation.schema.json": "bf05d64066f902a19f3d1d5359105c22b77c6538e27f29903f28c9b7a503fe13", - ".governance/ticket_activity.py": "c0aa97228676ae1b72fdbaade63a5f11eaced02e461d15bdc3884c69b9c1080b", - ".governance/ticket_allocation.py": "dac1d84caf462866b22df3c8e84952053f976d60285c930e3888f8fa3f11ddbe", + ".governance/ticket-allocation-receipt.schema.json": "c1cf2107a127aa1051e8ea73faa463247fa1e571cb2722d2dbc7c60f6369383c", + ".governance/ticket-allocation-request.schema.json": "4d38efa172b12411d88c824ba13210a19ecd75b84aa239961c520c3ce5aee2aa", + ".governance/ticket-allocation.schema.json": "a0e92bb340ea6f6ffc1a292af1c13ab18b734c726cad8a3a28b3bf201630c6ca", + ".governance/ticket_activity.py": "114e7e299b0f0ff5f27f75c506fdd8abf3f4f1a03d4c9085f146db64d550c8cd", + ".governance/ticket_allocation.py": "06a9e1f2b986a2dddb1be44b769a8b1029f1d0c5f06fedc44a229646370ac0bf", ".governance/ticket_index_merge_driver.py": "478a6aa42fa9ef8733756c7adbb2a569dd109c9b79a0c2aa033ba67b083beeac", - ".governance/ticket_input.py": "b7fa667798e3a855f8c3504b78c652b549f15cd63a32b225e2ad67b9320f0d5e", - ".governance/ticket_recovery.py": "c6442c6d16216e88550fa5bef223fd7274f064068a15aebaffb60c7f4932d276", - ".governance/ticket_storage.py": "33d0aa1b82d47eacba24b9a1dae855bd4fff16182f074fe412f329565f527427", + ".governance/ticket_input.py": "cb515f4af5585514c4ece6cf1de495eb74be832c3381914ea0f3faef8470d2c7", + ".governance/ticket_recovery.py": "caea6250331c9d93c8e5f28a4934b438daeb73b4966d568c1a2774980c2915df", + ".governance/ticket_restoration.py": "7ca146d50318c6b98eaf361c6043523b652b6178389c63f9e777af558e2c44ef", + ".governance/ticket_storage.py": "b23f5e21001fefda10937085b267ac4cf5939f85399bd715ac669ae139a054ee", ".governance/work-classification.dsl.json": "3a947c41938c0b8ef1717957f313ff9248764252735182de30b1f2d6878748b6", ".governance/work-classification.schema.json": "f5c2b518238543589e4f8d3805cc6455e19d6919643644aaeae034abf472a467", ".governance/work-continuity.schema.json": "5134e6884ddaa4fb3a0ffd200d281afb0f3b868b06f71d65e3da6b42f6fe0830", - ".governance/work-start-report.schema.json": "af3a86ad2bd6e40c3c770ec2c879e1e78f3d37d70583b734ffd58d2a14b2e8d6", - ".governance/work_continuity.py": "b1351150503159aadcd0f48fe568487b1863bb5dc350551237d7edd1c83a07f6", - ".governance/work_start_check.py": "190a01e95bdc7c06a0e297df977f989031db58d6d94fa0608090c452371df2be", + ".governance/work-start-report.schema.json": "f6744ed44359a892f44cfdc8c825182a2ba72b855ec3aadce244327e7771ba51", + ".governance/work_continuity.py": "10e2dc8ea71b3448be203c6f24ca00ebc8b1683c096e6845a8690d098ba4f63b", + ".governance/work_start_check.py": "22c3422dc8e715e71b47e433403ba2f7c4b5e573e61afc5a8100465ab86a364c", ".governance/workspace_lifecycle_check.py": "f264154a69c2c00a9218e6dbff87dcf2a3179768d94b4086374f001da6aa411f", ".governance/worktree_guard.py": "16408421c577a8c2eedd24800b69c116b3af11a4046d9533a470d67e4e4d0f4a", - ".governance/worktree_overlap_check.py": "5fe45763ff0a02276bb41288db1a1b0d9c3483934097c6f46978ccc711e9a807", - ".governance/worktree_path_check.py": "fad10912f3b14913cc348880996b636ba0d31ea66a853dd264b53e4e66f17feb", - ".governance/worktrees.lock.json": "5d42f7a7a1afc319dd8f670730f564271d886e22fe7ea61dd0d12911e7ce05ca", - ".governance/worktrees.schema.json": "bb5989c19ee33d9beafa34576ef568ef70384a664ccf763ac2e29dde3a464756", + ".governance/worktree_overlap_check.py": "14fb26def02790454a90fbd776df3a2b5c0551a55e8f2b32a174515f15670169", + ".governance/worktree_path_check.py": "106f91e6398564b96d5487dbd981ebb2078d7d366b327400b7d08467fa04c1fd", + ".governance/worktrees.lock.json": "da34dceef6573250b03ac471867f95d6cf4a96f2cb729df61efed51283c52f2c", + ".governance/worktrees.schema.json": "6b57184758bdceda5cd5ea98889427af1a762dd0afe801ac8e1279d26ccb2cb8", ".subactor/.gitignore": "dd223aed5e053f94c6808ac434368c16eeca7e77218f8426e8cf5e46ae441d03", ".subactor/manifest.json": "ab8b1cbe4052a6f0005a3c33a43fa2a70e8837cd32c18b4183d0d448c3a8cee2", - "AGENTS.md": "0e0d0cd249843bafecd34dda41f7e9bb1841df43e59bbc524f019683db29c9c5", + "AGENTS.md": "2273a46935c48f01ffc14be4ddb5d1de4a1de8118dec823b2fd769625870f1f0", "CLAUDE.md": "628e743294cd4e23531eece8053595fec526080b20f2fac74248e43e5227442b", "GEMINI.md": "f72a35f8a888b1727f4829fa33410e75a1e830a363cc7bf7c465e5c519535725", - "project/governance-check.bat": "04f4fd3ba15abd6b874bde8fab0dd869402b84b9c83ae72da40c1a804b068045", - "project/governance-check.sh": "8eb977ff01a96e47455d227ed5ced949eb53ea19537f870d9016f803840e048e", - "project/new-ticket.sh": "e70e7b9e47557ed34a42472372e9c86e9ab479dbce4925e1975ea31a3adc9889", - "project/readme.sh": "f0ab0e031cbcaca4657f3fe0624eb2a0e9df856478607e425fb4f5cf5fda9ff2", - "scripts/install-agent-hosts.sh": "579d662e91f7c6d3c2ed6b26097fd3dbe40da9777eb26eb7de3a08043ffb205b", + "project/governance-check.bat": "5ece7d85b011a1421bea0b6a5359a9b95ab878c96254f8143979cbcd5adaf76a", + "project/governance-check.sh": "961deddc05c5cbecbaf72a76503ed6bba94ea2b9096ea83381fb7365932a9ca8", + "project/new-ticket.sh": "b151412f7531fe2157756848b93dd406718c32b63122c45e38bc1c7ea320596f", + "project/readme.sh": "21474eb3aafc34b36eed596e785c5e2bb4fefed0b13c2bd2e617f3269ec3fe9a", + "scripts/install-agent-hosts.sh": "380e0e7eebffaa1c8d17f5a53afb0cbd02960eb6f6478bf1736664f6080033b6", "scripts/runtime.sh": "057d6b06de069f57abfdcad8e53c784c651bab7787c7a30053c8243aca8a5c34", - "wellmanifest_governance.py": "121d28323e5ba3f024fae82ba609dee74ffd6c19a30c9bd16a4c0472f70e572c", + "wellmanifest_governance.py": "2c63a4af5b2b92c37df27a5d2d1c5644bfbb216133d858f85701555c64c6b8cf", "worktree-guard.yaml": "8533a7c03a121a6df68b89cab212187313ffb0720aaf457941439148a25c3345" }, "schema": "new-project.lock/v1", @@ -116,7 +134,7 @@ "id": "wellmanifest/new-project", "publicationStatus": "published", "sourceRepository": "wellmanifest/new-project", - "sourceRevision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "version": "0.20.92" + "sourceRevision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "version": "0.20.162" } } diff --git a/.governance/manifest.schema.json b/.governance/manifest.schema.json index 171186a..c92cc55 100644 --- a/.governance/manifest.schema.json +++ b/.governance/manifest.schema.json @@ -134,6 +134,17 @@ "mode": { "const": "workstreams" }, "maxActiveTicketsPerWorkstream": { "type": "integer", "minimum": 1 }, "rejectActiveScopeOverlap": { "type": "boolean" }, + "idleTakeover": { + "description": "Idle ticket takeover (new-project.idle-takeover/v1); see error/GOV-IDLE-TAKEOVER.md.", + "type": "object", + "additionalProperties": false, + "required": ["enabled", "idleMinutes", "leaseMinutes"], + "properties": { + "enabled": { "type": "boolean" }, + "idleMinutes": { "type": "integer", "minimum": 5, "maximum": 240 }, + "leaseMinutes": { "type": "integer", "minimum": 15, "maximum": 480 } + } + }, "workstreams": { "type": "object", "minProperties": 1, diff --git a/.governance/owner_handoff.py b/.governance/owner_handoff.py new file mode 100755 index 0000000..c8464a4 --- /dev/null +++ b/.governance/owner_handoff.py @@ -0,0 +1,496 @@ +#!/usr/bin/env python3 +"""Local lease handoff for a protected invoker that authenticates old-owner consent. + +Request fields and file descriptors are data, never credentials. The public API +requires an independently supplied verifier on every apply, including recovery. +The standalone CLI deliberately provides observation only. +""" +from __future__ import annotations + +import argparse +import base64 +from contextlib import nullcontext +from datetime import datetime, timedelta, timezone +import hashlib +import importlib.util +import json +import os +from pathlib import Path +import re +import stat +import subprocess +import sys + + +def _sibling(name): + spec = importlib.util.spec_from_file_location('_owner_handoff_' + name, + Path(__file__).with_name(name + '.py')) + value = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = value + spec.loader.exec_module(value) + return value + + +control = _sibling('terminal_lease_release') +SCHEMA = 'new-project.owner-handoff/v1' +JOURNAL_SCHEMA = 'new-project.owner-handoff-journal/v1' +RESUME_SCHEMA = 'new-project.released-owner-resume/v1' +RESUME_JOURNAL_SCHEMA = 'new-project.released-owner-resume-journal/v1' +MAX_BYTES = 1024 * 1024 +MAX_FILE_BYTES = 64 * 1024 * 1024 +FIELDS = {'schema', 'requestId', 'worktreeId', 'ownerActor', 'ownerSession', 'consent', + 'expectedRevision', 'expectedFencingToken', 'expectedLeaseSha256', + 'expectedHeadSha', 'expectedDirtySha256', 'expectedIntentSha256', + 'expectedScopeHash', 'primaryCheckout', 'repositoryRef', 'targetOwnerActor', 'targetOwnerSession', 'ttlSeconds'} +RESUME_FIELDS = FIELDS | {'releaseEvidenceRef', 'expectedTerminalStateSha256'} + + +def _digest(raw): + return hashlib.sha256(raw).hexdigest() + + +def _encoded(value): + return control.encoded(value) + + +def _require(value, message): + if not value: + raise ValueError(message) + + +def _request(request): + _require(isinstance(request, dict), 'invalid handoff request') + released = request.get('schema') == RESUME_SCHEMA + _require(set(request) == (RESUME_FIELDS if released else FIELDS) + and request['schema'] in {SCHEMA, RESUME_SCHEMA}, 'invalid handoff request') + _require(request['consent'] is True, 'explicit consent required') + for key in ('requestId', 'worktreeId', 'ownerActor', 'ownerSession', + 'targetOwnerActor', 'targetOwnerSession', 'repositoryRef'): + value = request[key] + _require(isinstance(value, str) and 0 < len(value) <= 160 + and not any(ord(c) < 32 for c in value), 'invalid handoff identity') + _require(isinstance(request['primaryCheckout'], str) and Path(request['primaryCheckout']).is_absolute() + and '..' not in Path(request['primaryCheckout']).parts, 'invalid primary checkout') + match = control.WORKTREE_ID_RE.fullmatch(request['worktreeId']) + _require(match is not None, 'invalid worktree identity') + _require(request['ownerSession'] != request['targetOwnerSession'], 'fresh successor session required') + for key in ('expectedRevision', 'expectedFencingToken', 'ttlSeconds'): + _require(type(request[key]) is int and request[key] > 0, 'invalid handoff bounds') + _require(request['ttlSeconds'] <= 7200, 'handoff lifetime exceeds bound') + for key in ('expectedLeaseSha256', 'expectedDirtySha256', 'expectedIntentSha256', 'expectedScopeHash'): + _require(isinstance(request[key], str) and re.fullmatch('[0-9a-f]{64}', request[key]), + 'invalid handoff digest') + if released: + _require(isinstance(request['releaseEvidenceRef'], str) + and re.fullmatch(r'receipt:[A-Za-z0-9][A-Za-z0-9._:/-]{0,510}', request['releaseEvidenceRef']), + 'protected release evidence reference required') + _require(isinstance(request['expectedTerminalStateSha256'], str) + and re.fullmatch('[0-9a-f]{64}', request['expectedTerminalStateSha256']), + 'invalid terminal observation digest') + _require(isinstance(request['expectedHeadSha'], str) + and re.fullmatch('[0-9a-f]{40}', request['expectedHeadSha']), 'invalid HEAD') + return match[1], 'refs/heads/ticket/' + match[2] + '-' + match[3] + + +def _git(root, *args): + env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')} + result = subprocess.run(['git', '-C', str(root), *args], env=env, + capture_output=True, timeout=20, check=True) + return result.stdout + + +def _read(path, limit=MAX_BYTES): + with control.directory(path.parent) as (fd, verify): + raw = control.read_at(fd, path.name, limit) + verify() + return raw + + +def _file_row(root, name): + relative = Path(name) + _require(not relative.is_absolute() and '..' not in relative.parts, 'unsafe snapshot path') + path = root / relative + with control.directory(path.parent) as (fd, verify): + try: + info = os.stat(path.name, dir_fd=fd, follow_symlinks=False) + except FileNotFoundError: + verify() + return [name, 'missing'] + if stat.S_ISLNK(info.st_mode): + target = os.readlink(path.name, dir_fd=fd) + verify() + return [name, 'symlink', stat.S_IMODE(info.st_mode), target] + _require(stat.S_ISREG(info.st_mode), 'unsafe snapshot node') + _require(info.st_size <= MAX_FILE_BYTES, 'snapshot file exceeds bound') + descriptor = os.open(path.name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fd) + with os.fdopen(descriptor, 'rb') as stream: + opened = os.fstat(stream.fileno()) + _require((opened.st_dev, opened.st_ino) == (info.st_dev, info.st_ino), 'snapshot changed') + digest, count = hashlib.sha256(), 0 + while chunk := stream.read(1024 * 1024): + count += len(chunk) + _require(count <= MAX_FILE_BYTES, 'snapshot file exceeds bound') + digest.update(chunk) + after = os.fstat(stream.fileno()) + named = os.stat(path.name, dir_fd=fd, follow_symlinks=False) + identity = lambda s: (s.st_dev, s.st_ino, s.st_size, s.st_mtime_ns, s.st_ctime_ns, s.st_mode) + _require(identity(opened) == identity(after) == identity(named), 'snapshot changed') + verify() + return [name, 'file', stat.S_IMODE(info.st_mode), digest.hexdigest()] + + +def _repository_matches(root, request, lease): + original, selected = lease['repositoryRef'], request['repositoryRef'] + accepted = control._accepted_repositories(root) + if original == selected and selected in accepted: + return True + if request['schema'] != RESUME_SCHEMA or '/' in original: + return False + # Only this explicit operation can translate a historical basename. Its + # verifier must bind both names and the exact raw old lease, independently + # of the request. A local digest is not a remote repository mapping. + origin = _git(root, 'config', '--get', 'remote.origin.url').decode().strip() + canonical = control.canonical.canonical_owner_repository(origin) + return (canonical == selected and selected in accepted + and original == canonical.rsplit('/', 1)[-1]) + + +def _validate_original(root, request, lease): + projected = lease + if request['schema'] == RESUME_SCHEMA: + _require(_repository_matches(root, request, lease), 'repository mismatch') + # The original is always archived and CASed byte-for-byte. Validation + # projects only the explicitly authorized historical identity mapping; + # no other malformed field is repaired or accepted. + projected = dict(lease, repositoryRef=request['repositoryRef']) + _require(not control.canonical.validate_lease(projected), 'invalid canonical lease') + + +def _released_state(root, tree, ticket, lease, intent): + # Use the allocator's actual scope algorithm; the independent full current + # intent digest is also bound, while the historical birth plan is retained. + paths = intent.get('allowedPaths') + _require(isinstance(paths, list) and paths and all(isinstance(p, str) and p for p in paths), + 'invalid resume scope') + scope = _digest(json.dumps(paths, sort_keys=True, separators=(',', ':')).encode()) + _require(scope == lease['scopeHash'], 'resume scope changed since allocation') + carrier = _read(tree / 'project' / ticket / 'README.md').decode() + _require(control.activity.parse_ticket_state_text(carrier) == ('BLOCKED', 'HANDOFF'), + 'resume requires an unfinished blocked handoff') + policy_path = control.activity.policy_path(root) + policy_raw = _read(policy_path) + override_path = control.activity.override_path(root) + override_raw = _read(override_path) if override_path is not None else None + expected_policy = control.decode(policy_raw) + if override_raw is not None: + override = control.decode(override_raw) + expected_policy = dict(expected_policy, registry=dict(expected_policy['registry'], + missingPolicy=override.get('missingPolicy'))) + policy = control.activity.load_policy(root) + _require(policy == expected_policy, 'activity policy observation differs') + _require(_read(policy_path) == policy_raw, 'activity policy changed') + _require(control.activity.override_path(root) == override_path + and (override_path is None or _read(override_path) == override_raw), 'activity override changed') + registry_path = control.activity.registry_path(root, policy) + registry = control.decode(_read(registry_path)) # Missing/partial is never an empty registry. + rows = control.activity._validate_registry(registry, control.activity.repository_ref(root)) + _require(not any(row['ticket'] == ticket and row['targetBranch'] == lease['targetBranch'] + and policy['terminalOutcomes'].get(row['outcome'], {}).get('releasesReservation') is True + for row in rows), 'terminal delivery cannot be resumed') + target = _git(root, 'rev-parse', 'refs/heads/' + lease['targetBranch']).decode().strip() + return _digest(_encoded({'policy': policy, 'registry': registry, 'targetHead': target})) + + +def _snapshot(root, request, lease, *, check_expected=True): + ticket, branch = _request(request) + expected = {'ticketId': ticket, 'worktreeId': request['worktreeId'], 'branchRef': branch} + _require(all(lease[k] == v for k, v in expected.items()), 'lease scope mismatch') + _require(request['primaryCheckout'] == str(root) and _repository_matches(root, request, lease), + 'repository mismatch') + tree = root / '.worktrees' / request['worktreeId'] + with control.directory(tree) as (_, verify_tree): + rows = _git(root, 'worktree', 'list', '--porcelain', '-z').decode().split('\0\0') + matches = [row.split('\0') for row in rows if 'worktree ' + str(tree) in row.split('\0')] + _require(len(matches) == 1 and 'branch ' + branch in matches[0], 'unregistered worktree') + _require(_git(tree, 'rev-parse', '--show-toplevel').decode().strip() == str(tree), + 'noncanonical worktree') + link = _read(tree / '.git', 4096).decode().strip() + _require(link.startswith('gitdir: ') and not Path(link[8:]).is_absolute(), 'relative Git link required') + common = Path(_git(tree, 'rev-parse', '--git-common-dir').decode().strip()) + if not common.is_absolute(): + common = tree / common + _require(common.resolve() == root / '.git', 'foreign Git registration') + head = _git(tree, 'rev-parse', 'HEAD').decode().strip() + _require(_git(tree, 'symbolic-ref', 'HEAD').decode().strip() == branch, 'branch changed') + intent_path = tree / 'project' / ticket / 'intent.json' + intent_raw = _read(intent_path) + intent = control.decode(intent_raw) + _require(intent.get('ticket') == ticket and intent.get('workstream') == lease['workstream'], + 'intent identity mismatch') + terminal = (_released_state(root, tree, ticket, lease, intent) + if request['schema'] == RESUME_SCHEMA else None) + names = sorted(set(filter(None, _git(tree, 'ls-files', '-co', '--exclude-standard', '-z') + .decode().split('\0')))) + _require(len(names) <= 100000, 'snapshot exceeds bound') + files = [_file_row(tree, name) for name in names] + # Include index blob IDs and status, not only worktree contents: changing + # an already-staged file must invalidate the observation too. + dirty = _digest(_encoded({'files': files, + 'index': _git(tree, 'ls-files', '--stage', '-z').decode(), + 'status': _git(tree, 'status', '--porcelain=v1', '-z', + '--untracked-files=all').decode()})) + verify_tree() + observation = {'head': head, 'dirty': dirty, 'intent': _digest(intent_raw), + 'scope': lease['scopeHash'], 'branch': branch} + if terminal is not None: + observation['terminal'] = terminal + if check_expected: + _require(terminal == request['expectedTerminalStateSha256'], 'terminal observation changed') + if check_expected: + _require(head == request['expectedHeadSha'] and dirty == request['expectedDirtySha256'] + and observation['intent'] == request['expectedIntentSha256'] + and lease['scopeHash'] == request['expectedScopeHash'], 'workspace observation changed') + return observation + + +def observe(root, worktree_id, *, released=False): + """Read the exact snapshot for a caller's subsequent protected authorization. + + No grant is produced. The authority must independently authenticate consent + and bind these observations into the complete request before applying it. + """ + _require(isinstance(worktree_id, str) and control.WORKTREE_ID_RE.fullmatch(worktree_id), 'invalid worktree identity') + root, _, _ = control._controller_root(Path(root).absolute()) + lease = control.decode(_read(root / '.subactor/leases' / (worktree_id + '.json'))) + # Observation construction shares the same implementation and canonical + # checks as apply, with expected values filled only after the full snapshot. + repository = lease['repositoryRef'] + if released: + _require(lease['phase'] == 'released' and not lease['publicationFrozen'], 'released slot required') + if '/' not in repository: + origin = _git(root, 'config', '--get', 'remote.origin.url').decode().strip() + repository = control.canonical.canonical_owner_repository(origin) + _require(isinstance(repository, str), 'canonical origin required') + _validate_original(root, {'schema': RESUME_SCHEMA if released else SCHEMA, + 'repositoryRef': repository}, lease) + return dict(_observe_unbound(root, worktree_id, lease, released=released, repository=repository), + primaryCheckout=str(root), repositoryRef=repository) + + +def _observe_unbound(root, worktree_id, lease, *, released=False, repository=None): + # Placeholder expected values are used only by the read-only observer. + # Apply always checks a complete, independently authorized request. + request = {'schema': SCHEMA, 'requestId': 'observation', 'worktreeId': worktree_id, + 'ownerActor': lease['ownerActor'], 'ownerSession': lease['ownerSession'], + 'consent': True, 'expectedRevision': lease['leaseRevision'], + 'expectedFencingToken': lease['fencingToken'], 'expectedLeaseSha256': '0' * 64, + 'expectedHeadSha': '0' * 40, 'expectedDirtySha256': '0' * 64, + 'expectedIntentSha256': '0' * 64, 'expectedScopeHash': lease['scopeHash'], + 'primaryCheckout':str(root), 'repositoryRef':lease['repositoryRef'], + 'targetOwnerActor': lease['ownerActor'], 'targetOwnerSession':'observation' if lease['ownerSession']!='observation' else 'observation-2', + 'ttlSeconds': 1} + if released: + request.update(schema=RESUME_SCHEMA, repositoryRef=repository, + releaseEvidenceRef='receipt:observation', expectedTerminalStateSha256='0' * 64) + return _snapshot(root, request, lease, check_expected=False) + + +def _authorization(request, descriptor, verifier): + _require(descriptor is not None and callable(verifier), 'protected verifier required') + info = os.fstat(descriptor) + _require(stat.S_ISREG(info.st_mode) and info.st_size <= MAX_BYTES, 'bounded authorization FD required') + raw = os.pread(descriptor, MAX_BYTES + 1, 0) + _require(len(raw) <= MAX_BYTES, 'authorization exceeds bound') + authorization = control.decode(raw) + evidence = verifier(request, authorization) + _require(isinstance(evidence, dict) + and evidence.get('requestDigest') == _digest(_encoded(request)) + and isinstance(evidence.get('verificationRef'), str) and evidence['verificationRef'], + 'protected authorization rejected') + return raw, evidence + + +def _identity(fd, name): + info = os.stat(name, dir_fd=fd, follow_symlinks=False) + _require(stat.S_ISREG(info.st_mode) and info.st_nlink == 1, 'unsafe lease slot') + return {'device':info.st_dev, 'inode':info.st_ino, 'ctimeNs':info.st_ctime_ns} + + +def _ttl_limit(root): + for path in (root / '.governance/manifest.json', root / 'governance/manifest.hub.json'): + if os.path.lexists(path): + value = control.read_path(path).get('delivery', {}).get('maxActiveMinutes', 120) + _require(type(value) is int and value > 0, 'invalid lifetime policy') + return min(value * 60, 7200) + return 7200 + + +def _successor(lease, request, stamp): + successor = dict(lease) + successor.update(ownerActor=request['targetOwnerActor'], ownerSession=request['targetOwnerSession'], + leaseRevision=lease['leaseRevision'] + 1, fencingToken=lease['fencingToken'] + 1, + eventSequence=lease['eventSequence'] + 1, headSha=request['expectedHeadSha'], + issuedAt=stamp.strftime('%Y-%m-%dT%H:%M:%SZ'), + heartbeatAt=stamp.strftime('%Y-%m-%dT%H:%M:%SZ'), + expiresAt=(stamp + timedelta(seconds=request['ttlSeconds'])).strftime('%Y-%m-%dT%H:%M:%SZ'), + previousReceiptRef='receipt:owner-handoff/' + _digest(_encoded(request))) + if request['schema'] == RESUME_SCHEMA: + successor.update(phase='claimed', repositoryRef=request['repositoryRef'], + pullRequest=None, validatorRunId=None, + previousReceiptRef='receipt:released-owner-resume/' + _digest(_encoded(request))) + _require(not control.canonical.validate_lease(successor), 'invalid successor lease') + return successor + + +def _result(successor): + return {'status':'handoff', 'grantsAuthority':True, 'leaseRevision':successor['leaseRevision'], + 'fencingToken':successor['fencingToken'], 'head':successor['headSha'], + 'branch':successor['branchRef'], 'writerEnvironment':{ + 'NEW_PROJECT_WRITER_ACTOR':successor['ownerActor'], + 'NEW_PROJECT_WRITER_SESSION':successor['ownerSession'], + 'NEW_PROJECT_LEASE_REVISION':str(successor['leaseRevision']), + 'NEW_PROJECT_FENCING_TOKEN':str(successor['fencingToken'])}} + + +def _execute(root, request, fd, verify, name, policy, config, apply, authorization_fd, verifier): + auth_raw, evidence = _authorization(request, authorization_fd, verifier) if apply else (None, None) + identity = _identity(fd, name) + raw = control.read_at(fd, name, control.canonical.MAX_LEASE_BYTES, private=True) + _require(_identity(fd, name) == identity, 'lease identity changed') + _require(request['ttlSeconds'] <= _ttl_limit(root), 'lifetime exceeds project policy') + request_hash = _digest(_encoded(request)) + released = request['schema'] == RESUME_SCHEMA + namespace = 'released-owner-resume' if released else 'owner-handoff' + journal_schema = RESUME_JOURNAL_SCHEMA if released else JOURNAL_SCHEMA + journal_path = root / '.subactor/receipts' / namespace / (request_hash + '.json') + try: + journal = control.decode(_read(journal_path)) + except FileNotFoundError: + journal = None + if journal is not None: + _require(isinstance(journal, dict) and set(journal) == {'schema','request','original','successor', + 'observation','authorization','evidence','result','stamp','leaseIdentity'} + and journal.get('schema') == journal_schema and journal.get('request') == request, + 'journal request mismatch') + original = base64.b64decode(journal['original'], validate=True) + _require(_digest(original) == request['expectedLeaseSha256'], 'journal original mismatch') + _require(raw in (original, _encoded(journal['successor'])), 'journal CAS lost') + if raw == original: + _require(identity == journal['leaseIdentity'], 'journal lease identity changed') + if apply: + _require(auth_raw == base64.b64decode(journal['authorization'], validate=True) + and evidence == journal['evidence'], 'journal authorization mismatch') + lease = control.decode(original) + else: + original, lease = raw, control.decode(raw) + _require(_digest(raw) == request['expectedLeaseSha256'], 'lease CAS mismatch') + _validate_original(root, request, lease) + _require(lease['ownerActor'] == request['ownerActor'] and lease['ownerSession'] == request['ownerSession'] + and lease['leaseRevision'] == request['expectedRevision'] + and lease['fencingToken'] == request['expectedFencingToken'], 'owner fencing mismatch') + _require(lease['phase'] in ({'released'} if released else {'claimed', 'editing', 'validating'}) + and not lease['publicationFrozen'], + 'frozen ownership cannot be handed off') + if released and apply: + proof = evidence.get('releasedOwner') + expected = {'leaseId': lease['leaseId'], 'leaseSha256': request['expectedLeaseSha256'], + 'revision': lease['leaseRevision'], 'fencingToken': lease['fencingToken'], + 'repositoryRef': lease['repositoryRef'], 'canonicalRepositoryRef': request['repositoryRef'], + 'releaseEvidenceRef': request['releaseEvidenceRef']} + _require(isinstance(proof, dict) and set(proof) == set(expected) | {'writerState'} + and all(type(proof[k]) is type(value) and proof[k] == value for k, value in expected.items()) + and isinstance(proof['writerState'], str) + and proof['writerState'] in {'explicitly-released', 'controller-observed-stopped'}, + 'authenticated released-owner proof required') + observation = _snapshot(root, request, lease) + now = datetime.now(timezone.utc).replace(microsecond=0) + if journal is None: + successor = _successor(lease, request, now) + journal = {'schema':journal_schema, 'request':request, 'original':base64.b64encode(original).decode(), + 'successor':successor, 'observation':observation, + 'authorization':base64.b64encode(auth_raw).decode() if auth_raw is not None else None, + 'evidence':evidence, 'result':_result(successor), 'stamp':now.strftime('%Y-%m-%dT%H:%M:%SZ'), + 'leaseIdentity':identity} + stamp = datetime.fromisoformat(journal['stamp'].replace('Z', '+00:00')) + _require(stamp.tzinfo is not None and stamp <= now, 'invalid journal clock') + _require(journal['successor'] == _successor(lease, request, stamp) + and journal['result'] == _result(journal['successor']) + and journal['observation'] == observation, 'journal result mismatch') + successor = journal['successor'] + _require(not control.canonical.validate_lease(successor), 'invalid successor lease') + _require(datetime.fromisoformat(successor['expiresAt'].replace('Z', '+00:00')) > now, + 'successor lease expired; new authenticated handoff required') + if not apply: + return {'status': 'planned', 'grantsAuthority': False, 'head': observation['head'], + 'nextRevision': successor['leaseRevision'], 'nextFencingToken': successor['fencingToken']} + verify() + _require(control.read_path(policy) == config, 'controller policy changed') + if raw == _encoded(successor): + return dict(journal['result'], status='idempotent') + with control.directory(journal_path.parent, create=True) as (journal_fd, verify_journal): + try: + control.atomic_at(journal_fd, journal_path.name, _encoded(journal), exclusive=True) + except FileExistsError: + _require(control.read_at(journal_fd, journal_path.name) == _encoded(journal), 'journal changed') + verify_journal() + verify() + _require(_snapshot(root, request, lease) == observation, 'workspace changed before replacement') + auth_again, evidence_again = _authorization(request, authorization_fd, verifier) + _require(auth_again == auth_raw and evidence_again == evidence, 'authorization changed') + _require(request['ttlSeconds'] <= _ttl_limit(root), 'lifetime policy changed') + _require(control.read_path(policy) == config, 'controller policy changed') + _require(_snapshot(root, request, lease) == observation, 'workspace changed after authorization') + _require(_identity(fd, name) == identity, 'lease identity changed before replacement') + _require(control.read_at(fd, name, control.canonical.MAX_LEASE_BYTES, private=True) == original, + 'lease changed before replacement') + control._replace_lease(fd, name, _encoded(successor)) + verify() + return journal['result'] + + +def handoff(root, request, *, apply=False, authorization_fd=None, verifier=None): + """Apply only from a protected caller whose verifier authenticates consent. + + The callable is trusted executable authority, never selected by the request + or loaded from candidate paths. A caller that cannot authenticate the owner + must not provide it. Actor/session, FD data and request digests alone do not + implement authentication. The standalone CLI has no such verifier. + """ + _require(isinstance(request, dict) and request.get('schema') == SCHEMA, 'ordinary handoff schema required') + return _handoff(root, request, apply=apply, authorization_fd=authorization_fd, verifier=verifier) + + +def resume_released(root, request, *, apply=False, authorization_fd=None, verifier=None): + """Protected same-ticket resume; the verifier authenticates old-writer termination. + + Neither a released lease nor a caller's assertion proves a safe handoff. + The trusted host must acquire fresh, independent controller/owner evidence, + bind releasedOwner to this exact request and authenticate every replay. + """ + _require(isinstance(request, dict) and request.get('schema') == RESUME_SCHEMA, 'released resume schema required') + return _handoff(root, request, apply=apply, authorization_fd=authorization_fd, verifier=verifier) + + +def _handoff(root, request, *, apply, authorization_fd, verifier): + _request(request) + if apply: + _require(authorization_fd is not None and callable(verifier), 'protected verifier required') + root, policy, config = control._controller_root(Path(root).absolute()) + name = request['worktreeId'] + '.json' + with control.directory(root / '.subactor/leases') as (fd, verify_directory): + def verify(): + verify_directory() + _require(control.read_path(policy) == config, 'controller policy changed') + lock = control.lease_lock(fd, name, verify) if apply else nullcontext(verify) + with lock as verify_lock: + return _execute(root, request, fd, verify_lock, name, policy, config, + apply, authorization_fd, verifier) + + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', type=Path, required=True) + parser.add_argument('--request', type=Path, required=True) + parser.add_argument('--apply', action='store_true', help='requires a registered protected invoker; CLI refuses') + args = parser.parse_args() + print(json.dumps(handoff(args.root, control.read_path(args.request.absolute()), apply=args.apply))) diff --git a/.governance/package-manifest.json b/.governance/package-manifest.json index 166281b..85fc27b 100644 --- a/.governance/package-manifest.json +++ b/.governance/package-manifest.json @@ -1,6 +1,30 @@ { "schema": "new-project.package-manifest/v1", "files": [ + { + "source": "scripts/bootstrap_packaging_scope.py", + "target": ".governance/bootstrap_packaging_scope.py", + "strategy": "managed", + "executable": true + }, + { + "source": "scripts/legacy_terminal_retirement.py", + "target": ".governance/legacy_terminal_retirement.py", + "strategy": "managed", + "executable": true + }, + { + "source": "scripts/terminal_lease_release.py", + "target": ".governance/terminal_lease_release.py", + "strategy": "managed", + "executable": true + }, + { + "source": "scripts/owner_handoff.py", + "target": ".governance/owner_handoff.py", + "strategy": "managed", + "executable": true + }, { "source": "scripts/snapshot_allocation.py", "target": ".governance/snapshot_allocation.py", @@ -13,6 +37,12 @@ "strategy": "managed", "executable": false }, + { + "source": "scripts/ticket_restoration.py", + "target": ".governance/ticket_restoration.py", + "strategy": "managed", + "executable": false + }, { "source": "scripts/work_start_check.py", "target": ".governance/work_start_check.py", @@ -181,6 +211,18 @@ "strategy": "managed", "executable": false }, + { + "source": "error/GOV-HOST-MERGE.md", + "target": ".governance/error/GOV-HOST-MERGE.md", + "strategy": "managed", + "executable": false + }, + { + "source": "error/GOV-PUSH.md", + "target": ".governance/error/GOV-PUSH.md", + "strategy": "managed", + "executable": false + }, { "source": "error/GOV-APPROVAL.md", "target": ".governance/error/GOV-APPROVAL.md", @@ -277,6 +319,18 @@ "strategy": "managed", "executable": true }, + { + "source": "scripts/idle_takeover.py", + "target": ".governance/idle_takeover.py", + "strategy": "managed", + "executable": true + }, + { + "source": "error/GOV-IDLE-TAKEOVER.md", + "target": ".governance/error/GOV-IDLE-TAKEOVER.md", + "strategy": "managed", + "executable": false + }, { "source": "error/GOV-INTENT.md", "target": ".governance/error/GOV-INTENT.md", @@ -301,6 +355,18 @@ "strategy": "managed", "executable": true }, + { + "source": "scripts/continuity_namespace.py", + "target": ".governance/continuity_namespace.py", + "strategy": "managed", + "executable": false + }, + { + "source": "docs/information/continuity-namespaces.md", + "target": ".governance/docs/information/continuity-namespaces.md", + "strategy": "managed", + "executable": false + }, { "source": "scripts/ticket_input.py", "target": ".governance/ticket_input.py", @@ -445,6 +511,18 @@ "strategy": "managed", "executable": true }, + { + "source": "scripts/policy_dsl_check.py", + "target": ".governance/policy_dsl_check.py", + "strategy": "managed", + "executable": false + }, + { + "source": "governance/policy-dsl.lock.json", + "target": ".governance/policy-dsl.lock.json", + "strategy": "managed", + "executable": false + }, { "source": "scripts/repository_policy.py", "target": ".governance/repository_policy.py", @@ -553,6 +631,12 @@ "strategy": "managed", "executable": true }, + { + "source": "template/files/pre-push.template.sh", + "target": ".githooks/pre-push", + "strategy": "managed", + "executable": true + }, { "source": "scripts/precommit_standard_update.py", "target": ".governance/precommit_standard_update.py", @@ -702,6 +786,30 @@ "target": ".governance/error/GOV-VERSION.md", "strategy": "managed", "executable": false + }, + { + "source": "governance/standard-adoption-plan.schema.json", + "target": ".governance/standard-adoption-plan.schema.json", + "strategy": "managed", + "executable": false + }, + { + "source": "governance/standard-propagation-request.schema.json", + "target": ".governance/standard-propagation-request.schema.json", + "strategy": "managed", + "executable": false + }, + { + "source": "scripts/seed_baseline.py", + "target": ".governance/seed_baseline.py", + "strategy": "managed", + "executable": true + }, + { + "source": "scripts/controller_store_compaction.py", + "target": ".governance/controller_store_compaction.py", + "strategy": "managed", + "executable": true } ] } diff --git a/.governance/policy-dsl.lock.json b/.governance/policy-dsl.lock.json new file mode 100644 index 0000000..c56d0ce --- /dev/null +++ b/.governance/policy-dsl.lock.json @@ -0,0 +1,17 @@ +{ + "schema": "new-project.policy-dsl-lock/v1", + "dependency": { + "id": "wellmanifest/policy-dsl", + "version": "0.2.0-dev", + "sourceRepository": "wellmanifest/policy-dsl", + "sourceRevision": "0ffa41efd903d3e0fc3dbf4431f2771b34c1f70e", + "sourcePath": "tests/policy_dsl_check.py", + "sourceSha256": "9bc02c1805ef208a5d136c045c6a829b7394bc652208c26942dd2e31561881ac" + }, + "installation": { + "packageSourcePath": "scripts/policy_dsl_check.py", + "managedTargetPath": ".governance/policy_dsl_check.py", + "lockTargetPath": ".governance/policy-dsl.lock.json", + "networkRequired": false + } +} diff --git a/.governance/policy_dsl_check.py b/.governance/policy_dsl_check.py new file mode 100644 index 0000000..93d21c3 --- /dev/null +++ b/.governance/policy_dsl_check.py @@ -0,0 +1,1201 @@ +#!/usr/bin/env python3 +"""Dependency-free Policy DSL v1 parser and conformance checker. + +This module parses inert data and emits closed Policy IR. It intentionally has +no action executor and no shell integration. +""" + +from __future__ import annotations + +import argparse +import json +import math +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Iterable +from urllib.parse import urlsplit + + +ROOT = Path(__file__).resolve().parents[1] +SYMBOL = r"[A-Za-z_][A-Za-z0-9_.:/-]*" +STABLE_ID = r"[A-Z][A-Z0-9_-]*" +SCALAR_TYPES = {"STRING", "INTEGER", "NUMBER", "BOOLEAN", "URL", "PATH"} +SAFE_CANDIDATE_OPCODES = {"REQUIRE", "ALLOW", "REPORT", "VALIDATE", "RECORD"} + + +class PolicyError(Exception): + def __init__(self, code: str, message: str, line: int | None = None): + self.code = code + self.line = line + where = f"line {line}: " if line is not None else "" + super().__init__(f"{code}: {where}{message}") + + +@dataclass(frozen=True) +class Statement: + text: str + line: int + + +@dataclass(frozen=True) +class Token: + kind: str + value: str + line: int + + +TOKEN_RE = re.compile( + r"\s*(?:" + r"(?P\"(?:\\[\"\\/bfnrt]|\\u[0-9a-fA-F]{4}|[^\"\\\x00-\x1f])*\")|" + r"(?P[0-9]+(?:\.[0-9]+)?)|" + r"(?P\{" + SYMBOL + r"\})|" + r"(?P->)|" + r"(?P!=|<=|>=|=|<|>|\+|-|\*|/|%)|" + r"(?P\[)|(?P\])|" + r"(?P\()|(?P\))|(?P,)|" + r"(?P" + SYMBOL + r")" + r")" +) + + +def _strip_comment(line: str) -> str: + quoted = False + escaped = False + for index, char in enumerate(line): + if escaped: + escaped = False + elif char == "\\" and quoted: + escaped = True + elif char == '"': + quoted = not quoted + elif char == "#" and not quoted: + return line[:index] + return line + + +def statements(source: str) -> list[Statement]: + if source.startswith("\ufeff"): + raise PolicyError("POLICY-SYNTAX-001", "UTF-8 BOM is forbidden", 1) + if "\r" in source or "\t" in source: + raise PolicyError("POLICY-SYNTAX-001", "CR and tab characters are forbidden") + for char in source: + if char != "\n" and (ord(char) < 0x20 or ord(char) == 0x7F): + raise PolicyError("POLICY-SYNTAX-001", "control character is forbidden") + + result: list[Statement] = [] + buffer: list[str] = [] + start = 1 + square = round_ = 0 + continuation = False + + def emit() -> None: + nonlocal buffer, continuation + result.append(Statement(" ".join(buffer), start)) + buffer = [] + continuation = False + + for number, raw in enumerate(source.splitlines(), 1): + line = _strip_comment(raw).strip() + if not line: + if buffer and square == 0 and round_ == 0 and continuation: + emit() + continue + indented = raw[:1].isspace() + block_keyword = line == "END" or line.startswith( + ("RULE ", "DO ", "FORBID ", "ASSERT ", "NEXT ", "STATE ", "STATES ", "TRANSITION ", "TEMPLATE ", "SCOPE ") + ) + if buffer and square == 0 and round_ == 0 and continuation and (not indented or block_keyword): + emit() + # Shell syntax outside a quoted literal violates the inert boundary. + unquoted = re.sub(r'"(?:\\.|[^"\\])*"', '""', line) + if "$(" in unquoted or "`" in unquoted or re.search(r"(^|\s)(?:;|&&|\|\|)(\s|$)", unquoted): + raise PolicyError("POLICY-SECURITY-001", "shell syntax is not Policy DSL", number) + if not buffer: + start = number + buffer.append(line) + quoted = escaped = False + for char in line: + if escaped: + escaped = False + elif char == "\\" and quoted: + escaped = True + elif char == '"': + quoted = not quoted + elif not quoted: + square += (char == "[") - (char == "]") + round_ += (char == "(") - (char == ")") + if square < 0 or round_ < 0: + raise PolicyError("POLICY-SYNTAX-001", "unbalanced delimiter", number) + if square == 0 and round_ == 0: + if line.endswith(" WHEN") or (continuation and indented): + continuation = True + else: + emit() + if buffer and square == 0 and round_ == 0: + emit() + if buffer or square or round_: + raise PolicyError("POLICY-SYNTAX-001", "unterminated multiline statement", start) + return result + + +POLICY_SCHEMA_IDS = {"wellmanifest.policy/v1", "policy-sh@1"} +# Closed registry of independent record kinds that Markdown carriers may embed +# in `dsl` fences next to a Policy DSL document. Extending it is a spec change. +EMBEDDED_RECORD_STARTS = ("DECISION ",) + + +def extract_markdown(source: str) -> str: + """Extract the canonical distributed Policy DSL document from Markdown. + + Every `dsl` fence is classified. Unclassifiable fences fail closed so that + normative-looking text is never dropped silently. + """ + blocks: list[tuple[str, int]] = [] + current: list[str] | None = None + opened = 0 + for number, raw in enumerate(source.splitlines(), 1): + if current is None: + if raw.strip() == "```dsl": + current = [] + opened = number + elif raw.strip() == "```": + blocks.append(("\n".join(current) + "\n", opened)) + current = None + else: + current.append(raw) + if current is not None: + raise PolicyError("POLICY-SYNTAX-001", "unterminated dsl fence", opened) + + header: str | None = None + selected: list[str] = [] + binding_start = re.compile(r"^" + SYMBOL + r"\s+(?:=|IN)\s+") + schema_line = re.compile(r'^SCHEMA\s+"([^"]*)"$') + policy_starts = ( + "RULE ", + "STATE ", + "STATES ", + "TRANSITION ", + "TEMPLATE ", + "SCOPE ", + "ENV_FILE ", + "VARIABLE ", + "SECRET ", + "ASSERT ", + ) + for block, opened in blocks: + significant = [_strip_comment(line).strip() for line in block.splitlines()] + significant = [line for line in significant if line] + if not significant: + continue + first = significant[0] + if re.fullmatch(r"DOCUMENT <[^>]+>", first): + continue # illustrative placeholder metadata + if re.fullmatch(r"DOCUMENT " + SYMBOL, first): + schemas = {match.group(1) for line in significant if (match := schema_line.match(line))} + if schemas - POLICY_SCHEMA_IDS: + continue # independent embedded document + if header is not None: + raise PolicyError("POLICY-SYNTAX-001", "duplicate Policy DSL DOCUMENT fence", opened) + header = block + continue + if first.startswith(EMBEDDED_RECORD_STARTS): + continue # registered independent record kind + if first.startswith(policy_starts) or binding_start.match(first): + if header is None: + raise PolicyError("POLICY-SYNTAX-001", "Policy DSL fence precedes the DOCUMENT header", opened) + selected.append(block) + continue + raise PolicyError( + "POLICY-SYNTAX-001", + "dsl fence is neither Policy DSL, placeholder metadata, an independent DOCUMENT nor a registered record; " + "express normative text as Policy DSL or use a non-dsl fence", + opened, + ) + if header is None: + raise PolicyError("POLICY-SYNTAX-001", "Markdown has no concrete Policy DSL DOCUMENT fence") + return header + "".join(selected) + + +def tokenize(text: str, line: int) -> list[Token]: + result: list[Token] = [] + position = 0 + while position < len(text): + match = TOKEN_RE.match(text, position) + if not match: + raise PolicyError("POLICY-SYNTAX-001", f"unexpected token near {text[position:position + 16]!r}", line) + kind = match.lastgroup or "" + value = match.group(kind) + if kind == "SYMBOL" and value in {"AND", "OR", "NOT", "IN"}: + kind = "OP" + result.append(Token(kind, value, line)) + position = match.end() + result.append(Token("EOF", "", line)) + return result + + +class ExpressionParser: + PRECEDENCE = { + "OR": 10, + "AND": 20, + "IN": 30, + "=": 40, + "!=": 40, + "<": 50, + "<=": 50, + ">": 50, + ">=": 50, + "+": 60, + "-": 60, + "*": 70, + "/": 70, + "%": 70, + } + + def __init__(self, tokens: list[Token]): + self.tokens = tokens + self.index = 0 + + @property + def current(self) -> Token: + return self.tokens[self.index] + + def take(self, kind: str | None = None, value: str | None = None) -> Token: + current = self.current + if kind is not None and current.kind != kind: + raise PolicyError("POLICY-SYNTAX-001", f"expected {kind}, found {current.value!r}", current.line) + if value is not None and current.value != value: + raise PolicyError("POLICY-SYNTAX-001", f"expected {value!r}, found {current.value!r}", current.line) + self.index += 1 + return current + + def expression(self, minimum: int = 0) -> dict[str, Any]: + current = self.current + if current.kind == "OP" and current.value in {"NOT", "-"}: + self.take() + left = {"node": "unary", "operator": current.value, "operand": self.expression(80)} + else: + left = self.primary() + while self.current.kind == "OP" and self.current.value in self.PRECEDENCE: + operator = self.current.value + precedence = self.PRECEDENCE[operator] + if precedence < minimum: + break + self.take() + right = self.expression(precedence + 1) + left = {"node": "binary", "operator": operator, "left": left, "right": right} + return left + + def primary(self) -> dict[str, Any]: + current = self.current + if current.kind == "STRING": + self.take() + return {"node": "literal", "value": json.loads(current.value)} + if current.kind == "NUMBER": + self.take() + value: int | float = float(current.value) if "." in current.value else int(current.value) + return {"node": "literal", "value": value} + if current.kind == "SYMBOL": + self.take() + if current.value in {"TRUE", "FALSE", "true", "false"}: + return {"node": "literal", "value": current.value in {"TRUE", "true"}} + return {"node": "symbol", "name": current.value} + if current.kind == "PLACEHOLDER": + self.take() + return {"node": "symbol", "name": current.value} + if current.kind == "LBRACK": + return self.collection("RBRACK", "list") + if current.kind == "LPAREN": + return self.collection("RPAREN", "group") + raise PolicyError("POLICY-SYNTAX-001", f"expected expression, found {current.value!r}", current.line) + + def collection(self, closing: str, kind: str) -> dict[str, Any]: + self.take() + items: list[dict[str, Any]] = [] + while self.current.kind != closing: + if self.current.kind == "EOF": + raise PolicyError("POLICY-SYNTAX-001", "unterminated collection", self.current.line) + items.append(self.expression()) + if self.current.kind == "COMMA": + self.take() + elif self.current.kind != closing: + # A parenthesized action payload may be a typed sequence. + if kind != "group": + raise PolicyError("POLICY-SYNTAX-001", "list items require commas", self.current.line) + self.take(closing) + if kind == "group" and len(items) == 1: + return items[0] + node = "list" if kind == "list" else "sequence" + if node == "sequence" and len(items) < 2: + raise PolicyError("POLICY-SYNTAX-001", "empty grouping is forbidden", self.current.line) + return {"node": node, "items": items} + + def complete(self) -> dict[str, Any]: + value = self.expression() + self.take("EOF") + return value + + def sequence(self) -> dict[str, Any] | None: + items: list[dict[str, Any]] = [] + while self.current.kind != "EOF": + if self.current.kind == "COMMA": + self.take() + continue + if self.current.kind == "OP" and self.current.value not in {"NOT", "-"}: + # Domain actions use words such as IN/AND as typed prepositions + # when no left operand exists; they remain symbols, not text. + items.append({"node": "symbol", "name": self.take().value}) + continue + items.append(self.expression()) + if not items: + return None + return items[0] if len(items) == 1 else {"node": "sequence", "items": items} + + +def parse_expression(text: str, line: int) -> dict[str, Any]: + return ExpressionParser(tokenize(text, line)).complete() + + +def parse_condition(text: str, line: int) -> dict[str, Any]: + value = ExpressionParser(tokenize(text, line)).sequence() + if value is None: + raise PolicyError("POLICY-SYNTAX-001", "condition must not be empty", line) + return value + + +def parse_action(text: str, line: int) -> dict[str, Any]: + tokens = tokenize(text, line) + if tokens[0].kind != "SYMBOL" or not re.fullmatch(r"[A-Z][A-Z0-9_]*", tokens[0].value): + raise PolicyError("POLICY-SYNTAX-001", "action requires an uppercase opcode", line) + opcode = tokens[0].value + body = tokens[1:-1] + depth = 0 + guard_at: int | None = None + for index, token in enumerate(body): + if token.kind in {"LPAREN", "LBRACK"}: + depth += 1 + elif token.kind in {"RPAREN", "RBRACK"}: + depth -= 1 + elif depth == 0 and token.kind == "SYMBOL" and token.value == "WHEN": + guard_at = index + break + payload_tokens = body if guard_at is None else body[:guard_at] + guard_tokens = [] if guard_at is None else body[guard_at + 1:] + payload = ExpressionParser(payload_tokens + [Token("EOF", "", line)]).sequence() + guard = None + if guard_at is not None: + if not guard_tokens: + raise PolicyError("POLICY-SYNTAX-001", "action WHEN requires a condition", line) + guard = ExpressionParser(guard_tokens + [Token("EOF", "", line)]).sequence() + return {"kind": "action", "opcode": opcode, "payload": payload, "guard": guard} + + +def parse_next(text: str, line: int) -> list[dict[str, Any]]: + first = re.fullmatch(r"(" + SYMBOL + r")(.*)", text) + if not first: + raise PolicyError("POLICY-SYNTAX-001", "NEXT requires a target", line) + target, tail = first.group(1), first.group(2).strip() + if not tail: + return [{"target": target, "condition": None}] + if tail.startswith("OR "): + targets = [target] + tail[3:].split(" OR ") + if any(not re.fullmatch(SYMBOL, value) for value in targets): + raise PolicyError("POLICY-SYNTAX-001", "invalid NEXT targets", line) + return [{"target": value, "condition": None} for value in targets] + if not tail.startswith("WHEN "): + raise PolicyError("POLICY-SYNTAX-001", "NEXT accepts OR or WHEN after its target", line) + condition_text = tail[5:] + fallback: str | None = None + fallback_match = re.fullmatch(r"(.+) OR (" + SYMBOL + r")", condition_text) + if fallback_match: + condition_text, fallback = fallback_match.group(1), fallback_match.group(2) + result = [{"target": target, "condition": parse_condition(condition_text, line)}] + if fallback is not None: + result.append({"target": fallback, "condition": None}) + return result + + +def _quoted(value: str, line: int) -> str: + try: + parsed = json.loads(value) + except json.JSONDecodeError as error: + raise PolicyError("POLICY-SYNTAX-001", "invalid JSON string", line) from error + if not isinstance(parsed, str): + raise PolicyError("POLICY-SYNTAX-001", "expected string", line) + return parsed + + +def _parse_symbol_list(text: str, line: int) -> list[str]: + expr = parse_expression(text, line) + if expr.get("node") != "list" or not expr.get("items"): + raise PolicyError("POLICY-SYNTAX-001", "expected non-empty state symbol list", line) + names: list[str] = [] + for item in expr["items"]: + if item.get("node") != "symbol" or not re.fullmatch(SYMBOL, item.get("name", "")): + raise PolicyError("POLICY-SYNTAX-001", "state list items must be valid symbols", line) + names.append(item["name"]) + return names + + +class PolicyParser: + def __init__(self, source: str): + self.items = statements(source) + self.index = 0 + self.templates: dict[str, dict[str, Any]] = {} + self.uncompacted_rules: list[dict[str, Any]] = [] + self.uncompacted_transitions: list[dict[str, Any]] = [] + self.scoped_rule_count = 0 + self.state_set_transition_count = 0 + + @property + def current(self) -> Statement | None: + return self.items[self.index] if self.index < len(self.items) else None + + def take(self) -> Statement: + item = self.current + if item is None: + raise PolicyError("POLICY-SYNTAX-001", "unexpected end of document") + self.index += 1 + return item + + def required_match(self, pattern: str, label: str) -> re.Match[str]: + item = self.take() + match = re.fullmatch(pattern, item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", f"expected {label}", item.line) + return match + + def parse(self) -> dict[str, Any]: + name = self.required_match(r"DOCUMENT (" + SYMBOL + r")", "DOCUMENT").group(1) + version = int(self.required_match(r"VERSION ([1-9][0-9]*)", "VERSION").group(1)) + language: str | None = None + if self.current and self.current.text.startswith("LANGUAGE "): + language = self.required_match(r"LANGUAGE (" + SYMBOL + r")", "LANGUAGE").group(1) + mode = self.required_match(r"MODE (STRICT|PROCEDURAL)", "MODE").group(1) + purpose = policy = None + if self.current and self.current.text.startswith("PURPOSE "): + item = self.take() + match = re.fullmatch(r"PURPOSE (\".*\")", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid PURPOSE", item.line) + purpose = _quoted(match.group(1), item.line) + if self.current and self.current.text.startswith("POLICY "): + item = self.take() + match = re.fullmatch(r"POLICY (\".*\")", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid POLICY", item.line) + policy = _quoted(match.group(1), item.line) + + result: dict[str, Any] = { + "schema": "wellmanifest.policy/ir/v1", + "dialect": "wellmanifest.policy/v1", + "language_version": "1", + "document": {"name": name, "version": version, "language": language, "mode": mode, "purpose": purpose, "policy": policy}, + "environment": [], + "bindings": [], + "rules": [], + "assertions": [], + "states": [], + "transitions": [], + } + while self.current is not None: + text = self.current.text + if text.startswith("ENV_FILE ") or text.startswith("VARIABLE ") or text.startswith("SECRET "): + result["environment"].append(self.parse_environment()) + elif text.startswith("RULE "): + result["rules"].append(self.parse_rule()) + elif text.startswith("STATE "): + item = self.take() + match = re.fullmatch(r"STATE (" + SYMBOL + r")", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid STATE", item.line) + result["states"].append(match.group(1)) + elif text.startswith("STATES "): + result["states"].extend(self.parse_states()) + elif text.startswith("TRANSITION "): + result["transitions"].extend(self.parse_transitions()) + elif text.startswith("TEMPLATE "): + self.parse_template() + elif text.startswith("SCOPE "): + self.parse_scope(result) + elif text.startswith("ASSERT "): + item = self.take() + result["assertions"].append(parse_expression(item.text[7:], item.line)) + else: + result["bindings"].append(self.parse_binding()) + self.semantic_checks(result) + validate_ir(result) + return result + + def parse_environment(self) -> dict[str, Any]: + item = self.take() + match = re.fullmatch(r"ENV_FILE (\".*\") (OPTIONAL|REQUIRED)", item.text) + if match: + return {"kind": "env_file", "path": _quoted(match.group(1), item.line), "required": match.group(2) == "REQUIRED"} + match = re.fullmatch(r"VARIABLE (" + SYMBOL + r") TYPE (\w+) FROM ENV (REQUIRED|DEFAULT .+)", item.text) + if match: + value_type, tail = match.group(2), match.group(3) + if value_type not in SCALAR_TYPES: + raise PolicyError("POLICY-SEMANTIC-001", f"unknown scalar type {value_type}", item.line) + default = None + required = tail == "REQUIRED" + if tail.startswith("DEFAULT "): + expression = parse_expression(tail[8:], item.line) + if expression["node"] != "literal": + raise PolicyError("POLICY-SEMANTIC-001", "VARIABLE default must be a literal", item.line) + default = expression["value"] + _validate_variable_default(value_type, default, item.line) + return {"kind": "variable", "name": match.group(1), "value_type": value_type, "required": required, "default": default} + match = re.fullmatch(r"SECRET (" + SYMBOL + r") TYPE (\w+) FROM ENV REQUIRED REDACT", item.text) + if match: + if match.group(2) not in SCALAR_TYPES: + raise PolicyError("POLICY-SEMANTIC-001", f"unknown scalar type {match.group(2)}", item.line) + return {"kind": "secret", "name": match.group(1), "value_type": match.group(2), "required": True, "redact": True} + raise PolicyError("POLICY-SYNTAX-001", "invalid environment declaration", item.line) + + def parse_binding(self) -> dict[str, Any]: + item = self.take() + match = re.fullmatch(r"(" + SYMBOL + r")\s+(=|IN)\s+(.+)", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "unknown top-level statement", item.line) + return {"name": match.group(1), "operator": match.group(2), "value": parse_condition(match.group(3), item.line)} + + def parse_states(self) -> list[str]: + item = self.take() + match = re.fullmatch(r"STATES (\[.+\])", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid STATES list", item.line) + return _parse_symbol_list(match.group(1), item.line) + + def parse_transitions(self, scope_guard: dict[str, Any] | None = None) -> list[dict[str, Any]]: + item = self.take() + list_match = re.fullmatch(r"TRANSITION (\[.+\]) -> (" + SYMBOL + r")(?: WHEN (.+))?", item.text) + if list_match: + origins = _parse_symbol_list(list_match.group(1), item.line) + target = list_match.group(2) + raw_condition = list_match.group(3) + is_list = True + else: + match = re.fullmatch(r"TRANSITION (" + SYMBOL + r") -> (" + SYMBOL + r")(?: WHEN (.+))?", item.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid TRANSITION", item.line) + origins = [match.group(1)] + target = match.group(2) + raw_condition = match.group(3) + is_list = False + own_condition = parse_condition(raw_condition, item.line) if raw_condition else None + condition = own_condition + if scope_guard is not None: + condition = ( + scope_guard + if condition is None + else {"node": "binary", "operator": "AND", "left": scope_guard, "right": condition} + ) + edges = [{"from": origin, "to": target, "condition": condition} for origin in origins] + if is_list: + self.state_set_transition_count += len(origins) + else: + self.uncompacted_transitions.append({"from": origins[0], "to": target, "condition": own_condition}) + return edges + + def _apply_template_to_target(self, target: dict[str, Any], action: dict[str, Any], line: int) -> None: + payload = action.get("payload") + if action.get("guard") is not None or not isinstance(payload, dict) or payload.get("node") != "symbol": + raise PolicyError("POLICY-SYNTAX-001", "APPLY_TEMPLATE requires a single template identifier without WHEN", line) + template_id = payload["name"] + template = self.templates.get(template_id) + if template is None: + raise PolicyError("POLICY-SEMANTIC-001", f"unknown template {template_id}", line) + target["actions"].extend(dict(item) for item in template["actions"]) + target["forbidden"].extend(dict(item) for item in template["forbidden"]) + target["assertions"].extend(dict(item) for item in template["assertions"]) + if template["next"] and not target["next"]: + target["next"] = [dict(item) for item in template["next"]] + + def _collect_directives(self, target: dict[str, Any], raw_inline: dict[str, Any] | None = None) -> None: + while self.current is not None: + item = self.current + if item.text.startswith("DO "): + self.take() + action = parse_action(item.text[3:], item.line) + if action["opcode"] == "APPLY_TEMPLATE": + self._apply_template_to_target(target, action, item.line) + else: + target["actions"].append(action) + if raw_inline is not None: + raw_inline["actions"].append(action) + elif item.text.startswith("FORBID "): + self.take() + forbidden = parse_action(item.text[7:], item.line) + target["forbidden"].append(forbidden) + if raw_inline is not None: + raw_inline["forbidden"].append(forbidden) + elif item.text.startswith("ASSERT "): + self.take() + assertion = parse_expression(item.text[7:], item.line) + target["assertions"].append(assertion) + if raw_inline is not None: + raw_inline["assertions"].append(assertion) + elif item.text.startswith("NEXT "): + self.take() + next_targets = parse_next(item.text[5:], item.line) + target["next"] = next_targets + if raw_inline is not None: + raw_inline["next"] = next_targets + break + else: + break + + def parse_template(self) -> None: + header = self.take() + match = re.fullmatch(r"TEMPLATE (" + STABLE_ID + r")", header.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid TEMPLATE header", header.line) + template_id = match.group(1) + if template_id in self.templates: + raise PolicyError("POLICY-SEMANTIC-001", f"duplicate template {template_id}", header.line) + bundle: dict[str, Any] = {"actions": [], "forbidden": [], "assertions": [], "next": []} + self._collect_directives(bundle) + if self.current is None or self.current.text != "END": + line = self.current.line if self.current is not None else header.line + raise PolicyError("POLICY-SYNTAX-001", "TEMPLATE requires closing END", line) + self.take() + if not (bundle["actions"] or bundle["forbidden"] or bundle["assertions"] or bundle["next"]): + raise PolicyError("POLICY-SEMANTIC-001", f"empty template {template_id}", header.line) + self.templates[template_id] = bundle + + def parse_scope(self, result: dict[str, Any], outer_guard: dict[str, Any] | None = None) -> None: + header = self.take() + match = re.fullmatch(r"SCOPE WHEN (.+)", header.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid SCOPE WHEN header", header.line) + guard = parse_condition(match.group(1), header.line) + if outer_guard is not None: + guard = {"node": "binary", "operator": "AND", "left": outer_guard, "right": guard} + count = 0 + while self.current is not None and self.current.text != "END": + text = self.current.text + if text.startswith("RULE "): + result["rules"].append(self.parse_rule(scope_guard=guard)) + count += 1 + elif text.startswith("TRANSITION "): + result["transitions"].extend(self.parse_transitions(scope_guard=guard)) + count += 1 + elif text.startswith("SCOPE "): + self.parse_scope(result, outer_guard=guard) + count += 1 + else: + raise PolicyError("POLICY-SYNTAX-001", "SCOPE block accepts only RULE, TRANSITION, or nested SCOPE", self.current.line) + if self.current is None or self.current.text != "END": + line = self.current.line if self.current is not None else header.line + raise PolicyError("POLICY-SYNTAX-001", "SCOPE requires closing END", line) + self.take() + if count == 0: + raise PolicyError("POLICY-SEMANTIC-001", "empty SCOPE block", header.line) + + def parse_rule(self, scope_guard: dict[str, Any] | None = None) -> dict[str, Any]: + header = self.take() + match = re.fullmatch(r"RULE (" + STABLE_ID + r")(?: TYPE (REQUIRED|FORBIDDEN))?", header.text) + if not match: + raise PolicyError("POLICY-SYNTAX-001", "invalid RULE header", header.line) + if not self.current or not self.current.text.startswith("WHEN "): + raise PolicyError("POLICY-SYNTAX-001", "RULE requires WHEN", header.line) + condition_item = self.take() + own_condition = parse_condition(condition_item.text[5:], condition_item.line) + condition = own_condition + if scope_guard is not None: + self.scoped_rule_count += 1 + condition = {"node": "binary", "operator": "AND", "left": scope_guard, "right": own_condition} + rule: dict[str, Any] = { + "id": match.group(1), + "type": match.group(2) or "REQUIRED", + "condition": condition, + "actions": [], + "forbidden": [], + "assertions": [], + "next": [], + } + raw_inline: dict[str, Any] = { + "id": match.group(1), + "condition": own_condition, + "actions": [], + "forbidden": [], + "assertions": [], + "next": [], + } + self._collect_directives(rule, raw_inline) + self.uncompacted_rules.append(raw_inline) + return rule + + @staticmethod + def semantic_checks(ir: dict[str, Any]) -> None: + rule_ids = [rule["id"] for rule in ir["rules"]] + if len(rule_ids) != len(set(rule_ids)): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate rule identifier") + if len(ir["states"]) != len(set(ir["states"])): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate state") + binding_names = [item["name"] for item in ir["bindings"]] + if len(binding_names) != len(set(binding_names)): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate binding") + + +def parse(source: str) -> dict[str, Any]: + return PolicyParser(source).parse() + + +def parse_markdown(source: str) -> dict[str, Any]: + return parse(extract_markdown(source)) + + +def _keys(value: dict[str, Any], allowed: set[str], required: set[str], label: str) -> None: + if not isinstance(value, dict): + raise PolicyError("POLICY-SEMANTIC-001", f"{label} must be an object") + unknown = set(value) - allowed + missing = required - set(value) + if unknown or missing: + raise PolicyError("POLICY-SEMANTIC-001", f"closed {label}: unknown={sorted(unknown)}, missing={sorted(missing)}") + + +def validate_expression(value: Any) -> None: + if not isinstance(value, dict) or "node" not in value: + raise PolicyError("POLICY-SEMANTIC-001", "expression must be a typed object") + node = value["node"] + if node == "literal": + _keys(value, {"node", "value"}, {"node", "value"}, "literal") + if isinstance(value["value"], (dict, list)) or value["value"] is None: + raise PolicyError("POLICY-SEMANTIC-001", "invalid literal") + if isinstance(value["value"], float) and not math.isfinite(value["value"]): + raise PolicyError("POLICY-SEMANTIC-001", "literal number must be finite") + elif node == "symbol": + _keys(value, {"node", "name"}, {"node", "name"}, "symbol") + if not isinstance(value["name"], str) or not re.fullmatch( + r"(?:" + SYMBOL + r"|\{" + SYMBOL + r"\})", value["name"] + ) or len(value["name"]) > 160: + raise PolicyError("POLICY-SEMANTIC-001", "invalid symbol") + elif node == "unary": + _keys(value, {"node", "operator", "operand"}, {"node", "operator", "operand"}, "unary") + if value["operator"] not in {"NOT", "-"}: + raise PolicyError("POLICY-SEMANTIC-001", "invalid unary operator") + validate_expression(value["operand"]) + elif node == "binary": + _keys(value, {"node", "operator", "left", "right"}, {"node", "operator", "left", "right"}, "binary") + if value["operator"] not in ExpressionParser.PRECEDENCE: + raise PolicyError("POLICY-SEMANTIC-001", "invalid binary operator") + validate_expression(value["left"]) + validate_expression(value["right"]) + elif node in {"list", "sequence"}: + _keys(value, {"node", "items"}, {"node", "items"}, node) + if ( + not isinstance(value["items"], list) + or len(value["items"]) > 256 + or (node == "sequence" and len(value["items"]) < 2) + ): + raise PolicyError("POLICY-SEMANTIC-001", f"invalid {node}") + for item in value["items"]: + validate_expression(item) + else: + raise PolicyError("POLICY-SEMANTIC-001", f"unknown expression node {node!r}") + + +def validate_ir(ir: Any) -> None: + if not isinstance(ir, dict): + raise PolicyError("POLICY-SEMANTIC-001", "Policy IR must be an object") + root_keys = {"schema", "dialect", "language_version", "document", "environment", "bindings", "rules", "assertions", "states", "transitions"} + _keys(ir, root_keys, root_keys, "Policy IR") + if (ir["schema"], ir["dialect"], ir["language_version"]) != ("wellmanifest.policy/ir/v1", "wellmanifest.policy/v1", "1"): + raise PolicyError("POLICY-SEMANTIC-001", "incompatible Policy IR identity") + collection_limits = { + "environment": 128, + "bindings": 256, + "rules": 4096, + "assertions": 1024, + "states": 256, + "transitions": 1024, + } + for name, limit in collection_limits.items(): + if not isinstance(ir[name], list) or len(ir[name]) > limit: + raise PolicyError("POLICY-SEMANTIC-001", f"invalid {name} collection") + document_keys = {"name", "version", "language", "mode", "purpose", "policy"} + _keys(ir["document"], document_keys, document_keys, "document") + document = ir["document"] + if not isinstance(document["name"], str) or not re.fullmatch(SYMBOL, document["name"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid document name") + if isinstance(document["version"], bool) or not isinstance(document["version"], int) or document["version"] < 1: + raise PolicyError("POLICY-SEMANTIC-001", "invalid document version") + if document["language"] is not None and ( + not isinstance(document["language"], str) or not re.fullmatch(SYMBOL, document["language"]) + ): + raise PolicyError("POLICY-SEMANTIC-001", "invalid document language") + if document["mode"] not in {"STRICT", "PROCEDURAL"}: + raise PolicyError("POLICY-SEMANTIC-001", "invalid document mode") + for name, limit in (("purpose", 1000), ("policy", 320)): + if document[name] is not None and (not isinstance(document[name], str) or len(document[name]) > limit): + raise PolicyError("POLICY-SEMANTIC-001", f"invalid document {name}") + environment_names: list[str] = [] + for environment in ir["environment"]: + if not isinstance(environment, dict): + raise PolicyError("POLICY-SEMANTIC-001", "environment binding must be an object") + kind = environment.get("kind") + if kind == "env_file": + _keys(environment, {"kind", "path", "required"}, {"kind", "path", "required"}, "env_file") + if not isinstance(environment["path"], str) or not environment["path"] or len(environment["path"]) > 320: + raise PolicyError("POLICY-SEMANTIC-001", "invalid ENV_FILE path") + if not isinstance(environment["required"], bool): + raise PolicyError("POLICY-SEMANTIC-001", "invalid ENV_FILE requirement") + elif kind == "variable": + keys = {"kind", "name", "value_type", "required", "default"} + _keys(environment, keys, keys, "variable") + _validate_environment_name_type(environment) + if not isinstance(environment["required"], bool): + raise PolicyError("POLICY-SEMANTIC-001", "invalid VARIABLE requirement") + if environment["default"] is not None: + validate_expression({"node": "literal", "value": environment["default"]}) + _validate_variable_default(environment["value_type"], environment["default"]) + environment_names.append(environment["name"]) + elif kind == "secret": + keys = {"kind", "name", "value_type", "required", "redact"} + _keys(environment, keys, keys, "secret") + _validate_environment_name_type(environment) + if environment["required"] is not True or environment["redact"] is not True: + raise PolicyError("POLICY-SEMANTIC-001", "SECRET must be required and redacted") + environment_names.append(environment["name"]) + else: + raise PolicyError("POLICY-SEMANTIC-001", "unknown environment binding kind") + if len(environment_names) != len(set(environment_names)): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate environment name") + for binding in ir["bindings"]: + _keys(binding, {"name", "operator", "value"}, {"name", "operator", "value"}, "binding") + if not isinstance(binding["name"], str) or not re.fullmatch(SYMBOL, binding["name"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid binding name") + if binding["operator"] not in {"=", "IN"}: + raise PolicyError("POLICY-SEMANTIC-001", "invalid binding operator") + validate_expression(binding["value"]) + binding_names = [binding["name"] for binding in ir["bindings"]] + if len(binding_names) != len(set(binding_names)): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate binding") + for rule in ir["rules"]: + rule_keys = {"id", "type", "condition", "actions", "forbidden", "assertions", "next"} + _keys(rule, rule_keys, rule_keys, "rule") + if not isinstance(rule["id"], str) or not re.fullmatch(STABLE_ID, rule["id"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid rule identifier") + if rule["type"] not in {"REQUIRED", "FORBIDDEN"}: + raise PolicyError("POLICY-SEMANTIC-001", "invalid rule type") + for name, limit in (("actions", 128), ("forbidden", 128), ("assertions", 128), ("next", 32)): + if not isinstance(rule[name], list) or len(rule[name]) > limit: + raise PolicyError("POLICY-SEMANTIC-001", f"invalid rule {name}") + validate_expression(rule["condition"]) + for action in rule["actions"] + rule["forbidden"]: + _keys(action, {"kind", "opcode", "payload", "guard"}, {"kind", "opcode", "payload", "guard"}, "action") + if ( + action["kind"] != "action" + or not isinstance(action["opcode"], str) + or not re.fullmatch(r"[A-Z][A-Z0-9_]*", action["opcode"]) + or len(action["opcode"]) > 96 + ): + raise PolicyError("POLICY-SEMANTIC-001", "invalid action identity") + if action["payload"] is not None: + validate_expression(action["payload"]) + if action["guard"] is not None: + validate_expression(action["guard"]) + for assertion in rule["assertions"]: + validate_expression(assertion) + for target in rule["next"]: + _keys(target, {"target", "condition"}, {"target", "condition"}, "next target") + if not isinstance(target["target"], str) or not re.fullmatch(SYMBOL, target["target"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid NEXT target") + if target["condition"] is not None: + validate_expression(target["condition"]) + if len({rule["id"] for rule in ir["rules"]}) != len(ir["rules"]): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate rule identifier") + for assertion in ir["assertions"]: + validate_expression(assertion) + if any(not isinstance(state, str) or not re.fullmatch(SYMBOL, state) for state in ir["states"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid state") + if len(set(ir["states"])) != len(ir["states"]): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate state") + states = set(ir["states"]) + for rule in ir["rules"]: + for target in rule["next"]: + if target["target"] not in states: + raise PolicyError("POLICY-SEMANTIC-001", "NEXT target references undeclared state") + transition_edges: list[tuple[str, str]] = [] + for transition in ir["transitions"]: + _keys(transition, {"from", "to", "condition"}, {"from", "to", "condition"}, "transition") + if any(not isinstance(transition[name], str) or not re.fullmatch(SYMBOL, transition[name]) for name in ("from", "to")): + raise PolicyError("POLICY-SEMANTIC-001", "invalid transition state") + if transition["from"] not in states or transition["to"] not in states: + raise PolicyError("POLICY-SEMANTIC-001", "transition references undeclared state") + if transition["condition"] is not None: + validate_expression(transition["condition"]) + transition_edges.append((transition["from"], transition["to"])) + if len(transition_edges) != len(set(transition_edges)): + raise PolicyError("POLICY-SEMANTIC-001", "duplicate transition") + + +def _validate_environment_name_type(environment: dict[str, Any]) -> None: + if not isinstance(environment["name"], str) or not re.fullmatch(SYMBOL, environment["name"]): + raise PolicyError("POLICY-SEMANTIC-001", "invalid environment name") + if environment["value_type"] not in SCALAR_TYPES: + raise PolicyError("POLICY-SEMANTIC-001", "invalid environment scalar type") + + +def _validate_variable_default(value_type: str, default: Any, line: int | None = None) -> None: + valid = False + if value_type == "STRING": + valid = isinstance(default, str) and "\x00" not in default + elif value_type == "PATH": + valid = isinstance(default, str) and bool(default) and "\x00" not in default + elif value_type == "URL": + if isinstance(default, str) and "\x00" not in default: + parsed = urlsplit(default) + valid = bool(parsed.scheme and parsed.netloc) + elif value_type == "INTEGER": + valid = isinstance(default, int) and not isinstance(default, bool) + elif value_type == "NUMBER": + valid = isinstance(default, (int, float)) and not isinstance(default, bool) and math.isfinite(default) + elif value_type == "BOOLEAN": + valid = isinstance(default, bool) + if not valid: + raise PolicyError("POLICY-SEMANTIC-001", f"VARIABLE default literal does not match TYPE {value_type}", line) + + +def validate_candidate(candidate: Any) -> None: + validate_ir(candidate) + for rule in candidate["rules"]: + for action in rule["actions"] + rule["forbidden"]: + if action["opcode"] not in SAFE_CANDIDATE_OPCODES: + raise PolicyError("POLICY-SECURITY-001", f"candidate opcode {action['opcode']} is not proposal-safe") + + +def schema_is_closed(schema: Any) -> bool: + if isinstance(schema, dict): + if schema.get("type") == "object" and schema.get("additionalProperties") is not False: + return False + return all(schema_is_closed(value) for value in schema.values()) + if isinstance(schema, list): + return all(schema_is_closed(value) for value in schema) + return True + + +def _walk_symbols(node: Any, out: set[str]) -> None: + if isinstance(node, dict): + if node.get("node") == "symbol" and isinstance(node.get("name"), str): + out.add(node["name"]) + for value in node.values(): + _walk_symbols(value, out) + elif isinstance(node, list): + for item in node: + _walk_symbols(item, out) + + +def _top_and_conjuncts(node: dict[str, Any]) -> list[dict[str, Any]]: + if node.get("node") == "binary" and node.get("operator") == "AND": + return _top_and_conjuncts(node["left"]) + _top_and_conjuncts(node["right"]) + return [node] + + +def audit_compaction(source: str, *, markdown: bool = False) -> dict[str, Any]: + raw_policy = extract_markdown(source) if markdown else source + parser = PolicyParser(raw_policy) + ir = parser.parse() + findings: list[dict[str, Any]] = [] + saved_lines = 0 + + symbols: set[str] = set() + _walk_symbols(ir["rules"], symbols) + _walk_symbols(ir["assertions"], symbols) + _walk_symbols(ir["bindings"], symbols) + prose_symbols = sorted( + (name for name in symbols if len(name) > 48 or name.count("_") >= 6), + key=lambda item: (-len(item), item), + ) + if prose_symbols: + findings.append( + { + "code": "POLICY-COMPACT-001", + "construct": "SYMBOL_BINDING / OQL_REF", + "count": len(prose_symbols), + "examples": prose_symbols[:10], + "message": "Prose-encoded symbols (>48 chars or >=6 underscores) should be replaced with atomic domain symbols and contract references", + } + ) + + fan_in_groups: dict[tuple[str, str], list[str]] = {} + for transition in parser.uncompacted_transitions: + cond_key = json.dumps(transition["condition"], sort_keys=True) + key = (transition["to"], cond_key) + fan_in_groups.setdefault(key, []).append(transition["from"]) + for (target, _), origins in sorted(fan_in_groups.items()): + if len(origins) >= 3: + delta = len(origins) - 1 + saved_lines += delta + findings.append( + { + "code": "POLICY-COMPACT-002", + "construct": f"TRANSITION [{', '.join(origins)}] -> {target}", + "count": len(origins), + "lines_saved": delta, + "message": f"{len(origins)} transitions into {target} share an identical guard and can collapse into one state-set TRANSITION", + } + ) + + conjunct_rules: dict[str, list[str]] = {} + for rule in parser.uncompacted_rules: + seen_in_rule: set[str] = set() + for conjunct in _top_and_conjuncts(rule["condition"]): + ckey = json.dumps(conjunct, sort_keys=True) + if ckey not in seen_in_rule: + seen_in_rule.add(ckey) + conjunct_rules.setdefault(ckey, []).append(rule["id"]) + for ckey, rule_ids in sorted(conjunct_rules.items(), key=lambda item: (-len(item[1]), item[0])): + if len(rule_ids) >= 3: + delta = len(rule_ids) - 1 + saved_lines += delta + findings.append( + { + "code": "POLICY-COMPACT-003", + "construct": "SCOPE WHEN ... END", + "count": len(rule_ids), + "lines_saved": delta, + "rules": rule_ids, + "guard": json.loads(ckey), + "message": f"Guard predicate is repeated across {len(rule_ids)} rules and can be factored into SCOPE WHEN", + } + ) + + directive_support: dict[str, list[str]] = {} + for rule in parser.uncompacted_rules: + rule_directives: set[str] = set() + for act in rule["actions"]: + rule_directives.add("DO:" + json.dumps(act, sort_keys=True)) + for fbd in rule["forbidden"]: + rule_directives.add("FORBID:" + json.dumps(fbd, sort_keys=True)) + for asrt in rule["assertions"]: + rule_directives.add("ASSERT:" + json.dumps(asrt, sort_keys=True)) + if rule["next"]: + rule_directives.add("NEXT:" + json.dumps(rule["next"], sort_keys=True)) + for dkey in rule_directives: + directive_support.setdefault(dkey, []).append(rule["id"]) + + support_bundles: dict[tuple[str, ...], list[str]] = {} + for dkey, r_ids in directive_support.items(): + if len(r_ids) >= 2: + support_bundles.setdefault(tuple(r_ids), []).append(dkey) + + for r_tuple, dkeys in sorted(support_bundles.items(), key=lambda item: (-len(item[0]) * len(item[1]), item[0])): + if len(dkeys) >= 2: + dcount = len(dkeys) + rcount = len(r_tuple) + delta = (rcount - 1) * (dcount - 1) + saved_lines += max(0, delta) + findings.append( + { + "code": "POLICY-COMPACT-004", + "construct": "TEMPLATE ... END + DO APPLY_TEMPLATE ", + "count": rcount, + "directives_per_rule": dcount, + "lines_saved": max(0, delta), + "rules": list(r_tuple), + "message": f"Shared {dcount}-directive bundle across {rcount} rules can be extracted into a TEMPLATE", + } + ) + + return { + "schema": "wellmanifest.policy/compaction-audit/v1", + "document": ir["document"]["name"], + "stats": { + "rules": len(ir["rules"]), + "states": len(ir["states"]), + "transitions": len(ir["transitions"]), + "templates_used": len(parser.templates), + "scoped_rules": parser.scoped_rule_count, + "state_set_transitions": parser.state_set_transition_count, + "findings": len(findings), + "estimated_lines_saved": saved_lines, + }, + "findings": findings, + } + + +def self_test() -> None: + valid_path = ROOT / "examples/valid/contributing.policy" + invalid_path = ROOT / "examples/invalid/shell-injection.policy" + ir = parse(valid_path.read_text(encoding="utf-8")) + assert ir["document"]["version"] == 13 + assert ir["language_version"] == "1" + assert ir["rules"][0]["condition"]["node"] == "binary" + assert ir["rules"][0]["actions"][0]["payload"]["node"] == "symbol" + assert "text" not in json.dumps(ir, sort_keys=True) + schema = json.loads((ROOT / "schemas/policy-ir.schema.json").read_text(encoding="utf-8")) + assert schema_is_closed(schema) + grammar = (ROOT / "spec/policy-dsl-candidate.v1.gbnf").read_text(encoding="utf-8") + for forbidden in ('\"EXECUTE\"', '\"RUN\"', '\"approval_evidence\":', '\"execution_envelope\":', '\"credentials\":'): + assert forbidden not in grammar + try: + parse(invalid_path.read_text(encoding="utf-8")) + except PolicyError as error: + assert error.code == "POLICY-SECURITY-001" + else: + raise AssertionError("invalid fixture was accepted") + markdown = "before\n```dsl\n" + valid_path.read_text(encoding="utf-8") + "```\n```bash\nDO RUN evil\n```\n" + assert parse_markdown(markdown)["document"]["name"] == "CONTRIBUTING" + try: + parse_markdown(markdown + "```dsl\nDONE WHEN\n TESTS_PASSED\n```\n") + except PolicyError as error: + assert error.code == "POLICY-SYNTAX-001" + else: + raise AssertionError("unclassified dsl fence was silently ignored") + print("POLICY-CONFORMANCE-PASS") + + +def main(argv: Iterable[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + subparsers = parser.add_subparsers(dest="command", required=True) + validate_command = subparsers.add_parser("validate") + validate_command.add_argument("path", type=Path) + markdown_command = subparsers.add_parser("validate-markdown") + markdown_command.add_argument("path", type=Path) + ir_command = subparsers.add_parser("ir") + ir_command.add_argument("path", type=Path) + ir_command.add_argument("--check-schema", action="store_true") + candidate_command = subparsers.add_parser("validate-candidate") + candidate_command.add_argument("path", type=Path) + audit_command = subparsers.add_parser("audit") + audit_command.add_argument("path", type=Path) + audit_command.add_argument("--markdown", action="store_true") + subparsers.add_parser("self-test") + args = parser.parse_args(list(argv) if argv is not None else None) + try: + if args.command == "self-test": + self_test() + elif args.command == "validate-candidate": + validate_candidate(json.loads(args.path.read_text(encoding="utf-8"))) + print("POLICY-CANDIDATE-PASS") + elif args.command == "validate-markdown": + parse_markdown(args.path.read_text(encoding="utf-8")) + print("POLICY-MARKDOWN-PASS") + elif args.command == "audit": + raw = args.path.read_text(encoding="utf-8") + is_md = args.markdown or args.path.suffix.lower() == ".md" + report = audit_compaction(raw, markdown=is_md) + print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)) + else: + ir = parse(args.path.read_text(encoding="utf-8")) + if args.command == "ir": + if args.check_schema: + schema = json.loads((ROOT / "schemas/policy-ir.schema.json").read_text(encoding="utf-8")) + if not schema_is_closed(schema): + raise PolicyError("POLICY-SEMANTIC-001", "Policy IR Schema is not closed") + validate_ir(ir) + print(json.dumps(ir, ensure_ascii=False, indent=2, sort_keys=True)) + else: + print("POLICY-VALIDATION-PASS") + except (OSError, json.JSONDecodeError, PolicyError, AssertionError) as error: + print(error, file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.governance/prune_merged_worktrees.py b/.governance/prune_merged_worktrees.py index 6668c9f..b2a8142 100755 --- a/.governance/prune_merged_worktrees.py +++ b/.governance/prune_merged_worktrees.py @@ -1,22 +1,46 @@ #!/usr/bin/env python3 -"""Safely identify and prune linked worktrees whose branches are already merged. - -Validates that: -1. The worktree is not the primary checkout. -2. The worktree is clean (no uncommitted, modified, or untracked changes). -3. The worktree HEAD is reachable from target branch (default: origin/main or main). -4. After removing the worktree, deletes the released local branch. -5. Runs git worktree prune. +"""Prune clean integrated checkouts while preserving changed or declined refs. + +The caller must separately verify ownership, released writers and cleanup +permission. Git removal releases only the exact checkout registration. Branch +cleanup verifies the integration target and expected branch tip atomically; +this helper never forces deletion or globally prunes other registrations. """ from __future__ import annotations import argparse +from contextlib import contextmanager +import hashlib import json +import os +import re +import stat import subprocess import sys +import tempfile from pathlib import Path -from typing import Any +from typing import Any, Callable, Iterator + +CANONICAL_WORKTREE_RE = re.compile(r"^(ticket-([0-9]{3,}))--([a-z0-9]+(?:-[a-z0-9]+)*)$") +TERMINAL_LEASE_PHASES = frozenset({"released", "merged", "closed"}) +SAFE_TOP_LEVEL_RUNTIME_NAMES = frozenset({ + ".venv", + "venv", + ".pytest_cache", + ".mypy_cache", + ".ruff_cache", + ".hypothesis", + ".tox", + ".nox", + ".planfile", + ".coverage", + "htmlcov", + "node_modules", + "build", + "dist", +}) +SAFE_SUBACTOR_RUNTIME_DIRS = frozenset({"cache", "sessions", "recovery", "receipts"}) def git_cmd(cwd: Path, *args: str) -> subprocess.CompletedProcess[str]: @@ -52,7 +76,9 @@ def get_worktrees(repo: Path) -> list[dict[str, str]]: def is_worktree_clean(path: Path) -> bool: - res = git_cmd(path, "status", "--porcelain") + # Ignored files may contain unique data, so retain their checkout unless + # separately proven disposable under a terminal canonical lease. + res = git_cmd(path, "status", "--porcelain", "--untracked-files=all", "--ignored=matching") return res.returncode == 0 and not res.stdout.strip() @@ -61,77 +87,702 @@ def is_ancestor(repo: Path, commit: str, target: str) -> bool: return res.returncode == 0 +def _commit(repo: Path, ref: str) -> str | None: + result = git_cmd(repo, "rev-parse", "--verify", ref + "^{commit}") + value = result.stdout.strip() + if result.returncode == 0 and re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", value): + return value + return None + + +def _target(repo: Path, name: str) -> tuple[str, str, str]: + if name.startswith(("refs/heads/", "refs/remotes/")): + candidates = [(name, name)] + elif name.startswith("origin/"): + candidates = [(name, "refs/remotes/" + name)] + else: + candidates = [("origin/" + name, "refs/remotes/origin/" + name), + (name, "refs/heads/" + name)] + for display, full in candidates: + if full.startswith("refs/remotes/") and "/" not in full.removeprefix("refs/remotes/"): + continue + if git_cmd(repo, "check-ref-format", full).returncode != 0: + continue + if git_cmd(repo, "symbolic-ref", "--quiet", full).returncode == 0: + raise ValueError("Target must identify a direct branch reference, not a symbolic alias") + sha = _commit(repo, full) + if sha is not None: + return display, full, sha + raise ValueError(f"Target branch '{name}' not found in {repo}") + + +def _checkout_matches(path: Path, head: str, branch: str) -> bool: + if _commit(path, "HEAD") != head: + return False + symbolic = git_cmd(path, "symbolic-ref", "--quiet", "HEAD") + if symbolic.returncode not in (0, 1): + return False + return (symbolic.stdout.strip() if symbolic.returncode == 0 else "") == branch + + +def _no_symlink_components(path: Path) -> bool: + absolute = Path(os.path.abspath(path)) + if not absolute.is_absolute(): + return False + current = Path(absolute.anchor) + try: + for part in absolute.parts[1:]: + current = current / part + st = current.lstat() + if stat.S_ISLNK(st.st_mode): + return False + except OSError: + return False + return True + + +def _is_canonical_worktree(primary: Path, path: Path) -> tuple[bool, str | None]: + abs_primary = Path(os.path.abspath(primary)) + abs_path = Path(os.path.abspath(path)) + if abs_path.parent != abs_primary / ".worktrees": + return False, None + match = CANONICAL_WORKTREE_RE.fullmatch(abs_path.name) + if match is None: + return False, None + if not _no_symlink_components(abs_primary) or not _no_symlink_components(abs_path): + return False, None + return True, match.group(1) + + +def _validate_terminal_lease_bytes(raw: bytes, worktree_id: str, ticket_id: str) -> tuple[bool, str]: + if len(raw) > 65536: + return False, "lease exceeds bounded size" + try: + lease = json.loads(raw.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError): + return False, "lease unreadable" + if not isinstance(lease, dict): + return False, "lease invalid" + if lease.get("worktreeId") != worktree_id or lease.get("ticketId") != ticket_id: + return False, "lease binding mismatch" + phase = lease.get("phase") + if lease.get("publicationFrozen") is not False or phase not in TERMINAL_LEASE_PHASES: + return False, f"lease phase is {phase!r}" + return True, "ok" + + +@contextmanager +def _noop_lease_guard() -> Iterator[tuple[bool, str, Callable[[], tuple[bool, str]]]]: + yield True, "ok", lambda: (True, "ok") + + +@contextmanager +def _terminal_lease_guard( + primary: Path, + worktree_id: str, + ticket_id: str, + *, + require_lease: bool, + dry_run: bool, +) -> Iterator[tuple[bool, str, Callable[[], tuple[bool, str]]]]: + """Hold an exclusive lease lock across destructive pruning and verify inode/content CAS.""" + lease_dir = Path(os.path.abspath(primary)) / ".subactor" / "leases" + lease_name = f"{worktree_id}.json" + lock_name = f"{worktree_id}.json.lock" + lease_path = lease_dir / lease_name + if not os.path.lexists(lease_dir): + if require_lease: + yield False, "terminal lease required", lambda: (False, "terminal lease required") + return + yield ( + True, + "ok", + lambda: (False, "lease changed since observation") if os.path.lexists(lease_path) else (True, "ok"), + ) + return + if not _no_symlink_components(lease_dir): + yield False, "unsafe lease directory", lambda: (False, "unsafe lease directory") + return + + if os.name == "posix" and hasattr(os, "O_NOFOLLOW"): + import fcntl + + dir_flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + descriptors: list[int] = [] + try: + descriptors.append(os.open(lease_dir.anchor, dir_flags)) + for part in lease_dir.parts[1:]: + descriptors.append(os.open(part, dir_flags, dir_fd=descriptors[-1])) + except OSError: + for desc in reversed(descriptors): + os.close(desc) + yield False, "unsafe lease directory", lambda: (False, "unsafe lease directory") + return + + try: + lease_fd = descriptors[-1] + + def verify_dir() -> bool: + try: + for parent_fd, child_fd, part in zip(descriptors, descriptors[1:], lease_dir.parts[1:]): + named = os.stat(part, dir_fd=parent_fd, follow_symlinks=False) + held = os.fstat(child_fd) + if not stat.S_ISDIR(named.st_mode) or (named.st_dev, named.st_ino) != (held.st_dev, held.st_ino): + return False + except OSError: + return False + return True + + if not verify_dir(): + yield False, "unsafe lease directory", lambda: (False, "unsafe lease directory") + return + + if dry_run: + try: + lock_st = os.stat(lock_name, dir_fd=lease_fd, follow_symlinks=False) + except FileNotFoundError: + lock_st = None + except OSError: + yield False, "unsafe lease lock", lambda: (False, "unsafe lease lock") + return + if lock_st is not None: + if not stat.S_ISREG(lock_st.st_mode) or lock_st.st_nlink != 1: + yield False, "unsafe lease lock", lambda: (False, "unsafe lease lock") + return + try: + probe_fd = os.open(lock_name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=lease_fd) + except OSError: + yield False, "unsafe lease lock", lambda: (False, "unsafe lease lock") + return + try: + try: + fcntl.flock(probe_fd, fcntl.LOCK_SH | fcntl.LOCK_NB) + except BlockingIOError: + yield False, "lease lock active", lambda: (False, "lease lock active") + return + fcntl.flock(probe_fd, fcntl.LOCK_UN) + finally: + os.close(probe_fd) + try: + named_st = os.stat(lease_name, dir_fd=lease_fd, follow_symlinks=False) + except FileNotFoundError: + if require_lease: + yield False, "terminal lease required", lambda: (False, "terminal lease required") + else: + yield True, "ok", lambda: (True, "ok") + return + except OSError: + yield False, "lease unreadable", lambda: (False, "lease unreadable") + return + if not stat.S_ISREG(named_st.st_mode) or named_st.st_nlink != 1: + yield False, "lease must be a regular file", lambda: (False, "lease must be a regular file") + return + try: + fd = os.open(lease_name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=lease_fd) + with os.fdopen(fd, "rb") as stream: + raw = stream.read(65537) + except OSError: + yield False, "lease unreadable", lambda: (False, "lease unreadable") + return + if not verify_dir(): + yield False, "unsafe lease directory", lambda: (False, "unsafe lease directory") + return + ok, detail = _validate_terminal_lease_bytes(raw, worktree_id, ticket_id) + yield ok, detail, (lambda: (ok, detail)) + return + + try: + lock_fd = os.open( + lock_name, + os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, + 0o600, + dir_fd=lease_fd, + ) + except OSError: + yield False, "unsafe lease lock", lambda: (False, "unsafe lease lock") + return + + try: + lock_info = os.fstat(lock_fd) + if not stat.S_ISREG(lock_info.st_mode) or lock_info.st_nlink != 1: + yield False, "unsafe lease lock", lambda: (False, "unsafe lease lock") + return + try: + fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError: + yield False, "lease lock active", lambda: (False, "lease lock active") + return + + def inspect_locked() -> tuple[bool, str, tuple[Any, ...] | None]: + if not verify_dir(): + return False, "unsafe lease directory", None + try: + named_lock = os.stat(lock_name, dir_fd=lease_fd, follow_symlinks=False) + except OSError: + return False, "unsafe lease lock", None + if ( + not stat.S_ISREG(named_lock.st_mode) + or named_lock.st_nlink != 1 + or (named_lock.st_dev, named_lock.st_ino) != (lock_info.st_dev, lock_info.st_ino) + ): + return False, "unsafe lease lock", None + try: + named_lease = os.stat(lease_name, dir_fd=lease_fd, follow_symlinks=False) + except FileNotFoundError: + if require_lease: + return False, "terminal lease required", None + return True, "ok", ("absent",) + except OSError: + return False, "lease unreadable", None + if not stat.S_ISREG(named_lease.st_mode) or named_lease.st_nlink != 1: + return False, "lease must be a regular file", None + try: + fd = os.open(lease_name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=lease_fd) + with os.fdopen(fd, "rb") as stream: + st = os.fstat(stream.fileno()) + if ( + not stat.S_ISREG(st.st_mode) + or st.st_nlink != 1 + or (st.st_dev, st.st_ino) != (named_lease.st_dev, named_lease.st_ino) + ): + return False, "lease must be a regular file", None + raw = stream.read(65537) + except OSError: + return False, "lease unreadable", None + ok, detail = _validate_terminal_lease_bytes(raw, worktree_id, ticket_id) + if not ok: + return False, detail, None + return True, "ok", ("present", st.st_dev, st.st_ino, hashlib.sha256(raw).hexdigest()) + + ok, detail, initial_cas = inspect_locked() + if not ok: + yield False, detail, (lambda: (False, detail)) + return + + def revalidate() -> tuple[bool, str]: + cur_ok, cur_detail, cur_cas = inspect_locked() + if not cur_ok: + return False, cur_detail + if cur_cas != initial_cas: + return False, "lease changed since observation" + return True, "ok" + + yield True, "ok", revalidate + finally: + os.close(lock_fd) + finally: + for desc in reversed(descriptors): + os.close(desc) + return + + # Non-POSIX fallback with exact inode/mtime/content CAS revalidation. + def inspect_non_posix() -> tuple[bool, str, tuple[Any, ...] | None]: + if not os.path.lexists(lease_path): + if require_lease: + return False, "terminal lease required", None + return True, "ok", ("absent",) + try: + st = lease_path.lstat() + if not stat.S_ISREG(st.st_mode): + return False, "lease must be a regular file", None + raw = lease_path.read_bytes() + except OSError: + return False, "lease unreadable", None + ok, detail = _validate_terminal_lease_bytes(raw, worktree_id, ticket_id) + if not ok: + return False, detail, None + return True, "ok", ("present", st.st_size, st.st_mtime_ns, hashlib.sha256(raw).hexdigest()) + + ok, detail, initial_cas = inspect_non_posix() + if not ok: + yield False, detail, (lambda: (False, detail)) + return + + def revalidate_non_posix() -> tuple[bool, str]: + cur_ok, cur_detail, cur_cas = inspect_non_posix() + if not cur_ok: + return False, cur_detail + if cur_cas != initial_cas: + return False, "lease changed since observation" + return True, "ok" + + yield True, "ok", revalidate_non_posix + + +def _check_terminal_lease(primary: Path, worktree_id: str, ticket_id: str) -> tuple[bool, str]: + with _terminal_lease_guard(primary, worktree_id, ticket_id, require_lease=True, dry_run=True) as (ok, detail, _): + return ok, detail + + +def _link_inside(raw: str, target: Path, prefix: str) -> bool: + value = raw.removesuffix(" (deleted)") + if value == prefix or (value.startswith(prefix) and value[len(prefix)] == "/"): + return True + if value.startswith("/") and ("//" in value or "/./" in value or value.endswith("/.")): + try: + Path(value).relative_to(target) + return True + except ValueError: + return False + return False + + +def _worktree_in_use(path: Path, *, proc_root: Path = Path("/proc")) -> str | None: + git_dir_res = git_cmd(path, "rev-parse", "--path-format=absolute", "--git-dir") + if git_dir_res.returncode != 0 or not git_dir_res.stdout.strip(): + return "worktree git metadata unavailable" + git_dir = Path(git_dir_res.stdout.strip()) + for lock_name in ("locked", "index.lock", "HEAD.lock"): + if os.path.lexists(git_dir / lock_name): + return f"worktree {lock_name} present" + if os.name != "posix" or not proc_root.is_dir(): + return None + target = Path(os.path.abspath(path)) + prefix = str(target) + self_pid = os.getpid() + try: + proc_entries = list(proc_root.iterdir()) + except OSError: + return None + for entry in proc_entries: + if not entry.name.isdigit(): + continue + pid = int(entry.name) + if pid == self_pid: + continue + candidates = [entry / "cwd", entry / "exe"] + try: + candidates.extend((entry / "fd").iterdir()) + except OSError: + pass + for link in candidates: + try: + dest = os.readlink(link) + except OSError: + continue + if _link_inside(dest, target, prefix): + return f"worktree in use by active process (pid {pid})" + return None + + +def is_safe_ignored_runtime_path(worktree: Path, relpath: str) -> bool: + if ( + not relpath + or relpath.startswith("/") + or "\\" in relpath + or "\0" in relpath + ): + return False + clean = relpath.rstrip("/") + if not clean: + return False + parts = clean.split("/") + if any(part in {"", ".", ".."} for part in parts): + return False + top = parts[0] + leaf = parts[-1] + if len(parts) == 1 and ( + top in SAFE_TOP_LEVEL_RUNTIME_NAMES + or top.startswith(".coverage.") + or top.endswith(".egg-info") + ): + return True + if leaf == "__pycache__" or leaf.endswith((".pyc", ".pyo")): + return True + if leaf.endswith(".egg-info") and len(parts) <= 3: + return True + if len(parts) == 2 and top == ".subactor" and leaf in SAFE_SUBACTOR_RUNTIME_DIRS: + return True + if clean == ".subactor": + subactor_dir = worktree / ".subactor" + try: + st = subactor_dir.lstat() + if not stat.S_ISDIR(st.st_mode): + return False + children = [item.name for item in subactor_dir.iterdir()] + except OSError: + return False + return bool(children) and set(children) <= SAFE_SUBACTOR_RUNTIME_DIRS + return False + + +def _inspect_ignored_runtime_only(path: Path) -> tuple[bool, list[str]]: + res = git_cmd(path, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching") + if res.returncode != 0: + return False, [] + tokens = [tok for tok in res.stdout.split("\0") if tok] + if not tokens: + return True, [] + entries: list[str] = [] + for tok in tokens: + if not tok.startswith("!! "): + return False, [] + rel = tok[3:] + if not is_safe_ignored_runtime_path(path, rel): + return False, [] + entries.append(rel.rstrip("/")) + return True, entries + + +def _rmtree_at(parent_fd: int, name: str) -> None: + flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0) + dir_fd = os.open(name, flags, dir_fd=parent_fd) + try: + try: + os.fchmod(dir_fd, 0o700) + except OSError: + pass + for child in os.listdir(dir_fd): + child_st = os.stat(child, dir_fd=dir_fd, follow_symlinks=False) + if stat.S_ISDIR(child_st.st_mode): + _rmtree_at(dir_fd, child) + else: + os.unlink(child, dir_fd=dir_fd) + finally: + os.close(dir_fd) + os.rmdir(name, dir_fd=parent_fd) + + +def _remove_anchored_runtime_entry(worktree: Path, rel_entry: str) -> None: + if os.name != "posix" or not hasattr(os, "O_NOFOLLOW"): + import shutil + target = worktree / rel_entry + if not os.path.lexists(target): + return + st = target.lstat() + if stat.S_ISDIR(st.st_mode): + shutil.rmtree(target) + else: + target.unlink() + return + parts = [part for part in rel_entry.split("/") if part] + if not parts or any(part in {".", ".."} for part in parts): + raise ValueError(f"Unsafe runtime path: {rel_entry}") + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + fds = [os.open(str(Path(os.path.abspath(worktree))), flags)] + try: + for part in parts[:-1]: + fds.append(os.open(part, flags, dir_fd=fds[-1])) + parent_fd = fds[-1] + leaf = parts[-1] + try: + st = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False) + except FileNotFoundError: + return + if stat.S_ISDIR(st.st_mode): + _rmtree_at(parent_fd, leaf) + else: + os.unlink(leaf, dir_fd=parent_fd) + finally: + for fd in reversed(fds): + os.close(fd) + + +def _delete_exact_branch( + repo: Path, branch: str, head: str, target: str, target_sha: str, +) -> subprocess.CompletedProcess[str]: + # Prepare locks both exact names and verifies their expected OIDs. Inspect + # their direct/symbolic type while those locks are held, before committing. + command = ["git", "-C", str(repo), "update-ref", "--no-deref", "--stdin"] + transaction = (f"start\nverify {target} {target_sha}\n" + f"delete {branch} {head}\nprepare\n") + with tempfile.TemporaryFile(mode="w+t", encoding="utf-8", errors="replace") as errors: + try: + process = subprocess.Popen( + command, stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=errors, text=True, encoding="utf-8", errors="replace", + ) + except OSError as error: + return subprocess.CompletedProcess(command, 1, "", str(error)) + prefix = "" + output = "" + declined = None + try: + process.stdin.write(transaction) + process.stdin.flush() + prefix = process.stdout.readline() + process.stdout.readline() + if prefix != "start: ok\nprepare: ok\n": + declined = "reference transaction preparation failed" + else: + for ref in (target, branch): + if git_cmd(repo, "symbolic-ref", "--quiet", ref).returncode != 1: + declined = "reference became symbolic or could not be verified under lock" + break + if not declined: + try: + if any(item.get("branch") == branch for item in get_worktrees(repo)): + declined = "branch remains checked out elsewhere" + except RuntimeError as error: + declined = f"could not verify other checkout registrations: {error}" + if process.poll() is None: + process.stdin.write("abort\n" if declined else "commit\n") + process.stdin.flush() + output, _ = process.communicate() + except (OSError, ValueError) as error: + declined = f"reference transaction outcome unconfirmed: {error}" + finally: + if process.poll() is None or (process.stdout and not process.stdout.closed): + if process.poll() is None: + try: + process.stdin.write("abort\n") + process.stdin.flush() + except (OSError, ValueError): + pass + try: + remaining, _ = process.communicate(timeout=5) + output += remaining or "" + except subprocess.TimeoutExpired: + if process.poll() is None: + process.kill() + process.wait(timeout=5) + for stream in (process.stdin, process.stdout): + if stream and not stream.closed: + stream.close() + declined = "reference transaction interrupted; reconcile refs before retry" + errors.seek(0) + detail = errors.read() + if declined: + return subprocess.CompletedProcess(command, 1, prefix + output, declined + ": " + detail) + if process.returncode == 0 and "commit: ok\n" not in output: + return subprocess.CompletedProcess(command, 1, prefix + output, "commit outcome unconfirmed: " + detail) + return subprocess.CompletedProcess(command, process.returncode, prefix + output, detail) + + def prune_merged_worktrees( - repo: Path, target_branch: str = "main", dry_run: bool = False + repo: Path, + target_branch: str = "main", + dry_run: bool = False, + include_ignored_runtime: bool = True, ) -> dict[str, Any]: - target_ref = target_branch - if git_cmd(repo, "rev-parse", "--verify", f"origin/{target_branch}").returncode == 0: - target_ref = f"origin/{target_branch}" - elif git_cmd(repo, "rev-parse", "--verify", target_branch).returncode != 0: - raise ValueError(f"Target branch '{target_branch}' not found in {repo}") - + target_ref, target_full, target_sha = _target(repo, target_branch) wts = get_worktrees(repo) if not wts: return {"pruned": [], "skipped": []} - + primary = Path(wts[0].get("worktree", str(repo))) + target_name = (target_full.removeprefix("refs/heads/") + if target_full.startswith("refs/heads/") + else target_full.removeprefix("refs/remotes/").split("/", 1)[1]) pruned: list[dict[str, Any]] = [] skipped: list[dict[str, Any]] = [] - for wt in wts[1:]: - wt_path = Path(wt.get("worktree", "")) - wt_head = wt.get("HEAD", "") - wt_branch_raw = wt.get("branch", "") - branch_name = wt_branch_raw.removeprefix("refs/heads/") if wt_branch_raw else None + path = Path(wt.get("worktree", "")) + head = wt.get("HEAD", "") + branch = wt.get("branch", "") + name = branch.removeprefix("refs/heads/") if branch else None - if not wt_path.exists(): - skipped.append({"path": str(wt_path), "reason": "directory missing"}) - continue + def skip(reason: str, **extra: Any) -> None: + skipped.append({"path": str(path), "branch": name, "reason": reason, **extra}) - if not is_worktree_clean(wt_path): - skipped.append( - { - "path": str(wt_path), - "branch": branch_name, - "reason": "dirty (uncommitted changes)", - } - ) + if not path.exists(): + skip("directory missing") continue - - if not is_ancestor(repo, wt_head, target_ref): - skipped.append( - { - "path": str(wt_path), - "branch": branch_name, - "head": wt_head, - "reason": f"not merged into {target_ref}", - } - ) + if "locked" in wt: + skip("worktree locked") + continue + if branch and (not branch.startswith("refs/heads/") + or git_cmd(repo, "check-ref-format", branch).returncode != 0): + skip("invalid branch reference") + continue + if name == target_name or branch == target_full: + skip("target branch checkout") continue - if dry_run: - pruned.append({"path": str(wt_path), "branch": branch_name, "action": "would_remove"}) - else: - rm_res = git_cmd(repo, "worktree", "remove", str(wt_path)) - if rm_res.returncode != 0: - skipped.append( - { - "path": str(wt_path), - "branch": branch_name, - "reason": f"remove failed: {rm_res.stderr.strip()}", - } - ) + clean = is_worktree_clean(path) + runtime_entries: list[str] = [] + is_canonical, ticket_id = _is_canonical_worktree(primary, path) + + if not clean: + if not include_ignored_runtime or not is_canonical or ticket_id is None: + skip("dirty (uncommitted, untracked or ignored data)") + continue + only_safe_runtime, runtime_entries = _inspect_ignored_runtime_only(path) + if not only_safe_runtime or not runtime_entries: + skip("dirty (uncommitted, untracked or ignored data)") continue - if branch_name: - del_res = git_cmd(repo, "branch", "-d", branch_name) - if del_res.returncode != 0: - git_cmd(repo, "branch", "-D", branch_name) + if not is_ancestor(repo, head, target_sha): + skip(f"not merged into {target_ref}", head=head) + continue - pruned.append({"path": str(wt_path), "branch": branch_name, "action": "removed"}) + lease_file = primary / ".subactor" / "leases" / f"{path.name}.json" + require_lease = bool(runtime_entries) or os.path.lexists(lease_file) + guard_ctx = ( + _terminal_lease_guard( + primary, + path.name, + ticket_id, + require_lease=require_lease, + dry_run=dry_run, + ) + if (is_canonical and ticket_id is not None) + else _noop_lease_guard() + ) + with guard_ctx as (lease_ok, lease_detail, revalidate_lease): + if not lease_ok: + skip( + f"ignored runtime data retained ({lease_detail})" + if runtime_entries + else f"lease not terminal ({lease_detail})" + ) + continue + if is_canonical and ticket_id is not None: + in_use_reason = _worktree_in_use(path) + if in_use_reason is not None: + skip(in_use_reason) + continue + + if (_commit(repo, target_full) != target_sha + or not _checkout_matches(path, head, branch) + or (branch and _commit(repo, branch) != head)): + skip("checkout, branch or target changed since observation") + continue + if dry_run: + entry: dict[str, Any] = {"path": str(path), "branch": name, "action": "would_remove"} + if runtime_entries: + entry["cleanedIgnoredRuntime"] = True + pruned.append(entry) + continue - if not dry_run and pruned: - git_cmd(repo, "worktree", "prune") + rev_ok, rev_detail = revalidate_lease() + if not rev_ok: + skip( + f"ignored runtime data retained ({rev_detail})" + if runtime_entries + else f"lease not terminal ({rev_detail})" + ) + continue + if runtime_entries: + try: + for rel_entry in runtime_entries: + _remove_anchored_runtime_entry(path, rel_entry) + except (OSError, ValueError) as exc: + skip(f"ignored runtime cleanup failed: {exc}") + continue + if (_commit(repo, target_full) != target_sha + or not _checkout_matches(path, head, branch) + or (branch and _commit(repo, branch) != head)): + skip("checkout, branch or target changed since observation") + continue + rev_ok, rev_detail = revalidate_lease() + if not rev_ok: + skip(f"ignored runtime data retained ({rev_detail})") + continue + + # Git also refuses removal if tracked/untracked/non-runtime ignored data + # appeared after inspection; never turn its refusal into a force removal. + removed = git_cmd(repo, "worktree", "remove", str(path)) + if removed.returncode != 0: + skip(f"remove failed: {removed.stderr.strip()}") + continue + if branch: + deleted = _delete_exact_branch(repo, branch, head, target_full, target_sha) + if deleted.returncode != 0: + skip(f"branch cleanup declined or unconfirmed: {deleted.stderr.strip()}") + result_entry: dict[str, Any] = {"path": str(path), "branch": name, "action": "removed"} + if runtime_entries: + result_entry["cleanedIgnoredRuntime"] = True + pruned.append(result_entry) return {"target": target_ref, "pruned": pruned, "skipped": skipped} @@ -151,12 +802,29 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument( "--dry-run", action="store_true", help="Report what would be pruned without changing anything" ) + parser.add_argument( + "--include-ignored-runtime", + "--include-ignored-caches", + dest="include_ignored_runtime", + action="store_true", + default=True, + help="Allow pruning terminal-leased canonical worktrees containing only allowlisted ignored runtime caches (default)", + ) + parser.add_argument( + "--no-include-ignored-runtime", + dest="include_ignored_runtime", + action="store_false", + help="Retain canonical worktrees even when only allowlisted ignored runtime caches remain", + ) parser.add_argument("--json", action="store_true", help="Output JSON format") args = parser.parse_args(argv) try: report = prune_merged_worktrees( - args.repo.resolve(), target_branch=args.target_branch, dry_run=args.dry_run + args.repo.resolve(), + target_branch=args.target_branch, + dry_run=args.dry_run, + include_ignored_runtime=args.include_ignored_runtime, ) except Exception as exc: print(f"Error: {exc}", file=sys.stderr) diff --git a/.governance/remediation_intent.py b/.governance/remediation_intent.py index 9bb61cf..4f31abe 100755 --- a/.governance/remediation_intent.py +++ b/.governance/remediation_intent.py @@ -857,7 +857,7 @@ def _validate_planning_guidance(document, action_graph, errors): guidance.get("planningOrder"), "llmGuidance.planningOrder", errors, minimum=1 ) _string_list(guidance.get("openQuestions"), "llmGuidance.openQuestions", errors) - if set(planning_order) != set(action_graph): + if set(planning_order) != set(action_graph) or len(planning_order) != len(set(planning_order)): errors.append( _issue( MALFORMED_CODE, @@ -1113,15 +1113,17 @@ def _validate_analysis( def _validate_finding_paths(findings, allowed, forbidden, errors): - for finding in findings: - for affected_path in finding.get("affectedPaths", []): + for index, finding in enumerate(findings): + finding_id = finding.get("id") if isinstance(finding, dict) else None + id_str = str(finding_id) if finding_id is not None else str(index) + for affected_path in finding.get("affectedPaths", []) if isinstance(finding, dict) else []: if affected_path == "unresolved:agent": continue if not _matches(affected_path, allowed): errors.append( _issue( MALFORMED_CODE, - f"finding:{finding['id']}.affectedPaths", + f"finding:{id_str}.affectedPaths", f"path is outside scope.allowedPaths: {affected_path}", ) ) @@ -1129,7 +1131,7 @@ def _validate_finding_paths(findings, allowed, forbidden, errors): errors.append( _issue( MALFORMED_CODE, - f"finding:{finding['id']}.affectedPaths", + f"finding:{id_str}.affectedPaths", f"path matches scope.forbiddenPaths: {affected_path}", ) ) @@ -1149,11 +1151,15 @@ def _validate_unresolved_paths(document, status, owner_route, allowed, findings, for path in allowed: if path == "unresolved:agent": unresolved_paths.append("scope.allowedPaths") - for finding in findings: + for index, finding in enumerate(findings): + if not isinstance(finding, dict): + continue + finding_id = finding.get("id") + id_str = str(finding_id) if finding_id is not None else str(index) if "unresolved:agent" in finding.get("affectedPaths", []): - unresolved_paths.append(f"finding:{finding['id']}.affectedPaths") - if any(item.get("ref") == "unresolved:agent" for item in finding.get("evidence", [])): - unresolved_paths.append(f"finding:{finding['id']}.evidence") + unresolved_paths.append(f"finding:{id_str}.affectedPaths") + if any(isinstance(item, dict) and item.get("ref") == "unresolved:agent" for item in finding.get("evidence", [])): + unresolved_paths.append(f"finding:{id_str}.evidence") for action in actions: if "unresolved:agent" in action.get("paths", []): unresolved_paths.append(f"action:{action['id']}.paths") @@ -1223,11 +1229,16 @@ def validate_document(document: dict[str, Any]) -> dict[str, Any]: for finding_id in action.get("findingIds", []) } for finding in findings: - if finding.get("status") != "DEFERRED" and finding["id"] not in action_finding_ids: + if not isinstance(finding, dict): + continue + fid = finding.get("id") + if not fid: + continue + if finding.get("status") != "DEFERRED" and fid not in action_finding_ids: errors.append( _issue( MALFORMED_CODE, - f"finding:{finding['id']}", + f"finding:{fid}", "active finding must be resolved by at least one action", ) ) @@ -1237,7 +1248,7 @@ def validate_document(document: dict[str, Any]) -> dict[str, Any]: _validate_analysis(document, errors) _validate_unresolved_paths(document, status, owner_route, allowed, findings, actions, errors, warnings) - finding_ids = {item["id"] for item in findings} + finding_ids = {item["id"] for item in findings if isinstance(item, dict) and "id" in item} action_ids = {item["id"] for item in actions} for verification in verifications: for covered in verification.get("covers", []): @@ -1765,7 +1776,7 @@ def _projected_plan_items(diagnostics, plans, projection_record_ids): def _analyze_criterion_coverage(document, plan_corpora, findings): - all_plan_text = "\n".join(plan_corpora.values()) + all_plan_text = "\n".join(plan_corpora.values()).lower() for criterion in document["acceptanceCriteria"]: if criterion["id"].lower() not in all_plan_text and criterion["statement"].lower() not in all_plan_text: findings.append( diff --git a/.governance/repository_policy.py b/.governance/repository_policy.py index 75a2a06..94a4ffd 100755 --- a/.governance/repository_policy.py +++ b/.governance/repository_policy.py @@ -139,6 +139,10 @@ def _safe_snapshot_path(root: Path, raw_path: str, *, staged: bool) -> str | Non return error if _index_has_symlink(root, raw_path) if staged else _working_tree_has_symlink(root, raw_path): return "path contains a symlink" + if staged: + # Syntax and index mode were checked above. Staged bytes are read only + # from Git; mutable working-tree links or missing paths are irrelevant. + return None try: repository = root.resolve() resolved = (root / raw_path).resolve(strict=False) @@ -149,6 +153,19 @@ def _safe_snapshot_path(root: Path, raw_path: str, *, staged: bool) -> str | Non return None +def _source_paths_error(paths: Any) -> str | None: + if ( + not isinstance(paths, list) + or not paths + or any(relative_path_error(item, pattern=False) is not None for item in paths) + ): + return "repositoryPolicy.tickets.sourcePaths must be a safe non-empty path list" + normalized = [item.replace("\\", "/") for item in paths] + if len(normalized) != len(set(normalized)): + return "repositoryPolicy.tickets.sourcePaths must be a safe non-empty path list" + return None + + def policy_error(value: Any) -> str | None: if not isinstance(value, dict): return "repositoryPolicy must be an object" @@ -168,10 +185,12 @@ def policy_error(value: Any) -> str | None: if delivery.get("checkout") not in {"linked-worktree", "primary"}: return "repositoryPolicy.delivery.checkout is invalid" branches = delivery.get("targetBranches") - if not isinstance(branches, list) or not branches or len(branches) != len(set(branches)): + if not isinstance(branches, list) or not branches: return "repositoryPolicy.delivery.targetBranches must be unique and non-empty" if not all(isinstance(item, str) and item and "/" not in item for item in branches): return "repositoryPolicy.delivery.targetBranches contains an invalid branch" + if len(branches) != len(set(branches)): + return "repositoryPolicy.delivery.targetBranches must be unique and non-empty" tickets = value.get("tickets") if not isinstance(tickets, dict): return "repositoryPolicy.tickets must be an object" @@ -192,13 +211,9 @@ def policy_error(value: Any) -> str | None: if field in tickets and relative_path_error(tickets[field]) is not None: return f"repositoryPolicy.tickets.{field} must be a safe repository-relative path" if "sourcePaths" in tickets: - paths = tickets["sourcePaths"] - if ( - not isinstance(paths, list) - or not paths - or any(relative_path_error(item) is not None for item in paths) - ): - return "repositoryPolicy.tickets.sourcePaths must be a safe non-empty path list" + source_error = _source_paths_error(tickets["sourcePaths"]) + if source_error is not None: + return source_error preset = PROFILES[profile] if ( value.get("delivery", {}).get("mode") != preset["deliveryMode"] @@ -209,8 +224,14 @@ def policy_error(value: Any) -> str | None: return f"repositoryPolicy profile {profile} does not match its ticket backend" if profile != "local-audit" and value.get("enforcement") != preset["enforcement"]: return f"repositoryPolicy profile {profile} must use enforcement={preset['enforcement']}" - if tickets.get("backend") == "planfile" and "adapterPath" not in tickets: - return "planfile profile requires tickets.adapterPath" + if tickets.get("backend") == "planfile": + if "adapterPath" not in tickets or "sourcePaths" not in tickets: + return "planfile profile requires tickets.adapterPath and tickets.sourcePaths" + if relative_path_error(tickets["adapterPath"], pattern=False) is not None: + return "repositoryPolicy.tickets.adapterPath must be a safe repository-relative path" + source_error = _source_paths_error(tickets["sourcePaths"]) + if source_error is not None: + return source_error return None @@ -265,14 +286,26 @@ def adapter_error( return "external ticket adapter workstream is invalid" for field in ("allowedPaths", "forbiddenPaths", "sourcePaths"): values = adapter.get(field) - if not isinstance(values, list) or len(values) != len(set(values)): + if not isinstance(values, list): return f"external ticket adapter {field} is invalid" for item in values: error = relative_path_error(item, pattern=field != "sourcePaths") if error: return f"external ticket adapter {field} is invalid: {error}" + if len(values) != len(set(values)): + return f"external ticket adapter {field} is invalid" if not adapter["allowedPaths"]: return "external ticket adapter allowedPaths is empty" + if not adapter["sourcePaths"]: + return "external ticket adapter sourcePaths is empty" + declared_sources = tickets.get("sourcePaths") + source_error = _source_paths_error(declared_sources) + if source_error is not None: + return source_error + normalized_declared = {item.replace("\\", "/") for item in declared_sources} + normalized_adapter = {item.replace("\\", "/") for item in adapter["sourcePaths"]} + if normalized_adapter != normalized_declared: + return "external ticket adapter sourcePaths must match repositoryPolicy.tickets.sourcePaths" for source in adapter["sourcePaths"]: path_error = _safe_snapshot_path(root, source, staged=staged) if path_error: @@ -296,7 +329,7 @@ def adapter_error( return f"external ticket source does not contain {ticket}: {source}" if observed.lower() in {"done", "cancelled", "canceled", "closed"}: return f"external ticket {ticket} is terminal in {source}" - if raw_path in adapter["allowedPaths"] or raw_path in adapter["forbiddenPaths"]: + if _matches(raw_path, adapter["allowedPaths"]) or _matches(raw_path, adapter["forbiddenPaths"]): return "external ticket adapter cannot own itself" return None diff --git a/.governance/required-checks.schema.json b/.governance/required-checks.schema.json index 470b49e..ac25155 100644 --- a/.governance/required-checks.schema.json +++ b/.governance/required-checks.schema.json @@ -5,20 +5,34 @@ "description": "Per-repository required-check declaration. The hub instance may keep workflowFile + requiredCheckNames. Adopters with two workflows use requiredChecks.", "type": "object", "additionalProperties": false, - "required": ["schema", "repository"], + "required": [ + "schema", + "repository" + ], "properties": { - "schema": { "const": "new-project.required-checks/v1" }, - "version": { "type": "integer", "minimum": 1 }, + "schema": { + "const": "new-project.required-checks/v1" + }, + "version": { + "type": "integer", + "minimum": 1 + }, "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" }, - "workflowFile": { "type": "string", "minLength": 1 }, + "workflowFile": { + "type": "string", + "minLength": 1 + }, "requiredCheckNames": { "type": "array", "minItems": 1, "uniqueItems": true, - "items": { "type": "string", "minLength": 1 } + "items": { + "type": "string", + "minLength": 1 + } }, "requiredChecks": { "type": "array", @@ -26,36 +40,115 @@ "items": { "type": "object", "additionalProperties": false, - "required": ["name", "workflowFile"], + "required": [ + "name", + "workflowFile" + ], "properties": { - "name": { "type": "string", "minLength": 1 }, - "workflowFile": { "type": "string", "minLength": 1 } + "name": { + "type": "string", + "minLength": 1 + }, + "workflowFile": { + "type": "string", + "minLength": 1 + } } } }, "circularGovernanceChecksIgnoredByValidator": { "type": "array", - "items": { "type": "string", "minLength": 1 }, + "items": { + "type": "string", + "minLength": 1 + }, "uniqueItems": true }, "externalConsumers": { "type": "array", - "items": { "type": "object" } + "items": { + "type": "object" + } + }, + "externalChecks": { + "type": "array", + "maxItems": 1, + "uniqueItems": true, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "provider" + ], + "properties": { + "name": { + "const": "onedev/local-verify" + }, + "provider": { + "const": "onedev" + } + } + } } }, "oneOf": [ { - "required": ["workflowFile", "requiredCheckNames"], - "not": { "required": ["requiredChecks"] } + "required": [ + "workflowFile", + "requiredCheckNames" + ], + "not": { + "required": [ + "requiredChecks" + ] + } }, { - "required": ["requiredChecks"], + "required": [ + "requiredChecks" + ], "not": { "anyOf": [ - { "required": ["workflowFile"] }, - { "required": ["requiredCheckNames"] } + { + "required": [ + "workflowFile" + ] + }, + { + "required": [ + "requiredCheckNames" + ] + } ] } } + ], + "allOf": [ + { + "if": { + "required": [ + "externalChecks" + ], + "properties": { + "externalChecks": { + "minItems": 1 + } + } + }, + "then": { + "required": [ + "workflowFile", + "requiredCheckNames" + ], + "properties": { + "requiredCheckNames": { + "contains": { + "const": "onedev/local-verify" + } + } + } + } + } ] } diff --git a/.governance/seed_baseline.py b/.governance/seed_baseline.py new file mode 100755 index 0000000..0e78d0f --- /dev/null +++ b/.governance/seed_baseline.py @@ -0,0 +1,273 @@ +#!/usr/bin/env python3 +"""Explicit native-adopter seed transaction; no product or remote authority. + +The caller supplies an external exact-state request under existing session +authorization. The installed adoption lock pins the named seed profile. The +allocator owns reservation/locking; the normal Git hook checks the prepared +transaction. This is a local accidental-writer boundary, not hostile-OS-user +authentication or trusted publication approval. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import os +from pathlib import Path, PurePosixPath +import re +import subprocess + +SCHEMA = 'new-project.seed-baseline-request/v1' +PROFILE = 'seed-profile:new-project-native' +FIELDS = {'schema', 'root', 'repositoryRef', 'authorizationRef', 'createRepository', + 'execute', 'sourceRevision', 'lockSha256', 'seedProfileRef', + 'ownerActor', 'ownerSession', 'files'} +METADATA = {'README.md', 'VERSION', 'CHANGELOG.md', 'TODO.md', 'project/TICKETS.md', + '.gitignore', '.governance/manifest.json', '.governance/manifest.lock.json', + '.governance/required-checks.json'} +SECRET = re.compile(rb'-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|' + rb'gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}') + + +class SeedError(ValueError): + pass + + +def require(condition, reason): + if not condition: + raise SeedError(reason) + + +def digest(raw): + return hashlib.sha256(raw).hexdigest() + + +def canonical(value): + return json.dumps(value, sort_keys=True, separators=(',', ':')).encode() + + +def regular(path): + require(not any(p.is_symlink() for p in (path, *path.parents)), 'symlink_path') + require(path.is_file(), 'regular_file_required') + + +def load(path): + regular(path) + raw = path.read_bytes() + require(len(raw) <= 131072, 'document_too_large') + def pairs(items): + result = {} + for key, value in items: + require(key not in result, 'duplicate_json_key') + result[key] = value + return result + value = json.loads(raw, object_pairs_hook=pairs) + require(isinstance(value, dict), 'object_required') + return value + + +def git(root, *args, check=True, env=None): + clean = {k: v for k, v in (env or os.environ).items() if not k.startswith('GIT_')} + return subprocess.run(['git', '-C', str(root), *args], check=check, + capture_output=True, env=clean) + + +def stage(root): + result = {} + total = 0 + for row in git(root, 'ls-files', '--stage', '-z').stdout.split(b'\0'): + if not row: + continue + header, raw_name = row.split(b'\t', 1) + mode, oid, level = header.decode().split() + name = raw_name.decode() + path = PurePosixPath(name) + require(path.as_posix() == name and not path.is_absolute() + and '..' not in path.parts and not any(ord(c) < 32 for c in name), 'unsafe_name') + require(mode in ('100644', '100755') and level == '0', 'regular_stage_required') + regular(root / name) + raw = git(root, 'cat-file', 'blob', oid).stdout + total += len(raw) + require(total <= 16 * 1024 * 1024 and len(result) < 512, 'seed_size_limit') + require(raw == (root / name).read_bytes(), 'index_worktree_drift') + require(not SECRET.search(raw), 'secret_material') + result[name] = digest(raw) + return result + + +def context(root, request_path, actor, session, *, allowed_untracked=()): + require(root.is_absolute() and root == root.resolve(), 'canonical_root_required') + require(not any(p.is_symlink() for p in (root, *root.parents)), 'symlink_path') + require(request_path == request_path.resolve() and root not in request_path.parents, 'external_request_required') + request = load(request_path) + require(set(request) == FIELDS and request['schema'] == SCHEMA, 'request_shape') + require(request['root'] == str(root) and request['seedProfileRef'] == PROFILE, 'request_binding') + require(request['createRepository'] is True and request['execute'] is True + and re.fullmatch(r'authorization:session/[a-z0-9._/-]+', request['authorizationRef']), + 'explicit_new_repository_authority_required') + require(request['ownerActor'] == actor and request['ownerSession'] == session + and actor and session, 'writer_binding') + require(re.fullmatch(r'[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+', request['repositoryRef']), 'repository_binding') + require(git(root, 'rev-parse', '--verify', 'HEAD', check=False).returncode != 0, 'head_must_be_unborn') + require(not git(root, 'for-each-ref', '--format=%(refname)').stdout.strip(), 'existing_ref') + require(not git(root, 'remote').stdout.strip(), 'remote_forbidden') + require((root / '.git').is_dir() and not (root / '.git').is_symlink(), 'primary_checkout_required') + require(git(root, 'config', '--get', 'core.hooksPath', check=False).stdout.strip() == b'.githooks' + and os.access(root / '.githooks/pre-commit', os.X_OK), 'managed_hook_required') + branch = git(root, 'symbolic-ref', '--short', 'HEAD').stdout.decode().strip() + manifest = load(root / '.governance/manifest.json') + require(manifest['delivery']['targetBranches'] == [branch], 'target_branch_required') + lock_path = root / '.governance/manifest.lock.json' + lock = load(lock_path) + require(digest(lock_path.read_bytes()) == request['lockSha256'], 'adoption_lock_drift') + pin = lock.get('standard', {}) + require(pin.get('id') == 'wellmanifest/new-project' + and pin.get('sourceRepository') == 'wellmanifest/new-project' + and pin.get('publicationStatus') == 'published' + and re.fullmatch('[a-f0-9]{40}', request['sourceRevision']) + and pin.get('sourceRevision') == request['sourceRevision'], 'published_profile_required') + managed = lock.get('managedFiles', {}) + mapping_path = root / '.governance/package-manifest.json' + require(managed.get('.governance/package-manifest.json') == digest(mapping_path.read_bytes()), + 'package_manifest_drift') + mapping = load(mapping_path) + allowed = METADATA | {row['target'] for row in mapping['files']} + require(set(managed) <= allowed, 'profile_managed_paths') + initial = request['files'] + require(isinstance(initial, dict) and set(managed) <= set(initial) <= allowed, + 'concrete_seed_allowlist_required') + require(all(re.fullmatch('[a-f0-9]{64}', value) for value in initial.values()), 'file_digest_required') + require(all(initial.get(name) == sha for name, sha in managed.items()), 'managed_pin_drift') + require(set(METADATA) <= set(initial), 'seed_prerequisites_required') + require(load(root / '.governance/required-checks.json')['repository'] == request['repositoryRef'], + 'check_repository_binding') + # Validate carrier paths before Git classifies a symlinked parent as an + # unrelated untracked path, and before any ticket contents are read. + for name in allowed_untracked: + regular(root / name) + untracked = set(git(root, 'ls-files', '--others', '-z').stdout.decode().split('\0')) - {''} + require(untracked <= set(allowed_untracked), 'untracked_path') + return request + + +def preflight(root, request_path, actor, session): + request = context(root, request_path, actor, session) + require(stage(root) == request['files'], 'exact_seed_stage_required') + require(not (root / '.git/new-project-seed-reservation.json').exists(), 'seed_already_reserved') + require(not (root / '.git/new-project-ticket-high-water').exists(), 'existing_ticket_reservation') + probe = subprocess.run(['python3', '-B', str(root / '.governance/worktree_path_check.py'), + 'feature-probe', '--from-worktree', str(root)], + check=True, capture_output=True) + require(json.loads(probe.stdout).get('supported') is True, 'relative_worktrees_required') + return request + + +def prepare(root, request_path, actor, session, ticket): + # Validate without changing files or the index. Only this allocator's two + # ticket carriers may be untracked; other context callers stay strict. + require(re.fullmatch('ticket-[0-9]{3,}', ticket), 'native_ticket_required') + carriers = [f'project/{ticket}/README.md', f'project/{ticket}/intent.json'] + request = context(root, request_path, actor, session, allowed_untracked=carriers) + readme, intent_path = (root / name for name in carriers) + + # The managed allocator has reserved this exact ID under its clone lock. + counter = root / '.git/new-project-ticket-high-water' + regular(counter) + require(counter.read_text().strip() == str(int(ticket.removeprefix('ticket-'))), 'native_reservation_required') + require((root / '.git/new-project-ticket-allocation.lock').is_dir(), 'allocator_lock_required') + reservation = root / '.git/new-project-seed-reservation.json' + require(not reservation.exists() and not reservation.is_symlink(), 'seed_already_reserved') + intent = load(intent_path) + require(intent['ticket'] == ticket and 'delivery' not in intent, 'unborn_ticket_binding') + seed_files = request['files'] + initial = stage(root) + require(set(initial) == set(seed_files), 'exact_seed_stage_required') + require(all(initial[name] == sha for name, sha in seed_files.items() + if name != 'project/TICKETS.md'), 'seed_content_drift') + text = readme.read_text() + require('SESSION_EXECUTION_AUTHORIZATION' not in text, 'unexpected_ticket_content') + text += '\nSESSION_EXECUTION_AUTHORIZATION: explicit new-repository seed request; no product implementation before the real baseline.\n' + carrier_bytes = [text.encode(), intent_path.read_bytes()] + require(not any(SECRET.search(raw) for raw in carrier_bytes), 'secret_material') + require(len(initial) + len(carriers) <= 512 + and sum((root / name).stat().st_size for name in initial) + + sum(map(len, carrier_bytes)) <= 16 * 1024 * 1024, 'seed_size_limit') + request_sha256 = digest(request_path.read_bytes()) + + # Mutate only after request, paths, reservation, intent and seed validation. + readme.write_text(text) + names = [*seed_files, *carriers] + git(root, 'add', '--', *names) + actual = stage(root) + require(set(actual) == set(names), 'seed_stage_expansion') + require(all(actual[name] == sha for name, sha in seed_files.items() + if name != 'project/TICKETS.md'), 'seed_content_drift') + record = {'requestSha256': request_sha256, 'ticket': ticket, + 'files': actual, 'actor': actor, 'session': session} + with reservation.open('x') as stream: + json.dump(record, stream, sort_keys=True) + return record + + +def hook_check(root, request_path, actor, session): + context(root, request_path, actor, session) + record = load(root / '.git/new-project-seed-reservation.json') + require(record['actor'] == actor and record['session'] == session + and record['requestSha256'] == digest(request_path.read_bytes()), 'prepared_request_drift') + require((root / '.git/new-project-ticket-allocation.lock').is_dir(), 'allocator_lock_required') + counter = root / '.git/new-project-ticket-high-water' + require(counter.read_text().strip() == str(int(record['ticket'].removeprefix('ticket-'))), 'reservation_drift') + require(stage(root) == record['files'], 'prepared_stage_drift') + return record + + +def commit(root, request_path, actor, session): + record = hook_check(root, request_path, actor, session) + env = dict(os.environ, NEW_PROJECT_SEED_REQUEST=str(request_path), + NEW_PROJECT_WRITER_ACTOR=actor, NEW_PROJECT_WRITER_SESSION=session) + result = git(root, 'commit', '-m', f'chore: establish governed baseline ({record["ticket"]})', + env=env, check=False) + require(result.returncode == 0, 'seed_commit_rejected: ' + + (result.stdout + result.stderr).decode(errors='replace')[:200]) + head = git(root, 'rev-parse', 'HEAD').stdout.decode().strip() + require(len(git(root, 'rev-list', '--all').stdout.splitlines()) == 1, 'one_root_commit_required') + receipt = {'schema': 'new-project.seed-baseline-receipt/v1', 'ticket': record['ticket'], + 'baselineSha': head, 'requestSha256': record['requestSha256'], + 'seedProfileRef': PROFILE, 'sourceAuthority': 'session-new-repository-only', + 'productSourcePresent': False, 'remoteEffects': 0} + path = root / '.subactor/receipts/seed-baseline.json' + path.parent.mkdir(parents=True, exist_ok=True) + with path.open('x') as stream: + json.dump(receipt, stream, sort_keys=True) + return receipt + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('operation', choices=['preflight', 'prepare', 'hook-check', 'commit']) + parser.add_argument('--root', type=Path, required=True) + parser.add_argument('--request', type=Path, required=True) + parser.add_argument('--actor', default=os.environ.get('NEW_PROJECT_WRITER_ACTOR', '')) + parser.add_argument('--session', default=os.environ.get('NEW_PROJECT_WRITER_SESSION', '')) + parser.add_argument('--ticket') + parser.add_argument('--message-file', type=Path) + args = parser.parse_args() + try: + common = args.root.absolute(), args.request.absolute(), args.actor, args.session + result = (prepare(*common, args.ticket) if args.operation == 'prepare' + else {'preflight': preflight, 'hook-check': hook_check, 'commit': commit}[args.operation](*common)) + if args.message_file is not None: + require(args.operation == 'hook-check', 'message_check_requires_hook') + regular(args.message_file) + require(args.message_file.read_text().strip() == + f'chore: establish governed baseline ({result["ticket"]})', 'seed_message_binding') + print(json.dumps({'status': 'passed', 'operation': args.operation, + **({'receipt': result} if args.operation == 'commit' else {})})) + return 0 + except (ValueError, OSError, KeyError, TypeError, subprocess.SubprocessError) as error: + print(json.dumps({'status': 'refused', 'reason': str(error)[:250]})) + return 1 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/.governance/snapshot_migration.py b/.governance/snapshot_migration.py index b689d3d..f9d3c65 100755 --- a/.governance/snapshot_migration.py +++ b/.governance/snapshot_migration.py @@ -74,11 +74,16 @@ def tree(root, revision): for raw in git(root, 'ls-tree', '-r', '-z', '--full-tree', revision).split(b'\0'): if not raw: continue - metadata, name = raw.split(b'\t', 1) - mode, kind, oid = metadata.decode('ascii').split() - path = name.decode('utf-8') + try: + metadata, name = raw.split(b'\t', 1) + mode, kind, oid = metadata.decode('ascii').split() + path = name.decode('utf-8') + except ValueError: + raise MigrationError('GOV-SNAPSHOT-MIGRATION-005', 'Unreadable inventory path or metadata') from None if not safe_path(path) or kind != 'blob' or mode not in {'100644', '100755', '120000'}: raise MigrationError('GOV-SNAPSHOT-MIGRATION-005', 'Unsupported inventory path or object type') + if path in result: + raise MigrationError('GOV-SNAPSHOT-MIGRATION-005', 'Duplicate inventory path') result[path] = {'mode': mode, 'oid': oid} return result diff --git a/.governance/standard-adoption-plan.schema.json b/.governance/standard-adoption-plan.schema.json new file mode 100644 index 0000000..e80d7f8 --- /dev/null +++ b/.governance/standard-adoption-plan.schema.json @@ -0,0 +1,623 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://wellmanifest.com/schemas/standard-adoption-plan.v1.schema.json", + "type": "object", + "additionalProperties": false, + "required": [ + "schema", + "readOnly", + "grantsAuthority", + "source", + "target", + "prospectiveManifest", + "ownershipAdditions", + "files", + "allowedPaths", + "delivery", + "digest" + ], + "properties": { + "schema": { + "const": "new-project.standard-adoption-plan/v1" + }, + "readOnly": { + "const": true + }, + "grantsAuthority": { + "const": false + }, + "source": { + "type": "object", + "additionalProperties": false, + "required": [ + "repository", + "revision", + "version", + "packageSha256", + "exporterSha256", + "allocatorSha256" + ], + "properties": { + "repository": { + "const": "wellmanifest/new-project" + }, + "revision": { + "$ref": "#/$defs/sha" + }, + "version": { + "type": "string", + "minLength": 1 + }, + "packageSha256": { + "$ref": "#/$defs/sha256" + }, + "exporterSha256": { + "$ref": "#/$defs/sha256" + }, + "allocatorSha256": { + "$ref": "#/$defs/sha256" + } + } + }, + "target": { + "type": "object", + "additionalProperties": false, + "required": [ + "root", + "head", + "branch", + "statusSha256", + "index", + "dirtyFiles", + "files" + ], + "properties": { + "root": { + "type": "string", + "minLength": 1 + }, + "head": { + "$ref": "#/$defs/sha" + }, + "branch": { + "type": "string", + "minLength": 1, + "description": "Observed named primary branch; aliases require exact HEAD, local main and origin/main equality at export and verification." + }, + "statusSha256": { + "$ref": "#/$defs/sha256" + }, + "index": { + "$ref": "#/$defs/fileState" + }, + "dirtyFiles": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/literalPath" + }, + "additionalProperties": { + "$ref": "#/$defs/fileState" + } + }, + "files": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/literalPath" + }, + "additionalProperties": { + "$ref": "#/$defs/fileState" + } + } + } + }, + "prospectiveManifest": { + "type": "object", + "required": [ + "standard", + "coordination", + "delivery" + ] + }, + "ownershipAdditions": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/literalPath" + } + }, + "files": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "sha256", + "gitMode", + "strategy" + ], + "properties": { + "path": { + "$ref": "#/$defs/literalPath" + }, + "sha256": { + "$ref": "#/$defs/sha256" + }, + "gitMode": { + "enum": [ + "100644", + "100755" + ] + }, + "strategy": { + "enum": [ + "managed", + "seed", + "extendable", + "generated" + ] + } + } + } + }, + "allowedPaths": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/literalPath" + }, + "minItems": 1 + }, + "delivery": { + "type": "object", + "additionalProperties": false, + "required": [ + "acceptedBaseSha", + "targetBranch", + "outcome", + "nonGoals", + "complexity", + "estimatedMinutes", + "budgets", + "architecture", + "runtimeDependencies", + "validation" + ], + "properties": { + "acceptedBaseSha": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "targetBranch": { + "$ref": "#/$defs/branch" + }, + "outcome": { + "type": "string", + "minLength": 1 + }, + "nonGoals": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1, + "uniqueItems": true + }, + "complexity": { + "enum": [ + "XS", + "S", + "M", + "L" + ] + }, + "estimatedMinutes": { + "type": "integer", + "minimum": 1, + "maximum": 240 + }, + "snapshotMigration": { + "type": "object", + "additionalProperties": false, + "required": [ + "schema", + "repository", + "baseSha", + "sourceSha", + "sourceTree", + "inventorySha256", + "authorizationRef" + ], + "properties": { + "schema": { + "const": "new-project.snapshot-migration/v1" + }, + "repository": { + "type": "string", + "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" + }, + "baseSha": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "sourceSha": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "sourceTree": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "inventorySha256": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "authorizationRef": { + "type": "string", + "pattern": "^authorization:[A-Za-z0-9._/-]{1,200}$" + } + } + }, + "standardAdoption": { + "type": "object", + "additionalProperties": false, + "required": [ + "sourceRepository", + "fromRevision", + "toRevision" + ], + "properties": { + "sourceRepository": { + "const": "wellmanifest/new-project" + }, + "fromRevision": { + "oneOf": [ + { + "$ref": "#/$defs/sha" + }, + { + "type": "null" + } + ] + }, + "toRevision": { + "$ref": "#/$defs/sha" + }, + "managedTargetTakeovers": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "baseDigest" + ], + "properties": { + "path": { + "type": "string", + "minLength": 1, + "pattern": "^(?!/)(?![A-Za-z]:[/\\\\])(?!.*(?:^|/)\\.\\.(?:/|$))[^*?\\[]+$" + }, + "baseDigest": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + } + }, + "managedTargetRestorations": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "baseDigest" + ], + "properties": { + "path": { + "type": "string", + "minLength": 1, + "pattern": "^(?!/)(?![A-Za-z]:[/\\\\])(?!.*(?:^|/)\\.\\.(?:/|$))[^*?\\[]+$" + }, + "baseDigest": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + } + }, + "targetOwnedTransitions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "baseDigest", + "headDigest" + ], + "properties": { + "path": { + "type": "string", + "minLength": 1, + "pattern": "^(?!/)(?![A-Za-z]:[/\\\\])(?!.*(?:^|/)\\.\\.(?:/|$))[^*?\\[]+$" + }, + "baseDigest": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "headDigest": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + } + } + } + }, + "budgets": { + "type": "object", + "additionalProperties": false, + "required": [ + "maxImplementationFiles", + "maxAffectedComponents", + "maxPublicInterfaceChanges", + "maxRuntimeDependencies" + ], + "properties": { + "maxImplementationFiles": { + "type": "integer", + "minimum": 1 + }, + "maxAffectedComponents": { + "type": "integer", + "minimum": 1 + }, + "maxPublicInterfaceChanges": { + "type": "integer", + "minimum": 0 + }, + "maxRuntimeDependencies": { + "type": "integer", + "minimum": 0 + } + } + }, + "architecture": { + "type": "object", + "additionalProperties": false, + "required": [ + "status", + "decision", + "components", + "responsibilityChanges", + "interfaceChanges", + "dataChanges", + "ui", + "rollback" + ], + "properties": { + "status": { + "const": "accepted" + }, + "decision": { + "type": "string", + "minLength": 1 + }, + "components": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "paths" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "paths": { + "type": "array", + "items": { + "$ref": "#/$defs/glob" + }, + "minItems": 1, + "uniqueItems": true + } + } + } + }, + "responsibilityChanges": { + "type": "boolean" + }, + "interfaceChanges": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "dataChanges": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "kind", + "component", + "description" + ], + "properties": { + "kind": { + "enum": [ + "component-local-state", + "schema-migration", + "cross-component-migration", + "ownership-transfer", + "unknown" + ] + }, + "component": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string", + "minLength": 1 + } + } + } + ] + }, + "uniqueItems": true + }, + "ui": { + "type": "object", + "additionalProperties": false, + "required": [ + "impact", + "states", + "evidence" + ], + "properties": { + "impact": { + "enum": [ + "none", + "single-state", + "multi-state" + ] + }, + "states": { + "type": "array", + "items": { + "enum": [ + "loading", + "empty", + "error", + "success" + ] + }, + "uniqueItems": true + }, + "evidence": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + } + } + }, + "rollback": { + "type": "string", + "minLength": 1 + } + } + }, + "runtimeDependencies": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "validation": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "criterion", + "commands", + "evidence" + ], + "properties": { + "criterion": { + "type": "string", + "pattern": "^AC-[0-9]+$" + }, + "commands": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "minItems": 1, + "uniqueItems": true + }, + "evidence": { + "type": "string", + "minLength": 1 + } + } + } + } + } + }, + "digest": { + "$ref": "#/$defs/sha256" + } + }, + "$defs": { + "glob": { + "type": "string", + "minLength": 1, + "pattern": "^(?!/)(?![A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$" + }, + "branch": { + "type": "string", + "minLength": 1, + "pattern": "^(?!@?$)(?!HEAD$)(?![-/])(?![\\s\\S]*(?:\\.\\.|//|@\\{|[ ~^:?*\\[\\\\\\x00-\\x1f\\x7f]))(?![\\s\\S]*(?:^|/)\\.)(?![\\s\\S]*(?:^|/)[^/]*\\.lock(?:/|$))(?![\\s\\S]*[/.]$)[\\s\\S]+$" + }, + "sha": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "sha256": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "literalPath": { + "type": "string", + "minLength": 1, + "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.|\\.git)(?:/|$))(?!.*[\\\\*?\\[\\]\\x00-\\x1f\\x7f])[^/]+(?:/[^/]+)*$" + }, + "fileState": { + "type": [ + "object", + "null" + ], + "additionalProperties": false, + "required": [ + "sha256", + "mode" + ], + "properties": { + "sha256": { + "$ref": "#/$defs/sha256" + }, + "mode": { + "type": "integer", + "minimum": 0, + "maximum": 4095 + } + } + } + } +} diff --git a/.governance/standard-adoption.json b/.governance/standard-adoption.json index 3f2b5fe..7731443 100644 --- a/.governance/standard-adoption.json +++ b/.governance/standard-adoption.json @@ -12,526 +12,374 @@ "adoptions": [ { "id": "wellmanifest/authority-lifecycle", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "runtime-conformance", - "level": "S5", + "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/change_lease_check.py", + "sha256": "9c9402194b3ad785f48d7c31b1f9a5cd3257fd97e770ff7442d76e35ea9e0d33" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S5", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/code-dsl", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "protected-conformance", - "level": "S4", - "artifacts": [ - { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - } - ], + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "reference-only", + "level": "S0", + "artifacts": [], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ] }, { "id": "wellmanifest/deployment", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "runtime-conformance", - "level": "S5", - "artifacts": [ - { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - } - ], + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "reference-only", + "level": "S0", + "artifacts": [], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S5", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ] }, { "id": "wellmanifest/docs", "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "protected-conformance", - "level": "S3", + "revision": "ebe7501063ef4f3e63ded610c2d3183010ca636e", + "model": "local-conformance", + "level": "S2", "artifacts": [ { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "target": ".governance/docs.json", + "sha256": "9ec1c3fa308b00f9d5431df9297d3bd91c88cfd9d515189f319e9976157b03fb" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": "https://github.com/wellmanifest/docs/blob/ebe7501063ef4f3e63ded610c2d3183010ca636e/docs/standard/policy.json", + "sha256": "f6ba9c011ea1d9260e7fac3a1638a767d5ebc9f7d9b32ed51cc3aea22fe95d8c" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": "https://github.com/wellmanifest/docs/blob/ebe7501063ef4f3e63ded610c2d3183010ca636e/docs/standard/check.py", + "sha256": "8d76dc88c82897332d3671c236eac20610ed42713ad9dbb6e1515e1c4d9175f3" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/docs.json", + "sha256": "9ec1c3fa308b00f9d5431df9297d3bd91c88cfd9d515189f319e9976157b03fb" } ] }, { "id": "wellmanifest/git-lifecycle", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "protected-conformance", - "level": "S4", + "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/branch_lifecycle_check.py", + "sha256": "faf18a9449ed13f805f5442174c3f7b6cf4077e8891670e81800d586b1622daa" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/llm", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "protected-conformance", - "level": "S3", - "artifacts": [ - { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - } - ], + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "reference-only", + "level": "S0", + "artifacts": [], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ] }, { "id": "wellmanifest/logs", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "runtime-conformance", - "level": "S5", - "artifacts": [ - { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - } - ], + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "reference-only", + "level": "S0", + "artifacts": [], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S5", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ] }, { "id": "wellmanifest/merge", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "runtime-conformance", - "level": "S5", + "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/governance_check.py", + "sha256": "a7bfd191ecfb4f4cd160046530c324a1d0b25bd7521bba164e50ac3a56007510" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S5", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/new-project", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "protected-conformance", - "level": "S4", + "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/governance_check.py", + "sha256": "a7bfd191ecfb4f4cd160046530c324a1d0b25bd7521bba164e50ac3a56007510" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/poa", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "runtime-conformance", - "level": "S5", - "artifacts": [ - { - "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - } - ], + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "reference-only", + "level": "S0", + "artifacts": [], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S5", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ] }, { "id": "wellmanifest/ticket-lifecycle", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "protected-conformance", "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/governance_check.py", + "sha256": "a7bfd191ecfb4f4cd160046530c324a1d0b25bd7521bba164e50ac3a56007510" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/validation-attestation", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", "model": "protected-conformance", - "level": "S4", + "level": "S3", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/governance_check.py", + "sha256": "a7bfd191ecfb4f4cd160046530c324a1d0b25bd7521bba164e50ac3a56007510" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" }, { "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S4", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".github/workflows/new-project-governance.yml", + "sha256": "297606a400885f0a0d131de6df8d6fd6870940bdb5ecdd7f2f746fe77da033b9" } ] }, { "id": "wellmanifest/worktrees", - "version": "0.20.92", - "revision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", - "model": "protected-conformance", - "level": "S3", + "version": "0.20.162", + "revision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0", + "model": "local-conformance", + "level": "S2", "artifacts": [ { "target": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "sha256": "05600416b82d7e07d43c0e7f07f36df57afe9b90578b427b9f4756423e42b19e" + }, + { + "target": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" } ], "evidence": [ { "level": "S0", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/standard-packs.json", + "sha256": "2b2433af3ad23f09fd1b1ed92aa5d0eab737da4aa63838fa06559f61dd2b655d" }, { "level": "S1", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/worktree_path_check.py", + "sha256": "106f91e6398564b96d5487dbd981ebb2078d7d366b327400b7d08467fa04c1fd" }, { "level": "S2", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" - }, - { - "level": "S3", - "uri": ".governance/manifest.json", - "sha256": "3a63e819e01eeca10f9333c3286054168ed00eac6081a239d78994d8d7574319" + "uri": ".governance/manifest.lock.json", + "sha256": "05cf98d3bf85f9c01eb7aadb713ebd3ba14db3dd6dabcf77e96bb823f91f1f17" } ] } diff --git a/.governance/standard-packs.json b/.governance/standard-packs.json index 9e7d05a..4a68bd8 100644 --- a/.governance/standard-packs.json +++ b/.governance/standard-packs.json @@ -2,7 +2,9 @@ "schema": "wellmanifest.standard-pack-routing/v1", "owner": "wellmanifest/new-project", "purpose": "composition-only", - "aliases": {"wellmanifest/git": "wellmanifest/git-lifecycle"}, + "aliases": { + "wellmanifest/git": "wellmanifest/git-lifecycle" + }, "rules": { "oneSemanticOwner": true, "aliasesMustNotCreateRepositories": true, @@ -11,10 +13,22 @@ "runtimeBindingsRemainWithAdopter": true }, "executionModels": { - "reference-only": {"maximumLevel": "S0", "authorizesEffects": false}, - "local-conformance": {"maximumLevel": "S2", "authorizesEffects": false}, - "protected-conformance": {"maximumLevel": "S4", "authorizesEffects": false}, - "runtime-conformance": {"maximumLevel": "S5", "authorizesEffects": true} + "reference-only": { + "maximumLevel": "S0", + "authorizesEffects": false + }, + "local-conformance": { + "maximumLevel": "S2", + "authorizesEffects": false + }, + "protected-conformance": { + "maximumLevel": "S4", + "authorizesEffects": false + }, + "runtime-conformance": { + "maximumLevel": "S5", + "authorizesEffects": true + } }, "levels": { "S0": "Versioned normative contract with closed schemas and negative examples.", @@ -28,41 +42,109 @@ "baseline": { "extends": [], "requirements": [ - {"id": "wellmanifest/new-project", "minimumLevel": "S4"}, - {"id": "wellmanifest/git-lifecycle", "minimumLevel": "S4"}, - {"id": "wellmanifest/worktrees", "minimumLevel": "S3"}, - {"id": "wellmanifest/merge", "minimumLevel": "S4"}, - {"id": "wellmanifest/validation-attestation", "minimumLevel": "S4"}, - {"id": "wellmanifest/ticket-lifecycle", "minimumLevel": "S3"}, - {"id": "wellmanifest/logs", "minimumLevel": "S3"}, - {"id": "wellmanifest/docs", "minimumLevel": "S3"} + { + "id": "wellmanifest/new-project", + "minimumLevel": "S4" + }, + { + "id": "wellmanifest/git-lifecycle", + "minimumLevel": "S4" + }, + { + "id": "wellmanifest/worktrees", + "minimumLevel": "S2" + }, + { + "id": "wellmanifest/merge", + "minimumLevel": "S4" + }, + { + "id": "wellmanifest/validation-attestation", + "minimumLevel": "S4" + }, + { + "id": "wellmanifest/ticket-lifecycle", + "minimumLevel": "S3" + }, + { + "id": "wellmanifest/docs", + "minimumLevel": "S2" + } ] }, "domain-pack": { - "extends": ["baseline"], - "requirements": [{"id": "wellmanifest/dsl", "minimumLevel": "S4"}] + "extends": [ + "baseline" + ], + "requirements": [ + { + "id": "wellmanifest/dsl", + "minimumLevel": "S4" + } + ] }, "runtime-service": { - "extends": ["baseline"], + "extends": [ + "baseline" + ], "requirements": [ - {"id": "wellmanifest/poa", "minimumLevel": "S5"}, - {"id": "wellmanifest/authority-lifecycle", "minimumLevel": "S5"}, - {"id": "wellmanifest/logs", "minimumLevel": "S5"} + { + "id": "wellmanifest/poa", + "minimumLevel": "S5" + }, + { + "id": "wellmanifest/authority-lifecycle", + "minimumLevel": "S5" + }, + { + "id": "wellmanifest/logs", + "minimumLevel": "S5" + } ] }, "agent-executor": { - "extends": ["runtime-service"], + "extends": [ + "runtime-service" + ], "requirements": [ - {"id": "wellmanifest/repair-lifecycle", "minimumLevel": "S5"}, - {"id": "wellmanifest/validation-attestation", "minimumLevel": "S5"}, - {"id": "wellmanifest/session-recovery", "minimumLevel": "S3"} + { + "id": "wellmanifest/repair-lifecycle", + "minimumLevel": "S5" + }, + { + "id": "wellmanifest/validation-attestation", + "minimumLevel": "S5" + }, + { + "id": "wellmanifest/session-recovery", + "minimumLevel": "S3" + } ] }, "deployment": { - "extends": ["runtime-service"], + "extends": [ + "runtime-service" + ], + "requirements": [ + { + "id": "wellmanifest/deployment", + "minimumLevel": "S5" + }, + { + "id": "wellmanifest/merge", + "minimumLevel": "S5" + } + ] + }, + "embedded-fleet": { + "extends": [ + "deployment" + ], "requirements": [ - {"id": "wellmanifest/deployment", "minimumLevel": "S5"}, - {"id": "wellmanifest/merge", "minimumLevel": "S5"} + { + "id": "wellmanifest/semver", + "minimumLevel": "S3" + } ] } }, @@ -79,22 +161,147 @@ "transition": "Attach catalog and checker, record immutable evidence, enable the exact required check, then switch the adoption record to enforce." }, "packs": [ - {"id": "wellmanifest/new-project", "owns": ["repository bootstrap", "pack composition", "immutable adoption projection"]}, - {"id": "wellmanifest/git-lifecycle", "owns": ["repository identity", "branch and ref lifecycle", "pull-request lifecycle", "remote hygiene"]}, - {"id": "wellmanifest/worktrees", "owns": ["worktree placement", "worktree naming", "lease path identity", "local checkout audit handoff"]}, - {"id": "wellmanifest/merge", "owns": ["divergent-work disposition", "merge decision contract"], "excludes": ["merge execution", "deletion"]}, - {"id": "wellmanifest/validation-attestation", "owns": ["trusted exact-head evidence", "attestation validation"]}, - {"id": "wellmanifest/ticket-lifecycle", "owns": ["ticket state semantics", "ticket transition semantics"]}, - {"id": "wellmanifest/authority-lifecycle", "owns": ["authority lease semantics", "fencing and expiry semantics"]}, - {"id": "wellmanifest/llm", "owns": ["LLM policy boundary"], "excludes": ["runtime provider credentials", "runtime model routing"]}, - {"id": "wellmanifest/logs", "owns": ["structured log contract", "diagnostic event vocabulary"]}, - {"id": "wellmanifest/docs", "owns": ["documentation ownership", "canonical document paths", "documentation gate"]}, - {"id": "wellmanifest/poa", "owns": ["plan of action contract"]}, - {"id": "wellmanifest/dsl", "owns": ["DSL interoperability contract"]}, - {"id": "wellmanifest/code-dsl", "owns": ["code-level semantic query contract", "AST diagnostics model"]}, - {"id": "wellmanifest/nl-dsl-llm", "owns": ["tripartite natural-language, canonical DSL, and adaptive LLM contract", "universal MCP/CLI parity"]}, - {"id": "wellmanifest/repair-lifecycle", "owns": ["repair and remediation lifecycle"]}, - {"id": "wellmanifest/deployment", "owns": ["deployment contract", "deployment verification"]}, - {"id": "wellmanifest/session-recovery", "owns": ["LLM session recovery", "conversation storage resilience", "host resumption protocol", "session crash isolation", "state rehydration"]} + { + "id": "wellmanifest/new-project", + "owns": [ + "repository bootstrap", + "pack composition", + "immutable adoption projection" + ] + }, + { + "id": "wellmanifest/git-lifecycle", + "owns": [ + "repository identity", + "branch and ref lifecycle", + "pull-request lifecycle", + "remote hygiene" + ] + }, + { + "id": "wellmanifest/worktrees", + "owns": [ + "worktree placement", + "worktree naming", + "lease path identity", + "local checkout audit handoff" + ] + }, + { + "id": "wellmanifest/merge", + "owns": [ + "divergent-work disposition", + "merge decision contract" + ], + "excludes": [ + "merge execution", + "deletion" + ] + }, + { + "id": "wellmanifest/validation-attestation", + "owns": [ + "trusted exact-head evidence", + "attestation validation" + ] + }, + { + "id": "wellmanifest/ticket-lifecycle", + "owns": [ + "ticket state semantics", + "ticket transition semantics" + ] + }, + { + "id": "wellmanifest/authority-lifecycle", + "owns": [ + "authority lease semantics", + "fencing and expiry semantics" + ] + }, + { + "id": "wellmanifest/llm", + "owns": [ + "LLM policy boundary" + ], + "excludes": [ + "runtime provider credentials", + "runtime model routing" + ] + }, + { + "id": "wellmanifest/logs", + "owns": [ + "structured log contract", + "diagnostic event vocabulary" + ] + }, + { + "id": "wellmanifest/docs", + "owns": [ + "documentation ownership", + "canonical document paths", + "documentation gate" + ] + }, + { + "id": "wellmanifest/poa", + "owns": [ + "plan of action contract" + ] + }, + { + "id": "wellmanifest/dsl", + "owns": [ + "DSL interoperability contract" + ] + }, + { + "id": "wellmanifest/code-dsl", + "owns": [ + "code-level semantic query contract", + "AST diagnostics model" + ] + }, + { + "id": "wellmanifest/nl-dsl-llm", + "owns": [ + "tripartite natural-language, canonical DSL, and adaptive LLM contract", + "universal MCP/CLI parity" + ] + }, + { + "id": "wellmanifest/repair-lifecycle", + "owns": [ + "repair and remediation lifecycle" + ] + }, + { + "id": "wellmanifest/deployment", + "owns": [ + "deployment contract", + "deployment verification" + ] + }, + { + "id": "wellmanifest/session-recovery", + "owns": [ + "LLM session recovery", + "conversation storage resilience", + "host resumption protocol", + "session crash isolation", + "state rehydration" + ] + }, + { + "id": "wellmanifest/semver", + "owns": [ + "embedded semantic versioning", + "heterogeneous fleet release manifest", + "dual-build CI/CD", + "hardware safety contracts", + "A/B dual-bank OTA lifecycle" + ] + } ] } diff --git a/.governance/standard-propagation-request.schema.json b/.governance/standard-propagation-request.schema.json new file mode 100644 index 0000000..0c11e7d --- /dev/null +++ b/.governance/standard-propagation-request.schema.json @@ -0,0 +1,70 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://wellmanifest.com/schemas/standard-propagation-request.schema.json", + "title": "Advisory immutable standard propagation request", + "type": "object", + "additionalProperties": false, + "required": [ + "schema", + "readOnly", + "executionAuthorized", + "targets", + "source" + ], + "properties": { + "schema": { + "const": "new-project.standard-propagation-request/v1" + }, + "readOnly": { + "const": true + }, + "executionAuthorized": { + "const": false + }, + "targets": { + "type": "array", + "maxItems": 0 + }, + "source": { + "type": "object", + "additionalProperties": false, + "required": [ + "repository", + "version", + "tag", + "revision", + "publicationStatus", + "packageManifestSha256", + "adoptionToolSha256" + ], + "properties": { + "repository": { + "const": "wellmanifest/new-project" + }, + "version": { + "type": "string", + "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" + }, + "tag": { + "type": "string", + "pattern": "^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" + }, + "revision": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "publicationStatus": { + "const": "published" + }, + "packageManifestSha256": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "adoptionToolSha256": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + } + } + } + } +} diff --git a/.governance/standard_pack_check.py b/.governance/standard_pack_check.py index 07d03b0..ee10b3d 100755 --- a/.governance/standard_pack_check.py +++ b/.governance/standard_pack_check.py @@ -143,6 +143,25 @@ def visit(profile_name: str) -> None: return result +CI_EVIDENCE = (".github/workflows/", ".onedev-buildspec", ".governance/required-checks.json") +EXTERNAL_EVIDENCE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:") # RFC 3986 scheme (2+ chars, not a drive letter) + + +def evidence_proves(root, item) -> bool: + """External proof is taken as declared; repository evidence must exist and match its digest.""" + uri = item["uri"] + if EXTERNAL_EVIDENCE.match(uri): + return True + if PureWindowsPath(uri).drive or PureWindowsPath(uri).root or ".." in Path(uri).parts: + return False + try: + path = (root / uri).resolve() + path.relative_to(root.resolve()) + return path.is_file() and sha256(path) == item["sha256"] + except (OSError, ValueError, RuntimeError): + return False + + def adoption_artifact_findings(root, pack_id, record, level, findings) -> None: artifacts = record.get("artifacts") if LEVELS[level] >= LEVELS["S2"] and not isinstance(artifacts, list): @@ -185,15 +204,31 @@ def adoption_record_findings(root, pack_id, record, models, findings) -> None: if not isinstance(revision, str) or SHA40.fullmatch(revision) is None: findings.append(finding("STD-ADOPTION-REVISION", f"{pack_id} needs an immutable 40-character revision")) evidence = record.get("evidence") - evidence_levels = { - item.get("level") for item in evidence or [] - if isinstance(item, dict) and isinstance(item.get("uri"), str) - and SHA64.fullmatch(str(item.get("sha256", ""))) - } + by_level = {} + for item in evidence or []: + if (isinstance(item, dict) and isinstance(item.get("uri"), str) + and SHA64.fullmatch(str(item.get("sha256", ""))) and evidence_proves(root, item)): + by_level.setdefault(item.get("level"), item) for index in range(LEVELS[level] + 1): expected = f"S{index}" - if expected not in evidence_levels: + if expected not in by_level: findings.append(finding("STD-ADOPTION-EVIDENCE", f"{pack_id} lacks valid {expected} evidence")) + s3 = by_level.get("S3") + if s3 and not (EXTERNAL_EVIDENCE.match(s3["uri"]) or s3["uri"].startswith(CI_EVIDENCE)): + findings.append(finding("STD-ADOPTION-EVIDENCE", f"{pack_id} S3 evidence must be a CI definition or external proof", s3["uri"])) + for upper in ("S4", "S5"): + item = by_level.get(upper) + if item and not EXTERNAL_EVIDENCE.match(item["uri"]): + findings.append(finding("STD-ADOPTION-EVIDENCE", f"{pack_id} {upper} evidence must be external proof (hosted ruleset or runtime receipt)", item["uri"])) + lower = {by_level[f"S{i}"]["uri"] for i in range(3) if f"S{i}" in by_level} + seen = set() + for upper in ("S3", "S4", "S5"): + item = by_level.get(upper) + if item is None: + continue + if item["uri"] in lower or item["uri"] in seen: + findings.append(finding("STD-ADOPTION-EVIDENCE", f"{pack_id} {upper} evidence reuses lower-level proof", item["uri"])) + seen.add(item["uri"]) adoption_artifact_findings(root, pack_id, record, level, findings) diff --git a/.governance/terminal_lease_release.py b/.governance/terminal_lease_release.py new file mode 100755 index 0000000..e98c5d3 --- /dev/null +++ b/.governance/terminal_lease_release.py @@ -0,0 +1,583 @@ +#!/usr/bin/env python3 +"""Explicit current-owner release or verified controller settlement after merged delivery; never takeover. + +This POSIX local-single-clone controller does not repair invalid projections, +remove worktrees, infer owner death, or approve publication. Plan is read-only. +""" +from contextlib import contextmanager +from datetime import datetime, timezone +import argparse +import base64 +import hashlib +import importlib.util +import json +import os +from pathlib import Path +import re +import secrets +import stat +import subprocess +import sys + +REQUEST_SCHEMA = 'new-project.terminal-owner-release/v1' +SETTLEMENT_SCHEMA = 'new-project.terminal-controller-settlement/v1' +SETTLEMENT_REPORT_SCHEMA = 'new-project.terminal-settlement-report/v1' +SETTLED_BY = 'controller:verified-terminal-receipt' +SETTLEABLE_PHASES = {'claimed', 'editing', 'validating', 'approved', 'merged', 'closed'} +WORKTREE_ID_RE = re.compile(r'(ticket-([0-9]{3,}))--([a-z0-9]+(?:-[a-z0-9]+)*)') +TICKET_ID_RE = re.compile(r'ticket-[0-9]{3,}') +FIELDS = {'schema', 'requestId', 'worktreeId', 'ownerActor', 'ownerSession', 'ownerHandoff', + 'expectedRevision', 'expectedFencingToken', 'expectedLeaseSha256', 'terminalReceiptRef'} +MAX_BYTES = 1024 * 1024 +IDENTITY_FAILURES = frozenset({'invalid_canonical_lease', 'current_owner_mismatch', + 'lease_scope_mismatch', 'repository_identity_mismatch'}) + + +def require(condition, message): + if not condition: + raise PermissionError(message) + + +def sibling(name): + spec = importlib.util.spec_from_file_location('_terminal_owner_' + name, Path(__file__).with_name(name + '.py')) + value = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = value + spec.loader.exec_module(value) + return value + + +canonical = sibling('change_lease_check') +activity = sibling('ticket_activity') + + +def unique(pairs): + result = {} + for key, value in pairs: + require(key not in result, 'duplicate_json_key') + result[key] = value + return result + + +def decode(raw): + return json.loads(raw, object_pairs_hook=unique) + + +def encoded(value): + return (json.dumps(value, sort_keys=True, indent=2) + '\n').encode() + + +def sha(raw): + return hashlib.sha256(raw).hexdigest() + + +def git(root, *args, check=True): + env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')} + result = subprocess.run(['git', '-C', str(root), *args], env=env, capture_output=True, timeout=20) + if check: + require(result.returncode == 0, 'git_observation_unavailable') + return result.stdout.decode().strip() + + +@contextmanager +def directory(path, create=False): + """Keep all parents anchored; operations use the held directory descriptor.""" + require(os.name == 'posix' and hasattr(os, 'O_NOFOLLOW'), 'posix_controller_required') + path = Path(os.path.abspath(path)) + require('..' not in path.parts, 'unsafe_path') + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + descriptors = [os.open(path.anchor, flags)] + try: + for part in path.parts[1:]: + if create: + try: os.mkdir(part, 0o700, dir_fd=descriptors[-1]) + except FileExistsError: pass + descriptors.append(os.open(part, flags, dir_fd=descriptors[-1])) + def verify(): + for parent, child, part in zip(descriptors, descriptors[1:], path.parts[1:]): + named, held = os.stat(part, dir_fd=parent, follow_symlinks=False), os.fstat(child) + require(stat.S_ISDIR(named.st_mode) and (named.st_dev, named.st_ino) == (held.st_dev, held.st_ino), 'directory_identity_changed') + verify() + yield descriptors[-1], verify + finally: + for descriptor in reversed(descriptors): os.close(descriptor) + + +def read_at(fd, name, limit=MAX_BYTES, private=False): + descriptor = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fd) + with os.fdopen(descriptor, 'rb') as stream: + info = os.fstat(stream.fileno()) + require(stat.S_ISREG(info.st_mode) and (not private or info.st_nlink == 1), 'regular_private_file_required') + raw = stream.read(limit + 1) + require(len(raw) <= limit, 'input_exceeds_bound') + return raw + + +def read_path(path): + with directory(path.parent) as (fd, verify): + raw = read_at(fd, path.name) + verify() + return decode(raw) + + +@contextmanager +def lease_lock(fd, name, verify): + import fcntl + descriptor = os.open(name + '.lock', os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600, dir_fd=fd) + try: + info = os.fstat(descriptor) + require(stat.S_ISREG(info.st_mode) and info.st_nlink == 1, 'unsafe_lock') + fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) + def verify_lock(): + verify() + named = os.stat(name + '.lock', dir_fd=fd, follow_symlinks=False) + require(stat.S_ISREG(named.st_mode) and named.st_nlink == 1 + and (named.st_dev, named.st_ino) == (info.st_dev, info.st_ino), 'lock_identity_changed') + verify_lock() + yield verify_lock + finally: + os.close(descriptor) + + +def atomic_at(fd, name, raw, exclusive=False): + temporary = '.terminal-' + secrets.token_hex(12) + descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd) + try: + with os.fdopen(descriptor, 'wb') as stream: + stream.write(raw) + stream.flush() + os.fsync(stream.fileno()) + if exclusive: + os.link(temporary, name, src_dir_fd=fd, dst_dir_fd=fd, follow_symlinks=False) + else: + os.replace(temporary, name, src_dir_fd=fd, dst_dir_fd=fd) + os.fsync(fd) + finally: + try: os.unlink(temporary, dir_fd=fd) + except FileNotFoundError: pass + + +def _replace_lease(fd, name, raw): + atomic_at(fd, name, raw) + + +def request_identity(request): + require(isinstance(request, dict) and set(request) == FIELDS, 'invalid_request_fields') + require(request['schema'] == REQUEST_SCHEMA and request['ownerHandoff'] is True, 'explicit_owner_handoff_required') + for key in ('ownerActor', 'ownerSession', 'requestId', 'terminalReceiptRef'): + require(isinstance(request[key], str) and 0 < len(request[key]) <= 160, 'invalid_request_identity') + for key in ('expectedRevision', 'expectedFencingToken'): + require(type(request[key]) is int and request[key] > 0, 'invalid_request_fencing') + require(isinstance(request['expectedLeaseSha256'], str) and re.fullmatch('[0-9a-f]{64}', request['expectedLeaseSha256']), 'invalid_request_digest') + value = request['worktreeId'] + match = WORKTREE_ID_RE.fullmatch(value) if isinstance(value, str) else None + require(match is not None, 'invalid_worktree_identity') + return match[1], 'refs/heads/ticket/' + match[2] + '-' + match[3] + + +def _verify_terminal(root, request, lease): + # Activity receipts establish landed delivery, not approval authority. A + # finished lease releases only when receipt policy, Git ancestry and any + # remaining checkout state all verify fail-closed. + with activity.ActivityReadBatch(root): + policy = activity.load_policy(root) + rows = activity._validate_registry(activity._load(activity.registry_path(root, policy)), activity.repository_ref(root)) + receipt = next((r for r in rows if r['receiptRef'] == request['terminalReceiptRef']), None) + # Any terminal outcome the managed policy declares with + # releasesReservation=true may release an already-finished lease; + # landed delivery is still verified against Git ancestry below. + rule = policy['terminalOutcomes'].get(receipt['outcome']) if receipt is not None else None + require(receipt is not None and receipt['ticket'] == lease['ticketId'] + and rule is not None and rule.get('releasesReservation') is True + and receipt['targetBranch'] == lease['targetBranch'], 'matching_merged_receipt_required') + require(rule and rule.get('releasesReservation') is True + and activity._terminal_verified(root, receipt, rule, activity._target_ref(root, receipt['targetBranch'])), 'terminal_delivery_unverified') + if lease['phase'] in {'approved', 'merged', 'closed'}: + require(lease['headSha'] == receipt['headSha'], 'publication_head_mismatch') + tree = root / '.worktrees' / lease['worktreeId'] + branch_head = git(root, 'rev-parse', '--verify', lease['branchRef'], check=False) + if not branch_head and lease['phase'] in {'claimed', 'editing', 'validating'}: + # An allocation head is the accepted base, not the later published + # commit. Explicit release/settlement may release an already-removed + # delivery, but may neither remove nor normalize remaining state. + require(not os.path.lexists(tree), 'terminal_checkout_still_present') + require(not git(root, 'for-each-ref', '--format=%(refname)', lease['branchRef']), + 'terminal_ref_still_present') + registrations = git(root, 'worktree', 'list', '--porcelain', '-z') + require(not any('worktree ' + str(tree) in fields or 'branch ' + lease['branchRef'] in fields + for fields in (row.split('\0') for row in registrations.split('\0\0'))), + 'terminal_checkout_still_registered') + require(lease['headSha'] is not None + and git(root, '--no-replace-objects', 'merge-base', lease['headSha'], receipt['headSha']) + == lease['headSha'], 'terminal_allocation_base_unverified') + else: + require((branch_head or lease['headSha']) == receipt['headSha'], 'terminal_head_mismatch') + if tree.exists(): + with directory(tree): pass + require(git(tree, 'rev-parse', 'HEAD') == receipt['headSha'] + and git(tree, 'symbolic-ref', 'HEAD') == lease['branchRef'] + and not git(tree, 'status', '--porcelain', '--untracked-files=all'), 'worktree_has_unpublished_work') + return receipt + + +def _apply_transitions(lease, *, request_digest, requested_by, idempotency_prefix, authority_ref, stamp): + require(not canonical.validate_lease(lease), 'invalid_canonical_lease') + phase = lease['phase'] + if phase in {'claimed', 'editing', 'validating'}: actions = ['cancel', 'release'] + elif phase == 'approved': actions = ['record-merge', 'close', 'release'] + elif phase == 'merged': actions = ['close', 'release'] + elif phase in {'closed', 'cancelled'}: actions = ['release'] + else: raise PermissionError('phase_requires_existing_controller_reconciliation') + current, receipts = dict(lease), [] + for action in actions: + transition = {'schema': canonical.REQUEST_SCHEMA, 'requestId': request_digest + '-' + action, + 'leaseId': current['leaseId'], 'action': action, 'expectedRevision': current['leaseRevision'], + 'expectedFencingToken': current['fencingToken'], 'expectedPhase': current['phase'], + 'requestedBy': requested_by, 'idempotencyKey': idempotency_prefix + ':' + action, + 'targetHeadSha': current['headSha'], 'replacementReceiptRef': None, + 'authorityRef': authority_ref, 'requestedAt': stamp} + receipt, errors = canonical.evaluate_transition(current, transition) + require(not errors and receipt is not None, 'canonical_transition_refused') + current.update(phase=receipt['phaseAfter'], leaseRevision=receipt['leaseRevision'], + fencingToken=receipt['fencingToken'], eventSequence=current['eventSequence'] + 1, + publicationFrozen=receipt['phaseAfter'] in canonical.FROZEN_PHASES, previousReceiptRef=receipt['receiptRef']) + receipts.append(receipt) + require(not canonical.validate_lease(current), 'invalid_release_result') + return current, receipts + + +def replacement(lease, request, stamp): + return _apply_transitions( + lease, + request_digest=sha(encoded(request)), + requested_by=request['ownerActor'], + idempotency_prefix=request['requestId'], + authority_ref=request['terminalReceiptRef'], + stamp=stamp, + ) + + +def _settlement_replacement(lease, settlement, stamp): + require(lease.get('phase') in SETTLEABLE_PHASES, 'phase_requires_existing_controller_reconciliation') + digest = sha(encoded(settlement)) + return _apply_transitions( + lease, + request_digest=digest, + requested_by=SETTLED_BY, + idempotency_prefix='settlement:' + digest[:48], + authority_ref=settlement['terminalReceiptRef'], + stamp=stamp, + ) + + +def _accepted_repositories(root): + accepted = {'local/' + sha(str(root).encode())} + origin_url = git(root, 'config', '--get', 'remote.origin.url', check=False) + try: + canonical_identity = canonical.canonical_owner_repository(origin_url) if origin_url else None + except Exception: + # An origin that cannot be canonicalized leaves the local digest authoritative. + canonical_identity = None + if canonical_identity: + accepted.add(canonical_identity) + return accepted + + +def _controller_root(root): + require(os.name == 'posix' and hasattr(os, 'O_NOFOLLOW'), 'posix_controller_required') + root = Path(root).absolute() + with directory(root): pass + root = Path(git(root, 'worktree', 'list', '--porcelain').splitlines()[0].removeprefix('worktree ')) + require(root.is_absolute(), 'primary_checkout_unavailable') + policy = root / '.governance/ticket-allocation.json' + if not policy.exists(): policy = root / 'governance/ticket-allocation.json' + config = read_path(policy) + require(isinstance(config, dict) and set(config) == {'$schema', 'schema', 'mode'} + and config['schema'] == 'new-project.ticket-allocation/v1' + and config['mode'] == 'local-single-clone', 'registered_controller_required') + return root, policy, config + + +def _execute(root, request, fd, verify, name, apply): + raw = read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) + current = decode(raw) + require(not canonical.validate_lease(current), 'invalid_canonical_lease') + ticket, branch = request_identity(request) + accepted_repositories = _accepted_repositories(root) + expected = {'ticketId': ticket, 'worktreeId': request['worktreeId'], 'branchRef': branch} + require(all(current[k] == v for k, v in expected.items()), 'lease_scope_mismatch') + require(current['ownerActor'] == request['ownerActor'] + and current['ownerSession'] == request['ownerSession'], 'current_owner_mismatch') + require(current['repositoryRef'] in accepted_repositories, 'repository_identity_mismatch') + journal_path = root / '.subactor/receipts/terminal-owner-release' / (sha(encoded(request)) + '.json') + if journal_path.exists() or journal_path.is_symlink(): + journal = read_path(journal_path) + original = base64.b64decode(journal['original'], validate=True) + require(journal['request'] == request and sha(original) == request['expectedLeaseSha256'], 'journal_request_mismatch') + prior = decode(original) + require(prior['leaseRevision'] == request['expectedRevision'] + and prior['fencingToken'] == request['expectedFencingToken'], 'journal_fencing_mismatch') + target, receipts = replacement(prior, request, journal['stamp']) + require(journal['replacement'] == target and journal['transitions'] == receipts, 'journal_transition_mismatch') + if raw == encoded(target): + return {'status': 'idempotent', 'leaseRevision': target['leaseRevision'], 'fencingToken': target['fencingToken']} + require(raw == original, 'journal_lease_compare_and_swap_lost') + else: + require(sha(raw) == request['expectedLeaseSha256'] and current['leaseRevision'] == request['expectedRevision'] + and current['fencingToken'] == request['expectedFencingToken'], 'lease_compare_and_swap_lost') + stamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ') + target, receipts = replacement(current, request, stamp) + journal = {'schema': REQUEST_SCHEMA, 'request': request, 'original': base64.b64encode(raw).decode(), + 'replacement': target, 'transitions': receipts, 'stamp': stamp} + _verify_terminal(root, request, current) + verify() + require(read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) == raw, 'lease_compare_and_swap_lost') + if not apply: + return {'status': 'planned', 'grantsAuthority': False, 'actions': [r['action'] for r in receipts]} + with directory(journal_path.parent, create=True) as (journal_fd, verify_journal): + try: atomic_at(journal_fd, journal_path.name, encoded(journal), exclusive=True) + except FileExistsError: + require(read_at(journal_fd, journal_path.name) == encoded(journal), 'journal_changed') + verify_journal() + verify() + require(read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) == raw, 'lease_compare_and_swap_lost') + _replace_lease(fd, name, encoded(target)) + verify() + return {'status': 'released', 'leaseRevision': target['leaseRevision'], 'fencingToken': target['fencingToken'], + 'receipt': str(journal_path), 'worktreeCleanup': 'separate_controller_required'} + + +def release_owner(root, request, *, apply=False, actor=None, session=None): + request_identity(request) + require(os.name == 'posix' and hasattr(os, 'O_NOFOLLOW'), 'posix_controller_required') + if apply: + require(actor == request['ownerActor'] and session == request['ownerSession'], 'invoking_owner_context_required') + root, policy, config = _controller_root(root) + with directory(root / '.subactor/leases') as (fd, verify_directory): + def verify(): + verify_directory() + require(read_path(policy) == config, 'controller_policy_changed') + name = request['worktreeId'] + '.json' + if apply: + with lease_lock(fd, name, verify) as verify_lock: + return _execute(root, request, fd, verify_lock, name, True) + return _execute(root, request, fd, verify, name, False) + + +def _index_releasing_receipts(root): + with activity.ActivityReadBatch(root): + policy = activity.load_policy(root) + reg_path = activity.registry_path(root, policy) + if not os.path.lexists(reg_path): + return {} + rows = activity._validate_registry(activity._load(reg_path), activity.repository_ref(root)) + by_ticket_branch = {} + for row in rows: + rule = policy['terminalOutcomes'].get(row['outcome']) + if rule is not None and rule.get('releasesReservation') is True: + by_ticket_branch.setdefault((row['ticket'], row['targetBranch']), []).append(row) + return by_ticket_branch + + +def _select_verified_receipt(root, candidates, lease): + require(bool(candidates), 'matching_merged_receipt_required') + verified = [] + last_error = 'matching_merged_receipt_required' + for candidate in candidates: + try: + verified.append(_verify_terminal(root, {'terminalReceiptRef': candidate['receiptRef']}, lease)) + except (OSError, ValueError, TypeError, KeyError, PermissionError, subprocess.SubprocessError, activity.ActivityError) as exc: + last_error = str(exc) or type(exc).__name__ + require(bool(verified), last_error) + require(len({item['headSha'] for item in verified}) == 1, 'ambiguous_terminal_receipts') + return verified[-1] + + +def _settle_one(root, fd, verify, name, stem, file_ticket, expected_branch, accepted_repositories, receipts_index, apply): + raw = read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) + current = decode(raw) + require(not canonical.validate_lease(current), 'invalid_canonical_lease') + require(current['ticketId'] == file_ticket and current['worktreeId'] == stem + and current['branchRef'] == expected_branch, 'lease_scope_mismatch') + require(current['repositoryRef'] in accepted_repositories, 'repository_identity_mismatch') + if current['phase'] == 'released': + return None, 'already_released' + require(current['phase'] in SETTLEABLE_PHASES, + 'phase_requires_existing_controller_reconciliation') + candidates = receipts_index.get((current['ticketId'], current['targetBranch']), ()) + receipt = _select_verified_receipt(root, candidates, current) + settlement = { + 'schema': SETTLEMENT_SCHEMA, + 'settledBy': SETTLED_BY, + 'worktreeId': stem, + 'ticketId': current['ticketId'], + 'leaseId': current['leaseId'], + 'expectedRevision': current['leaseRevision'], + 'expectedFencingToken': current['fencingToken'], + 'expectedLeaseSha256': sha(raw), + 'terminalReceiptRef': receipt['receiptRef'], + } + journal_path = root / '.subactor/receipts/terminal-owner-release' / ('settlement-' + sha(encoded(settlement)) + '.json') + if journal_path.exists() or journal_path.is_symlink(): + journal = read_path(journal_path) + original = base64.b64decode(journal['original'], validate=True) + require(journal.get('schema') == SETTLEMENT_SCHEMA + and journal.get('settledBy') == SETTLED_BY + and journal.get('terminalReceiptRef') == receipt['receiptRef'] + and journal.get('settlement') == settlement + and sha(original) == settlement['expectedLeaseSha256'], 'journal_request_mismatch') + prior = decode(original) + require(prior['leaseRevision'] == settlement['expectedRevision'] + and prior['fencingToken'] == settlement['expectedFencingToken'], 'journal_fencing_mismatch') + target, transitions = _settlement_replacement(prior, settlement, journal['stamp']) + require(journal['replacement'] == target and journal['transitions'] == transitions, 'journal_transition_mismatch') + require(raw == original, 'journal_lease_compare_and_swap_lost') + else: + stamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ') + target, transitions = _settlement_replacement(current, settlement, stamp) + journal = { + 'schema': SETTLEMENT_SCHEMA, + 'settledBy': SETTLED_BY, + 'terminalReceiptRef': receipt['receiptRef'], + 'settlement': settlement, + 'original': base64.b64encode(raw).decode(), + 'replacement': target, + 'transitions': transitions, + 'stamp': stamp, + } + verify() + require(read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) == raw, 'lease_compare_and_swap_lost') + if not apply: + return ({ + 'worktreeId': stem, + 'ticketId': current['ticketId'], + 'status': 'planned', + 'grantsAuthority': False, + 'settledBy': SETTLED_BY, + 'terminalReceiptRef': receipt['receiptRef'], + 'actions': [r['action'] for r in transitions], + }, None) + with directory(journal_path.parent, create=True) as (journal_fd, verify_journal): + try: atomic_at(journal_fd, journal_path.name, encoded(journal), exclusive=True) + except FileExistsError: + require(read_at(journal_fd, journal_path.name) == encoded(journal), 'journal_changed') + verify_journal() + verify() + require(read_at(fd, name, canonical.MAX_LEASE_BYTES, private=True) == raw, 'lease_compare_and_swap_lost') + _replace_lease(fd, name, encoded(target)) + verify() + return ({ + 'worktreeId': stem, + 'ticketId': current['ticketId'], + 'status': 'released', + 'leaseRevision': target['leaseRevision'], + 'fencingToken': target['fencingToken'], + 'settledBy': SETTLED_BY, + 'terminalReceiptRef': receipt['receiptRef'], + 'receipt': str(journal_path), + 'worktreeCleanup': 'separate_controller_required', + }, None) + + +def settle_verified_leases(root, *, ticket=None, apply=False): + require(os.name == 'posix' and hasattr(os, 'O_NOFOLLOW'), 'posix_controller_required') + if ticket is not None: + require(isinstance(ticket, str) and TICKET_ID_RE.fullmatch(ticket) is not None, 'invalid_ticket_identity') + root, policy, config = _controller_root(root) + leases_dir = root / '.subactor/leases' + if not os.path.lexists(leases_dir): + require(ticket is None, 'matching_lease_not_found') + return { + 'schema': SETTLEMENT_REPORT_SCHEMA, + 'mode': 'apply' if apply else 'plan', + 'grantsAuthority': False, + 'settledBy': SETTLED_BY, + 'settled': [], + 'skipped': [], + } + accepted_repositories = _accepted_repositories(root) + receipts_index = _index_releasing_receipts(root) + settled, skipped = [], [] + matched_ticket = 0 + with directory(leases_dir) as (fd, verify_directory): + def verify(): + verify_directory() + require(read_path(policy) == config, 'controller_policy_changed') + names = sorted(entry for entry in os.listdir(fd) if entry.endswith('.json')) + for name in names: + stem = name[:-5] + match = WORKTREE_ID_RE.fullmatch(stem) + if match is None: + if ticket is None: + skipped.append({'worktreeId': stem, 'ticketId': None, 'reason': 'invalid_worktree_identity'}) + continue + file_ticket = match[1] + if ticket is not None and file_ticket != ticket: + continue + matched_ticket += 1 + expected_branch = 'refs/heads/ticket/' + match[2] + '-' + match[3] + try: + if apply: + with lease_lock(fd, name, verify) as verify_lock: + record, skip_reason = _settle_one( + root, fd, verify_lock, name, stem, file_ticket, + expected_branch, accepted_repositories, receipts_index, True, + ) + else: + record, skip_reason = _settle_one( + root, fd, verify, name, stem, file_ticket, + expected_branch, accepted_repositories, receipts_index, False, + ) + if record is not None: + settled.append(record) + elif skip_reason is not None: + skipped.append({'worktreeId': stem, 'ticketId': file_ticket, 'reason': skip_reason}) + except (OSError, ValueError, TypeError, KeyError, PermissionError, subprocess.SubprocessError, activity.ActivityError) as exc: + verify() + skipped.append({ + 'worktreeId': stem, + 'ticketId': file_ticket, + 'reason': str(exc) or type(exc).__name__, + }) + if ticket is not None: + require(matched_ticket > 0, 'matching_lease_not_found') + refused = [item for item in skipped if item['reason'] != 'already_released'] + require(not refused, refused[0]['reason'] if refused else 'settlement_refused') + return { + 'schema': SETTLEMENT_REPORT_SCHEMA, + 'mode': 'apply' if apply else 'plan', + 'grantsAuthority': False, + 'settledBy': SETTLED_BY, + 'settled': settled, + 'skipped': skipped, + } + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', type=Path, default=Path.cwd()) + mode = parser.add_mutually_exclusive_group(required=True) + mode.add_argument('--request', type=Path) + mode.add_argument('--settle-verified', action='store_true') + parser.add_argument('--ticket', default=None) + parser.add_argument('--apply', action='store_true') + args = parser.parse_args(argv) + try: + if args.settle_verified: + print(json.dumps(settle_verified_leases(args.root, ticket=args.ticket, apply=args.apply))) + return 0 + require(args.ticket is None, 'ticket_filter_requires_settle_verified') + print(json.dumps(release_owner(args.root, read_path(args.request.absolute()), apply=args.apply, + actor=os.environ.get('NEW_PROJECT_WRITER_ACTOR'), session=os.environ.get('NEW_PROJECT_WRITER_SESSION')))) + return 0 + except (OSError, ValueError, TypeError, KeyError, PermissionError, subprocess.SubprocessError, activity.ActivityError) as exc: + # These labels are static controller predicates, never exception text + # from a path, Git process, JSON input or private owner identifier. + reason = exc.args[0] if (type(exc) is PermissionError and len(exc.args) == 1 + and type(exc.args[0]) is str and exc.args[0] in IDENTITY_FAILURES) else None + detail = f' reason={reason};' if reason else '' + print(f'GOV-CHANGE-LEASE-002: terminal owner release refused;{detail} preserve evidence and reconcile the exact owner, CAS, receipt and controller.', file=sys.stderr) + return 2 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/.governance/ticket-allocation-receipt.schema.json b/.governance/ticket-allocation-receipt.schema.json index 32b3e52..80f4ea2 100644 --- a/.governance/ticket-allocation-receipt.schema.json +++ b/.governance/ticket-allocation-receipt.schema.json @@ -7,17 +7,17 @@ "required": ["schema", "allocationId", "repositoryRef", "ticket", "number", "requestDigest", "processUri", "issuer", "fencingToken", "issuedAt", "expiresAt", "receiptRef", "proofDigest"], "properties": { "schema": {"const": "new-project.ticket-allocation-receipt/v1"}, - "allocationId": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, - "repositoryRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, + "allocationId": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, + "repositoryRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, "ticket": {"type": "string", "pattern": "^ticket-[0-9]{3,}$"}, "number": {"type": "integer", "minimum": 1}, "requestDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, - "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, - "issuer": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, + "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, + "issuer": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, "fencingToken": {"type": "integer", "minimum": 1}, "issuedAt": {"type": "string", "format": "date-time"}, "expiresAt": {"type": "string", "format": "date-time"}, - "receiptRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, + "receiptRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, "proofDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"} } } diff --git a/.governance/ticket-allocation-request.schema.json b/.governance/ticket-allocation-request.schema.json index b7d24e7..6b02160 100644 --- a/.governance/ticket-allocation-request.schema.json +++ b/.governance/ticket-allocation-request.schema.json @@ -7,7 +7,7 @@ "required": ["schema", "repositoryRef", "allocationKey", "titleDigest", "agent", "workstream", "classification", "processUri"], "properties": { "schema": {"const": "new-project.ticket-allocation-request/v1"}, - "repositoryRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, + "repositoryRef": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, "allocationKey": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$"}, "titleDigest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, "agent": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$"}, @@ -22,6 +22,6 @@ "origin": {"enum": ["regression", "requested", "health"]} } }, - "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"} + "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"} } } diff --git a/.governance/ticket-allocation.schema.json b/.governance/ticket-allocation.schema.json index b8a3ad9..c1c5f14 100644 --- a/.governance/ticket-allocation.schema.json +++ b/.governance/ticket-allocation.schema.json @@ -26,8 +26,8 @@ "additionalProperties": false, "required": ["processUri", "issuer", "maxReceiptAgeSeconds"], "properties": { - "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, - "issuer": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://[^\\s]+$"}, + "processUri": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, + "issuer": {"type": "string", "pattern": "^[a-z][a-z0-9+.-]*://\\S+$"}, "maxReceiptAgeSeconds": {"type": "integer", "minimum": 30, "maximum": 3600} } } diff --git a/.governance/ticket_activity.py b/.governance/ticket_activity.py index cf6c377..5a2b206 100755 --- a/.governance/ticket_activity.py +++ b/.governance/ticket_activity.py @@ -63,6 +63,11 @@ def __init__(self, root: Path): self.root = root.resolve() self.queries = {} self.files = {} + self.ancestors = {} + self.derived = {} + self.branch_heads = None + self.consulted_ticket_numbers = set() + self.worktree_registration = "" self.context_reset = None def __enter__(self): @@ -70,13 +75,17 @@ def __enter__(self): raise ActivityError("activity read batch is already open") self.queries.clear() self.files.clear() + self.ancestors.clear() + self.derived.clear() + self.branch_heads = None + self.consulted_ticket_numbers.clear() self.context_reset = _READ_BATCH.set(self) try: - # Fence checkout identity, HEAD and registration even when every - # historical receipt belongs to a different ticket branch. + # Fence checkout identity, HEAD and this checkout's own worktree + # registration without coupling unrelated sibling worktree commits. _git(self.root, "rev-parse", "--path-format=absolute", "--git-common-dir", check=False) _git(self.root, "rev-parse", "--verify", "HEAD", check=False) - _git(self.root, "worktree", "list", "--porcelain", check=False) + self.worktree_registration = self._worktree_registration() self.directory_names = self._directories() except BaseException as error: _READ_BATCH.reset(self.context_reset) @@ -86,6 +95,23 @@ def __enter__(self): raise return self + def _worktree_registration(self) -> str: + raw = _run_git(self.root, "worktree", "list", "--porcelain", "-z", check=False) + if not raw: + return "" + matched: list[str] = [] + for stanza in raw.split("\0\0"): + fields = [item for item in stanza.split("\0") if item] + if not fields or not fields[0].startswith("worktree "): + continue + path_str = fields[0].removeprefix("worktree ") + try: + if Path(path_str).resolve() == self.root: + matched.append("\0".join(fields)) + except OSError: + continue + return "\0\0".join(matched) if matched else raw + def _directories(self): project = self.root / "project" return sorted(p.name for p in project.iterdir()) if project.is_dir() else None @@ -97,9 +123,26 @@ def __exit__(self, kind, value, traceback): if kind is None: if self.directory_names != self._directories(): raise ActivityError("ticket inventory changed during activity inspection; retry") + if self.worktree_registration != self._worktree_registration(): + raise ActivityError("Git state changed during activity inspection; retry") for (args, check), expected in self.queries.items(): if _run_git(self.root, *args, check=check) != expected: raise ActivityError("Git state changed during activity inspection; retry") + if self.branch_heads is not None and self.consulted_ticket_numbers: + latest_listed = _run_git( + self.root, + "for-each-ref", + "--format=%(refname) %(objectname)", + "refs/remotes/origin", + "refs/heads", + ) + latest_heads = _branch_heads_by_ticket(latest_listed) + for number in self.consulted_ticket_numbers: + if latest_heads.get(number, ()) != self.branch_heads.get(number, ()): + raise ActivityError("Git state changed during activity inspection; retry") + for (older, newer), expected in self.ancestors.items(): + if _run_ancestor(self.root, older, newer) != expected: + raise ActivityError("Git state changed during activity inspection; retry") for (path, operation), expected in self.files.items(): if _file_observation(path, operation) != expected: raise ActivityError("activity document changed during inspection; retry") @@ -108,6 +151,10 @@ def __exit__(self, kind, value, traceback): finally: self.queries.clear() self.files.clear() + self.ancestors.clear() + self.derived.clear() + self.branch_heads = None + self.consulted_ticket_numbers.clear() def _file_observation(path: Path, operation: str): @@ -256,13 +303,62 @@ def repository_ref(root: Path) -> str: return f"local:{common}" +def _ticket_state_fields(text: str) -> tuple[set[str], set[str]]: + """Read explicit metadata, including the historical inline header. + + A status projection never grants authority. Ignore fenced examples and + refuse contradictory declarations rather than select whichever comes first. + """ + statuses: set[str] = set() + states: set[str] = set() + fence: str | None = None + fence_length = 0 + for raw_line in text.split("\n"): + line = raw_line.removesuffix("\r") + delimiter = re.match(r"^[ \t]{0,3}(`{3,}|~{3,})(.*)$", line) + if fence is not None: + if (delimiter and delimiter.group(1)[0] == fence + and len(delimiter.group(1)) >= fence_length + and not delimiter.group(2).strip()): + fence = None + continue + if delimiter: + fence = delimiter.group(1)[0] + fence_length = len(delimiter.group(1)) + continue + status = re.fullmatch(r"-[ \t]+\*\*Status\*\*:[ \t]*([A-Z_]+)[ \t]*", line, re.I) + workflow = re.fullmatch(r"-[ \t]+\*\*Workflow state\*\*:[ \t]*([A-Z_]+)[ \t]*", line, re.I) + legacy = re.fullmatch( + r"Status:[ \t]*([A-Z_]+)(?:[ \t]*/[ \t]*([A-Z_]+))?[ \t]*\.?[ \t]*", + line, re.I, + ) + if status: + statuses.add(status.group(1).upper()) + if workflow: + states.add(workflow.group(1).upper()) + if legacy: + statuses.add(legacy.group(1).upper()) + if legacy.group(2): + states.add(legacy.group(2).upper()) + return statuses, states + + +def parse_ticket_state_text(text: str) -> tuple[str | None, str | None]: + statuses, states = _ticket_state_fields(text) + if len(statuses) > 1 or len(states) > 1: + return None, None + return next(iter(statuses), None), next(iter(states), None) + + def projection_status(ticket_dir: Path) -> str | None: try: text = _read_text(ticket_dir / "README.md") except OSError: return None - match = re.search(r"(?mi)^-[ \t]+\*\*Status\*\*:[ \t]*([A-Z_]+)[ \t]*$", text) - return match.group(1).upper() if match else None + statuses, states = _ticket_state_fields(text) + if len(statuses) > 1 or len(states) > 1: + raise ActivityError("ticket status or workflow declarations conflict") + return next(iter(statuses), None) def _validate_terminal_receipt(receipt, seen): @@ -302,7 +398,7 @@ def _validate_registry(value: Any, expected_repository: str) -> list[dict[str, s return receipts -def _ancestor(root: Path, older: str, newer: str) -> bool: +def _run_ancestor(root: Path, older: str, newer: str) -> bool: result = subprocess.run( ["git", "-C", str(root), "merge-base", "--is-ancestor", older, newer], capture_output=True, check=False, timeout=20, @@ -311,6 +407,18 @@ def _ancestor(root: Path, older: str, newer: str) -> bool: return result.returncode == 0 +def _ancestor(root: Path, older: str, newer: str) -> bool: + batch = _READ_BATCH.get() + if batch is None: + return _run_ancestor(root, older, newer) + if root.resolve() != batch.root: + raise ActivityError("activity read batch cannot cross checkouts") + key = (older, newer) + if key not in batch.ancestors: + batch.ancestors[key] = _run_ancestor(root, older, newer) + return batch.ancestors[key] + + def _linear_series(root: Path, base: str, head: str) -> list[str] | None: """Return the exact single-parent chain from base to head, or fail closed.""" raw = _git(root, "rev-list", "--reverse", "--ancestry-path", f"{base}..{head}", check=False) @@ -342,6 +450,12 @@ def _stable_patch_id(payload: bytes, env: dict[str, str]) -> str | None: return fields[0] if len(fields) >= 2 and SHA_RE.fullmatch(fields[0]) else None +# project/readme.sh regenerates this index from the ticket directories. A +# squash or rebase onto a target where a sibling already added the same rows +# drops its hunk, so patch identity covers every authored path but not it. +GENERATED_INDEX_PATHSPEC = ("--", ":(top)", ":(top,exclude)project/TICKETS.md") + + def _patch_id(root: Path, commit: str) -> str | None: """Return Git's stable patch identity for one non-empty commit.""" env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")} @@ -356,6 +470,7 @@ def _patch_id(root: Path, commit: str) -> str | None: "--binary", "--full-index", commit, + *GENERATED_INDEX_PATHSPEC, ], capture_output=True, check=False, @@ -381,6 +496,7 @@ def _range_patch_id(root: Path, base: str, head: str) -> str | None: "--full-index", base, head, + *GENERATED_INDEX_PATHSPEC, ], capture_output=True, check=False, @@ -468,18 +584,152 @@ def _advanced_ticket_branch(root: Path, ticket: str, head_sha: str, terminal_sha return bool(current and current != head_sha and _ancestor(root, head_sha, current) and not _ancestor(root, current, terminal_sha)) -def _unmerged_ticket_branch(root: Path, ticket: str, target: str) -> bool: - """Keep supported outstanding ticket branches active from a strict inventory.""" - listed = _git(root, "for-each-ref", "--format=%(refname) %(objectname)", - "refs/remotes/origin", "refs/heads") +TICKET_BRANCH_TOKEN_RE = re.compile( + r"(?:^|[^0-9a-z])ticket[-_/]?0*([0-9]+)(?=[^0-9a-z]|$)", re.IGNORECASE +) + + +def _branch_heads_by_ticket(listed: str) -> dict[str, tuple[str, ...]]: + grouped: dict[str, list[str]] = {} for entry in listed.splitlines(): ref, _, head = entry.partition(" ") branch = ref.removeprefix("refs/remotes/origin/").removeprefix("refs/heads/") - if _ticket_branch_matches(branch, ticket) and not _ancestor(root, head, target): - return True - return False + for match in TICKET_BRANCH_TOKEN_RE.finditer(branch): + number = str(int(match.group(1))) + heads = grouped.setdefault(number, []) + if head not in heads: + heads.append(head) + return {number: tuple(heads) for number, heads in grouped.items()} + + +def _unmerged_ticket_branch(root: Path, ticket: str, target: str) -> bool: + """Keep supported outstanding ticket branches active from a strict inventory.""" + batch = _READ_BATCH.get() + if batch is not None: + if root.resolve() != batch.root: + raise ActivityError("activity read batch cannot cross checkouts") + if batch.branch_heads is None: + listed = _run_git( + root, + "for-each-ref", + "--format=%(refname) %(objectname)", + "refs/remotes/origin", + "refs/heads", + ) + batch.branch_heads = _branch_heads_by_ticket(listed) + number = str(int(ticket.removeprefix("ticket-"))) + batch.consulted_ticket_numbers.add(number) + heads = batch.branch_heads.get(number, ()) + else: + listed = _git(root, "for-each-ref", "--format=%(refname) %(objectname)", + "refs/remotes/origin", "refs/heads") + heads = tuple( + entry.partition(" ")[2] + for entry in listed.splitlines() + if _ticket_branch_matches( + entry.partition(" ")[0].removeprefix("refs/remotes/origin/").removeprefix("refs/heads/"), + ticket, + ) + ) + return any(not _ancestor(root, head, target) for head in heads) +def _target_tree_entries(root: Path, spec: str) -> frozenset[str]: + raw = _git(root, "ls-tree", "--name-only", spec, check=False) + batch = _READ_BATCH.get() + if batch is not None: + key = ("tree_entries", spec, raw) + if key not in batch.derived: + batch.derived[key] = frozenset(raw.splitlines()) + return batch.derived[key] + return frozenset(raw.splitlines()) + + +def _is_tracking_carrier(path: str, parent: str) -> bool: + prefix = f"{parent}/" if parent else "" + if path in {"TODO.md", f"{prefix}TICKETS.md", "project/TICKETS.md"}: + return True + return re.match(rf"^{re.escape(prefix)}ticket-[0-9]{{3,}}(?:/|$)", path) is not None + + +def _target_delivery_evidence( + root: Path, + target: str, + parent: str, +) -> tuple[dict[str, str | None], frozenset[str], frozenset[str]]: + status_raw = _git( + root, + "grep", + "-I", + "-E", + r"^[[:space:]]*-[[:space:]]*\*\*Status\*\*:", + target, + "--", + parent or ".", + check=False, + ) + log_raw = _git( + root, + "log", + "-m", + "--first-parent", + "--format=@@COMMIT@@%s", + "-z", + "--name-only", + target, + check=False, + ) + batch = _READ_BATCH.get() + key = ("target_delivery_evidence", target, parent, status_raw, log_raw) + if batch is not None and key in batch.derived: + return batch.derived[key] + + prefix = f"{parent}/" if parent else "" + readme_re = re.compile(rf"^{re.escape(prefix)}(ticket-[0-9]{{3,}})/README\.md$") + ticket_path_re = re.compile(rf"^{re.escape(prefix)}(ticket-[0-9]{{3,}})(?:/|$)") + + statuses: dict[str, str | None] = {} + target_prefix = f"{target}:" + for line in status_raw.splitlines(): + if not line.startswith(target_prefix): + continue + rel_path, sep, matched = line[len(target_prefix):].partition(":") + if not sep: + continue + match = readme_re.fullmatch(rel_path) + if match is None: + continue + ticket_name = match.group(1) + if ticket_name not in statuses: + parsed_status, _ = parse_ticket_state_text(matched) + statuses[ticket_name] = parsed_status + + delivered_names: set[str] = set() + delivered_numbers: set[str] = set() + for record in log_raw.split("@@COMMIT@@"): + if not record: + continue + parts = record.split("\x00") + subject = parts[0] + paths: list[str] = [] + for index, raw_path in enumerate(parts[1:]): + cleaned = raw_path.removeprefix("\n") if index == 0 else raw_path + if cleaned: + paths.append(cleaned) + if not any(not _is_tracking_carrier(path, parent) for path in paths): + continue + for path in paths: + path_match = ticket_path_re.match(path) + if path_match is not None: + delivered_names.add(path_match.group(1)) + for token_match in TICKET_BRANCH_TOKEN_RE.finditer(subject): + delivered_numbers.add(str(int(token_match.group(1)))) + + result = (statuses, frozenset(delivered_names), frozenset(delivered_numbers)) + if batch is not None: + batch.derived[key] = result + return result + def delivery_landed(root: Path, ticket_dir: Path, target: str) -> bool: """Answer from Git whether this ticket's delivery is already on the target. @@ -496,24 +746,30 @@ def delivery_landed(root: Path, ticket_dir: Path, target: str) -> bool: release — was reasoning over that noise, which is why declaring a conflict never helped anyone. - A ticket's own directory is committed together with its delivery, because a - commit carrying only tracking carriers is refused. Its presence on the - target ref is therefore the ancestry evidence the policy asks for. A branch - for the same ticket that the target does not yet contain means more of the - delivery is still in flight, and the ticket stays active. + Mere directory existence on the target ref is insufficient when planning or + allocation commits the ticket stub before implementation lands. Require + either a terminal ticket status on the target ref or a first-parent commit + on the target ref tying the ticket to at least one non-carrier delivery + path, with no unmerged ticket branch still in flight. """ try: relative = ticket_dir.resolve().relative_to(root.resolve()).as_posix() except ValueError: return False - present = subprocess.run( - ["git", "-C", str(root), "cat-file", "-e", f"{target}:{relative}"], - capture_output=True, check=False, timeout=20, - env={key: value for key, value in os.environ.items() if not key.startswith("GIT_")}, - ) - if present.returncode != 0: + parent, _, name = relative.rpartition("/") + spec = f"{target}:{parent}" if parent else target + if not name or name not in _target_tree_entries(root, spec): + return False + if _unmerged_ticket_branch(root, ticket_dir.name, target): + return False + statuses, delivered_names, delivered_numbers = _target_delivery_evidence(root, target, parent) + target_status = statuses.get(name) + if target_status in {"DONE", "CANCELLED", "CLOSED"}: + return True + if target_status in {"PLAN", "BACKLOG", "BLOCKED"}: return False - return not _unmerged_ticket_branch(root, ticket_dir.name, target) + number = str(int(name.removeprefix("ticket-"))) if TICKET_RE.fullmatch(name) else None + return name in delivered_names or (number is not None and number in delivered_numbers) def resolve(root: Path, ticket_dir: Path, active_statuses: set[str], *, status_override: str | None = None) -> ActivityResolution: diff --git a/.governance/ticket_allocation.py b/.governance/ticket_allocation.py index 883afac..5a04a76 100755 --- a/.governance/ticket_allocation.py +++ b/.governance/ticket_allocation.py @@ -76,15 +76,33 @@ def parse_config(path: Path) -> dict: def canonical_repository_ref(url: str) -> str: + if not isinstance(url, str) or not url or any(ch.isspace() for ch in url): + raise AllocationError("origin URL must be a non-empty URL without whitespace") match = re.fullmatch(r"git@([^:]+):(.+?)(?:\.git)?", url) if match: host, path = match.groups() - return f"git+ssh://{host.lower()}/{path.removesuffix('.git')}" - parsed = urlparse(url) - if parsed.scheme and parsed.hostname: + url = f"ssh://git@{host}/{path}" + try: + parsed = urlparse(url) + host, port = parsed.hostname, parsed.port + except ValueError: + raise AllocationError("origin URL has an invalid authority") from None + if parsed.scheme and host: + if parsed.password is not None or parsed.query or parsed.fragment: + raise AllocationError("origin URL contains credentials or an ambiguous suffix") path = parsed.path.lstrip("/").removesuffix(".git") - scheme = "git+ssh" if parsed.scheme == "ssh" else parsed.scheme.lower() - return f"{scheme}://{parsed.hostname.lower()}/{path}" + if not path: + raise AllocationError("origin URL must identify a repository path") + scheme = "git+ssh" if parsed.scheme.lower() in {"ssh", "git+ssh"} else parsed.scheme.lower() + if scheme == "git+ssh" and not parsed.username: + raise AllocationError("SSH origin URL requires an explicit username") + authority = f"[{host.lower()}]" if ':' in host else host.lower() + if scheme == "git+ssh" and parsed.username != "git": + authority = f"{parsed.username}@{authority}" + default_port = {"git+ssh": 22, "https": 443, "http": 80, "git": 9418}.get(scheme) + if port is not None and port != default_port: + authority += f":{port}" + return f"{scheme}://{authority}/{path}" raise AllocationError("origin URL cannot be normalized to a repository URI") diff --git a/.governance/ticket_input.py b/.governance/ticket_input.py index 57e7408..ff63919 100644 --- a/.governance/ticket_input.py +++ b/.governance/ticket_input.py @@ -155,9 +155,10 @@ def database_rows(root, database): or connection.execute("PRAGMA user_version").fetchone()[0] != 1): raise TicketInputError("unsupported Registry database schema") rows, total = [], 0 - for row in connection.execute("""SELECT ticket, revision, document_sha256, document_json + cursor = connection.execute("""SELECT ticket, revision, document_sha256, document_json FROM ticket_versions AS t WHERE revision=(SELECT MAX(revision) - FROM ticket_versions WHERE ticket=t.ticket) ORDER BY ticket"""): + FROM ticket_versions WHERE ticket=t.ticket) ORDER BY ticket""") + for row in cursor: total += len(row[3].encode("utf-8")) if total > MAX_BYTES or len(rows) >= 10000: raise TicketInputError("ticket input exceeds bound") diff --git a/.governance/ticket_recovery.py b/.governance/ticket_recovery.py index ebd8156..0cfd73a 100644 --- a/.governance/ticket_recovery.py +++ b/.governance/ticket_recovery.py @@ -73,9 +73,15 @@ def controller_lock(store): def validate_lease(store, request, intent, repository, branch, worktree): - state = load(store / "state.json") + resource = start.digest({"repositoryRef": repository, "targetBranch": intent["delivery"]["targetBranch"]}) + try: + state = start.read_controller_projection( + safe_path(store), resources=(resource,), lease_ids=(request["leaseId"],)) + except (start.ObservationError, OSError, ValueError, KeyError, TypeError) as error: + raise RecoveryError("Unsupported or unreadable controller store") from error require(state.get("schema") == "subactor.repository-change-lease-store/v1", "Unsupported controller store") - lease = state["leases"][request["leaseId"]] + lease = state["leases"].get(request["leaseId"]) + require(isinstance(lease, dict), "Controller owner, scope or CAS mismatch") expected = { "schema": "wellmanifest.change-lease/v1", "leaseId": request["leaseId"], "leaseRevision": request["leaseRevision"], "fencingToken": request["fencingToken"], @@ -87,7 +93,6 @@ def validate_lease(store, request, intent, repository, branch, worktree): "publicationFrozen": False, } require(all(lease.get(k) == v for k, v in expected.items()), "Controller owner, scope or CAS mismatch") - resource = start.digest({"repositoryRef": repository, "targetBranch": expected["targetBranch"]}) require(state["active"].get(resource) == lease["leaseId"], "Lease is not the active controller owner") expires = datetime.fromisoformat(lease["expiresAt"].replace("Z", "+00:00")) require(expires.tzinfo is not None and expires > datetime.now(timezone.utc), "Expired lease; explicit controller handoff required") diff --git a/.governance/ticket_restoration.py b/.governance/ticket_restoration.py new file mode 100644 index 0000000..5389e89 --- /dev/null +++ b/.governance/ticket_restoration.py @@ -0,0 +1,350 @@ +#!/usr/bin/env python3 +"""Restore the checkout of an already reserved ticket; never allocate or approve. + +The allocator's reservation record, high-water mark and the external controller +lease stay authoritative. Restoration re-registers the canonical checkout and +writes only the ticket's own README.md and intent.json from a pinned snapshot. +It grants neither source-editing nor merge authority: normal work-start +admission and independent review remain mandatory afterwards. +""" +from __future__ import annotations + +import argparse +from contextlib import contextmanager +from datetime import datetime, timezone +import hashlib +import json +import os +from pathlib import Path +import re +import stat +import sys +import tempfile +from urllib.parse import urlparse + +sys.dont_write_bytecode = True +from governance_check import validate_intent_value +import ticket_recovery as recovery +import work_start_check as start +from ticket_allocation import canonical_repository_ref + +require = recovery.require +safe = recovery.safe_path +FIELDS = {"schema", "ticket", "worktreeId", "headSha", "snapshotPath", "snapshotSha256", + "leaseId", "leaseRevision", "fencingToken", "ownerActor", "ownerSession"} +METADATA = ("README.md", "intent.json") +RESTORING_PHASES = {"claimed", "editing"} + + +def validate_request(request, workstream, local=False): + fields = FIELDS | {"reservationSha256"} if local else FIELDS + schema = "new-project.local-ticket-restoration-request/v1" if local else "new-project.ticket-restoration-request/v1" + require(isinstance(request, dict) and set(request) == fields + and request["schema"] == schema, "Invalid restoration request") + if local: + require(isinstance(request["reservationSha256"], str) + and re.fullmatch(r"[0-9a-f]{64}", request["reservationSha256"]), "Invalid reservation digest") + ticket = request["ticket"] + require(isinstance(ticket, str) and re.fullmatch(r"ticket-[0-9]{3,}", ticket), "Invalid ticket identity") + require(isinstance(request["worktreeId"], str) and re.fullmatch( + re.escape(ticket) + r"--[a-z0-9]+(?:-[a-z0-9]+)*", request["worktreeId"]), "Noncanonical worktree identity") + require(request["headSha"] is None or (isinstance(request["headSha"], str) + and re.fullmatch(r"[0-9a-f]{40}", request["headSha"])), "Invalid exact-head binding") + require(isinstance(request["snapshotSha256"], str) + and re.fullmatch(r"[0-9a-f]{64}", request["snapshotSha256"]), "Invalid snapshot digest") + require(isinstance(request["snapshotPath"], str) and Path(request["snapshotPath"]).is_absolute(), + "Absolute snapshot path required") + for field in ("leaseRevision", "fencingToken"): + require(type(request[field]) is int and request[field] > 0, "Positive integer CAS required") + for field in ("leaseId", "ownerActor", "ownerSession"): + require(isinstance(request[field], str) and 0 < len(request[field]) <= 255, "Explicit owner required") + require(isinstance(workstream, str) and workstream, "Workstream required") + + +def unique(pairs): + result = {} + for key, value in pairs: + require(key not in result, "Duplicate JSON key") + result[key] = value + return result + + +def load_snapshot(request, workstream): + # Hash and parse the same bytes; the path is never reopened after hashing. + descriptor = os.open(safe(request["snapshotPath"]), os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) + with os.fdopen(descriptor, "rb") as stream: + require(stat.S_ISREG(os.fstat(stream.fileno()).st_mode), "Regular file required") + raw = stream.read(4 * 1024 * 1024 + 1) + require(len(raw) <= 4 * 1024 * 1024, "Snapshot too large") + require(hashlib.sha256(raw).hexdigest() == request["snapshotSha256"], "Snapshot digest mismatch") + snapshot = json.loads(raw, object_pairs_hook=unique) + require(isinstance(snapshot, dict) and set(snapshot) == {"schema", "ticket", "files"} + and snapshot["schema"] == "new-project.ticket-metadata-snapshot/v1" + and snapshot["ticket"] == request["ticket"], "Invalid metadata snapshot") + files = snapshot["files"] + require(isinstance(files, dict) and set(files) == set(METADATA) + and all(isinstance(v, str) for v in files.values()), "Snapshot must hold exactly README.md and intent.json") + intent = json.loads(files["intent.json"], object_pairs_hook=unique) + _, error = validate_intent_value(intent, request["ticket"]) + require(error is None and intent.get("ticket") == request["ticket"], "Invalid snapshot intent") + require(intent.get("workstream") == workstream, "Workstream mismatch") + require(re.search(r"^- \*\*Status\*\*: IN_PROGRESS$", files["README.md"], re.M), + "Terminal identity cannot be restored as active work") + return files, intent + + +def reservation(primary, common, request, workstream): + number = int(request["ticket"][7:]) + highwater = safe(common / "new-project-ticket-high-water") + previous = highwater.read_text().strip() if highwater.exists() else "0" + require(re.fullmatch(r"[0-9]+", previous) and number <= int(previous), + "Identity is not reserved; allocate normally") + leases = safe(primary / ".subactor" / "leases") + matches = [p for p in sorted(leases.glob("ticket-*.json")) + if p.name.startswith(request["ticket"] + "--")] + require([p.name for p in matches] == [request["worktreeId"] + ".json"], "Missing or ambiguous reservation") + record = recovery.load(matches[0]) + slug = request["worktreeId"][len(request["ticket"]) + 2:] + expected = {"schema": "wellmanifest.change-lease/v1", "ticketId": request["ticket"], + "worktreeId": request["worktreeId"], "workstream": workstream, + "branchRef": f"refs/heads/ticket/{request['ticket'][7:]}-{slug}", + "ownerActor": request["ownerActor"], "ownerSession": request["ownerSession"]} + require(all(record.get(k) == v for k, v in expected.items()), "Reservation identity or owner mismatch") + require(isinstance(record.get("headSha"), str) and re.fullmatch(r"[0-9a-f]{40}", record["headSha"]), + "Reservation base unavailable") + return record + + +def controller(store, request, record, intent, repository): + resource = start.digest({"repositoryRef": repository, "targetBranch": record["targetBranch"]}) + try: + state = start.read_controller_projection( + safe(store), resources=(resource,), lease_ids=(request["leaseId"],)) + except (start.ObservationError, OSError, ValueError, KeyError, TypeError) as error: + raise recovery.RecoveryError("Unsupported or unreadable controller store") from error + require(state.get("schema") == "subactor.repository-change-lease-store/v1", "Unsupported controller store") + lease = state["leases"].get(request["leaseId"]) + require(isinstance(lease, dict), "Controller owner, scope or CAS mismatch") + expected = {"schema": "wellmanifest.change-lease/v1", "leaseId": request["leaseId"], + "leaseRevision": request["leaseRevision"], "fencingToken": request["fencingToken"], + "ownerActor": request["ownerActor"], "ownerSession": request["ownerSession"], + "repositoryRef": repository, "ticketId": request["ticket"], + "targetBranch": record["targetBranch"], "branchRef": record["branchRef"], + "workstream": record["workstream"], "worktreeId": request["worktreeId"], + "scopeHash": start.digest(intent["allowedPaths"]), "publicationFrozen": False} + require(all(lease.get(k) == v for k, v in expected.items()) and lease.get("phase") in RESTORING_PHASES, + "Controller owner, scope or CAS mismatch") + require(state["active"].get(resource) == lease["leaseId"], "Lease is not the active controller owner") + expires = datetime.fromisoformat(lease["expiresAt"].replace("Z", "+00:00")) + require(expires.tzinfo is not None and expires > datetime.now(timezone.utc), + "Expired lease; explicit controller handoff required") + return lease + + +@contextmanager +def authority(primary, store, request, record, intent, repository, local_owner): + """Hold the selected authority lock; never fall back between owner backends.""" + if local_owner is None: + with recovery.controller_lock(store): + yield lambda: controller(store, request, record, intent, repository) + return + import terminal_lease_release as anchored + path = primary / ".subactor/leases" / (request["worktreeId"] + ".json") + with anchored.directory(path.parent) as (fd, verify): + with anchored.lease_lock(fd, path.name, verify) as verify_lock: + def check(): + verify_lock() + raw = anchored.read_at(fd, path.name, private=True) + info = os.stat(path.name, dir_fd=fd, follow_symlinks=False) + require(info.st_uid == os.geteuid(), "Reservation belongs to another OS owner") + require(hashlib.sha256(raw).hexdigest() == request["reservationSha256"], "Reservation changed") + lease = json.loads(raw, object_pairs_hook=unique) + require(lease == record, "Reservation changed before locking") + require(not anchored.canonical.validate_lease(lease), "Invalid local lease") + expected = {key: request[key] for key in + ("leaseId", "leaseRevision", "fencingToken", "ownerActor", "ownerSession")} + expected.update(ticketId=request["ticket"], worktreeId=request["worktreeId"], + branchRef=record["branchRef"], targetBranch=record["targetBranch"], + workstream=record["workstream"], scopeHash=start.digest(intent["allowedPaths"])) + require(all(lease.get(k) == v for k, v in expected.items()), "Local owner, scope or CAS mismatch") + require(tuple(str(request[k]) for k in ("ownerActor", "ownerSession", "leaseRevision", "fencingToken")) + == tuple(local_owner), "Explicit current writer identity required") + legacy = "local/" + hashlib.sha256(str(primary).encode()).hexdigest() + require(lease["repositoryRef"] in {repository, legacy}, "Local repository mismatch") + require(lease["phase"] in RESTORING_PHASES and not lease["publicationFrozen"], "Local lease is frozen or inactive") + issued, heartbeat, expires = (datetime.fromisoformat(lease[k].replace("Z", "+00:00")) + for k in ("issuedAt", "heartbeatAt", "expiresAt")) + require(all(t.tzinfo is not None for t in (issued, heartbeat, expires)) + and issued <= heartbeat <= datetime.now(timezone.utc) < expires, + "Expired lease; explicit controller handoff required") + verify_lock() + return lease + yield check + + +def observe(primary, request, record, files, intent): + """Return the exact current restoration state; reject every collision.""" + ticket, branch = request["ticket"], record["branchRef"] + canonical = safe(primary / ".worktrees" / request["worktreeId"]) + head = start.git(primary, "rev-parse", "--verify", "--quiet", branch + "^{commit}", optional=True) + head = head.strip() if head else None + target = request["headSha"] or record["headSha"] + require(head in (None, target), "Branch head differs from the bound restoration head") + require(start.git(primary, "cat-file", "-e", target + "^{commit}", optional=True) is not None, + "Bound restoration head is unreachable") + base = record["headSha"] + require(start.git(primary, "merge-base", "--is-ancestor", base, target, optional=True) is not None, + "Restoration head does not descend from the reserved base") + accepted = intent.get("delivery", {}).get("acceptedBaseSha") + require(accepted is None or start.git(primary, "merge-base", "--is-ancestor", accepted, target, + optional=True) is not None, "Accepted base is not an ancestor") + registered = None + for entry in start.worktrees(primary): + path = safe(entry["worktree"]) + if path == canonical: + require("prunable" not in entry, "Stale canonical registration; prune it after confirming the loss") + require(entry.get("branch") == branch, "Canonical checkout registration collides") + registered = path + continue + require(entry.get("branch") != branch, "Ticket branch is checked out elsewhere") + require(not (path / "project" / ticket).exists(), "Ticket already exists in another checkout") + refs = start.git(primary, "for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads").splitlines() + for name in refs: + other = start.TICKET.fullmatch(name) + require(not other or other[1] != ticket[7:] or "refs/heads/" + name == branch, "Ticket branch collision") + require(registered is not None or not os.path.lexists(canonical), "Unregistered path occupies the checkout") + committed = bool(start.git(primary, "ls-tree", "--name-only", target, f"project/{ticket}").strip()) + present = {} + if registered: + backlink = Path(start.git(canonical, "rev-parse", "--absolute-git-dir").strip()) / "gitdir" + require(not Path(backlink.read_text().strip()).is_absolute(), "Relative worktree registration required") + paths = start.dirty_observation(canonical)[2] + require(all(p.startswith(f"project/{ticket}/") for p in paths), "Restored checkout has foreign changes") + directory = canonical / "project" / ticket + require(not directory.is_symlink(), "Symlinked ticket metadata") + for name in METADATA if not committed else (): + path = directory / name + if os.path.lexists(path): + require(not path.is_symlink() and path.read_text() == files[name], + "Existing ticket metadata differs; preserve and continue under normal admission") + present[name] = True + return {"canonical": canonical, "branchHead": head, "target": target, "registered": registered is not None, + "committed": committed, "present": sorted(present)} + + +def write_new(common, path, content): + parent = path.parent + require(not any(p.is_symlink() for p in (parent, *parent.parents)) and parent.is_dir(), + "Ticket metadata directory must be a non-symlinked directory") + descriptor, temporary = tempfile.mkstemp(prefix=".new-project-ticket-restore-", dir=parent) + try: + with os.fdopen(descriptor, "w") as stream: + stream.write(content) + stream.flush() + os.fsync(stream.fileno()) + require(os.stat(temporary, follow_symlinks=False).st_dev == os.stat(parent, follow_symlinks=False).st_dev, + "Temporary restoration file must reside on the destination filesystem") + os.link(temporary, path) # never replaces an existing file + finally: + try: + os.unlink(temporary) + except FileNotFoundError: + pass + + +def restore(root, request_path, store, workstream, *, local_owner=None): + require(os.name == "posix" and hasattr(os, "O_NOFOLLOW"), "POSIX local controller adapter required") + root, request_path = map(safe, (root, request_path)) + require((store is None) == (local_owner is not None), "Select exactly one restoration authority") + store = safe(store) if store is not None else None + common = safe(start.git(root, "rev-parse", "--path-format=absolute", "--git-common-dir").strip()) + primary = safe(start.worktrees(root)[0]["worktree"]) + require(start.configured_mode(primary) == "files" and not (primary / "project.sqlite").exists(), + "SQLite identity requires its registered adapter") + policy = next((p for p in (primary / ".governance/ticket-allocation.json", + primary / "governance/ticket-allocation.json") if p.exists()), None) + if policy: + from ticket_allocation import parse_config + require(parse_config(policy)["mode"] == "local-single-clone", "Registered allocation requires its controller adapter") + lock = safe(common / "new-project-ticket-allocation.lock") + lock.mkdir() # same non-stealable clone lock as allocation and recovery + try: + request = recovery.load(request_path) + validate_request(request, workstream, local_owner is not None) + locations = (request_path, safe(request["snapshotPath"])) + ((store,) if store is not None else ()) + for location in start.worktrees(primary): + checkout = safe(location["worktree"]) + require(not any(p.is_relative_to(checkout) for p in locations), + "Controller, request and snapshot must be outside all checkouts") + require(not any(p.is_relative_to(common) for p in locations), "Recovery inputs cannot reside in Git metadata") + files, intent = load_snapshot(request, workstream) + record = reservation(primary, common, request, workstream) + origin = urlparse(canonical_repository_ref(start.git(primary, "config", "--get", "remote.origin.url").strip())) + require(origin.hostname == "github.com" and origin.scheme in {"https", "git+ssh"}, + "This controller adapter requires a canonical GitHub repository") + repository = origin.path.lstrip("/") + with authority(primary, store, request, record, intent, repository, local_owner) as check: + lease = check() + state = observe(primary, request, record, files, intent) + steps = [] + if state["branchHead"] is None: + check() + start.git(primary, "update-ref", record["branchRef"], state["target"], "") # create-only CAS + steps.append("branch") + if not state["registered"]: + check() + name = record["branchRef"].removeprefix("refs/heads/") + start.git(primary, "worktree", "add", "--relative-paths", str(state["canonical"]), name) + steps.append("checkout") + state = observe(primary, request, record, files, intent) + check() + if not state["committed"]: + directory = state["canonical"] / "project" / request["ticket"] + check() + directory.mkdir(exist_ok=True) + for name in METADATA: + if name not in state["present"]: + check() + write_new(common, directory / name, files[name]) + steps.append(name) + return {"schema": "new-project.ticket-restoration-result/v1", "ticket": request["ticket"], + "worktreeId": request["worktreeId"], "branchRef": record["branchRef"], + "headSha": state["target"], "outcome": "RESTORED" if steps else "ALREADY_RESTORED", + "steps": steps, "metadata": "committed" if state["committed"] else "snapshot", + "snapshotSha256": request["snapshotSha256"], "leaseId": lease["leaseId"], + "leaseRevision": lease["leaseRevision"], "fencingToken": lease["fencingToken"], + "requestDigest": start.digest(request), "grantsEditAuthority": False, + "grantsMergeAuthority": False, + "nextAction": f"python3 .governance/work_start_check.py --workstream {workstream} " + f"--ticket {request['ticket']}"} + finally: + lock.rmdir() + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--root", type=Path, required=True) + parser.add_argument("--request", type=Path, required=True) + backend = parser.add_mutually_exclusive_group(required=True) + backend.add_argument("--lease-store", type=Path) + backend.add_argument("--local-reservation", action="store_true") + for name, variable in (("actor", "WRITER_ACTOR"), ("session", "WRITER_SESSION"), + ("revision", "LEASE_REVISION"), ("fencing", "FENCING_TOKEN")): + parser.add_argument("--" + name, default=os.environ.get("NEW_PROJECT_" + variable, "")) + parser.add_argument("--workstream", required=True) + args = parser.parse_args() + try: + owner = (args.actor, args.session, args.revision, args.fencing) if args.local_reservation else None + print(json.dumps(restore(args.root, args.request, args.lease_store, args.workstream, local_owner=owner))) + return 0 + except recovery.RecoveryError as error: + print("GOV-TICKET-ALLOCATION-003: " + str(error) + "; preserve work and re-observe before retry.", file=sys.stderr) + return 5 + except (OSError, ValueError, KeyError, TypeError, ImportError, start.ObservationError): + print("GOV-TICKET-ALLOCATION-003: restoration rejected; re-observe the reservation, snapshot, controller " + "ownership and registered checkouts; preserve all work.", file=sys.stderr) + return 5 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.governance/ticket_storage.py b/.governance/ticket_storage.py index fffe595..38e7812 100644 --- a/.governance/ticket_storage.py +++ b/.governance/ticket_storage.py @@ -163,14 +163,24 @@ def ownership_hint(manifest, workstream, unowned): "Drop them from --path, or allocate the work in the owning workstream.") -def scoped_paths(root, workstream, paths): +def scoped_paths(root, workstream, paths, bootstrap_adoption_digest=None): """Share the gate's ownership predicate; narrowing is never write authority.""" if not paths: return [] from governance_check import pattern_covered_by from work_start_check import manifest_at, material, patterns + if any( + not isinstance(raw, str) + or not raw + or "\\" in raw + or raw.startswith(("/", "!")) + or ":" in raw + or any(part in {"", ".", ".."} for part in raw.split("/")) + for raw in paths + ): + raise ValueError("canonical repository-relative scope required") scope = patterns(paths) - if any(any(part in {"", "."} for part in path.split("/")) for path in scope): + if any(any(part in {"", ".", ".."} for part in path.split("/")) for path in scope): raise ValueError("canonical repository-relative scope required") manifest = manifest_at(Path(root)) workstreams = manifest['coordination']['workstreams'] @@ -181,14 +191,45 @@ def scoped_paths(root, workstream, paths): if not material(scope): raise ScopeOwnershipError( "scope has no implementation path; ticket tracking files alone are not material work") + bootstrap = set() + if bootstrap_adoption_digest is not None: + if (not isinstance(bootstrap_adoption_digest, str) + or re.fullmatch(r'[0-9a-f]{64}', bootstrap_adoption_digest) is None + or workstream not in {'governance', manifest['coordination']['integration']['workstream']}): + raise ScopeOwnershipError('first bootstrap requires an exact digest and its declared owner') + from work_start_check import ObservationError, bootstrap_owned_paths + try: + bootstrap = bootstrap_owned_paths(Path(root), manifest, bootstrap_adoption_digest) + except (ObservationError, OSError, ValueError) as error: + raise ScopeOwnershipError('bootstrap adoption ownership evidence unavailable') from error unowned = [path for path in scope if not any(pattern_covered_by(path, owner) for owner in owned)] + if (unowned and bootstrap_adoption_digest is not None + and workstream == manifest['coordination']['integration']['workstream']): + # Integration retains dependency-manifest ownership. Its first native + # adoption may also carry the exact installer-owned governance assets; + # this is the gate's verified-adoption exception, not arbitrary scope. + governance = patterns(workstreams['governance']['ownedPaths']) + verified = {path for path in bootstrap + if any(pattern_covered_by(path, owner) for owner in governance)} + unowned = [path for path in unowned if path not in verified] + if (unowned and workstream == 'governance' + and (Path(root) / '.subactor/receipts/bootstrap-adoption.json').exists()): + from work_start_check import ObservationError, bootstrap_seed_paths + try: + seeds = bootstrap_seed_paths(Path(root), manifest) + except (ObservationError, OSError, ValueError) as error: + raise ScopeOwnershipError('bootstrap required seed evidence unavailable') from error + unowned = [path for path in unowned if path not in seeds] if unowned: raise ScopeOwnershipError(ownership_hint(manifest, workstream, unowned)) return scope def persist_scope(args): - scope = scoped_paths(args.root, args.workstream, args.path) + if getattr(args, 'bootstrap_adoption_digest', None) is not None and args.ticket is not None: + raise ScopeOwnershipError('bootstrap digest is admission-only; it cannot rewrite a ticket') + scope = scoped_paths(args.root, args.workstream, args.path, + getattr(args, 'bootstrap_adoption_digest', None)) if args.ticket is not None: if not scope or re.fullmatch(r"ticket-[0-9]{3,}", args.ticket) is None: raise ValueError("reserved identity and explicit scope required") @@ -203,6 +244,80 @@ def persist_scope(args): return scope +def radar_readme(readme, intent, root): + """Assess initial intent through the external product; never grant authority. + + Radar is advisory and separately installed. A missing/failed runtime is + visible in the README rather than blocking identity allocation or inventing + a score. No network installation, shell command or repository edit occurs. + """ + readme = re.sub(r"\n\n.*?\n?", + "\n", readme, flags=re.S) + heading = "\n\n## Ticket Radar\n\n" + notice = "Initial planned-scope estimate; advisory only, not execution or merge approval.\n" + ticket = {"id": intent["ticket"], "name": intent["summary"], + "description": "", "files": intent["allowedPaths"], + "acceptance_criteria": [], "delivery": intent.get("delivery", {})} + budget = intent.get("delivery", {}).get("estimatedMinutes", 30) + reason = "runtime not installed" + try: + result = subprocess.run( + ["ticket-radar", "--repository-root", str(root)], + input=json.dumps({"ticket": ticket, "budget_minutes": budget}), + capture_output=True, text=True, timeout=10, check=False, + ) + reason = "runtime failed or returned an invalid assessment" + if result.returncode or len(result.stdout) > 1024 * 1024: + raise ValueError("radar invocation failed") + bundle = json.loads(result.stdout) + if not isinstance(bundle, dict) or bundle.get("schema") != "subactor.ticket-radar-bundle/v1": + raise ValueError("unknown radar bundle") + record = json.loads(bundle["jsonl"]) + if (record["schema"] != "subactor.ticket-radar/v1" + or record["ticket_ref"] != intent["ticket"] + or record.get("authority", "ADVISORY") != "ADVISORY" + or record["assessment_mode"] != "predicted" + or record["complexity"] not in {"XS", "S", "M", "L", "XL"} + or type(record["score"]) is not int or not 0 <= record["score"] <= 100 + or type(record["estimate"]["minutes"]) is not int + or not 0 <= record["estimate"]["minutes"] <= 100000 + or type(record["estimate"]["budget_minutes"]) is not int + or not 5 <= record["estimate"]["budget_minutes"] <= 240 + or type(record["split"]["recommended"]) is not bool): + raise ValueError("invalid planned assessment") + diagnostics = record.get("diagnostics", []) + if (not isinstance(diagnostics, list) or len(diagnostics) > 40 + or any(not isinstance(v, str) or not re.fullmatch(r"[A-Z0-9_-]{1,100}", v) + for v in diagnostics)): + raise ValueError("invalid diagnostics") + body = ("| Measure | Initial assessment |\n| --- | --- |\n" + f"| Impact score | {record['score']}/100 |\n" + f"| Complexity | {record['complexity']} |\n" + f"| Estimated effort | {record['estimate']['minutes']} min |\n" + f"| Planning budget | {record['estimate']['budget_minutes']} min |\n" + f"| Split recommended | {'yes' if record['split']['recommended'] else 'no'} |\n") + if diagnostics: + body += "\nDiagnostics: " + ", ".join(diagnostics) + ".\n" + except subprocess.TimeoutExpired: + body = "Assessment unavailable: runtime timed out.\n" + except (OSError, ValueError, KeyError, TypeError): + body = "Assessment unavailable: " + reason + ".\n" + return readme.rstrip() + "\n" + heading + notice + "\n" + body + "\n" + + +def assess_file_ticket(args): + if re.fullmatch(r"ticket-[0-9]{3,}", args.ticket or "") is None: + raise ValueError("reserved ticket identity required") + directory = args.root / "project" / args.ticket + for name in ("README.md", "intent.json"): + no_links((directory / name).absolute()) + intent = json.loads((directory / "intent.json").read_text(encoding="utf-8")) + if intent["ticket"] != args.ticket: + raise ValueError("allocated intent identity mismatch") + path = directory / "README.md" + path.write_text(radar_readme(path.read_text(encoding="utf-8"), intent, args.root), encoding="utf-8") + + def create(args): ticket = args.ticket if re.fullmatch(r"ticket-[0-9]{3,}", ticket or "") is None: @@ -219,6 +334,7 @@ def create(args): "stacks": [], "dependsOn": [], "conflictsWith": [], "integrationTicket": None} readme = (f"# {args.title}\n\n- **Status**: IN_PROGRESS\n- **Workflow state**: EDIT\n\n" "## Goal and scope\n\nComplete the bounded intent in SQLite before implementation.\n") + readme = radar_readme(readme, intent, args.root) content = json.dumps({"README.md": readme, "intent.json": json.dumps(intent, indent=2) + "\n"}) invoke(args.runtime_root, args.runtime_sha256, "init", "--repository", str(args.root)) receipt = invoke(args.runtime_root, args.runtime_sha256, "create", "--repository", str(args.root), @@ -228,25 +344,30 @@ def create(args): def main(): parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("command", choices=["digest", "verify", "highest", "create", "active", "scope"]) + parser.add_argument("command", choices=["digest", "verify", "highest", "create", "active", "scope", "radar"]) parser.add_argument("--root", type=Path, default=Path.cwd()) parser.add_argument("--runtime-root") parser.add_argument("--runtime-sha256") parser.add_argument("--active-status", action="append", default=[]) parser.add_argument("--path", action="append", default=[]) + parser.add_argument("--bootstrap-adoption-digest") for name in ("ticket", "title", "workstream", "kind", "priority", "origin", "allocation-key"): parser.add_argument("--" + name) args = parser.parse_args() try: - if args.command == "scope": + if args.bootstrap_adoption_digest is not None and args.command != 'scope': + raise ValueError('bootstrap digest is scope-admission-only') + if args.command == "radar": + assess_file_ticket(args) + elif args.command == "scope": print(json.dumps(persist_scope(args))) elif args.command == "active": - from ticket_activity import resolve + import ticket_activity text = read_file(args.root, args.ticket, "README.md").decode("utf-8") - match = re.search(r"(?mi)^-[ \t]+\*\*Status\*\*:[ \t]*([A-Z_]+)[ \t]*$", text) - if match is None: + status, _ = ticket_activity.parse_ticket_state_text(text) + if status is None: raise ValueError("ticket status required") - result = resolve(args.root, args.root / "project" / args.ticket, set(args.active_status), status_override=match.group(1)) + result = ticket_activity.resolve(args.root, args.root / "project" / args.ticket, set(args.active_status), status_override=status) raise SystemExit(0 if result.active else 1) elif args.command == "highest": database = primary_database(args.root) diff --git a/.governance/work-start-report.schema.json b/.governance/work-start-report.schema.json index 022f3b3..106193e 100644 --- a/.governance/work-start-report.schema.json +++ b/.governance/work-start-report.schema.json @@ -302,6 +302,9 @@ }, "publication": { "$ref": "#/$defs/publicationObservation" + }, + "editingResource": { + "$ref": "#/$defs/editingResourceObservation" } } }, @@ -343,6 +346,43 @@ } ], "$defs": { + "editingResourceObservation": { + "$anchor": "editingResourceObservation", + "type": "object", + "additionalProperties": false, + "required": ["schema", "observedAt", "readOnly", "grantsAuthority", "queueSupported", "repositoryRef", "targetBranch", "ticket", "resource", "state", "reason", "holder", "stateDigest", "nextAction"], + "properties": { + "schema": {"const": "new-project.editing-resource-observation/v1"}, + "observedAt": {"type": "string", "format": "date-time"}, + "readOnly": {"const": true}, + "grantsAuthority": {"const": false}, + "queueSupported": {"type": "boolean"}, + "repositoryRef": {"type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"}, + "targetBranch": {"type": "string"}, + "ticket": {"type": ["string", "null"]}, + "resource": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, + "state": {"enum": ["AVAILABLE", "QUEUED", "HELD_BY_TICKET", "HELD_BY_OTHER", "HELD_EXPIRED", "UNAVAILABLE"]}, + "reason": {"enum": [null, "controller-store-missing", "controller-state-unreadable", "controller-state-invalid", "controller-state-changed", "controller-transport-failure", "controller-pin-mismatch", "controller-policy-denied"]}, + "holder": { + "oneOf": [ + {"type": "null"}, + { + "type": "object", + "additionalProperties": false, + "required": ["leaseId", "ticketId", "phase", "expiresAt"], + "properties": { + "leaseId": {"type": "string"}, + "ticketId": {"type": ["string", "null"]}, + "phase": {"type": "string"}, + "expiresAt": {"type": "string"} + } + } + ] + }, + "stateDigest": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}, + "nextAction": {"type": "string", "minLength": 1} + } + }, "publicationObservation": { "$anchor": "publicationObservation", "type": "object", diff --git a/.governance/work_continuity.py b/.governance/work_continuity.py index 74b93a6..23c7be2 100755 --- a/.governance/work_continuity.py +++ b/.governance/work_continuity.py @@ -22,6 +22,8 @@ import subprocess import sys import tempfile +import secrets +from contextvars import ContextVar import time from datetime import datetime, timezone from typing import Any, Iterable @@ -63,6 +65,9 @@ ] +_TRANSACTION_PARENTS = ContextVar("continuity_transaction_parents", default=None) + + class ContinuityError(RuntimeError): def __init__(self, code: str, message: str): super().__init__(message) @@ -501,52 +506,107 @@ def load_local_manifest(root: Path) -> dict[str, Any]: return validate_manifest_value(load_json(root / ".subactor" / "manifest.json")) +def namespace_module(): + spec = importlib.util.spec_from_file_location( + "_continuity_namespace", Path(__file__).with_name("continuity_namespace.py")) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + def storage_paths(root: Path) -> tuple[Path, Path, int, int]: continuity = load_local_manifest(root)["continuity"] - return ( + legacy = ( root / continuity["eventStreamPath"], root / continuity["checkpointIndexPath"], continuity["checkpointIndexMaxEntries"], continuity["checkpointIndexMaxBytes"], ) + return namespace_module().select(root, repository_ref(root), legacy, sys.modules[__name__]) @contextmanager -def _posix_stream_descriptor(path: Path, append: bool): - no_follow = getattr(os, "O_NOFOLLOW", None) - directory_flag = getattr(os, "O_DIRECTORY", None) +def _posix_parent_directory(path: Path, create: bool): + no_follow, directory_flag = getattr(os, "O_NOFOLLOW", None), getattr(os, "O_DIRECTORY", None) if no_follow is None or directory_flag is None: fail("GOV-CONTINUITY-001", "safe continuity directory opens are unavailable") - directory_flags = os.O_RDONLY | directory_flag | no_follow | getattr(os, "O_CLOEXEC", 0) - directory = os.open(path.anchor, directory_flags) - descriptor = None + flags = os.O_RDONLY | directory_flag | no_follow | getattr(os, "O_CLOEXEC", 0) + directories = [os.open(path.anchor, flags)] try: for part in path.parts[1:-1]: try: - child = os.open(part, directory_flags, dir_fd=directory) + child = os.open(part, flags, dir_fd=directories[-1]) except FileNotFoundError: - if not append: + if not create: raise try: - os.mkdir(part, mode=0o700, dir_fd=directory) + os.mkdir(part, mode=0o700, dir_fd=directories[-1]) except FileExistsError: - pass # Reopen with no-follow; a concurrent link is never traversed. - child = os.open(part, directory_flags, dir_fd=directory) - os.close(directory) - directory = child + pass + child = os.open(part, flags, dir_fd=directories[-1]) + directories.append(child) + def verify(): + for parent, child, part in zip(directories, directories[1:], path.parts[1:-1]): + named, held = os.stat(part, dir_fd=parent, follow_symlinks=False), os.fstat(child) + if not stat.S_ISDIR(named.st_mode) or (named.st_dev, named.st_ino) != (held.st_dev, held.st_ino): + fail("GOV-CONTINUITY-001", "continuity parent identity changed") + yield directories[-1], verify + finally: + for descriptor in reversed(directories): + os.close(descriptor) + + +@contextmanager +def _parent_directory(path: Path, create: bool): + path = path.absolute() + if not path.name or ".." in path.parts: + fail("GOV-CONTINUITY-001", "continuity needs a confined file path") + bindings = _TRANSACTION_PARENTS.get() + if bindings is not None: + if path.parent not in bindings: + fail("GOV-CONTINUITY-001", "continuity path was not bound before the transaction") + descriptor, verify = bindings[path.parent] + verify() + yield descriptor, verify + return + with ExitStack() as handles: + try: + if os.name == "posix": + descriptor, raw_verify = handles.enter_context(_posix_parent_directory(path, create)) + elif os.name == "nt": + handles.enter_context(_windows_stream_descriptor(path, create, parents_only=True)) + descriptor, raw_verify = None, lambda: None + else: + fail("GOV-CONTINUITY-001", "safe continuity directories are unavailable") + except FileNotFoundError: + raise + except (OSError, NotImplementedError) as error: + raise ContinuityError("GOV-CONTINUITY-001", "continuity directory is unsafe or unavailable") from error + def verify(): + try: + raw_verify() + except (OSError, NotImplementedError) as error: + raise ContinuityError("GOV-CONTINUITY-001", "continuity directory identity is unavailable") from error + verify() + yield descriptor, verify + + +@contextmanager +def _posix_stream_descriptor(path: Path, append: bool): + with _parent_directory(path, append) as (directory, verify): flags = (os.O_WRONLY | os.O_CREAT | os.O_APPEND) if append else os.O_RDONLY - flags |= no_follow | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NONBLOCK", 0) + flags |= os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NONBLOCK", 0) descriptor = os.open(path.name, flags, 0o600, dir_fd=directory) - yield descriptor - finally: - if descriptor is not None: + try: + yield descriptor + verify() + finally: os.close(descriptor) - os.close(directory) @contextmanager -def _windows_stream_descriptor(path: Path, append: bool, *, readwrite: bool = False): +def _windows_stream_descriptor(path: Path, append: bool, *, readwrite: bool = False, parents_only: bool = False): # Open reparse points themselves. Held directory handles omit DELETE # sharing, so parent names cannot be replaced during the file operation. # https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew @@ -573,7 +633,9 @@ class FileInformation(ctypes.Structure): handles = [] descriptor = None def open_handle(candidate, directory=False): - access = 0x80 if directory else ( + # Attribute-only handles do not participate in delete-sharing checks. + # FILE_LIST_DIRECTORY | FILE_READ_ATTRIBUTES protects empty parents too. + access = 0x81 if directory else ( 0xC0000080 if readwrite else (0x40000080 if append else 0x80000000)) flags = 0x00200000 | (0x02000000 if directory else 0) creation = 4 if append and not directory else 3 # OPEN_ALWAYS / OPEN_EXISTING @@ -607,10 +669,13 @@ def open_handle(candidate, directory=False): except FileExistsError: pass open_handle(current, directory=True) + if parents_only: + yield None + return handle = open_handle(path) descriptor = msvcrt.open_osfhandle( handle, os.O_BINARY | os.O_NOINHERIT | ( - os.O_RDWR if readwrite else (os.O_APPEND if append else os.O_RDONLY)) + os.O_RDWR if readwrite else ((os.O_WRONLY | os.O_APPEND) if append else os.O_RDONLY)) ) handles.pop() # The CRT descriptor now owns the file handle. yield descriptor @@ -735,73 +800,64 @@ def index_payload(value: dict[str, Any], maximum_bytes: int) -> bytes: def write_index(path: Path, value: dict[str, Any], maximum_bytes: int) -> None: payload = index_payload(value, maximum_bytes) - path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - descriptor, temporary_name = tempfile.mkstemp(prefix="checkpoint-index.", suffix=".json", dir=path.parent) - temporary = Path(temporary_name) - try: - if hasattr(os, "fchmod"): - os.fchmod(descriptor, 0o600) - with os.fdopen(descriptor, "wb") as stream: - stream.write(payload) - stream.flush() - os.fsync(stream.fileno()) - os.replace(temporary, path) - try: - directory_descriptor = os.open(path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)) + if not path.name or ".." in path.absolute().parts: + fail("GOV-CONTINUITY-001", "continuity index needs a confined file path") + path = path.absolute() + with _parent_directory(path, True) as (directory, verify): + if os.name == "posix": + temporary = "checkpoint-index." + secrets.token_hex(16) + ".json" + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) + descriptor = os.open(temporary, flags, 0o600, dir_fd=directory) try: - os.fsync(directory_descriptor) + with os.fdopen(descriptor, "wb") as stream: + stream.write(payload) + stream.flush() + os.fsync(stream.fileno()) + verify() + os.replace(temporary, path.name, src_dir_fd=directory, dst_dir_fd=directory) + verify() + try: + os.fsync(directory) + except OSError: + pass # Preserve support for filesystems without directory fsync. finally: - os.close(directory_descriptor) - except OSError: - pass - finally: - if temporary.exists(): - temporary.unlink() + try: + os.unlink(temporary, dir_fd=directory) + except FileNotFoundError: + pass + else: + # All Windows ancestors remain held without DELETE sharing until + # replacement and cleanup finish. Preserve native atomic replace. + descriptor, name = tempfile.mkstemp(prefix="checkpoint-index.", suffix=".json", dir=path.parent) + temporary = Path(name) + try: + with os.fdopen(descriptor, "wb") as stream: + stream.write(payload) + stream.flush() + os.fsync(stream.fileno()) + os.replace(temporary, path) + finally: + if temporary.exists(): + temporary.unlink() @contextmanager def _posix_lock_descriptor(path: Path): - """Anchor every parent and recheck public names after a potentially long wait.""" - no_follow = getattr(os, "O_NOFOLLOW", None) - directory_flag = getattr(os, "O_DIRECTORY", None) - if no_follow is None or directory_flag is None: - fail("GOV-CONTINUITY-001", "safe continuity lock directory opens are unavailable") - directory_flags = os.O_RDONLY | directory_flag | no_follow | getattr(os, "O_CLOEXEC", 0) - directories = [os.open(path.anchor, directory_flags)] - descriptor = None - try: - for part in path.parts[1:-1]: - try: - child = os.open(part, directory_flags, dir_fd=directories[-1]) - except FileNotFoundError: - try: - os.mkdir(part, mode=0o700, dir_fd=directories[-1]) - except FileExistsError: - pass - child = os.open(part, directory_flags, dir_fd=directories[-1]) - directories.append(child) - descriptor = os.open(path.name, os.O_RDWR | os.O_CREAT | no_follow + with _parent_directory(path, True) as (directory, verify_parent): + descriptor = os.open(path.name, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NONBLOCK", 0), - 0o600, dir_fd=directories[-1]) - def verify_identity(): - # Held descriptors prevent traversal through a swapped link. They - # alone do not prove the public path still names the locked inode. - for parent, child, part in zip(directories, directories[1:], path.parts[1:-1]): - named = os.stat(part, dir_fd=parent, follow_symlinks=False) - held = os.fstat(child) - if not stat.S_ISDIR(named.st_mode) or (named.st_dev, named.st_ino) != (held.st_dev, held.st_ino): - fail("GOV-CONTINUITY-001", "continuity lock parent identity changed") - named = os.stat(path.name, dir_fd=directories[-1], follow_symlinks=False) - held = os.fstat(descriptor) - if (not stat.S_ISREG(named.st_mode) or named.st_nlink != 1 - or (named.st_dev, named.st_ino) != (held.st_dev, held.st_ino)): - fail("GOV-CONTINUITY-001", "continuity lock file identity changed") - yield descriptor, verify_identity - finally: - if descriptor is not None: + 0o600, dir_fd=directory) + try: + def verify_identity(): + verify_parent() + named = os.stat(path.name, dir_fd=directory, follow_symlinks=False) + held = os.fstat(descriptor) + if (not stat.S_ISREG(named.st_mode) or named.st_nlink != 1 + or (named.st_dev, named.st_ino) != (held.st_dev, held.st_ino)): + fail("GOV-CONTINUITY-001", "continuity lock file identity changed") + yield descriptor, verify_identity + finally: os.close(descriptor) - for directory in reversed(directories): - os.close(directory) @contextmanager @@ -830,14 +886,30 @@ def verify_identity(): @contextmanager -def storage_transaction(event_path: Path): - """Stable OS-owned lock; never unlink it while another writer can use it.""" - if not event_path.name or ".." in event_path.absolute().parts: - fail("GOV-CONTINUITY-001", "continuity transaction needs a confined file path") - lock_path = event_path.with_name(event_path.name + ".lock").absolute() - with _lock_descriptor(lock_path) as (descriptor, verify_identity): - with _locked_transaction(descriptor, verify_identity): - yield +def storage_transaction(event_path: Path, *additional_paths: Path): + """Bind every storage parent before waiting; never unlink the OS-owned lock.""" + candidates = (event_path, *additional_paths) + if any(not path.name or ".." in path.absolute().parts for path in candidates): + fail("GOV-CONTINUITY-001", "continuity transaction needs confined file paths") + paths = [path.absolute() for path in candidates] + lock_path = paths[0].with_name(paths[0].name + ".lock") + with ExitStack() as handles: + bindings = {} + for path in paths: + if path.parent not in bindings: + bindings[path.parent] = handles.enter_context(_parent_directory(path, True)) + token = _TRANSACTION_PARENTS.set(bindings) + try: + with _lock_descriptor(lock_path) as (descriptor, verify_lock): + def verify_identity(): + for _, verify in bindings.values(): + verify() + verify_lock() + with _locked_transaction(descriptor, verify_identity): + verify_identity() + yield + finally: + _TRANSACTION_PARENTS.reset(token) @contextmanager @@ -885,7 +957,7 @@ def commit_event(root: Path, event: dict[str, Any]) -> dict[str, Any]: repository = repository_ref(root) event_path, index_path, maximum, maximum_bytes = storage_paths(root) validate_event(event) - with storage_transaction(event_path): + with storage_transaction(event_path, index_path): events, _ = event_state(iter_events(event_path), repository) matching = next((existing for existing in events if existing["eventRef"] == event["eventRef"]), None) if matching is not None: @@ -1151,7 +1223,7 @@ def rebuild_index(args: argparse.Namespace) -> dict[str, Any]: root = args.root.resolve() repository = repository_ref(root) event_path, index_path, maximum, maximum_bytes = storage_paths(root) - with storage_transaction(event_path): + with storage_transaction(event_path, index_path): events, _ = event_state(iter_events(event_path), repository) index = index_from_events(repository, events, maximum) write_index(index_path, index, maximum_bytes) @@ -1331,6 +1403,11 @@ def parser() -> argparse.ArgumentParser: pin_parser = subparsers.add_parser("verify-pin", help="validate only the local immutable standard pin") pin_parser.add_argument("--root", type=Path, default=Path.cwd()) pin_parser.add_argument("--staged", action="store_true", help="read managed candidates from the Git index") + namespace_parser = subparsers.add_parser("init-namespace", help="plan an isolated repository advisory store") + namespace_parser.add_argument("--root", type=Path, default=Path.cwd()) + namespace_parser.add_argument("--expected-legacy-repository", required=True) + namespace_parser.add_argument("--expected-legacy-sha256", required=True) + namespace_parser.add_argument("--apply", action="store_true") return result @@ -1350,6 +1427,8 @@ def main() -> int: output = verify(args) elif args.command == "rebuild-index": output = rebuild_index(args) + elif args.command == "init-namespace": + output = namespace_module().initialize(args, sys.modules[__name__]) else: output = verify_pin(args) print(json.dumps(output, indent=2, sort_keys=True, ensure_ascii=False)) diff --git a/.governance/work_start_check.py b/.governance/work_start_check.py index 3a0a2aa..c2e9961 100755 --- a/.governance/work_start_check.py +++ b/.governance/work_start_check.py @@ -3,12 +3,18 @@ from __future__ import annotations import argparse +import codecs +from contextlib import ExitStack from datetime import datetime, timezone import hashlib +import importlib.util +import io import json +import math import os from pathlib import Path import re +import stat import subprocess import sys import traceback @@ -28,32 +34,77 @@ class ObservationError(ValueError): pass +class UnknownWorkstream(ObservationError): + """The requested workstream is not declared; a caller input error, not divergent local work.""" + + def __init__(self, declared): + super().__init__("Workstream is not declared in the governance manifest") + self.declared = declared + + +_OBSERVATION_LOG = ".subactor/receipts/work-start/observation-failures.log" +_OBSERVATION_LOG_MAX_BYTES = 128 * 1024 + + def _record_observation_failure(root, error): - """Write the real exception locally so RECONCILE is self-diagnosable. - - The GOV-WORK-START-001 payload printed to stdout stays deliberately - generic (remote URLs or secret-bearing input never leak into shared - CI/agent transcripts). But collapsing every failure — including plain - bugs like a missing tracked file — into that one sentence made a - one-line root cause take a full investigation to find. This writes the - real traceback to a local, gitignored file only; stdout is unchanged. - """ + """Best-effort private, bounded diagnostics; never dirty or follow links.""" try: - log_path = Path(root) / ".governance" / ".observation-failures.log" - log_path.parent.mkdir(parents=True, exist_ok=True) - entry = ( - f"{datetime.now(timezone.utc).isoformat()} " - f"{type(error).__name__}: {error}\n" - f"{traceback.format_exc()}\n" - ) - with open(log_path, "a", encoding="utf-8") as f: - f.write(entry) - # Keep the file bounded; this is a debugging aid, not an audit log. - lines = log_path.read_text(encoding="utf-8").splitlines(keepends=True) - if len(lines) > 2000: - log_path.write_text("".join(lines[-2000:]), encoding="utf-8") - except OSError: - pass + import fcntl + + root = Path(root).absolute() + # Do not infer ignore policy, or mutate a tracked diagnostic. + if git(root, "check-ignore", "--quiet", "--", _OBSERVATION_LOG, + optional=True) is None: + return False + if git(root, "ls-files", "--error-unmatch", "--", _OBSERVATION_LOG, + optional=True) is not None: + return False + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + with ExitStack() as stack: + directory = os.open(root.anchor, flags) + stack.callback(os.close, directory) + for part in root.parts[1:]: + directory = os.open(part, flags, dir_fd=directory) + stack.callback(os.close, directory) + for part in Path(_OBSERVATION_LOG).parent.parts: + try: + os.mkdir(part, 0o700, dir_fd=directory) + except FileExistsError: + pass + directory = os.open(part, flags, dir_fd=directory) + stack.callback(os.close, directory) + info = os.fstat(directory) + if info.st_uid != os.geteuid() or stat.S_IMODE(info.st_mode) & 0o077: + return False + fd = os.open(Path(_OBSERVATION_LOG).name, + os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, + 0o600, dir_fd=directory) + stack.callback(os.close, fd) + fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) + info = os.fstat(fd) + if (not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 + or info.st_uid != os.geteuid() + or stat.S_IMODE(info.st_mode) & 0o077 + or info.st_size > _OBSERVATION_LOG_MAX_BYTES): + return False + previous = os.read(fd, _OBSERVATION_LOG_MAX_BYTES).decode("utf-8", "replace") + entry = (f"{datetime.now(timezone.utc).isoformat()} " + f"{type(error).__name__}: {str(error)[:8192]}\n" + f"{traceback.format_exc()[-65536:]}\n") + bounded = "".join((previous + entry).splitlines(keepends=True)[-2000:]) + data = bounded.encode("utf-8", "replace")[-_OBSERVATION_LOG_MAX_BYTES:] + data = data.decode("utf-8", "ignore").encode("utf-8") + os.lseek(fd, 0, os.SEEK_SET) + view = memoryview(data) + while view: + count = os.write(fd, view) + if count <= 0: + raise OSError("Incomplete diagnostic write") + view = view[count:] + os.ftruncate(fd, len(data)) + return True + except (OSError, ObservationError, ImportError, AttributeError, UnicodeError, NotImplementedError): + return False def digest(value): @@ -88,6 +139,13 @@ def read_json(path): raise ObservationError("Missing or invalid governance input") from error +def quarantined(path, primary): + """Checkouts parked under the repository's .worktrees/.quarantine/ directory are preserved evidence, not claims.""" + resolved = Path(path).resolve() + quarantine_root = (Path(primary) / ".worktrees" / ".quarantine").resolve() + return resolved != quarantine_root and resolved.is_relative_to(quarantine_root) + + def _historical_inactive_logs(root, ticket_dir, key, status, dirty_paths, target_sha): """Recognize unchanged inactive legacy prose, never a writer or allocation. @@ -182,6 +240,123 @@ def unchanged_committed_legacy_carriers(root, head): raise ObservationError("Changed legacy carrier requires owner reconciliation") +def bootstrap_historical_refs(root, head): + """Observe integrated history only; preserve refs and independent ownership.""" + refs = git(root, "for-each-ref", "--format=%(refname) %(objectname)", "refs/heads/ticket/") + if not refs: + return refs + if git(root, "rev-parse", "--is-shallow-repository").strip() != "false": + raise ObservationError("Bootstrap history is incomplete") + names = set() + for line in refs.splitlines(): + ref, sha = line.split(" ", 1) + # Equality is ambiguous: a newly reserved writer may still be at base. + # A checked merge-base also refuses missing/unreadable ancestry. + if sha == head or git(root, "merge-base", head, sha).strip() != sha: + raise ObservationError("Bootstrap ticket ref is not strictly integrated") + names.add(ref) + leases = root / ".subactor/leases" + if leases.is_symlink() or (leases.exists() and not leases.is_dir()): + raise ObservationError("Bootstrap lease observation unavailable") + for path in leases.glob("*.json"): + lease = read_json(path) + if lease.get("branchRef") not in names: + continue + try: + expiry = datetime.fromisoformat(lease["expiresAt"].replace("Z", "+00:00")) + if expiry.tzinfo is None: + raise ValueError("unbound expiry") + except (KeyError, TypeError, ValueError, AttributeError) as error: + raise ObservationError("Bootstrap lease expiry unavailable") from error + if expiry > datetime.now(timezone.utc): + raise ObservationError("Bootstrap historical ref retains a live lease") + return refs + + +WELLMAN_SCAFFOLD_PROFILES = frozenset({ + "wellmanifest/new-project", + "profile:baseline", + "profile:domain-pack", + "profile:runtime-service", + "profile:agent-executor", + "profile:deployment", + "profile:embedded-fleet", + "profile:full", +}) +WELLMAN_SCAFFOLD_VERSION_RE = re.compile( + r"\A(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)" + r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)" + r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?" + r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\Z" +) + + +def bootstrap_scaffold_at_head(root, head): + """Verify committed legacy provenance, or prove governance was absent. + + The published installer also accepts an exact untracked scaffold. Its + receipt still binds the original clone/HEAD and every installed byte; + absence in Git is not a reason to invent a preliminary scaffold commit. + A checked tree read distinguishes absence from an unreadable Git object. + """ + paths = set(git(root, "ls-tree", "-r", "--name-only", "-z", head, + "--", ".governance").split("\0")) - {""} + if ".governance/manifest.json" not in paths: + if paths: + raise ObservationError("Untracked scaffold cannot replace committed governance") + return + original = json.loads(git(root, "show", f"{head}:.governance/manifest.json")) + standard = original.get("standard", {}) if isinstance(original, dict) else {} + if (not isinstance(original, dict) or set(original) != {"schema", "standard"} + or original.get("schema") != "wellmanifest.manifest/v1" + or not isinstance(standard, dict) or set(standard) != {"id", "version"} + or standard.get("id") not in WELLMAN_SCAFFOLD_PROFILES + or not isinstance(standard.get("version"), str) + or not WELLMAN_SCAFFOLD_VERSION_RE.fullmatch(standard["version"])): + raise ObservationError("Bootstrap requires an exact legacy scaffold") + + +def bootstrap_preserved_worktrees(root, head): + """Observe canonical integrated checkouts; never retire or take over them. + + The existing historical-ref lease check remains independently required. + Callers compare repeated observations; cleanliness is not writer authority. + """ + inventory = worktrees(root) + if Path(inventory[0]["worktree"]) != root: + raise ObservationError("Bootstrap requires the registered primary checkout") + common = git(root, "rev-parse", "--path-format=absolute", "--git-common-dir").strip() + observed = [] + for item in inventory[1:]: + branch = item.get("branch", "") + match = re.fullmatch(r"refs/heads/ticket/([0-9]{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)", branch) + path = Path(item["worktree"]) + if (not match or set(item) != {"worktree", "HEAD", "branch"} + or path != root / ".worktrees" / f"ticket-{match[1]}--{match[2]}" + or any(p.is_symlink() for p in (path, *path.parents)) + or not path.is_dir()): + raise ObservationError("Bootstrap worktree is not a preserved canonical checkout") + sha = git(path, "rev-parse", "HEAD").strip() + if (sha != item["HEAD"] or sha == head + or git(root, "merge-base", head, sha).strip() != sha + or git(root, "rev-parse", branch).strip() != sha + or git(path, "symbolic-ref", "HEAD").strip() != branch + or Path(git(path, "rev-parse", "--show-toplevel").strip()) != path + or git(path, "rev-parse", "--path-format=absolute", "--git-common-dir").strip() != common): + raise ObservationError("Bootstrap worktree bindings are not strictly integrated") + # Non-default index flags and ignored submodules must not hide changes. + flags = git(path, "ls-files", "-v", "-z").split("\0") + if (any(field and field[0] != "H" for field in flags) + or git(path, "status", "--porcelain=v1", "--untracked-files=all", + "--ignore-submodules=none")): + raise ObservationError("Bootstrap preserved worktree is not observably clean") + _, checksum, dirty = dirty_observation(path) + if dirty: + raise ObservationError("Bootstrap preserved worktree changed during observation") + observed.append({"registration": item, "dirtyDigest": checksum}) + return {"inventory": inventory, "preserved": observed} + + def bootstrap_owned_paths(root, manifest, expected_digest): """A first allocator may acknowledge only exact installer-owned bytes. @@ -208,20 +383,14 @@ def bootstrap_owned_paths(root, manifest, expected_digest): if git(root, "cat-file", "-e", f"{head}:.governance/{name}", optional=True) is not None: raise ObservationError("Fresh bootstrap cannot replace committed governance") elif kind == "legacy-scaffold": - original = json.loads(git(root, "show", f"{head}:.governance/manifest.json")) - standard = original.get("standard", {}) - if (set(original) != {"schema", "standard"} - or original.get("schema") != "wellmanifest.manifest/v1" - or set(standard) != {"id", "version"} - or standard.get("id") != "profile:baseline" - or not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", str(standard.get("version", "")))): - raise ObservationError("Bootstrap requires a committed exact legacy scaffold") + bootstrap_scaffold_at_head(root, head) else: raise ObservationError("Unknown bootstrap kind") - if (len(worktrees(root)) != 1 - or git(root, "for-each-ref", "--format=%(refname)", "refs/heads/ticket/") - or (Path(common) / "new-project-ticket-high-water").exists()): + high_water = Path(common) / "new-project-ticket-high-water" + if high_water.exists() or high_water.is_symlink(): raise ObservationError("Bootstrap acknowledgement is first-allocation only") + historical_refs = bootstrap_historical_refs(root, head) + preserved_worktrees = bootstrap_preserved_worktrees(root, head) if kind == "fresh": unchanged_committed_legacy_carriers(root, head) elif list((root / "project").glob("ticket-*")): @@ -241,15 +410,48 @@ def bootstrap_owned_paths(root, manifest, expected_digest): raise ObservationError("Bootstrap receipt includes paths outside adoption") if not set(lock["managedFiles"]).issubset(files): raise ObservationError("Bootstrap receipt omits managed files") - for rel, checksum in files.items(): - patterns([rel]) - path = root / rel - if (any(p.is_symlink() for p in (path, *path.parents)) or not path.is_file() - or not re.fullmatch(r"[0-9a-f]{64}", str(checksum)) - or hashlib.sha256(path.read_bytes()).hexdigest() != checksum - or (rel in lock["managedFiles"] and lock["managedFiles"][rel] != checksum)): - raise ObservationError("Bootstrap payload changed or is not installed") - return set(dirty).intersection(files) + def verify_bootstrap_files(): + for rel, checksum in files.items(): + patterns([rel]) + path = root / rel + if (any(p.is_symlink() for p in (path, *path.parents)) or not path.is_file() + or not re.fullmatch(r"[0-9a-f]{64}", str(checksum)) + or hashlib.sha256(path.read_bytes()).hexdigest() != checksum + or (rel in lock["managedFiles"] and lock["managedFiles"][rel] != checksum)): + raise ObservationError("Bootstrap payload changed or is not installed") + + verify_bootstrap_files() + if (git(root, "rev-parse", "HEAD").strip() != head + or bootstrap_historical_refs(root, head) != historical_refs + or bootstrap_preserved_worktrees(root, head) != preserved_worktrees + or high_water.exists() or high_water.is_symlink()): + raise ObservationError("Bootstrap allocation state changed during observation") + _, final_digest, final_dirty = dirty_observation(root) + if final_digest != expected_digest or final_dirty != dirty: + raise ObservationError("Bootstrap changed during admission") + verify_bootstrap_files() + return set(final_dirty).intersection(files) + + +def bootstrap_seed_paths(root, manifest): + """A scope query may observe only exact first-installer required seeds. + + The allocator still requires its explicit dirty acknowledgement afterwards; + this query changes no intent, ownership, reservation or authority. + """ + root = Path(root).resolve() + if root != Path(worktrees(root)[0]["worktree"]).resolve(): + return set() + _, checksum, _ = dirty_observation(root) + owned = bootstrap_owned_paths(root, manifest, checksum) + from governance_check import initial_adoption_seed_paths + lock = read_json(root / ".governance/manifest.lock.json") + try: + return owned & initial_adoption_seed_paths( + root, git(root, "rev-parse", "HEAD").strip(), + lock["standard"]["sourceRevision"], manifest) + except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as error: + raise ObservationError("Bootstrap required seed evidence unavailable") from error def changes(root, base, head): @@ -315,7 +517,40 @@ def dirty_observation(root): hashes[rel] = checksum.hexdigest() else: hashes[rel] = "absent-or-submodule" - return material(sorted(paths)), digest({"status": status, "files": hashes}), sorted(paths) + index = git(root, "ls-files", "--stage", "-z") + return material(sorted(paths)), digest({"status": status, "files": hashes, "index": index}), sorted(paths) + + +def outstanding_detached_paths(root, paths, target): + """Subtract exact integrated bytes, without modifying or releasing the checkout.""" + trees = {} + for item in git(root, "ls-tree", "-r", "--full-tree", "-z", target).split("\0"): + if item: + metadata, name = item.split("\t", 1) + mode, kind, oid = metadata.split() + if kind == "blob" and mode in {"100644", "100755"}: + trees[name] = (mode, oid) + indexes = {} + for item in git(root, "ls-files", "--stage", "-z").split("\0"): + if item: + metadata, name = item.split("\t", 1) + mode, oid, stage = metadata.split() + indexes.setdefault(name, []).append((mode, oid, stage)) + outstanding = [] + for name in paths: + path = root / name + accepted = trees.get(name) + if (not accepted or indexes.get(name) != [(*accepted, "0")] + or any(p.is_symlink() for p in (path, *path.parents)) or not path.is_file()): + outstanding.append(name) + continue + mode = "100755" if path.stat().st_mode & 0o100 else "100644" + # Raw hashing deliberately ignores clean/textconv filters and index + # flags: assume-unchanged cannot conceal different filesystem bytes. + oid = git(root, "hash-object", "--no-filters", "--", name).strip() + if (mode, oid) != accepted: + outstanding.append(name) + return outstanding def dirty_modified(root, paths): @@ -434,18 +669,624 @@ def contains(head, remote_sha): observation["status"] = "changed" return unknown() return observation - except (ObservationError, ValueError): + except (ObservationError, ValueError, subprocess.SubprocessError): observation["status"] = "unavailable" return unknown() +CONTROLLER_STORE_SCHEMA = "subactor.repository-change-lease-store/v1" +FREE_LEASE_PHASES = {"closed", "cancelled", "released"} +REPOSITORY_REF = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+") +MAX_CONTROLLER_STATE_BYTES = 128 * 1024 * 1024 +_CONTROLLER_CHUNK_BYTES = 65536 +_MAX_JSON_DEPTH = 64 +_MAX_JSON_STRING_CHARS = 1024 * 1024 +_MAX_CAPTURED_ITEMS = 4096 +_MAX_OBJECT_KEYS = 250000 +_JSON_WS_RE = re.compile(r"[ \t\r\n]+") +_JSON_NUMBER_RE = re.compile(r"-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?") +RESOURCE_ACTIONS = { + "AVAILABLE": "Acquire the editing lease from the controller, then re-run work-start with --ticket before any write.", + "HELD_BY_TICKET": "Continue only under the existing lease after verifying its owner, fencing token and expiry.", + "HELD_EXPIRED": "The expired holder still blocks the resource until the controller releases it or records a " + "protected takeover; expiry alone never authorizes takeover.", + "HELD_BY_OTHER": "Wait for the holder's release or a protected handoff; do not prepare an expiring admission now.", + "UNAVAILABLE": "Restore controller access; do not infer availability from disjoint paths or retry an admission.", +} + + +class _ControllerStateChanged(ObservationError): + pass + + +def _open_controller_state(store): + path = Path(os.path.abspath(store)) / "state.json" + if any(p.is_symlink() for p in (path, *path.parents)): + raise ObservationError("Symlinked controller state") + descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) + stream = os.fdopen(descriptor, "rb") + if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode): + stream.close() + raise ObservationError("Controller state must be a regular file") + return stream + + +def _controller_bytes(store, *, max_bytes=MAX_CONTROLLER_STATE_BYTES): + with _open_controller_state(store) as stream: + chunks = [] + total = 0 + while True: + chunk = stream.read(_CONTROLLER_CHUNK_BYTES) + if not chunk: + break + total += len(chunk) + if total > max_bytes: + raise ObservationError("Controller state too large") + chunks.append(chunk) + return b"".join(chunks) + + +_DEFAULT_CONTROLLER_BYTES = _controller_bytes + + +def _stream_controller_digest(store, *, max_bytes=MAX_CONTROLLER_STATE_BYTES): + with _open_controller_state(store) as stream: + hasher = hashlib.sha256() + total = 0 + while True: + chunk = stream.read(_CONTROLLER_CHUNK_BYTES) + if not chunk: + break + total += len(chunk) + if total > max_bytes: + raise ObservationError("Controller state too large") + hasher.update(chunk) + return hasher.hexdigest() + + +class _StreamJsonScanner: + """Bounded RFC 8259 streaming reader with strict UTF-8 and duplicate-key rejection.""" + + def __init__(self, stream, *, max_bytes=MAX_CONTROLLER_STATE_BYTES): + self.stream = stream + self.max_bytes = max_bytes + self.decoder = codecs.getincrementaldecoder("utf-8")("strict") + self.hasher = hashlib.sha256() + self.total_bytes = 0 + self.buf = "" + self.pos = 0 + self.eof = False + + def _fill(self): + if self.eof: + return False + while True: + chunk = self.stream.read(_CONTROLLER_CHUNK_BYTES) + if not chunk: + tail = self.decoder.decode(b"", final=True) + self.eof = True + if self.pos >= _CONTROLLER_CHUNK_BYTES: + self.buf = self.buf[self.pos:] + tail + self.pos = 0 + else: + self.buf += tail + return bool(tail) + self.total_bytes += len(chunk) + if self.total_bytes > self.max_bytes: + raise ObservationError("Controller state too large") + self.hasher.update(chunk) + decoded = self.decoder.decode(chunk, final=False) + if self.pos >= _CONTROLLER_CHUNK_BYTES: + self.buf = self.buf[self.pos:] + decoded + self.pos = 0 + else: + self.buf += decoded + if decoded: + return True + + def skip_ws(self): + while True: + match = _JSON_WS_RE.match(self.buf, self.pos) + if match is not None: + self.pos = match.end() + if self.pos < len(self.buf) or self.eof: + return + self._fill() + + def peek(self): + self.skip_ws() + return self.buf[self.pos] if self.pos < len(self.buf) else "" + + def read_string(self): + while True: + try: + value, end = json.decoder.scanstring(self.buf, self.pos + 1, True) + if len(value) > _MAX_JSON_STRING_CHARS: + raise ValueError("JSON string exceeds controller bound") + self.pos = end + return value + except json.JSONDecodeError: + if self.eof or (len(self.buf) - self.pos) > (_MAX_JSON_STRING_CHARS * 6): + raise ValueError("Invalid JSON string") from None + self._fill() + + def read_number(self, *, capture=False): + while not self.eof and (len(self.buf) - self.pos) < 128: + self._fill() + while True: + match = _JSON_NUMBER_RE.match(self.buf, self.pos) + if match is None: + raise ValueError("Invalid JSON number") + if match.end() == len(self.buf) and not self.eof: + if (len(self.buf) - self.pos) > 1024: + raise ValueError("Oversized JSON number") + self._fill() + continue + break + token = match.group(0) + self.pos = match.end() + if any(ch in token for ch in ".eE"): + number = float(token) + if not math.isfinite(number): + raise ValueError("Non-finite JSON number") + return number if capture else None + if capture: + if len(token) > 64: + raise ValueError("Integer exceeds controller bound") + return int(token) + return None + + def read_literal(self): + while not self.eof and (len(self.buf) - self.pos) < 5: + self._fill() + for literal, value in (("true", True), ("false", False), ("null", None)): + if self.buf.startswith(literal, self.pos): + self.pos += len(literal) + return value + raise ValueError("Invalid JSON literal") + + def skip_value(self, initial_depth): + ch = self.peek() + if not ch: + raise ValueError("Unexpected EOF") + if ch == '"': + self.read_string() + return + if ch in "-0123456789": + self.read_number(capture=False) + return + if ch in "tfn": + self.read_literal() + return + if ch not in "{[": + raise ValueError("Invalid JSON token") + if initial_depth + 1 > _MAX_JSON_DEPTH: + raise ValueError("JSON nesting too deep") + self.pos += 1 + stack = [["obj", set(), True] if ch == "{" else ["arr", None, True]] + while stack: + kind, seen, first = stack[-1] + cur = self.peek() + if not cur: + raise ValueError("Unterminated JSON container") + if kind == "obj": + if cur == "}" and first: + self.pos += 1 + stack.pop() + continue + if not first: + if cur == "}": + self.pos += 1 + stack.pop() + continue + if cur != ",": + raise ValueError("Expected ',' or '}' in object") + self.pos += 1 + cur = self.peek() + if cur != '"': + raise ValueError("Expected object key") + key = self.read_string() + if key in seen or len(seen) >= _MAX_OBJECT_KEYS: + raise ValueError("Duplicate or excessive JSON key") + seen.add(key) + if self.peek() != ":": + raise ValueError("Expected ':' after object key") + self.pos += 1 + stack[-1][2] = False + val_ch = self.peek() + else: + if cur == "]" and first: + self.pos += 1 + stack.pop() + continue + if not first: + if cur == "]": + self.pos += 1 + stack.pop() + continue + if cur != ",": + raise ValueError("Expected ',' or ']' in array") + self.pos += 1 + val_ch = self.peek() + else: + val_ch = cur + stack[-1][2] = False + if not val_ch: + raise ValueError("Unexpected EOF") + if val_ch == '"': + self.read_string() + elif val_ch in "-0123456789": + self.read_number(capture=False) + elif val_ch in "tfn": + self.read_literal() + elif val_ch in "{[": + if initial_depth + len(stack) + 1 > _MAX_JSON_DEPTH: + raise ValueError("JSON nesting too deep") + self.pos += 1 + stack.append(["obj", set(), True] if val_ch == "{" else ["arr", None, True]) + else: + raise ValueError("Invalid JSON value") + + def capture_value(self, initial_depth): + ch = self.peek() + if not ch: + raise ValueError("Unexpected EOF") + if ch == '"': + return self.read_string() + if ch in "-0123456789": + return self.read_number(capture=True) + if ch in "tfn": + return self.read_literal() + if ch not in "{[": + raise ValueError("Invalid JSON token") + if initial_depth + 1 > _MAX_JSON_DEPTH: + raise ValueError("JSON nesting too deep") + self.pos += 1 + root_container = {} if ch == "{" else [] + stack = [["obj", root_container, True] if ch == "{" else ["arr", root_container, True]] + items = 0 + while stack: + kind, container, first = stack[-1] + cur = self.peek() + if not cur: + raise ValueError("Unterminated JSON container") + if kind == "obj": + if cur == "}" and first: + self.pos += 1 + stack.pop() + continue + if not first: + if cur == "}": + self.pos += 1 + stack.pop() + continue + if cur != ",": + raise ValueError("Expected ',' or '}' in object") + self.pos += 1 + cur = self.peek() + if cur != '"': + raise ValueError("Expected object key") + key = self.read_string() + if key in container: + raise ValueError("Duplicate JSON key") + if self.peek() != ":": + raise ValueError("Expected ':' after object key") + self.pos += 1 + stack[-1][2] = False + val_ch = self.peek() + else: + key = None + if cur == "]" and first: + self.pos += 1 + stack.pop() + continue + if not first: + if cur == "]": + self.pos += 1 + stack.pop() + continue + if cur != ",": + raise ValueError("Expected ',' or ']' in array") + self.pos += 1 + val_ch = self.peek() + else: + val_ch = cur + stack[-1][2] = False + items += 1 + if items > _MAX_CAPTURED_ITEMS: + raise ValueError("Captured controller entry exceeds bound") + if not val_ch: + raise ValueError("Unexpected EOF") + if val_ch == '"': + child = self.read_string() + if kind == "obj": + container[key] = child + else: + container.append(child) + elif val_ch in "-0123456789": + child = self.read_number(capture=True) + if kind == "obj": + container[key] = child + else: + container.append(child) + elif val_ch in "tfn": + child = self.read_literal() + if kind == "obj": + container[key] = child + else: + container.append(child) + elif val_ch in "{[": + if initial_depth + len(stack) + 1 > _MAX_JSON_DEPTH: + raise ValueError("JSON nesting too deep") + self.pos += 1 + child = {} if val_ch == "{" else [] + if kind == "obj": + container[key] = child + else: + container.append(child) + stack.append(["obj", child, True] if val_ch == "{" else ["arr", child, True]) + else: + raise ValueError("Invalid JSON value") + return root_container + + +def _parse_controller_stream(stream, *, wanted_resources=None, wanted_leases=None, + max_bytes=MAX_CONTROLLER_STATE_BYTES): + scanner = _StreamJsonScanner(stream, max_bytes=max_bytes) + if scanner.peek() != "{": + raise ValueError("Controller store root must be an object") + scanner.pos += 1 + root_keys = set() + schema = None + saw_active = False + saw_leases = False + active_map = {} + captured_leases = {} + lease_keys = set() + targets = set(wanted_leases or ()) + first_root = True + while True: + cur = scanner.peek() + if not cur: + raise ValueError("Unterminated controller store object") + if cur == "}" and first_root: + scanner.pos += 1 + break + if not first_root: + if cur == "}": + scanner.pos += 1 + break + if cur != ",": + raise ValueError("Expected ',' or '}' in controller store") + scanner.pos += 1 + cur = scanner.peek() + if cur != '"': + raise ValueError("Expected top-level key in controller store") + top_key = scanner.read_string() + if top_key in root_keys: + raise ValueError("Duplicate JSON key") + root_keys.add(top_key) + if scanner.peek() != ":": + raise ValueError("Expected ':' after top-level key") + scanner.pos += 1 + first_root = False + if top_key == "schema": + if scanner.peek() != '"': + raise ValueError("schema must be a string") + schema = scanner.read_string() + elif top_key == "active": + if scanner.peek() != "{": + raise ValueError("active must be an object") + scanner.pos += 1 + saw_active = True + seen_active = set() + first_active = True + while True: + ac = scanner.peek() + if not ac: + raise ValueError("Unterminated active object") + if ac == "}" and first_active: + scanner.pos += 1 + break + if not first_active: + if ac == "}": + scanner.pos += 1 + break + if ac != ",": + raise ValueError("Expected ',' or '}' in active") + scanner.pos += 1 + ac = scanner.peek() + if ac != '"': + raise ValueError("Expected resource key in active") + res_key = scanner.read_string() + if res_key in seen_active or len(seen_active) >= _MAX_OBJECT_KEYS: + raise ValueError("Duplicate or excessive active key") + seen_active.add(res_key) + if scanner.peek() != ":": + raise ValueError("Expected ':' in active") + scanner.pos += 1 + first_active = False + vc = scanner.peek() + if vc == '"': + holder_val = scanner.read_string() + elif vc == "n": + holder_val = scanner.read_literal() + if holder_val is not None: + raise ValueError("Invalid active value") + else: + raise ValueError("Active resource holder must be string or null") + if wanted_resources is None or res_key in wanted_resources: + if len(active_map) >= _MAX_CAPTURED_ITEMS: + raise ValueError("Captured active map exceeds bound") + active_map[res_key] = holder_val + if isinstance(holder_val, str): + targets.add(holder_val) + elif top_key == "leases": + if scanner.peek() != "{": + raise ValueError("leases must be an object") + scanner.pos += 1 + saw_leases = True + first_lease = True + while True: + lc = scanner.peek() + if not lc: + raise ValueError("Unterminated leases object") + if lc == "}" and first_lease: + scanner.pos += 1 + break + if not first_lease: + if lc == "}": + scanner.pos += 1 + break + if lc != ",": + raise ValueError("Expected ',' or '}' in leases") + scanner.pos += 1 + lc = scanner.peek() + if lc != '"': + raise ValueError("Expected lease key") + lid = scanner.read_string() + if lid in lease_keys or len(lease_keys) >= _MAX_OBJECT_KEYS: + raise ValueError("Duplicate or excessive lease key") + lease_keys.add(lid) + if scanner.peek() != ":": + raise ValueError("Expected ':' after lease key") + scanner.pos += 1 + first_lease = False + if lid in targets: + lease_obj = scanner.capture_value(initial_depth=2) + if not isinstance(lease_obj, dict): + raise ValueError("Lease record must be an object") + captured_leases[lid] = lease_obj + else: + scanner.skip_value(initial_depth=2) + else: + scanner.skip_value(initial_depth=1) + if scanner.peek() != "": + raise ValueError("Trailing data in controller state") + if schema != CONTROLLER_STORE_SCHEMA: + raise ValueError("unsupported store") + if not saw_active: + raise KeyError("active") + if not saw_leases: + raise KeyError("leases") + return { + "schema": schema, + "active": active_map, + "leases": captured_leases, + "leaseKeys": lease_keys, + "stateDigest": scanner.hasher.hexdigest(), + } + + +def read_controller_projection(store, *, resources=(), lease_ids=(), + max_bytes=MAX_CONTROLLER_STATE_BYTES): + """Stream-validate controller state.json and extract only requested active/lease entries.""" + wanted_resources = set(resources) if resources else None + wanted_leases = {lid for lid in lease_ids if isinstance(lid, str)} + with _open_controller_state(store) as stream: + first = _parse_controller_stream( + stream, wanted_resources=wanted_resources, + wanted_leases=wanted_leases, max_bytes=max_bytes) + missing_present = { + holder_id for holder_id in first["active"].values() + if isinstance(holder_id, str) + and holder_id not in first["leases"] + and holder_id in first["leaseKeys"] + } + if missing_present: + stream.seek(0) + second = _parse_controller_stream( + stream, wanted_resources=wanted_resources, + wanted_leases=wanted_leases | missing_present, max_bytes=max_bytes) + if second["stateDigest"] != first["stateDigest"]: + raise _ControllerStateChanged("Controller state changed during read") + first = second + first.pop("leaseKeys", None) + return first + + +def controller_observation(store, repository, target, ticket=None): + """Read-only availability of the controller's exclusive editing resource; never a grant or a queue entry.""" + observation = { + "schema": "new-project.editing-resource-observation/v1", + "observedAt": datetime.now(timezone.utc).isoformat(), + "readOnly": True, "grantsAuthority": False, "queueSupported": False, + "repositoryRef": repository, "targetBranch": target, "ticket": ticket, + "resource": digest({"repositoryRef": repository, "targetBranch": target}), + "state": "UNAVAILABLE", "reason": None, "holder": None, "stateDigest": None, + } + custom_bytes = _controller_bytes is not _DEFAULT_CONTROLLER_BYTES + try: + if custom_bytes: + raw = _controller_bytes(store) + else: + state = read_controller_projection(store, resources=(observation["resource"],)) + except FileNotFoundError: + observation["reason"] = "controller-store-missing" + except _ControllerStateChanged: + observation["reason"] = "controller-state-changed" + except (OSError, ObservationError): + observation["reason"] = "controller-state-unreadable" + except (ValueError, KeyError, TypeError, AttributeError): + observation["reason"] = "controller-state-invalid" + else: + try: + if custom_bytes: + state = _parse_controller_stream( + io.BytesIO(raw), wanted_resources={observation["resource"]}) + missing_present = { + hid for hid in state["active"].values() + if isinstance(hid, str) and hid not in state["leases"] and hid in state["leaseKeys"] + } + if missing_present: + state = _parse_controller_stream( + io.BytesIO(raw), wanted_resources={observation["resource"]}, + wanted_leases=missing_present) + holder_id = state["active"].get(observation["resource"]) + holder = None if holder_id is None else state["leases"][holder_id] + if holder is not None: + expires = datetime.fromisoformat(holder["expiresAt"].replace("Z", "+00:00")) + if expires.tzinfo is None or not isinstance(holder["phase"], str): + raise ValueError("invalid holder") + except (ValueError, KeyError, TypeError, AttributeError): + observation["reason"] = "controller-state-invalid" + else: + try: + changed = (_controller_bytes(store) != raw if custom_bytes + else _stream_controller_digest(store) != state["stateDigest"]) + except (OSError, ObservationError): + changed = True + if changed: + observation["reason"] = "controller-state-changed" + elif holder is None or holder["phase"] in FREE_LEASE_PHASES: + observation["state"] = "AVAILABLE" + observation["stateDigest"] = state["stateDigest"] + else: + # A safe reference only: no owner session, credential or plan. + observation["holder"] = {"leaseId": holder_id, "ticketId": holder.get("ticketId"), + "phase": holder["phase"], "expiresAt": holder["expiresAt"]} + if holder["phase"] == "expired" or expires <= datetime.now(timezone.utc): + observation["state"] = "HELD_EXPIRED" + elif ticket is not None and holder.get("ticketId") == ticket: + observation["state"] = "HELD_BY_TICKET" + else: + observation["state"] = "HELD_BY_OTHER" + observation["stateDigest"] = state["stateDigest"] + observation["nextAction"] = RESOURCE_ACTIONS[observation["state"]] + return observation + + def inspect(root, workstream, requested_paths=(), ticket=None, storage=None, observe_publication=False, expected_dirty_digest=None, recovery_intent=None, - bootstrap_adoption_digest=None): + bootstrap_adoption_digest=None, controller=None): root = Path(git(root, "rev-parse", "--show-toplevel").strip()).resolve() manifest = manifest_at(root) coordination = manifest["coordination"] - stream = coordination["workstreams"][workstream] + declared = coordination["workstreams"] + if workstream not in declared: + raise UnknownWorkstream(sorted(name for name in declared + if isinstance(name, str) and re.fullmatch(r"[A-Za-z0-9._-]{1,64}", name))) + stream = declared[workstream] limit = coordination["maxActiveTicketsPerWorkstream"] if type(limit) is not int or limit < 1: raise ObservationError("Invalid workstream WIP limit") @@ -518,17 +1359,28 @@ def inspect(root, workstream, requested_paths=(), ticket=None, storage=None, intent = recovery_intent status_override = "IN_PROGRESS" else: - intent = read_json(ticket_dir / "intent.json") + try: + intent = read_json(ticket_dir / "intent.json") + except ObservationError: + # A quarantined checkout may hold an interrupted merge. Record it + # instead of aborting every allocation; its Git delta is still + # compared below as pending work. + if not quarantined(path, primary): + raise + intent = None status_override = None - if intent.get("ticket") != ticket_id or intent.get("schema") not in ( - "new-project.intent/v2", "new-project.intent/v3"): - raise ObservationError("Branch/intent identity mismatch") - patterns(intent.get("allowedPaths")) - resolution = resolve_activity(path, ticket_dir, statuses, status_override=status_override) - active, status = resolution.active, resolution.projectionStatus - activity_authority = resolution.authority - if status is None: - raise ObservationError("Ticket status unknown") + if intent is None: + active, status, activity_authority = False, "QUARANTINED_UNREADABLE", "quarantine" + else: + if intent.get("ticket") != ticket_id or intent.get("schema") not in ( + "new-project.intent/v2", "new-project.intent/v3"): + raise ObservationError("Branch/intent identity mismatch") + patterns(intent.get("allowedPaths")) + resolution = resolve_activity(path, ticket_dir, statuses, status_override=status_override) + active, status = resolution.active, resolution.projectionStatus + activity_authority = resolution.authority + if status is None: + raise ObservationError("Ticket status unknown") canonical = bool(ticket_id and path.resolve().parent == primary / ".worktrees" and path.name.startswith(ticket_id + "--")) entries.append({"path": str(path.resolve()), "branch": branch or None, @@ -611,6 +1463,9 @@ def inspect(root, workstream, requested_paths=(), ticket=None, storage=None, contribution = changes(root, comparison_sha, entry["headSha"]) pending_paths = [p for p in entry["dirtyPaths"] if not (Path(entry["path"]) == primary and p in bootstrap_owned)] + if (pending_paths and Path(entry["path"]) != primary and entry["branch"] is None + and entry["ticket"] is None and not entry["active"] and entry["ahead"] == 0): + pending_paths = outstanding_detached_paths(Path(entry["path"]), pending_paths, target_sha) contested = intersects(requested, pending_paths + contribution) reserved = entry["active"] and intersects(requested, entry["allowedPaths"]) if contested or reserved: @@ -684,21 +1539,109 @@ def inspect(root, workstream, requested_paths=(), ticket=None, storage=None, for key, row in records.items()}) if observe_publication: payload["publication"] = publication_observation(root, entries, target) - payload["observationDigest"] = digest({"refs": refs, "manifest": manifest, "report": payload, - "ticketStorage": mode, "ticketInputDigest": storage_digest}) + if controller: + payload["editingResource"] = controller_observation(*controller, target, ticket) if refs != git(root, "for-each-ref", "--format=%(refname) %(objectname)", "refs/heads", "refs/remotes"): raise ObservationError("Refs changed during observation; retry") if manifest != manifest_at(root) or registrations != worktrees(root): raise ObservationError("Manifest or worktree registrations changed; retry") + disjoint_peer_updated = False for entry in entries: - if dirty_observation(Path(entry["path"]))[1] != entry["dirtyDigest"]: - raise ObservationError("Workspace changed during observation; retry") + new_dirty, new_dirty_hash, new_all_dirty = dirty_observation(Path(entry["path"])) + if new_dirty_hash != entry["dirtyDigest"]: + _reconcile_disjoint_peer_mutation( + entry, new_dirty, new_dirty_hash, new_all_dirty, + root=root, primary=primary, selected=selected, requested=requested, + comparison_sha=comparison_sha, statuses=statuses, mode=mode, records=records) + disjoint_peer_updated = True if database and database.exists(): if records != {item["ticket"]: item for item in load_input(root, database=database)}: raise ObservationError("Ticket database changed during observation; retry") + if disjoint_peer_updated and observe_publication: + payload["publication"] = publication_observation(root, entries, target) + if refs != git(root, "for-each-ref", "--format=%(refname) %(objectname)", "refs/heads", "refs/remotes"): + raise ObservationError("Refs changed during observation; retry") + payload["observationDigest"] = "" + payload["observationDigest"] = digest({"refs": refs, "manifest": manifest, "report": payload, + "ticketStorage": mode, "ticketInputDigest": storage_digest}) return payload +def _reconcile_disjoint_peer_mutation(entry, new_dirty, new_dirty_hash, new_all_dirty, *, + root, primary, selected, requested, comparison_sha, + statuses, mode, records): + """Allow uncommitted progress only inside an unchanged, non-overlapping peer ticket checkout.""" + peer_path = Path(entry["path"]).resolve() + ticket_id = entry["ticket"] + if (entry is selected or peer_path == root or peer_path == primary + or not ticket_id or not entry["branch"] or entry["intentDigest"] is None + or entry["status"] == "QUARANTINED_UNREADABLE" + or not peer_path.is_dir() or peer_path.is_symlink() + or quarantined(peer_path, primary)): + raise ObservationError("Workspace changed during observation; retry") + head = git(peer_path, "rev-parse", "--verify", "HEAD").strip() + branch = (git(peer_path, "symbolic-ref", "--quiet", "HEAD", optional=True) or "").strip() + if head != entry["headSha"] or branch != entry["branch"]: + raise ObservationError("Workspace changed during observation; retry") + new_pending = bool(new_all_dirty or entry["ahead"] or ticket_id in records) + if not new_pending or new_pending != entry["pending"]: + raise ObservationError("Workspace changed during observation; retry") + for dirty_path in (*entry["allDirtyPaths"], *new_all_dirty): + carrier = re.match(r"^project/(ticket-[0-9]{3,})/", dirty_path) + if carrier and carrier.group(1) != ticket_id: + raise ObservationError("Workspace changed during observation; retry") + ticket_dir = peer_path / "project" / ticket_id + if ticket_dir.is_symlink(): + raise ObservationError("Workspace changed during observation; retry") + if mode == "sqlite": + record = records.get(ticket_id) + if not record: + raise ObservationError("Workspace changed during observation; retry") + re_intent = json.loads(record["files"]["intent.json"][0]) + readme = record["files"]["README.md"][0].decode("utf-8") + status_match = re.search(r"(?mi)^-[ \t]+\*\*Status\*\*:[ \t]*([A-Z_]+)[ \t]*$", readme) + if status_match is None: + raise ObservationError("Workspace changed during observation; retry") + status_override = status_match[1] + else: + re_intent = read_json(ticket_dir / "intent.json") + status_override = None + if digest(re_intent) != entry["intentDigest"]: + raise ObservationError("Workspace changed during observation; retry") + re_res = resolve_activity(peer_path, ticket_dir, statuses, status_override=status_override) + if ((re_res.active, re_res.projectionStatus, re_res.authority) + != (entry["active"], entry["status"], entry["activityAuthority"])): + raise ObservationError("Workspace changed during observation; retry") + if (intersects(requested, entry["allowedPaths"]) + or intersects(requested, entry["dirtyPaths"]) + or intersects(requested, new_dirty) + or intersects(requested, changes(root, comparison_sha, entry["headSha"]))): + raise ObservationError("Workspace changed during observation; retry") + entry["dirtyPaths"] = new_dirty + entry["allDirtyPaths"] = new_all_dirty + entry["dirtyDigest"] = new_dirty_hash + entry["dirtyNewestModifiedAt"] = dirty_modified(peer_path, new_all_dirty) + entry["pending"] = new_pending + + +def refresh_autonomy_board(root): + """Best effort: every work start rewrites the ignored GOV-IDLE-TAKEOVER board; it never changes the route.""" + checker = Path(__file__).resolve().parent / "idle_takeover.py" + if not checker.is_file(): + return + try: + spec = importlib.util.spec_from_file_location("work_start_idle_takeover", checker) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + board = module.observe(Path(root)) + path = module.write_board(board) + except Exception: # noqa: BLE001 - the board is advisory; observation errors must not alter the route + return + eligible = [item["ticket"] for item in board["tickets"] if item["state"] == "IDLE_TAKEOVER_ELIGIBLE"] + print(f"autonomy board: {path}" + (f"; idle takeover candidates: {', '.join(eligible)}" if eligible else ""), + file=sys.stderr) + + def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--root", type=Path, default=Path.cwd()) @@ -711,6 +1654,10 @@ def main(argv=None): parser.add_argument("--storage", choices=["files", "sqlite"]) parser.add_argument("--observe-publication", action="store_true", help="Read origin refs twice without fetching; distinguish remote code from integration/release authority.") + parser.add_argument("--controller-store", type=Path, metavar="DIR", + help="Read-only availability of the controller editing resource (state.json); never a grant.") + parser.add_argument("--controller-repository", metavar="OWNER/NAME", + help="Exact repository reference the controller resource is bound to (with --controller-store).") parser.add_argument("--expect-dirty-digest", metavar="SHA256", help="With --ticket: dirtyDigest of the selected checkout from this session's previous observation; " "a mismatch blocks reuse (clone-local CAS, not a lease).") @@ -718,6 +1665,9 @@ def main(argv=None): if args.expect_dirty_digest is not None and ( not args.ticket or not re.fullmatch(r"[0-9a-f]{64}", args.expect_dirty_digest)): parser.error("--expect-dirty-digest requires --ticket and a lowercase SHA-256 digest") + if (args.controller_store is None) != (args.controller_repository is None) or ( + args.controller_repository is not None and not REPOSITORY_REF.fullmatch(args.controller_repository)): + parser.error("--controller-store and --controller-repository OWNER/NAME must be passed together") if args.bootstrap_adoption_digest is not None and ( not args.allocation_check or args.ticket or args.storage == "sqlite" or not re.fullmatch(r"[0-9a-f]{64}", args.bootstrap_adoption_digest)): @@ -725,22 +1675,37 @@ def main(argv=None): try: payload = inspect(args.root, args.workstream, args.path, args.ticket, args.storage, args.observe_publication, args.expect_dirty_digest, - bootstrap_adoption_digest=args.bootstrap_adoption_digest) + bootstrap_adoption_digest=args.bootstrap_adoption_digest, + controller=(args.controller_store, args.controller_repository) + if args.controller_store else None) except (ObservationError, ActivityError, KeyError, TypeError, ValueError, OSError, StopIteration) as error: # Stdout stays generic — no exception content: remote URLs or # secret-bearing input never leak there. The real cause is written # to a local-only log instead of being discarded (see # _record_observation_failure). - _record_observation_failure(args.root, error) + if isinstance(error, UnknownWorkstream): + # The whole cause fits on stdout, so nothing is logged. Declared + # names come from the checked-in manifest and disclose nothing; + # the caller's raw argument is not echoed. + print(json.dumps({"schema": SCHEMA, "readOnly": True, "grantsAuthority": False, + "createsWorktree": False, "route": "RECONCILE", "diagnostic": CODE, + "reason": "GOV-WORKSTREAM-001: --workstream is not declared in the governance " + "manifest; no checkout needs reconciling. Declared workstreams: " + + (", ".join(error.declared) or "none") + "."})) + return 3 + logged = _record_observation_failure(args.root, error) print(json.dumps({"schema": SCHEMA, "readOnly": True, "grantsAuthority": False, "createsWorktree": False, "route": "RECONCILE", "diagnostic": CODE, "reason": "Observation incomplete or inconsistent; preserve work and reconcile. " - "Real cause logged locally in .governance/.observation-failures.log " - "(gitignored) — read it before opening a new ticket."})) + + ("Real cause logged locally in " + _OBSERVATION_LOG + + " (ignored by Git) — read it before opening a new ticket." + if logged else "Local diagnostic was not written; preserve work " + "and inspect the existing checkout and ignore policy.")})) return 3 if args.allocation_check and payload["route"] != "NEW_TICKET_CANDIDATE": payload["diagnostic"] = CODE + refresh_autonomy_board(args.root) print(json.dumps(payload, sort_keys=True, ensure_ascii=True)) return 3 if payload["diagnostic"] else 0 diff --git a/.governance/worktree_overlap_check.py b/.governance/worktree_overlap_check.py index 0d64ef1..974bcc6 100755 --- a/.governance/worktree_overlap_check.py +++ b/.governance/worktree_overlap_check.py @@ -18,6 +18,7 @@ import shutil import subprocess import sys +import time from dataclasses import asdict, dataclass from pathlib import Path from typing import Any @@ -379,7 +380,7 @@ def nul_records(output: str) -> list[str]: return records -def dirty_paths(path: Path, ignore: tuple[str, ...]) -> tuple[str, ...]: +def unignored_dirty_paths(path: Path) -> set[str]: names: set[str] = set() records = iter(nul_records(run_git( path, "status", "--porcelain=v1", "-z", "--untracked-files=all"))) @@ -395,7 +396,13 @@ def dirty_paths(path: Path, ignore: tuple[str, ...]) -> tuple[str, ...]: if original is None: raise AuditError('Git status is missing a rename/copy source path') names.add(original) - return tuple(sorted(name for name in names if name and not path_ignored(name, ignore))) + return {name for name in names if name} + + +def dirty_paths(path: Path, ignore: tuple[str, ...]) -> tuple[str, ...]: + return tuple( + sorted(name for name in unignored_dirty_paths(path) if not path_ignored(name, ignore)) + ) def committed_against( @@ -444,10 +451,9 @@ def merge_tree_conflicts(path: Path, left: str, right: str) -> tuple[str, ...] | """ try: result = subprocess.run( - ["git", "-C", str(path), "merge-tree", "--write-tree", "--name-only", left, right], + ["git", "-C", str(path), "merge-tree", "--write-tree", "--name-only", "-z", left, right], capture_output=True, check=False, - text=True, timeout=60, env=detached_git_env(), ) @@ -457,12 +463,12 @@ def merge_tree_conflicts(path: Path, left: str, right: str) -> tuple[str, ...] | return () if result.returncode != 1: return None - lines = result.stdout.splitlines() + records = result.stdout.split(b"\x00") conflicted: list[str] = [] - for line in lines[1:]: - if not line.strip(): + for record in records[1:]: + if not record: break - conflicted.append(line.strip()) + conflicted.append(record.decode("utf-8", errors="surrogateescape")) return tuple(sorted(set(conflicted))) @@ -513,12 +519,12 @@ def changes_against_shared_default(first, second, first_dirty, second_dirty, fir if first_default == second_default: first_base = run_git(first.path, "merge-base", first.head, first_default) second_base = run_git(second.path, "merge-base", second.head, second_default) - first_committed = set(run_git(first.path, "diff", "--name-only", "--no-renames", first_base, first.head).splitlines()) - second_committed = set(run_git(second.path, "diff", "--name-only", "--no-renames", second_base, second.head).splitlines()) - first_renames = run_git(first.path, "diff", "--name-only", "--find-renames", - "--diff-filter=R", first_base, first.head) - second_renames = run_git(second.path, "diff", "--name-only", "--find-renames", - "--diff-filter=R", second_base, second.head) + first_committed = set(nul_records(run_git(first.path, "diff", "--name-only", "-z", "--no-renames", first_base, first.head))) + second_committed = set(nul_records(run_git(second.path, "diff", "--name-only", "-z", "--no-renames", second_base, second.head))) + first_renames = nul_records(run_git(first.path, "diff", "--name-only", "-z", "--find-renames", + "--diff-filter=R", first_base, first.head)) + second_renames = nul_records(run_git(second.path, "diff", "--name-only", "-z", "--find-renames", + "--diff-filter=R", second_base, second.head)) # Replace both sides only after every strict Git read succeeds. # Rename/directory-rename conflicts can be reported at a path # edited under another name. Preserve the conservative path @@ -560,8 +566,8 @@ def contested_paths( # Use strict reads here: committed_against's best-effort empty # result must not turn an unreadable peer into permission to write. try: - first_committed = set(run_git(first.path, "diff", "--name-only", base, first.head).splitlines()) - second_committed = set(run_git(second.path, "diff", "--name-only", base, second.head).splitlines()) + first_committed = set(nul_records(run_git(first.path, "diff", "--name-only", "-z", base, first.head))) + second_committed = set(nul_records(run_git(second.path, "diff", "--name-only", "-z", base, second.head))) first_changes = first_committed | first_dirty second_changes = second_committed | second_dirty except AuditError: @@ -572,20 +578,22 @@ def contested_paths( dirty_overlap = (first_dirty & second_changes) | (second_dirty & first_changes) conflicts: set[str] = set() if first.head and second.head and first.head != second.head: - if not is_ancestor(first.path, first.head, second.head) and not is_ancestor( - first.path, second.head, first.head - ): - reported = merge_tree_conflicts(first.path, first.head, second.head) - if reported is None: - # No usable merge-tree: fall back to the path-intersection proxy. - conflicts = first_changes & second_changes - else: - conflicts = set(reported) - if shared_default: - # A branch can conflict with main without contending with - # this particular peer. Keep the conflict in its inventory, - # but require contributions from both writers for pairing. - conflicts &= first_changes & second_changes + shared_pair_overlap = first_changes & second_changes + if not (shared_default and not shared_pair_overlap): + if not is_ancestor(first.path, first.head, second.head) and not is_ancestor( + first.path, second.head, first.head + ): + reported = merge_tree_conflicts(first.path, first.head, second.head) + if reported is None: + # No usable merge-tree: fall back to the path-intersection proxy. + conflicts = shared_pair_overlap + else: + conflicts = set(reported) + if shared_default: + # A branch can conflict with main without contending with + # this particular peer. Keep the conflict in its inventory, + # but require contributions from both writers for pairing. + conflicts &= shared_pair_overlap return tuple( sorted( name @@ -595,13 +603,18 @@ def contested_paths( ) -def changed_paths(path: Path, ignore: tuple[str, ...]) -> tuple[str, ...]: +def changed_paths( + path: Path, + ignore: tuple[str, ...], + *, + dirty: tuple[str, ...] | None = None, +) -> tuple[str, ...]: """Everything this checkout has touched relative to the default branch. Used for reporting and for attributing a ticket to the checkout writing it, never for deciding whether two checkouts collide. """ - names: set[str] = set(dirty_paths(path, ignore)) + names: set[str] = set(dirty_paths(path, ignore) if dirty is None else dirty) branch = default_branch(path) base = None for candidate in (f"origin/{branch}", branch): @@ -711,30 +724,42 @@ def ticket_scopes(root: Path) -> tuple[tuple[TicketScope, ...], tuple[str, ...]] statuses = active_statuses(root) if not statuses: return (), () - try: - with ActivityReadBatch(root): - directories = (project / name for name in virtual) if virtual is not None else project.iterdir() - for directory in sorted(directories, key=lambda item: item.name): - if (virtual is None and not directory.is_dir()) or TICKET_DIRECTORY_RE.fullmatch(directory.name) is None: - continue - override = ticket_status_override(virtual, directory) - try: - resolution = resolve_ticket_activity(root, directory, statuses, **override) - except ActivityError as error: - errors.append(f"{directory.name}: {error}") - resolution = None - if resolution is not None and not resolution.active: - continue - try: - intent = scope_intent(directory, virtual) - except AuditError as error: - # Keep the checkout and its known identity. The error - # fails its audit without blocking an unrelated identity. - errors.append(f"{directory.name}: {error}") - continue - scopes.append(ticket_scope_record(directory, intent)) - except ActivityError as error: - errors.append(str(error)) + transient_git_messages = { + "Git state changed during activity inspection; retry", + "ticket inventory changed during activity inspection; retry", + } + for attempt in range(3): + scopes = [] + errors = [] + try: + with ActivityReadBatch(root): + directories = (project / name for name in virtual) if virtual is not None else project.iterdir() + for directory in sorted(directories, key=lambda item: item.name): + if (virtual is None and not directory.is_dir()) or TICKET_DIRECTORY_RE.fullmatch(directory.name) is None: + continue + override = ticket_status_override(virtual, directory) + try: + resolution = resolve_ticket_activity(root, directory, statuses, **override) + except ActivityError as error: + errors.append(f"{directory.name}: {error}") + resolution = None + if resolution is not None and not resolution.active: + continue + try: + intent = scope_intent(directory, virtual) + except AuditError as error: + # Keep the checkout and its known identity. The error + # fails its audit without blocking an unrelated identity. + errors.append(f"{directory.name}: {error}") + continue + scopes.append(ticket_scope_record(directory, intent)) + break + except ActivityError as error: + if str(error) in transient_git_messages and attempt < 2: + time.sleep(0.05 * (attempt + 1)) + continue + errors.append(str(error)) + break return tuple(scopes), tuple(errors) @@ -756,28 +781,38 @@ def has_pending_work(path: Path, dirty: bool) -> bool: return True -def inspect_checkout(path: Path, ignore: tuple[str, ...]) -> Checkout: +def inspect_checkout( + path: Path, ignore: tuple[str, ...], only_identity: str | None = None +) -> Checkout: common = Path(run_git(path, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve() try: head = run_git(path, "rev-parse", "--verify", "HEAD") except AuditError: head = None branch = run_git(path, "branch", "--show-current") or None - dirty = bool(run_git(path, "status", "--porcelain=v1", "--untracked-files=all")) + raw_dirty = unignored_dirty_paths(path) + dirty = bool(raw_dirty) pending = has_pending_work(path, dirty) - scopes, activity_errors = ticket_scopes(path) if pending else ((), ()) + identity = repository_identity(path) + in_scope = pending and (only_identity is None or identity == only_identity) + scopes, activity_errors = ticket_scopes(path) if in_scope else ((), ()) + filtered_dirty = ( + tuple(sorted(name for name in raw_dirty if not path_ignored(name, ignore))) + if in_scope + else () + ) return Checkout( path=path.resolve(), common_git_dir=common, - identity=repository_identity(path), + identity=identity, head=head, branch=branch, dirty=dirty, pending=pending, - # A leftover contributes nothing to any merge, so skip the three - # expensive reads it would only feed into comparisons that are skipped. - dirty_paths=dirty_paths(path, ignore) if pending else (), - changed_paths=changed_paths(path, ignore) if pending else (), + # A leftover or out-of-scope identity contributes nothing to any merge + # in this audit, so skip the expensive reads that would be discarded. + dirty_paths=filtered_dirty, + changed_paths=changed_paths(path, ignore, dirty=filtered_dirty) if in_scope else (), tickets=scopes, activity_errors=activity_errors, ) @@ -822,7 +857,9 @@ def workspace_candidates(workspace_root): return candidate_paths -def discover_checkouts(workspace_root: Path, ignore: tuple[str, ...]) -> list[Checkout]: +def discover_checkouts( + workspace_root: Path, ignore: tuple[str, ...], only_identity: str | None = None +) -> list[Checkout]: candidate_paths = workspace_candidates(workspace_root) pending = sorted(candidate_paths, key=str) @@ -846,7 +883,7 @@ def discover_checkouts(workspace_root: Path, ignore: tuple[str, ...]) -> list[Ch checkouts: list[Checkout] = [] for candidate in sorted(candidate_paths, key=str): try: - checkouts.append(inspect_checkout(candidate, ignore)) + checkouts.append(inspect_checkout(candidate, ignore, only_identity)) except AuditError as error: raise AuditError(f"Cannot inspect checkout {candidate}: {error}") from error return checkouts @@ -1169,7 +1206,9 @@ def main(argv: list[str] | None = None) -> int: if args.focus_checkout is not None else None ) - checkouts = discover_checkouts(args.workspace_root.expanduser().resolve(), ignore) + checkouts = discover_checkouts( + args.workspace_root.expanduser().resolve(), ignore, only_identity + ) inventory = workspace_inventory(checkouts) findings = overlap_findings( checkouts, ignore, only_identity, focus_checkout, inventory diff --git a/.governance/worktree_path_check.py b/.governance/worktree_path_check.py index 1ae9623..88da583 100755 --- a/.governance/worktree_path_check.py +++ b/.governance/worktree_path_check.py @@ -201,7 +201,7 @@ def parse_worktree_porcelain(raw: bytes) -> list[dict[str, Any]]: def registered_worktrees(start_path: str) -> list[dict[str, Any]]: """Observe Git's registered worktrees; this function performs no repair.""" - raw = _git_output(["-C", start_path, "worktree", "list", "--porcelain", "-z"]) + raw = _git_output(["-C", start_path, "worktree", "list", "--porcelain", "-z"], cwd=None) records = parse_worktree_porcelain(raw) if not records: raise ValueError("Git returned no registered worktrees") @@ -362,6 +362,14 @@ def inventory( branch=observed.get("branch"), path_style=path_style, ) + anomalies = list(entry.get("anomalies", [])) + if observed.get("stale") or (observed.get("prunable") and not os.path.exists(path)): + if "stale-registration" not in anomalies: + anomalies.append("stale-registration") + if observed.get("merged"): + if "merged-leftover" not in anomalies: + anomalies.append("merged-leftover") + entry["anomalies"] = anomalies entry.update( { "head": observed.get("head"), @@ -411,6 +419,8 @@ def validate_inventory(record: dict[str, Any]) -> list[str]: "detached": entry.get("detached", False), "locked": entry.get("locked", False), "prunable": entry.get("prunable", False), + "stale": "stale-registration" in entry.get("anomalies", []), + "merged": "merged-leftover" in entry.get("anomalies", []), } for entry in record["entries"] if isinstance(entry, dict) @@ -559,6 +569,7 @@ def main() -> int: repository_name=args.repository_name, primary_checkout=primary, registered=registered_worktrees(args.from_worktree), + path_style="windows" if os.name == "nt" else "posix", ) print(json.dumps(record, indent=2)) return 0 diff --git a/.governance/worktrees.lock.json b/.governance/worktrees.lock.json index acb3ff5..30fadd6 100644 --- a/.governance/worktrees.lock.json +++ b/.governance/worktrees.lock.json @@ -2,22 +2,22 @@ "schema": "new-project.worktrees-lock/v1", "dependency": { "id": "wellmanifest/worktrees", - "version": "0.5.3", + "version": "0.5.4", "sourceRepository": "wellmanifest/worktrees", - "sourceRevision": "57bcd6b6f5d266fa9952824f1d89d4d45d8a386d" + "sourceRevision": "0be9ad1387bd416fd5c1c6ee68a7b7050d5f2a3e" }, "artifacts": [ { "sourcePath": "models/worktrees.schema.json", "packageSourcePath": "subprojects/worktrees/worktrees.schema.json", "managedTargetPath": ".governance/worktrees.schema.json", - "sourceSha256": "bb5989c19ee33d9beafa34576ef568ef70384a664ccf763ac2e29dde3a464756" + "sourceSha256": "6b57184758bdceda5cd5ea98889427af1a762dd0afe801ac8e1279d26ccb2cb8" }, { "sourcePath": "operations/conformance.py", "packageSourcePath": "subprojects/worktrees/conformance.py", "managedTargetPath": ".governance/worktree_path_check.py", - "sourceSha256": "fad10912f3b14913cc348880996b636ba0d31ea66a853dd264b53e4e66f17feb" + "sourceSha256": "106f91e6398564b96d5487dbd981ebb2078d7d366b327400b7d08467fa04c1fd" } ], "installation": { diff --git a/.governance/worktrees.schema.json b/.governance/worktrees.schema.json index 1212c65..c6559f4 100644 --- a/.governance/worktrees.schema.json +++ b/.governance/worktrees.schema.json @@ -128,7 +128,13 @@ "slug": {"$ref": "#/$defs/nullableSlug"}, "anomalies": { "type": "array", - "items": {"const": "duplicate-delivery"}, + "items": { + "enum": [ + "duplicate-delivery", + "stale-registration", + "merged-leftover" + ] + }, "uniqueItems": true }, "head": {"$ref": "#/$defs/nullableString"}, diff --git a/AGENTS.md b/AGENTS.md index 68cc53f..103ce52 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,7 @@ navigation only and are never fetched or executed by an agent. - Agent contract: [agent.schema.json](https://github.com/wellmanifest/agent/blob/main/standard/agent.schema.json) - LLM policy boundary: [wellmanifest/llm README](https://github.com/wellmanifest/llm/blob/main/README.md) - Session recovery: [session-recovery.schema.json](https://github.com/wellmanifest/session-recovery/blob/main/standard/session-recovery.schema.json) +- Embedded SemVer & Heterogeneous Fleet: [embedded-release.schema.json](https://github.com/wellmanifest/semver/blob/main/schemas/embedded-release.schema.json) - Offer pointer: [wellmanifest/offer README](https://github.com/wellmanifest/offer/blob/main/README.md) - Brand pointer: [wellmanifest/brand README](https://github.com/wellmanifest/brand/blob/main/README.md) @@ -48,7 +49,7 @@ files until a repository's protected CI adoption canary succeeds. This target repository follows `wellmanifest/new-project` policy-as-code. HOME vs ADOPT: wellmanifest owns standards; product CLI/daemons HOME in -`subactor` or `semcod`. "w ramach wellmanifest" means ADOPT packs such as +`subactor`, `semcod`, `paxlet-com` or `dockuri`. "w ramach wellmanifest" means ADOPT packs such as `wellmanifest/{new-project,dsl,logs}`, not HOME wellmanifest. For SERVICE/FEATURE that create a repo, fill `intent.json` `placement` (`home`, `shape`, `runtimeOwner`, `adopt`) in WAIT_FOR_APPROVAL. @@ -63,6 +64,16 @@ authorized work, read-only assistance, accepted fenced handoff or serialization. A new ticket needs a free scope and WIP capacity. Recheck owner, intent, current state and controller fencing before writing. `--force-new` is not a bypass. Unknown ownership or remote/independent-clone state must not be guessed. +Run `.governance/idle_takeover.py observe` and read +`.subactor/cache/autonomy-board.md` (owner, idle time, canonical worktree path +and links to project, branch, README, PR and issues for every ticket). A ticket +with no activity for `coordination.idleTakeover.idleMinutes` is +`IDLE_TAKEOVER_ELIGIBLE`; continue it only through `idle_takeover.py takeover` +(`GOV-IDLE-TAKEOVER`). Take the ticket, branch, `worktreePath`, `leasePath` and +`writerEnvironment` only from that JSON result and work only inside +`/.worktrees/--` (wellmanifest/worktrees v5): +never create, move or hand-write a worktree or lease, never treat a linked +worktree as the primary checkout, and stop on the first non-zero exit. 1. Read `.governance/manifest.json`, `TODO.md`, `project/TICKETS.md` and the active ticket. @@ -272,6 +283,30 @@ Markdown approval is an audit note, not trusted merge approval. Required merge approval comes from the repository's protected review, attestation and ruleset boundary. +## Project-bound development execution + +Before running Python or pytest, select the independently approved full Wellman +runtime and verify its source pin and `run --help` capability. Use +`/bin/wellman run --root -- python -m pytest ...` +or the executor's enrolled SDK adapter. Reuse the canonical `wellman.execution` +implementation; do not copy admission logic into project scripts. The static +checker is the separate `wellman-governance` command and cannot mediate a child +process. Never select a runtime merely because a command named `wellman` is on PATH. + +The child cwd, candidate source, interpreter association and development +temp/cache must bind to that Git checkout. Prepare its local `.venv` first. +Reuse of the same repository's registered primary `.venv` must be explicit; +another project's mutable environment is not a fallback. Development scratch +belongs in the checkout's ignored private `.subactor/cache/`. Immutable tools, +protected CI scratch and external receipt stores require distinct declared roles, +pins and ownership; their location alone neither grants nor denies authority. + +Missing enrollment or a missing/mismatched execution receipt is a prerequisite +to repair, never evidence of successful execution. Preserve the real command, +stdout/stderr and exit status. A static governance PASS, a local execution +observation or these instructions do not establish universal shell/IDE mediation, +a filesystem sandbox, a writer lease or independent publication approval. + ## Bounded session controls Every implementation session is bounded by the ticket's `maxActiveMinutes` and diff --git a/project/TICKETS.md b/project/TICKETS.md index 9b985dd..f88be6c 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -16,4 +16,5 @@ | **ticket-012** | [`README.md`](./ticket-012/README.md) | - | - | - | - | - | | **ticket-013** | [`README.md`](./ticket-013/README.md) | - | - | - | - | - | | **ticket-015** | [`README.md`](./ticket-015/README.md) | - | - | - | - | - | +| **ticket-016** | [`README.md`](./ticket-016/README.md) | - | - | - | - | - | diff --git a/project/governance-check.bat b/project/governance-check.bat index d4feb7d..12e806b 100644 --- a/project/governance-check.bat +++ b/project/governance-check.bat @@ -7,9 +7,9 @@ if errorlevel 1 ( exit /b 1 ) if exist "%REPO_ROOT%\.governance\governance_check.py" ( - python "%REPO_ROOT%\.governance\governance_check.py" --root "%REPO_ROOT%" --manifest .governance/manifest.json --lock .governance/manifest.lock.json --stack-profiles .governance/stack-profiles.json %* + python "%REPO_ROOT%\.governance\governance_check.py" --root "%REPO_ROOT%" --manifest .governance/manifest.json --lock .governance/manifest.lock.json --stack-profiles .governance/stack-profiles.json --infer-ticket-base %* ) else ( - python "%REPO_ROOT%\scripts\governance_check.py" --root "%REPO_ROOT%" --manifest governance\manifest.hub.json --stack-profiles governance\stack-profiles.json --work-classification governance\work-classification.dsl.json %* + python "%REPO_ROOT%\scripts\governance_check.py" --root "%REPO_ROOT%" --manifest governance\manifest.hub.json --stack-profiles governance\stack-profiles.json --work-classification governance\work-classification.dsl.json --infer-ticket-base %* ) set "GOVERNANCE_EXIT=%ERRORLEVEL%" exit /b %GOVERNANCE_EXIT% diff --git a/project/governance-check.sh b/project/governance-check.sh index 256538f..84f5340 100755 --- a/project/governance-check.sh +++ b/project/governance-check.sh @@ -8,6 +8,7 @@ if [ -f "$repo_root/.governance/governance_check.py" ]; then --manifest .governance/manifest.json \ --lock .governance/manifest.lock.json \ --stack-profiles .governance/stack-profiles.json \ + --infer-ticket-base \ "$@" else PYTHONDONTWRITEBYTECODE=1 python3 "$repo_root/scripts/governance_check.py" \ @@ -15,5 +16,6 @@ else --manifest governance/manifest.hub.json \ --stack-profiles governance/stack-profiles.json \ --work-classification governance/work-classification.dsl.json \ + --infer-ticket-base \ "$@" fi diff --git a/project/new-ticket.sh b/project/new-ticket.sh index 3195e34..d2caa29 100755 --- a/project/new-ticket.sh +++ b/project/new-ticket.sh @@ -6,6 +6,17 @@ set -euo pipefail TITLE="New Task Ticket" USERS="" AGENT="antigravity" +WRITER_ACTOR="" +WRITER_SESSION="" +WRITER_IDENTITY_EXPLICIT=false +SEED_BASELINE_REQUEST="" +SEED_MODE=false + +if [[ "${NEW_PROJECT_WRITER_ACTOR+set}" == "set" || "${NEW_PROJECT_WRITER_SESSION+set}" == "set" ]]; then + WRITER_ACTOR="${NEW_PROJECT_WRITER_ACTOR:-}" + WRITER_SESSION="${NEW_PROJECT_WRITER_SESSION:-}" + WRITER_IDENTITY_EXPLICIT=true +fi WORKSTREAM="" SCOPE_ARGUMENTS=() FORCE_NEW=false @@ -20,9 +31,13 @@ SNAPSHOT_MATERIALIZE="" MIGRATION_AUTHORIZATION="" MIGRATION_AUTHORIZATION_SHA256="" RECOVER_REQUEST="" +RECOVERY_HELPER=ticket_recovery +LOCAL_RESTORATION=false RECOVERY_LEASE_STORE="" WORKTREE_SLUG="" BOOTSTRAP_ADOPTION_DIGEST="" +STANDARD_ADOPTION_PLAN="" +ADOPTION_PROJECTION="" CALLER_CHECKOUT="$(pwd -P)" ALLOCATOR_PACKAGE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" @@ -40,6 +55,10 @@ Usage: ./project/new-ticket.sh [options] -t, --title TITLE Ticket title -a, --agent ID Agent provider/id used for ai-{ID}.md + --writer-actor ID Explicit allocating actor (or NEW_PROJECT_WRITER_ACTOR) + --writer-session ID Explicit session (or NEW_PROJECT_WRITER_SESSION) + --seed-baseline-request FILE + Exact external authority/state for one governance-only unborn seed -w, --workstream ID Required workstream from the governance registry --path PATTERN Repeatable owned implementation scope; persisted in intent -u, --users IDS Compatibility input only; human files are not created @@ -67,17 +86,23 @@ Usage: ./project/new-ticket.sh [options] Independently pinned grant digest --recover-request FILE Explicit exact-state pre-adoption recovery request + --restore-request FILE + Exact request restoring an already reserved ticket checkout + --restore-local-request FILE + Restore under the explicit live local writer and exact reservation digest --recovery-lease-store DIR - Existing external local controller store (recovery only) + Existing external local controller store (recovery/restoration) --bootstrap-adoption-digest SHA Confirm ownership of exact first scaffold adoption delta + --standard-adoption-plan FILE + Recompute an exact published upgrade plan before local allocation --worktree-slug SLUG Canonical linked-worktree slug; defaults to a stable title slug -Accepted classification values are read from the work classification contract, -not hardcoded here. The defaults are that contract's own answer for an -unclassified new ticket (rule W-CLASS-006 plus the service priority default); -declare the three explicitly for a defect or new behavior. +Accepted classification values come from the work classification contract, +not hardcoded here. The defaults for an unclassified new ticket follow that +contract (rule W-CLASS-006 plus the service priority default); declare the +three explicitly for a defect or new behavior. Only a human may authorize --force-new. Human-owned user-*.md files must be created and written by that human or by a trusted intake boundary. @@ -110,6 +135,12 @@ while [[ $# -gt 0 ]]; do AGENT="$2" shift 2 ;; + --writer-actor) + require_value "$@"; WRITER_ACTOR="$2"; WRITER_IDENTITY_EXPLICIT=true; shift 2 ;; + --writer-session) + require_value "$@"; WRITER_SESSION="$2"; WRITER_IDENTITY_EXPLICIT=true; shift 2 ;; + --seed-baseline-request) + require_value "$@"; SEED_BASELINE_REQUEST="$2"; shift 2 ;; -w|--workstream) require_value "$@" WORKSTREAM="$2" @@ -145,12 +176,21 @@ while [[ $# -gt 0 ]]; do require_value "$@"; MIGRATION_AUTHORIZATION="$2"; shift 2 ;; --migration-authorization-sha256) require_value "$@"; MIGRATION_AUTHORIZATION_SHA256="$2"; shift 2 ;; - --recover-request) - require_value "$@"; RECOVER_REQUEST="$2"; shift 2 ;; + --recover-request|--restore-request|--restore-local-request) + require_value "$@" + if [[ -n "$RECOVER_REQUEST" ]]; then + echo "GOV-TICKET-ALLOCATION-003: pass exactly one recovery or restoration request." >&2 + exit 5 + fi + [[ "$1" != --recover-request ]] && RECOVERY_HELPER=ticket_restoration + [[ "$1" == --restore-local-request ]] && LOCAL_RESTORATION=true + RECOVER_REQUEST="$2"; shift 2 ;; --recovery-lease-store) require_value "$@"; RECOVERY_LEASE_STORE="$2"; shift 2 ;; --bootstrap-adoption-digest) require_value "$@"; BOOTSTRAP_ADOPTION_DIGEST="$2"; shift 2 ;; + --standard-adoption-plan) + require_value "$@"; STANDARD_ADOPTION_PLAN="$2"; shift 2 ;; --worktree-slug) require_value "$@"; WORKTREE_SLUG="$2"; shift 2 ;; --ticket-store-root) @@ -206,6 +246,10 @@ if [[ ! "$AGENT" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then exit 2 fi +if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + STANDARD_ADOPTION_PLAN="$(python3 -B -c 'import os,sys; print(os.path.abspath(sys.argv[1]))' "$STANDARD_ADOPTION_PLAN")" +fi + # Allocation may be requested from a linked checkout, but the clone's primary # checkout is the only valid authority for admission and canonical layout. Do # not infer it from $PWD: Git's registered-worktree order is the durable @@ -223,6 +267,10 @@ fi TICKET_STORAGE="${TICKET_STORAGE:-$(git config --local --get new-project.ticketStorage 2>/dev/null || true)}" TICKET_STORAGE="${TICKET_STORAGE:-files}" +if [[ -n "$STANDARD_ADOPTION_PLAN" && ( "$TICKET_STORAGE" != files || "$REFRESH_REMOTE" == true || "$FORCE_NEW" == true || -n "$BOOTSTRAP_ADOPTION_DIGEST" || -n "$SNAPSHOT_PROPOSAL" || -n "$SNAPSHOT_MATERIALIZE" || -n "$MIGRATION_AUTHORIZATION" || -n "$MIGRATION_AUTHORIZATION_SHA256" || -n "$RECOVER_REQUEST" || -n "$RECOVERY_LEASE_STORE" ) ]]; then + echo "GOV-TICKET-ALLOCATION-003: adoption plans require exclusive local file allocation without bootstrap or recovery overrides." >&2 + exit 5 +fi if [[ "$TICKET_STORAGE" != files && "$TICKET_STORAGE" != sqlite ]]; then echo "GOV-TICKET-ALLOCATION-003: unknown ticket storage mode." >&2 exit 1 @@ -325,15 +373,34 @@ if ! grep -Fxq -- "$WORKSTREAM" <<< "$WORKSTREAM_REGISTRY"; then exit 1 fi +# Validate caller identity before any reservation, refresh or scaffold effect. +# Provider names and timestamps are not session identity. +if [[ -z "$SNAPSHOT_PROPOSAL$SNAPSHOT_MATERIALIZE$RECOVER_REQUEST" ]]; then + if [[ "$WRITER_IDENTITY_EXPLICIT" == true ]]; then + if [[ ! "$WRITER_ACTOR" =~ ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,159}$ || + ! "$WRITER_SESSION" =~ ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,254}$ ]]; then + echo "GOV-CHANGE-LEASE-001: allocation requires explicit valid writer actor and session." >&2 + exit 2 + fi + else + WRITER_ACTOR="agent:${AGENT}" + WRITER_SESSION="allocation-$(date -u +"%Y-%m-%dT%H:%M:%SZ")-$$-$(python3 -c 'import secrets; print(secrets.token_hex(4))')" + fi +fi + is_active_ticket() { - local directory="$1" resolver status arguments=() runner=() + local directory="$1" resolver status arguments=() runner=() candidates=() if [[ "$TICKET_STORAGE" != sqlite ]]; then [[ -f "$directory/README.md" ]] || return 1 fi - for resolver in .governance/ticket_activity.py scripts/ticket_activity.py; do - [[ -f "$resolver" ]] && break + candidates=(.governance/ticket_activity.py scripts/ticket_activity.py) + if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + candidates+=("$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_activity.py") + fi + for resolver in "${candidates[@]}"; do + [[ -f "$resolver" && ! -L "$resolver" ]] && break done - if [[ ! -f "$resolver" ]]; then + if [[ ! -f "$resolver" || -L "$resolver" ]]; then echo "GOV-TICKET-ACTIVITY-001: managed ticket activity resolver is missing." >&2 echo " remediation: restore the complete pinned governance package before allocating." >&2 exit 1 @@ -380,10 +447,11 @@ require_classification_value() { exit 1 fi local allowed - allowed="$(python3 -c 'import json,sys + if ! allowed="$(python3 -c 'import json,sys data = json.load(open(sys.argv[1])) -print("\n".join(data["dimensions"][sys.argv[2]]))' "$dsl" "$dimension")" - if ! grep -Fxq -- "$value" <<< "$allowed"; then +values = data["dimensions"][sys.argv[2]] +print("\n".join(values)) +raise SystemExit(0 if sys.argv[3] in values else 1)' "$dsl" "$dimension" "$value")"; then echo "GOV-CLASS-001: '$value' is not a declared $dimension in $dsl." >&2 echo " accepted: $(printf '%s' "$allowed" | tr '\n' ' ')" >&2 exit 1 @@ -394,14 +462,52 @@ require_classification_value kind "$KIND" require_classification_value priority "$PRIORITY" require_classification_value origin "$ORIGIN" +# The incoming immutable package owns its verifier; the plan never names code. +# Old adopters invoke this published source package's native allocator from +# their primary checkout. A partial installed package is not a fallback. +verify_standard_adoption() { + local runtime="$ALLOCATOR_PACKAGE_ROOT/scripts/create_adoption_lock.py" + if [[ ! -f "$runtime" || -L "$runtime" ]]; then + echo "GOV-TICKET-ALLOCATION-003: adoption allocation requires the complete immutable source package." >&2 + return 5 + fi + python3 -B - "$runtime" "$STANDARD_ADOPTION_PLAN" "$PWD" "$WORKSTREAM" "${SCOPE_ARGUMENTS[@]}" <<'PYADOPTION' +import importlib.util, json, sys +from pathlib import Path +runtime, plan_path, root, workstream, *scope = sys.argv[1:] +spec = importlib.util.spec_from_file_location("native_adoption_plan", runtime) +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +plan = module.verify_allocation_plan(Path(plan_path), Path(root), workstream, + [argument.removeprefix("--path=") for argument in scope] or None) +print(json.dumps({key: plan[key] for key in ("allowedPaths", "delivery", "digest")})) +PYADOPTION +} + # Validate the explicit scope before any identity reservation or registered # allocation request. The same argv is used for admission and both stores. -if (( ${#SCOPE_ARGUMENTS[@]} )); then +if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + if ! ADOPTION_PROJECTION="$(verify_standard_adoption)"; then + echo "GOV-TICKET-ALLOCATION-003: adoption allocation proof is invalid; preserve the target and recompute the exact published plan." >&2 + exit 5 + fi + if [[ -z "$TICKET_STORAGE_HELPER" && -f "$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_storage.py" && ! -L "$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_storage.py" ]]; then + TICKET_STORAGE_HELPER="$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_storage.py" + fi + mapfile -t adoption_paths < <(python3 -B -c 'import json,sys; print("\n".join(json.load(sys.stdin)["allowedPaths"]))' <<< "$ADOPTION_PROJECTION") + SCOPE_ARGUMENTS=() + for adoption_path in "${adoption_paths[@]}"; do SCOPE_ARGUMENTS+=("--path=$adoption_path"); done +elif (( ${#SCOPE_ARGUMENTS[@]} )); then if [[ -z "$TICKET_STORAGE_HELPER" ]]; then echo "GOV-WORK-START-001: explicit scope requires the managed ticket storage bridge." >&2 exit 3 fi - python3 "$TICKET_STORAGE_HELPER" scope --root "$PWD" --workstream "$WORKSTREAM" "${SCOPE_ARGUMENTS[@]}" >/dev/null + scope_bootstrap_arguments=() + if [[ -n "$BOOTSTRAP_ADOPTION_DIGEST" ]]; then + scope_bootstrap_arguments+=(--bootstrap-adoption-digest "$BOOTSTRAP_ADOPTION_DIGEST") + fi + python3 "$TICKET_STORAGE_HELPER" scope --root "$PWD" --workstream "$WORKSTREAM" \ + "${scope_bootstrap_arguments[@]}" "${SCOPE_ARGUMENTS[@]}" >/dev/null fi allocation_config() { @@ -416,16 +522,20 @@ allocation_config() { } allocation_runtime() { - local candidate + local candidate candidates=() if [[ -n "$SNAPSHOT_PROPOSAL" || -n "$SNAPSHOT_MATERIALIZE" || -n "$MIGRATION_AUTHORIZATION" || -n "$MIGRATION_AUTHORIZATION_SHA256" ]]; then for candidate in "$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_allocation.py" "$ALLOCATOR_PACKAGE_ROOT/.governance/ticket_allocation.py"; do if [[ -f "$candidate" ]]; then printf '%s' "$candidate"; return 0; fi done return 1 fi - for candidate in .governance/ticket_allocation.py scripts/ticket_allocation.py; do - if [[ -f "$candidate" ]]; then - printf '%s' "$candidate" + candidates=(.governance/ticket_allocation.py scripts/ticket_allocation.py) + if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + candidates+=("$ALLOCATOR_PACKAGE_ROOT/scripts/ticket_allocation.py") + fi + for candidate in "${candidates[@]}"; do + if [[ -f "$candidate" && ! -L "$candidate" ]]; then + printf '%s' "$(cd "$(dirname "$candidate")" && pwd -P)/$(basename "$candidate")" return 0 fi done @@ -446,19 +556,42 @@ if ALLOCATION_CONFIG="$(allocation_config)"; then exit 5 fi fi +if [[ -n "$PRIMARY_CHECKOUT" && -z "$ALLOCATION_RUNTIME" ]]; then + ALLOCATION_RUNTIME="$(allocation_runtime || true)" +fi if [[ "$ALLOCATION_MODE" == "local-single-clone" && ( -n "$ALLOCATION_KEY" || -n "$ALLOCATION_RECEIPT" ) ]]; then echo "GOV-TICKET-ALLOCATION-003: registered allocation inputs are forbidden in local-single-clone mode." >&2 echo " remediation: remove the inputs or adopt a registered allocator policy." >&2 exit 5 fi +if [[ -n "$SEED_BASELINE_REQUEST" ]]; then + if [[ "$ALLOCATION_MODE" != local-single-clone || "$TICKET_STORAGE" != files \ + || -z "$PRIMARY_CHECKOUT" || "$WRITER_IDENTITY_EXPLICIT" != true \ + || -n "$RECOVER_REQUEST" || -n "$STANDARD_ADOPTION_PLAN" \ + || "$REFRESH_REMOTE" == true || "$FORCE_NEW" == true ]]; then + echo "GOV-TICKET-ALLOCATION-003: seed requires explicit local file allocation and writer identity only." >&2 + exit 5 + fi + SEED_RUNNER="$PRIMARY_CHECKOUT/.governance/seed_baseline.py" + python3 -B "$SEED_RUNNER" preflight --root "$PRIMARY_CHECKOUT" \ + --request "$SEED_BASELINE_REQUEST" --actor "$WRITER_ACTOR" --session "$WRITER_SESSION" + SEED_MODE=true +fi +if [[ -n "$STANDARD_ADOPTION_PLAN" && "$ALLOCATION_MODE" != local-single-clone ]]; then + echo "GOV-TICKET-ALLOCATION-003: adoption plans do not support registered allocation." >&2 + exit 5 +fi + if [[ -n "$BOOTSTRAP_ADOPTION_DIGEST" ]]; then if [[ ! "$BOOTSTRAP_ADOPTION_DIGEST" =~ ^[0-9a-f]{64}$ || "$TICKET_STORAGE" != files || "$ALLOCATION_MODE" != local-single-clone || "$REFRESH_REMOTE" == true || "$FORCE_NEW" == true || ${#SCOPE_ARGUMENTS[@]} -eq 0 || -n "$RECOVER_REQUEST$SNAPSHOT_PROPOSAL$SNAPSHOT_MATERIALIZE$MIGRATION_AUTHORIZATION$MIGRATION_AUTHORIZATION_SHA256" ]]; then echo "GOV-WORK-START-001: bootstrap acknowledgement requires exclusive first bounded file allocation." >&2 exit 3 fi +fi +if [[ -n "$TICKET_STORAGE_HELPER" && -f "$TICKET_STORAGE_HELPER" ]]; then # Keep the validated bridge for metadata rendering after entering the new - # checkout; its base deliberately does not yet contain native governance. + # checkout; its base may not yet contain native governance. TICKET_STORAGE_HELPER="$(cd "$(dirname "$TICKET_STORAGE_HELPER")" && pwd -P)/$(basename "$TICKET_STORAGE_HELPER")" fi @@ -494,7 +627,9 @@ if [[ -n "$SNAPSHOT_PROPOSAL" || -n "$SNAPSHOT_MATERIALIZE" || -n "$MIGRATION_AU fi if [[ -n "$RECOVER_REQUEST" || -n "$RECOVERY_LEASE_STORE" ]]; then - if [[ -z "$RECOVER_REQUEST" || -z "$RECOVERY_LEASE_STORE" || "$TICKET_STORAGE" != files || "$ALLOCATION_MODE" != local-single-clone || "$REFRESH_REMOTE" == true || "$FORCE_NEW" == true || ${#SCOPE_ARGUMENTS[@]} -ne 0 ]]; then + if [[ -z "$RECOVER_REQUEST" || "$TICKET_STORAGE" != files || "$ALLOCATION_MODE" != local-single-clone || "$REFRESH_REMOTE" == true || "$FORCE_NEW" == true || ${#SCOPE_ARGUMENTS[@]} -ne 0 ]] \ + || { [[ "$LOCAL_RESTORATION" == false ]] && [[ -z "$RECOVERY_LEASE_STORE" ]]; } \ + || { [[ "$LOCAL_RESTORATION" == true ]] && [[ -n "$RECOVERY_LEASE_STORE" || "$WRITER_IDENTITY_EXPLICIT" != true || -z "$WRITER_ACTOR" || -z "$WRITER_SESSION" ]]; }; then echo "GOV-TICKET-ALLOCATION-003: recovery requires both inputs, file storage and local allocation; scope comes only from the bound request." >&2 exit 5 fi @@ -502,16 +637,33 @@ if [[ -n "$RECOVER_REQUEST" || -n "$RECOVERY_LEASE_STORE" ]]; then # binds an already-existing canonical linked checkout. Resolve normal # allocation from primary, but execute this bounded recovery at the caller # checkout so its exact ticket branch and managed helper remain available. + # Restoration re-registers an already reserved identity whose checkout is + # lost; it shares these inputs and exclusions but never reserves a number. cd "$CALLER_CHECKOUT" - for candidate in .governance/ticket_recovery.py scripts/ticket_recovery.py; do + restoration_authority=(--lease-store "$RECOVERY_LEASE_STORE") + if [[ "$LOCAL_RESTORATION" == true ]]; then + restoration_authority=(--local-reservation --actor "$WRITER_ACTOR" --session "$WRITER_SESSION") + fi + for candidate in ".governance/$RECOVERY_HELPER.py" "scripts/$RECOVERY_HELPER.py"; do if [[ -f "$candidate" ]]; then - exec python3 "$candidate" --root . --request "$RECOVER_REQUEST" --lease-store "$RECOVERY_LEASE_STORE" --workstream "$WORKSTREAM" + exec python3 "$candidate" --root . --request "$RECOVER_REQUEST" "${restoration_authority[@]}" --workstream "$WORKSTREAM" fi done echo "GOV-TICKET-ALLOCATION-003: restore the managed recovery helper." >&2 exit 5 fi +# Fail before clone locking, identity reservation or worktree creation when +# the host cannot provide race-resistant directory-relative lease writes. +if [[ "$TICKET_STORAGE" != sqlite ]]; then + python3 - <<'PY_LEASE_CAPABILITIES' +import os +if (not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY") + or os.open not in os.supports_dir_fd or os.mkdir not in os.supports_dir_fd): + raise SystemExit("GOV-TICKET-ALLOCATION-003: race-resistant lease creation is unsupported on this host") +PY_LEASE_CAPABILITIES +fi + allocation_lock="" allocation_state="" release_allocation_lock() { @@ -548,10 +700,24 @@ fi # The clone allocation lock covers this observation and the identity effect; # it is NOT a writer lease. Recheck admission and fencing before development. # Unborn/non-Git bootstrap has no branch history yet and retains seed behavior. +if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + if ! rechecked_projection="$(verify_standard_adoption)"; then + echo "GOV-TICKET-ALLOCATION-003: adoption allocation proof changed under the clone lock." >&2 + exit 5 + fi + if [[ "$rechecked_projection" != "$ADOPTION_PROJECTION" ]]; then + echo "GOV-TICKET-ALLOCATION-003: adoption plan changed before reservation." >&2 + exit 5 + fi +fi if git rev-parse --verify HEAD >/dev/null 2>&1; then start_runtime="" - for candidate in .governance/work_start_check.py scripts/work_start_check.py; do - if [[ -f "$candidate" ]]; then + start_candidates=(.governance/work_start_check.py scripts/work_start_check.py) + if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + start_candidates+=("$ALLOCATOR_PACKAGE_ROOT/scripts/work_start_check.py") + fi + for candidate in "${start_candidates[@]}"; do + if [[ -f "$candidate" && ! -L "$candidate" ]]; then start_runtime="$candidate" break fi @@ -704,7 +870,7 @@ fi WORKTREE_PATH="" LEASE_PATH="" -if [[ -n "$PRIMARY_CHECKOUT" ]]; then +if [[ -n "$PRIMARY_CHECKOUT" && "$SEED_MODE" != true ]]; then # Filesystem-backed ticket content must never be materialized in the primary # checkout. Plan and verify the exact v5 path before reserving identity; # after reservation every later failure remains observable for recovery. @@ -717,9 +883,13 @@ if [[ -n "$PRIMARY_CHECKOUT" ]]; then fi WORKTREE_CONTRACT="" - for candidate in .governance/worktree_path_check.py subprojects/worktrees/conformance.py; do - if [[ -f "$candidate" ]]; then - WORKTREE_CONTRACT="$candidate" + worktree_candidates=(.governance/worktree_path_check.py subprojects/worktrees/conformance.py) + if [[ -n "$STANDARD_ADOPTION_PLAN" ]]; then + worktree_candidates+=("$ALLOCATOR_PACKAGE_ROOT/subprojects/worktrees/conformance.py") + fi + for candidate in "${worktree_candidates[@]}"; do + if [[ -f "$candidate" && ! -L "$candidate" ]]; then + WORKTREE_CONTRACT="$(cd "$(dirname "$candidate")" && pwd -P)/$(basename "$candidate")" break fi done @@ -744,19 +914,58 @@ if [[ -n "$PRIMARY_CHECKOUT" ]]; then echo "GOV-TICKET-ALLOCATION-003: dirty primary requires an explicit disjoint --path scope admitted by work-start; preserve existing changes." >&2 exit 5 fi - if [[ "$(git -C "$PRIMARY_CHECKOUT" symbolic-ref --quiet --short HEAD 2>/dev/null || true)" != "$TARGET_BRANCH" ]]; then - echo "GOV-TICKET-ALLOCATION-003: allocation requires the registered primary checkout on $TARGET_BRANCH." >&2 + observe_primary_base() { + local branch head target remote + branch="$(git -C "$PRIMARY_CHECKOUT" symbolic-ref --quiet HEAD 2>/dev/null)" || return 1 + head="$(git -C "$PRIMARY_CHECKOUT" rev-parse --verify 'HEAD^{commit}')" || return 1 + target="$(git -C "$PRIMARY_CHECKOUT" rev-parse --verify "refs/heads/$TARGET_BRANCH^{commit}")" || return 1 + remote="$(git -C "$PRIMARY_CHECKOUT" rev-parse --verify "refs/remotes/origin/$TARGET_BRANCH^{commit}" 2>/dev/null || true)" + [[ "$head" == "$target" ]] || return 1 + if [[ "$branch" != "refs/heads/$TARGET_BRANCH" ]]; then + # A named alias is safe only with a complete, identical observed target. + # This does not refresh refs, switch primary or release active scope. + [[ "$branch" == refs/heads/* && "$remote" == "$head" ]] || return 1 + fi + printf '%s\t%s\t%s\t%s\n' "$branch" "$head" "$target" "$remote" + } + if ! primary_base_observation="$(observe_primary_base)"; then + echo "GOV-TICKET-ALLOCATION-003: primary must be on $TARGET_BRANCH or a named alias exactly matching local and origin target commits." >&2 exit 5 fi - if ! base_sha="$(git -C "$PRIMARY_CHECKOUT" rev-parse --verify "refs/heads/$TARGET_BRANCH^{commit}")"; then - echo "GOV-TICKET-ALLOCATION-003: observed target branch is unavailable." >&2 - exit 5 + base_sha="$(cut -f2 <<< "$primary_base_observation")" + # Leases bind the canonical owner/repository identity; path planning binds a + # separate local label that never becomes repositoryRef. + origin_url="$(git -C "$PRIMARY_CHECKOUT" config --get remote.origin.url 2>/dev/null || true)" + if [[ -n "$origin_url" && -n "$ALLOCATION_RUNTIME" ]]; then + canonical_origin="$(python3 "$ALLOCATION_RUNTIME" repository-ref --url "$origin_url" 2>/dev/null || true)" + else + canonical_origin="" + fi + if [[ -n "$canonical_origin" ]]; then + repository_ref="$(python3 - "$canonical_origin" <<'PY' +from urllib.parse import urlparse +import sys +value = urlparse(sys.argv[1]) +parts = value.path.strip('/').split('/') +if len(parts) == 2 and value.netloc and all(part not in ('', '.', '..') for part in parts): + print('/'.join(parts)) +PY +)" + else + repository_ref="" fi - # The layout contract needs a stable label, not a remote URL (which may - # contain credentials in misconfigured clones). - repository_ref="$(basename "$PRIMARY_CHECKOUT")" - if ! layout="$(python3 "$WORKTREE_CONTRACT" plan --repository "$repository_ref" \ - --repository-name "$(basename "$PRIMARY_CHECKOUT")" --ticket "$ticket_id" \ + if [[ -z "${repository_ref:-}" ]]; then + repository_ref="local/$(python3 - "$PRIMARY_CHECKOUT" <<'PY' +import hashlib +from pathlib import Path +import sys +print(hashlib.sha256(str(Path(sys.argv[1]).resolve(strict=True)).encode('utf-8')).hexdigest()) +PY +)" || exit 5 + fi + layout_repository_name="$(basename "$PRIMARY_CHECKOUT")" + if ! layout="$(python3 "$WORKTREE_CONTRACT" plan --repository "$layout_repository_name" \ + --repository-name "$layout_repository_name" --ticket "$ticket_id" \ --slug "$WORKTREE_SLUG" --from-worktree "$PRIMARY_CHECKOUT" \ --path-style "$(python3 -c 'import os; print("windows" if os.name == "nt" else "posix")')")"; then echo "GOV-TICKET-ALLOCATION-003: canonical Worktrees v5 layout could not be planned." >&2 @@ -787,6 +996,15 @@ for key in ("branch", "worktreePath", "leasePath"): exit 5 fi + if [[ -n "$STANDARD_ADOPTION_PLAN" && "$(verify_standard_adoption)" != "$ADOPTION_PROJECTION" ]]; then + echo "GOV-TICKET-ALLOCATION-003: adoption plan changed at the identity boundary." >&2 + exit 5 + fi + if ! rechecked_primary_base="$(observe_primary_base)" \ + || [[ "$rechecked_primary_base" != "$primary_base_observation" ]]; then + echo "GOV-TICKET-ALLOCATION-003: primary branch or target changed before ticket reservation." >&2 + exit 5 + fi reserve_ticket_number if ! git -C "$PRIMARY_CHECKOUT" worktree add --relative-paths -b "$WORKTREE_BRANCH" "$WORKTREE_PATH" "$base_sha"; then echo "GOV-TICKET-ALLOCATION-004: ticket number remains reserved; preserve and reconcile the failed worktree allocation." >&2 @@ -796,8 +1014,13 @@ for key in ("branch", "worktreePath", "leasePath"): ticket_dir="project/$ticket_id" fi -if [[ -n "$BOOTSTRAP_ADOPTION_DIGEST" ]]; then - mkdir -p project +ticket_parent="$(dirname "$ticket_dir")" +if [[ "$ticket_parent" != "." ]]; then + if [[ -L "$ticket_parent" || ( -e "$ticket_parent" && ! -d "$ticket_parent" ) ]]; then + echo "GOV-TICKET-LOCK-003: ticket directory already exists or cannot be created: $ticket_dir" >&2 + exit 4 + fi + mkdir -p "$ticket_parent" fi if ! mkdir "$ticket_dir" 2>/dev/null; then @@ -885,15 +1108,15 @@ else cat > "$ticket_dir/intent.json" </dev/null; then + echo "ticket-radar advisory: storage helper declined the assessment; README records it." >&2 + cat >> "$ticket_dir/README.md" <<'RADAR' + + +## Ticket Radar + +Assessment unavailable: managed ticket storage bridge declined the radar assessment. +Advisory only; no execution or merge approval. + +RADAR + fi + else + cat >> "$ticket_dir/README.md" <<'RADAR' + + +## Ticket Radar + +Assessment unavailable: managed ticket storage bridge is not installed. +Advisory only; no execution or merge approval. + +RADAR + fi +fi + +if [[ "$SEED_MODE" == true ]]; then + # Only the seed's own ticket carriers may precede a real baseline. Ordinary + # implementation still receives a canonical linked checkout and lease. + python3 -B "$SEED_RUNNER" prepare --root "$PRIMARY_CHECKOUT" \ + --request "$SEED_BASELINE_REQUEST" --actor "$WRITER_ACTOR" \ + --session "$WRITER_SESSION" --ticket "$ticket_id" + python3 -B "$SEED_RUNNER" commit --root "$PRIMARY_CHECKOUT" \ + --request "$SEED_BASELINE_REQUEST" --actor "$WRITER_ACTOR" --session "$WRITER_SESSION" + base_sha="$(git rev-parse HEAD)" + if [[ -z "$WORKTREE_SLUG" ]]; then + WORKTREE_SLUG="$(printf '%s' "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')" + fi + origin_url="$(git -C "$PRIMARY_CHECKOUT" config --get remote.origin.url 2>/dev/null || true)" + if [[ -n "$origin_url" && -n "$ALLOCATION_RUNTIME" ]]; then + canonical_origin="$(python3 "$ALLOCATION_RUNTIME" repository-ref --url "$origin_url" 2>/dev/null || true)" + else + canonical_origin="" + fi + if [[ -n "$canonical_origin" ]]; then + repository_ref="$(python3 - "$canonical_origin" <<'PY' +from urllib.parse import urlparse +import sys +value = urlparse(sys.argv[1]) +parts = value.path.strip('/').split('/') +if len(parts) == 2 and value.netloc and all(part not in ('', '.', '..') for part in parts): + print('/'.join(parts)) +PY +)" + else + repository_ref="" + fi + if [[ -z "${repository_ref:-}" ]]; then + repository_ref="local/$(python3 - "$PRIMARY_CHECKOUT" <<'PY' +import hashlib +from pathlib import Path +import sys +print(hashlib.sha256(str(Path(sys.argv[1]).resolve(strict=True)).encode('utf-8')).hexdigest()) +PY +)" || exit 5 + fi + layout_repository_name="$(basename "$PRIMARY_CHECKOUT")" + layout="$(python3 .governance/worktree_path_check.py plan --repository "$layout_repository_name" \ + --repository-name "$layout_repository_name" --ticket "$ticket_id" --slug "$WORKTREE_SLUG" \ + --from-worktree "$PRIMARY_CHECKOUT" --path-style posix)" + python3 .governance/worktree_path_check.py validate - --check-filesystem <<< "$layout" >/dev/null + mapfile -t layout_values < <(python3 -c 'import json,sys; v=json.load(sys.stdin); print(v["branch"]); print(v["worktreePath"]); print(v["leasePath"])' <<< "$layout") + WORKTREE_BRANCH="${layout_values[0]}" + WORKTREE_PATH="${layout_values[1]}" + LEASE_PATH="${layout_values[2]}" + git worktree add --relative-paths -b "$WORKTREE_BRANCH" "$WORKTREE_PATH" "$base_sha" + cd "$WORKTREE_PATH" +fi + if [[ -n "$LEASE_PATH" ]]; then # A lease is local operational state, deliberately ignored by Git. Its # identity and scope bind the new branch/worktree before any implementation # begins; O_EXCL means a stale or competing lease is never overwritten. python3 - "$ticket_dir/intent.json" "$LEASE_PATH" "$ticket_id" "$WORKSTREAM" \ "$WORKTREE_BRANCH" "$WORKTREE_SLUG" "$repository_ref" "$TARGET_BRANCH" \ - "$base_sha" "$AGENT" "$timestamp" <<'PY' + "$base_sha" "$WRITER_ACTOR" "$WRITER_SESSION" "$timestamp" <<'PY' from datetime import datetime, timedelta, timezone import hashlib import json @@ -939,7 +1262,7 @@ from pathlib import Path import sys (intent_path, lease_path, ticket, workstream, branch, slug, repository, - target_branch, head, agent, issued_at) = sys.argv[1:] + target_branch, head, actor, session, issued_at) = sys.argv[1:] intent_file = Path(intent_path) lease_file = Path(lease_path) if intent_file.is_symlink() or lease_file.exists() or lease_file.is_symlink(): @@ -964,8 +1287,8 @@ lease = { "scopeHash": hashlib.sha256(canonical(allowed)).hexdigest(), "branchRef": "refs/heads/" + branch, "worktreeId": f"{ticket}--{slug}", - "ownerActor": "agent:" + agent, - "ownerSession": f"allocation-{ticket}-{issued_at}", + "ownerActor": actor, + "ownerSession": session, "phase": "claimed", "leaseRevision": 1, "fencingToken": 1, @@ -980,16 +1303,32 @@ lease = { "previousReceiptRef": None, "eventSequence": 1, } -lease_file.parent.mkdir(parents=True, exist_ok=True) -for parent in (lease_file.parent, *lease_file.parent.parents): - if parent == Path(parent.anchor): - break - if parent.is_symlink(): - raise SystemExit("lease parent is symlinked") -payload = json.dumps(lease, indent=2, sort_keys=True).encode("utf-8") + b"\n" -descriptor = os.open(lease_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) -with os.fdopen(descriptor, "wb") as stream: - stream.write(payload) +# Bind every directory lookup to an already-open directory descriptor. A +# pathname check followed by pathname creation can follow a replaced ancestor. +if (not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY") + or os.open not in os.supports_dir_fd or os.mkdir not in os.supports_dir_fd): + raise SystemExit("race-resistant lease creation is unsupported on this host") +if not lease_file.is_absolute() or ".." in lease_file.parts: + raise SystemExit("lease path must be an absolute canonical path") +directory_flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW +parent_descriptor = os.open(lease_file.anchor, directory_flags) +try: + for component in lease_file.parts[1:-1]: + try: + os.mkdir(component, mode=0o700, dir_fd=parent_descriptor) + except FileExistsError: + pass + child_descriptor = os.open(component, directory_flags, dir_fd=parent_descriptor) + os.close(parent_descriptor) + parent_descriptor = child_descriptor + payload = json.dumps(lease, indent=2, sort_keys=True).encode("utf-8") + b"\n" + descriptor = os.open(lease_file.name, + os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, + 0o600, dir_fd=parent_descriptor) + with os.fdopen(descriptor, "wb") as stream: + stream.write(payload) +finally: + os.close(parent_descriptor) PY fi @@ -997,8 +1336,11 @@ if [[ -n "$USERS" ]]; then echo "warning: --users=$USERS did not create user-* files; human-owned input must come from a human or trusted intake boundary" >&2 fi -if [[ -f project/readme.sh ]]; then - bash ./project/readme.sh +# The older adopter's index generator may require a different carrier format. +# A plan allocates untracked metadata only; leave existing index bytes intact +# until the separately authorized material upgrade installs its pinned tool. +if [[ -z "$STANDARD_ADOPTION_PLAN" && -f project/readme.sh ]]; then + T2C_TICKET_INDEX_OWN="project/$ticket_id" bash ./project/readme.sh fi if [[ -n "$WORKTREE_PATH" ]]; then diff --git a/project/readme.sh b/project/readme.sh index e400747..f7ac993 100755 --- a/project/readme.sh +++ b/project/readme.sh @@ -17,6 +17,15 @@ if [[ "$index_file" == *".."* ]]; then exit 2 fi +# The allocator names the ticket it has just created in this checkout. That one +# untracked directory is indexed so the ticket's own PR carries exactly its own +# row, instead of the next ticket's PR adding it (issue #516). +own_ticket="${T2C_TICKET_INDEX_OWN:-}" +if [[ -n "$own_ticket" && ! "$own_ticket" =~ ^project/ticket-[0-9]+$ ]]; then + echo "Own ticket must be project/ticket-NNN: $own_ticket" >&2 + exit 2 +fi + mkdir -p project if [[ ! -f "$index_file" ]]; then if [[ -f template/files/project.template.md ]]; then @@ -35,17 +44,23 @@ EOF fi fi -start_count="$(grep -c '^$' "$index_file" || true)" -end_count="$(grep -c '^$' "$index_file" || true)" -if [[ "$start_count" -eq 0 && "$end_count" -eq 0 ]]; then +start_line="$(grep -n '^$' "$index_file" | cut -d: -f1 || true)" +end_line="$(grep -n '^$' "$index_file" | cut -d: -f1 || true)" +if [[ -z "$start_line" && -z "$end_line" ]]; then printf '\n\n\n' >> "$index_file" - start_count=1 - end_count=1 + start_line="$(grep -n '^$' "$index_file" | cut -d: -f1 || true)" + end_line="$(grep -n '^$' "$index_file" | cut -d: -f1 || true)" fi +start_count="$(echo -n "$start_line" | grep -c . || true)" +end_count="$(echo -n "$end_line" | grep -c . || true)" if [[ "$start_count" != 1 || "$end_count" != 1 ]]; then echo "$index_file must contain exactly one ticket-index marker pair" >&2 exit 2 fi +if [[ "$start_line" -ge "$end_line" ]]; then + echo "$index_file ticket-index markers must appear in order (START before END)" >&2 + exit 2 +fi table_file="$(mktemp "${TMPDIR:-/tmp}/new-project-ticket-table.XXXXXX")" index_dir="$(dirname "$index_file")" @@ -65,7 +80,7 @@ for dir in project/ticket-*; do # else's. Indexing it writes rows whose links resolve in no commit but that # author's working tree, so whoever regenerates the index next ships broken # links. An untracked ticket appears in the index once it is committed. - if git rev-parse --git-dir >/dev/null 2>&1 && [[ -z "$(git ls-files -- "$dir")" ]]; then + if [[ "$dir" != "$own_ticket" ]] && git rev-parse --git-dir >/dev/null 2>&1 && [[ -z "$(git ls-files -- "$dir")" ]]; then printf 'skipping untracked %s; commit it to have it indexed\n' "$dir" >&2 continue fi diff --git a/project/ticket-016/README.md b/project/ticket-016/README.md new file mode 100644 index 0000000..b1f4ba7 --- /dev/null +++ b/project/ticket-016/README.md @@ -0,0 +1,24 @@ +# Ticket 016: Adopt new-project 0.20.162 + +- **ID**: ticket-016 +- **Owner**: unresolved:human +- **Status**: IN_PROGRESS +- **Workflow state**: EDIT +- **Created**: 2026-11-19 + +## Goal and scope + +Fleet update to wellmanifest/new-project 0.20.162 (from 0.20.92). The release inventories every +managed `.governance/docs/**` copy for the docs checker, stops `baseline` demanding unprovable S3 levels, ignores +adoption tickets that already landed, and admits requested carrier-only follow-up commits. Standard records are +rebuilt from verifiable evidence in `audit` mode. + +## Acceptance criteria + +- [ ] AC-1: Goal reports the target up-to-date at 0.20.162. +- [ ] AC-2: `project/governance-check.sh` passes. + +## Tracking boundary + +This directory contains the minimal reviewed intent. Optional participant prose +and raw command logs are not required delivery output. diff --git a/project/ticket-016/intent.json b/project/ticket-016/intent.json new file mode 100644 index 0000000..25c3617 --- /dev/null +++ b/project/ticket-016/intent.json @@ -0,0 +1,247 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-016", + "summary": "Adopt new-project 0.20.162", + "workstream": "governance", + "classification": { + "kind": "BUG", + "priority": "P1", + "origin": "regression" + }, + "allowedPaths": [ + "project/ticket-016/**", + "TODO.md", + "project/TICKETS.md", + ".githooks/commit-msg", + ".githooks/pre-commit", + ".githooks/pre-push", + ".github/workflows/new-project-branch-hygiene.yml", + ".github/workflows/new-project-governance.yml", + ".governance/AGENT_DECISIONS.md", + ".governance/agent-hosts.json", + ".governance/agent-hosts.schema.json", + ".governance/agent_host_check.py", + ".governance/bootstrap_packaging_scope.py", + ".governance/branch_intent_reconciliation.py", + ".governance/branch_lifecycle_check.py", + ".governance/change-evaluation.schema.json", + ".governance/change-lease.schema.json", + ".governance/change_lease_check.py", + ".governance/check_required_checks.py", + ".governance/continuity_namespace.py", + ".governance/controller_store_compaction.py", + ".governance/decision_record.py", + ".governance/diagnostics.json", + ".governance/docs/information/continuity-namespaces.md", + ".governance/error/GOV-AGENT-HOST.md", + ".governance/error/GOV-ARCHITECTURE-001.md", + ".governance/error/GOV-CHANGE-LEASE.md", + ".governance/error/GOV-HOST-MERGE.md", + ".governance/error/GOV-IDLE-TAKEOVER.md", + ".governance/error/GOV-INTENT.md", + ".governance/error/GOV-PACKAGING.md", + ".governance/error/GOV-PHYS.md", + ".governance/error/GOV-PUSH.md", + ".governance/error/GOV-TICKET-ALLOCATION.md", + ".governance/error/GOV-VERSION.md", + ".governance/error/GOV-WORK-CONTINUITY.md", + ".governance/error/GOV-WORK-START.md", + ".governance/generate_required_checks.py", + ".governance/governance_check.py", + ".governance/idle_takeover.py", + ".governance/intent.schema.json", + ".governance/legacy_terminal_retirement.py", + ".governance/managed-copies.json", + ".governance/manifest.base.json", + ".governance/manifest.json", + ".governance/manifest.lock.json", + ".governance/manifest.schema.json", + ".governance/owner_handoff.py", + ".governance/package-manifest.json", + ".governance/policy-dsl.lock.json", + ".governance/policy_dsl_check.py", + ".governance/prune_merged_worktrees.py", + ".governance/remediation_intent.py", + ".governance/repository_policy.py", + ".governance/required-checks.schema.json", + ".governance/seed_baseline.py", + ".governance/snapshot_migration.py", + ".governance/standard-adoption-plan.schema.json", + ".governance/standard-adoption.json", + ".governance/standard-packs.json", + ".governance/standard-propagation-request.schema.json", + ".governance/standard_pack_check.py", + ".governance/terminal_lease_release.py", + ".governance/ticket-allocation-receipt.schema.json", + ".governance/ticket-allocation-request.schema.json", + ".governance/ticket-allocation.schema.json", + ".governance/ticket_activity.py", + ".governance/ticket_allocation.py", + ".governance/ticket_input.py", + ".governance/ticket_recovery.py", + ".governance/ticket_restoration.py", + ".governance/ticket_storage.py", + ".governance/work-start-report.schema.json", + ".governance/work_continuity.py", + ".governance/work_start_check.py", + ".governance/worktree_overlap_check.py", + ".governance/worktree_path_check.py", + ".governance/worktrees.lock.json", + ".governance/worktrees.schema.json", + "AGENTS.md", + "project/governance-check.bat", + "project/governance-check.sh", + "project/new-ticket.sh", + "project/readme.sh", + "pyproject.toml", + "scripts/install-agent-hosts.sh", + "wellmanifest_governance.py" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null, + "delivery": { + "acceptedBaseSha": "9743270358ba89528e66563b389c3096ec3289ff", + "targetBranch": "main", + "outcome": "Adopt wellmanifest/new-project 0.20.162 with the official Goal generator; standard records hold only verifiable evidence.", + "nonGoals": [ + "No manual editing of lock digests or managed copies.", + "No product code changes.", + "No unproven S4/S5 claims." + ], + "complexity": "L", + "estimatedMinutes": 60, + "standardAdoption": { + "sourceRepository": "wellmanifest/new-project", + "fromRevision": "fcbb13e0ae04c688d825d5a87e2d2721dfab483d", + "toRevision": "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0" + }, + "budgets": { + "maxImplementationFiles": 15, + "maxAffectedComponents": 5, + "maxPublicInterfaceChanges": 3, + "maxRuntimeDependencies": 3 + }, + "architecture": { + "status": "accepted", + "decision": "Goal generates the managed 0.20.162 set; target-owned standard records are rebuilt from verifiable evidence in audit mode.", + "components": [ + { + "name": "governance-adoption", + "paths": [ + ".githooks/commit-msg", + ".githooks/pre-commit", + ".githooks/pre-push", + ".github/workflows/new-project-branch-hygiene.yml", + ".github/workflows/new-project-governance.yml", + ".governance/AGENT_DECISIONS.md", + ".governance/agent-hosts.json", + ".governance/agent-hosts.schema.json", + ".governance/agent_host_check.py", + ".governance/bootstrap_packaging_scope.py", + ".governance/branch_intent_reconciliation.py", + ".governance/branch_lifecycle_check.py", + ".governance/change-evaluation.schema.json", + ".governance/change-lease.schema.json", + ".governance/change_lease_check.py", + ".governance/check_required_checks.py", + ".governance/continuity_namespace.py", + ".governance/controller_store_compaction.py", + ".governance/decision_record.py", + ".governance/diagnostics.json", + ".governance/docs/information/continuity-namespaces.md", + ".governance/error/GOV-AGENT-HOST.md", + ".governance/error/GOV-ARCHITECTURE-001.md", + ".governance/error/GOV-CHANGE-LEASE.md", + ".governance/error/GOV-HOST-MERGE.md", + ".governance/error/GOV-IDLE-TAKEOVER.md", + ".governance/error/GOV-INTENT.md", + ".governance/error/GOV-PACKAGING.md", + ".governance/error/GOV-PHYS.md", + ".governance/error/GOV-PUSH.md", + ".governance/error/GOV-TICKET-ALLOCATION.md", + ".governance/error/GOV-VERSION.md", + ".governance/error/GOV-WORK-CONTINUITY.md", + ".governance/error/GOV-WORK-START.md", + ".governance/generate_required_checks.py", + ".governance/governance_check.py", + ".governance/idle_takeover.py", + ".governance/intent.schema.json", + ".governance/legacy_terminal_retirement.py", + ".governance/managed-copies.json", + ".governance/manifest.base.json", + ".governance/manifest.json", + ".governance/manifest.lock.json", + ".governance/manifest.schema.json", + ".governance/owner_handoff.py", + ".governance/package-manifest.json", + ".governance/policy-dsl.lock.json", + ".governance/policy_dsl_check.py", + ".governance/prune_merged_worktrees.py", + ".governance/remediation_intent.py", + ".governance/repository_policy.py", + ".governance/required-checks.schema.json", + ".governance/seed_baseline.py", + ".governance/snapshot_migration.py", + ".governance/standard-adoption-plan.schema.json", + ".governance/standard-adoption.json", + ".governance/standard-packs.json", + ".governance/standard-propagation-request.schema.json", + ".governance/standard_pack_check.py", + ".governance/terminal_lease_release.py", + ".governance/ticket-allocation-receipt.schema.json", + ".governance/ticket-allocation-request.schema.json", + ".governance/ticket-allocation.schema.json", + ".governance/ticket_activity.py", + ".governance/ticket_allocation.py", + ".governance/ticket_input.py", + ".governance/ticket_recovery.py", + ".governance/ticket_restoration.py", + ".governance/ticket_storage.py", + ".governance/work-start-report.schema.json", + ".governance/work_continuity.py", + ".governance/work_start_check.py", + ".governance/worktree_overlap_check.py", + ".governance/worktree_path_check.py", + ".governance/worktrees.lock.json", + ".governance/worktrees.schema.json", + "AGENTS.md", + "pyproject.toml", + "scripts/install-agent-hosts.sh", + "wellmanifest_governance.py" + ] + } + ], + "responsibilityChanges": false, + "interfaceChanges": [], + "dataChanges": [], + "ui": { + "impact": "none", + "states": [], + "evidence": [] + }, + "rollback": "Restore accepted base 9743270358ba89528e66563b389c3096ec3289ff; no runtime data is migrated." + }, + "runtimeDependencies": [], + "validation": [ + { + "criterion": "AC-1", + "commands": [ + "goal governance adopt --target-root . --source-revision 8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0 --check" + ], + "evidence": "Goal reports the target up-to-date at 0.20.162." + }, + { + "criterion": "AC-2", + "commands": [ + "bash project/governance-check.sh" + ], + "evidence": "The governance gate passes." + } + ] + } +} diff --git a/pyproject.toml b/pyproject.toml index d3ffa14..95e7961 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -93,7 +93,7 @@ max_commits = 500 badge_color_thresholds = { low = 1.0, medium = 5.0, high = 10.0, critical = 50.0 } [tool.wellmanifest] -standard = "0.20.92" -revision = "fcbb13e0ae04c688d825d5a87e2d2721dfab483d" +standard = "0.20.162" +revision = "8e6b51dc91a2ac7e1e771908e0fac5e12da0b9a0" gate = "project/governance-check.sh" # release-target: 1.0.51 diff --git a/scripts/install-agent-hosts.sh b/scripts/install-agent-hosts.sh index f633309..d14dce8 100755 --- a/scripts/install-agent-hosts.sh +++ b/scripts/install-agent-hosts.sh @@ -60,90 +60,214 @@ if [[ -z "$TARGET" && "$USER_INSTALL" == false ]]; then fi fi -contract_path() { - local root="$1" - for candidate in "governance/agent-hosts.json" ".governance/agent-hosts.json"; do - if [[ -f "$root/$candidate" ]]; then - python3 - "$root/$candidate" <<'PY' || return 1 -import json, sys -contract = json.load(open(sys.argv[1], encoding="utf-8")) -hooks = contract.get("hook", {}).get("additionalHooks", []) -allowed = {".githooks/commit-msg", ".githooks/prepare-commit-msg"} -if (not isinstance(hooks, list) - or any(not isinstance(hook, str) or hook not in allowed for hook in hooks) - or len(hooks) != len(set(hooks))): - raise SystemExit("GOV-AGENT-HOST-004: invalid additional hook declaration") -PY - printf '%s\n' "$root/$candidate" - return 0 - fi - done - echo "Agent host contract not found under $root" >&2 - return 1 -} +# Validate the complete selected package before copying anything. The caller +# owns the target checkout exclusively; observed path changes fail closed. +bootstrap_host_files() { + python3 - "$1" "$2" "$3" "${4:-bootstrap}" <<'PY' +import json +import os +from pathlib import Path, PurePosixPath, PureWindowsPath +import stat +import sys +import tempfile -# Emits "\t" lines for every file the contract governs. -contract_targets() { - python3 - "$1" "$2" <<'PY' -import json, pathlib, sys -contract = json.load(open(sys.argv[1], encoding="utf-8")) -root = pathlib.Path(sys.argv[2]) -hub = root / "governance/manifest.hub.json" -source_paths = {} -if hub.is_file(): - package = json.loads((root / "governance/package-manifest.json").read_text()) - source_paths = {item["target"]: item["source"] for item in package["files"]} -for host in contract["hosts"]: - print(f"{host['file']}\t0") -print(f"{contract['hook']['path']}\t1") -for hook in contract["hook"].get("additionalHooks", []): - print(f"{hook}\t1") -for runtime_file in contract["hook"]["runtimeFiles"]: - # The hub owns package sources; adopters own the managed target paths. - relative = source_paths.get(runtime_file, runtime_file) - print(f"{relative}\t0") -PY -} -hooks_path_config() { - python3 - "$1" <<'PY' -import json, sys -print(json.load(open(sys.argv[1], encoding="utf-8"))["hook"]["hooksPathConfig"]) -PY -} +def fail(message): + raise SystemExit("GOV-AGENT-HOST-004: " + message) + + +def alias(metadata): + return stat.S_ISLNK(metadata.st_mode) or bool(getattr(metadata, 'st_file_attributes', 0) & 0x400) + + +def relative(value): + if (not isinstance(value, str) or not value or '\\' in value or ':' in value + or any(ord(char) < 32 or ord(char) == 127 for char in value)): + fail('invalid host package path') + path = PurePosixPath(value) + if (path.is_absolute() or PureWindowsPath(value).drive or path.as_posix() != value + or any(part in {'', '.', '..'} or part.casefold() == '.git' + or part.endswith(('.', ' ')) for part in value.split('/'))): + fail('host package paths must be canonical and repository-relative') + return path.parts + + +def directory_root(value): + path = Path(value).absolute() + for item in (path, *path.parents): + metadata = item.lstat() + if alias(metadata) or not stat.S_ISDIR(metadata.st_mode): + fail('bootstrap roots must be regular directories without aliases') + return path.resolve() + + +def checked(root, name, *, required=False, directory=False): + parts = relative(name) + path = root + for index, part in enumerate(parts): + path /= part + try: + metadata = path.lstat() + except FileNotFoundError: + if required: + fail('a required host package file is missing') + continue + if alias(metadata): + fail('symlink or reparse point in host package path') + expect_directory = index < len(parts) - 1 or directory + if not (stat.S_ISDIR(metadata.st_mode) if expect_directory else stat.S_ISREG(metadata.st_mode)): + fail('unsupported host package filesystem entry') + return path + + +def identity(metadata): + return metadata.st_dev, metadata.st_ino, metadata.st_mode, metadata.st_size, metadata.st_mtime_ns -# Emits "\t\t" for every file the host contract -# needs in a target checkout: the instruction files, the hook, and the contract -# itself, because activate_in_place reads the contract from the target. -package_host_files() { - python3 - "$1" "$2" "$3" <<'PY' -import json, sys -manifest = json.load(open(sys.argv[1], encoding="utf-8")) -contract = json.load(open(sys.argv[2], encoding="utf-8")) -contract_source = sys.argv[3] -governed = ( - {host["file"] for host in contract["hosts"]} - | {contract["hook"]["path"]} - | set(contract["hook"].get("additionalHooks", [])) - | set(contract["hook"]["runtimeFiles"]) -) -selected = [item for item in manifest["files"] - if item["target"] in governed or item["source"] == contract_source] -missing = governed - {item["target"] for item in selected} -if missing or not any(item["source"] == contract_source for item in selected): - raise SystemExit("Incomplete host package mapping") -for item in selected: - print(f"{item['source']}\t{item['target']}\t{int(bool(item['executable']))}") + +def source_bytes(root, name): + path = checked(root, name, required=True) + before = path.lstat() + flags = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_NONBLOCK', 0) | getattr(os, 'O_BINARY', 0) + descriptor = os.open(path, flags) + with os.fdopen(descriptor, 'rb') as stream: + opened = os.fstat(stream.fileno()) + if alias(opened) or not stat.S_ISREG(opened.st_mode) or identity(opened) != identity(before): + fail('host package source changed before reading') + data = stream.read() + after = os.fstat(stream.fileno()) + observed = checked(root, name, required=True).lstat() + if identity(before) != identity(after) or identity(before) != identity(observed): + fail('host package source changed while reading') + return data + + +def unique_object(pairs): + result = {} + for key, value in pairs: + if key in result: + fail('duplicate host package JSON key') + result[key] = value + return result + + +def document(data): + value = json.loads(data.decode('utf-8'), object_pairs_hook=unique_object) + if not isinstance(value, dict): + fail('host package metadata must be an object') + return value + + +try: + source, target = directory_root(sys.argv[1]), directory_root(sys.argv[2]) + contract_names = ('governance/agent-hosts.json', '.governance/agent-hosts.json') + contract_source = next((name for name in contract_names if (source / name).exists() or (source / name).is_symlink()), None) + if contract_source is None: + fail('source host contract is missing') + frozen = {contract_source: source_bytes(source, contract_source)} + contract = document(frozen[contract_source]) + hook = contract['hook'] + if not isinstance(hook, dict): + fail('host hook declaration must be an object') + hosts = [host['file'] for host in contract['hosts']] + additional = hook.get('additionalHooks', []) + allowed = {'.githooks/commit-msg', '.githooks/prepare-commit-msg', '.githooks/pre-push'} + if not isinstance(additional, list) or len(set(additional)) != len(additional) or any(name not in allowed for name in additional): + fail('invalid additional hook declaration') + runtime = hook['runtimeFiles'] + if not isinstance(runtime, list): + fail('host runtime files must be an array') + governed = set(hosts + [hook['path']] + additional + runtime) + for name in governed: + relative(name) + relative(hook['hooksPathConfig']) + if PurePosixPath(hook['path']).parent.as_posix() != hook['hooksPathConfig']: + fail('hook path and hooksPathConfig disagree') + if len(sys.argv) > 4 and sys.argv[4] == 'in-place': + source_paths = {} + if (source / 'governance/manifest.hub.json').is_file(): + package = document(source_bytes(source, 'governance/package-manifest.json')) + if not isinstance(package['files'], list): + fail('host package mappings must be an array') + for item in package['files']: + relative(item['target']) + relative(item['source']) + source_paths[item['target']] = item['source'] + activation = [(name, False) for name in hosts] + activation += [(hook['path'], True), *((name, True) for name in additional)] + activation += [(source_paths.get(name, name), False) for name in runtime] + checked(target, hook['hooksPathConfig'], required=True, directory=True) + for name, _ in activation: + checked(target, name, required=True) + # Return only this validated snapshot; activation never re-reads the contract. + print(hook['hooksPathConfig']) + for name, executable in activation: + print(name + '\t' + ('1' if executable else '0')) + raise SystemExit(0) + frozen['governance/package-manifest.json'] = source_bytes(source, 'governance/package-manifest.json') + manifest = document(frozen['governance/package-manifest.json']) + selected, targets, plan, contracts = [], set(), [], [] + if not isinstance(manifest['files'], list): + fail('host package mappings must be an array') + for item in manifest['files']: + if not isinstance(item, dict): + fail('host package mappings must be objects') + if item['target'] in governed or item['source'] == contract_source: + relative(item['source']) + relative(item['target']) + folded = item['target'].casefold() + if folded in targets or not isinstance(item['executable'], bool): + fail('duplicate target or invalid executable flag') + targets.add(folded) + checked(target, item['target']) + if item['source'] not in frozen: + frozen[item['source']] = source_bytes(source, item['source']) + data = frozen[item['source']] + plan.append((item['target'], data, item['executable'])) + selected.append(item['target']) + if item['source'] == contract_source: + contracts.append(item['target']) + if governed - set(selected) or len(contracts) != 1 or contracts[0] not in contract_names: + fail('incomplete or ambiguous host package mapping') + # Activation prefers governance/ over .governance/. Preserve an unrelated + # existing contract rather than copying files and activating another one. + for name in contract_names: + if name in selected: + break + if (target / name).exists() or (target / name).is_symlink(): + if document(source_bytes(target, name)) != contract: + fail('existing target host contract differs from the selected package') + break + if sys.argv[3] != 'true': + for name, data, executable in plan: + parts = relative(name) + for index in range(1, len(parts)): + parent_name = '/'.join(parts[:index]) + parent = checked(target, parent_name, directory=True) + parent.mkdir(exist_ok=True) + checked(target, parent_name, required=True, directory=True) + destination = checked(target, name) + descriptor, temporary = tempfile.mkstemp(prefix='.host-bootstrap.', dir=destination.parent) + try: + with os.fdopen(descriptor, 'wb') as stream: + stream.write(data) + os.chmod(temporary, 0o755 if executable else 0o644) + checked(target, name) + os.replace(temporary, destination) + finally: + if os.path.exists(temporary): + os.unlink(temporary) +except (OSError, ValueError, TypeError, KeyError): + fail('host package is invalid, unreadable or changed during bootstrap') PY } activate_in_place() { local dest="$1" dest="$(cd "$dest" && pwd)" - local contract hooks targets - contract="$(contract_path "$dest")" || return 1 - hooks="$(hooks_path_config "$contract")" || return 1 - targets="$(contract_targets "$contract" "$dest")" || return 1 + local activation hooks targets + activation="$(bootstrap_host_files "$dest" "$dest" true in-place)" || return 1 + hooks="${activation%%$'\n'*}" + targets="${activation#*$'\n'}" local missing=() while IFS=$'\t' read -r target is_hook; do @@ -185,14 +309,16 @@ activate_in_place() { local driver_path="" for candidate in ".governance/ticket_index_merge_driver.py" "scripts/ticket_index_merge_driver.py"; do - if [[ -f "$dest/$candidate" ]]; then + if [[ -f "$dest/$candidate" && ! -L "$dest/$candidate" ]]; then driver_path="$candidate" break fi done if [[ -n "$driver_path" ]]; then - git -C "$dest" config merge.wellmanifest-ticket-index.name "Wellmanifest Ticket Index Merge Driver" || true - git -C "$dest" config merge.wellmanifest-ticket-index.driver "python3 $driver_path %O %A %B %P" || true + for driver_key in "wellmanifest-ticket-index" "ticket-index"; do + git -C "$dest" config "merge.${driver_key}.name" "Wellmanifest Ticket Index Merge Driver" || return 1 + git -C "$dest" config "merge.${driver_key}.driver" "python3 $driver_path %O %A %B" || return 1 + done fi echo "Activated host contract and core.hooksPath=$hooks in $dest" @@ -205,34 +331,7 @@ bootstrap_into() { echo "Target is not a git work tree: $dest" >&2 exit 1 fi - local contract files - contract="$(contract_path "$SOURCE")" || return 1 - local manifest="$SOURCE/governance/package-manifest.json" - if [[ ! -f "$manifest" ]]; then - echo "Source has no governance/package-manifest.json: $SOURCE" >&2 - exit 1 - fi - - files="$(package_host_files "$manifest" "$contract" "${contract#"$SOURCE/"}")" || return 1 - # Validate the entire input before the first destination write. - while IFS=$'\t' read -r source target executable; do - if [[ ! -f "$SOURCE/$source" ]]; then - echo "Source file missing: $SOURCE/$source" >&2 - return 1 - fi - done <<< "$files" - if [[ "$CHECK_ONLY" == true ]]; then - activate_in_place "$dest" - return $? - fi - while IFS=$'\t' read -r source target executable; do - mkdir -p "$dest/$(dirname "$target")" || return 1 - cp -f "$SOURCE/$source" "$dest/$target" || return 1 - if [[ "$executable" == "1" ]]; then - chmod +x "$dest/$target" || return 1 - fi - done <<< "$files" - + bootstrap_host_files "$SOURCE" "$dest" "$CHECK_ONLY" || return 1 activate_in_place "$dest" } @@ -268,6 +367,13 @@ paragraph = [ "Allocate tickets only through that script. Never commit on main or a dirty", "primary checkout. Run `./scripts/install-agent-hosts.sh` once per clone so", "the git hook is active.", + "Put every final result in the owning repository through its ticket:", + "reports and analyses under `docs/` per `wellmanifest/docs` (`check.py --prepare`", + "before writing, `--deliverable` after commit), error runbooks under `errors/`", + "per `wellmanifest/logs`. Never leave a final result only in /tmp, a scratchpad,", + "`$HOME/.local/state` or the chat. Before claiming done run", + "`./project/governance-check.sh` and the Wellman standards check (`wellman check`);", + "a required standard that is not installed is an error to fix, not to skip.", ] text = path.read_text(encoding="utf-8") if path.exists() else "" lines = text.splitlines() diff --git a/wellmanifest_governance.py b/wellmanifest_governance.py index b398385..f14bc20 100644 --- a/wellmanifest_governance.py +++ b/wellmanifest_governance.py @@ -136,9 +136,9 @@ def pytest_sessionstart(session: object) -> None: root = Path(str(rootpath)).resolve() gate_sh = root / "project" / "governance-check.sh" gate_bat = root / "project" / "governance-check.bat" - if not gate_sh.is_file() and not gate_bat.is_file(): + if not gate_sh.is_file() and not (sys.platform.startswith("win") and gate_bat.is_file()): raise GovernanceGateError( - "GOV-PACKAGING-003: managed governance gate is missing" + "GOV-PACKAGING-003: managed governance gate for this platform is missing" ) if os.environ.get("WELLMANIFEST_GOVERNANCE_ACTIVE") == "1": raise GovernanceGateError("GOV-PACKAGING-003: recursive gate invocation")