@pennixrv/trellis 0.6.27 → 0.6.29

package/dist/templates/trellis/scripts/subnode_artifact.py

@@ -3,7 +3,7 @@
 
 The coordinator creates an immutable brief before dispatching a subnode. The
 subnode appends its worklog and writes its own final report. This helper never
-dispatches workers, decides acceptance, or mutates task state.
+dispatches workers, makes the acceptance judgment, or mutates task state.
 """
 
 from __future__ import annotations
@@ -12,6 +12,7 @@ import argparse
 import json
 import re
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, NoReturn
 
@@ -30,6 +31,13 @@ SECRET_PATTERNS = (
     re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),
     re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),
 )
+TERMINAL_LIFECYCLES = {"done", "error", "killed", "crashed"}
+DISPOSITION_OUTCOMES = {"accepted", "rejected", "deferred"}
+REQUIRED_DISPOSITION_CHECKS = {
+    "report_validation",
+    "source_recheck",
+    "protected_target_check",
+}
 
 
 class ArtifactError(Exception):
@@ -232,6 +240,8 @@ def _validate_brief_data(
     _require_text_list(brief.get("stop_conditions"), "brief.stop_conditions")
     _require_text(brief.get("deadline"), "brief.deadline", max_len=128)
     _validate_channel_ref(brief.get("channel_ref"))
+    if brief["channel_ref"]["worker_handle"] != subnode_id:
+        _fail("channel_ref.worker_handle must match brief.subnode_id")
     _validate_retry_target(
         brief.get("retry_of"),
         task_dir,
@@ -362,6 +372,41 @@ def _validate_report_file(
     return report, evidence, brief, node_dir
 
 
+def _validate_disposition_data(
+    disposition: dict[str, Any],
+    report: dict[str, Any],
+    brief: dict[str, Any],
+) -> None:
+    if disposition.get("schema_version") != SCHEMA_VERSION:
+        _fail(f"disposition.schema_version must be {SCHEMA_VERSION}")
+    for field in ("task_id", "work_id", "subnode_id", "role_id"):
+        if disposition.get(field) != brief.get(field):
+            _fail(f"disposition.{field} does not match brief.{field}")
+    if disposition.get("report_path") != brief.get("report_path"):
+        _fail("disposition.report_path does not match brief.report_path")
+    if disposition.get("report_status") != report.get("status"):
+        _fail("disposition.report_status does not match report.status")
+    if disposition.get("outcome") not in DISPOSITION_OUTCOMES:
+        _fail("disposition.outcome must be accepted, rejected, or deferred")
+    terminal = disposition.get("terminal")
+    if not isinstance(terminal, dict):
+        _fail("disposition.terminal must be an object")
+    if terminal.get("lifecycle") not in TERMINAL_LIFECYCLES:
+        _fail("disposition.terminal.lifecycle must be done, error, killed, or crashed")
+    sequence = terminal.get("seq")
+    if isinstance(sequence, bool) or not isinstance(sequence, int) or sequence < 1:
+        _fail("disposition.terminal.seq must be a positive integer")
+    _require_text(terminal.get("observed_at"), "disposition.terminal.observed_at", max_len=128)
+    checks = _require_text_list(disposition.get("checks"), "disposition.checks")
+    if len(checks) != len(set(checks)):
+        _fail("disposition.checks must not contain duplicates")
+    missing = REQUIRED_DISPOSITION_CHECKS.difference(checks)
+    if missing:
+        _fail("disposition.checks is missing: " + ", ".join(sorted(missing)))
+    _require_text(disposition.get("reason"), "disposition.reason")
+    _require_text(disposition.get("decided_at"), "disposition.decided_at", max_len=128)
+
+
 def _init(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
     task_dir = resolve_task_dir(args.task, repo_root)
@@ -425,6 +470,42 @@ def _validate(args: argparse.Namespace) -> None:
     print(f"Validated pending-review report: {report['subnode_id']}")
 
 
+def _disposition(args: argparse.Namespace) -> None:
+    repo_root = get_repo_root()
+    report, _evidence, brief, node_dir = _validate_report_file(args.report, repo_root)
+    disposition_path = node_dir / "disposition.json"
+    if disposition_path.exists() or disposition_path.is_symlink():
+        _fail(f"disposition already exists and cannot be replaced: {disposition_path}")
+    disposition = {
+        "schema_version": SCHEMA_VERSION,
+        "task_id": brief["task_id"],
+        "work_id": brief["work_id"],
+        "subnode_id": brief["subnode_id"],
+        "role_id": brief["role_id"],
+        "report_path": brief["report_path"],
+        "report_status": report["status"],
+        "outcome": args.outcome,
+        "terminal": {
+            "lifecycle": args.terminal_lifecycle,
+            "seq": args.terminal_seq,
+            "observed_at": args.terminal_at,
+        },
+        "checks": args.check,
+        "reason": args.reason,
+        "decided_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _validate_disposition_data(disposition, report, brief)
+    try:
+        with disposition_path.open("x", encoding="utf-8") as stream:
+            json.dump(disposition, stream, indent=2, ensure_ascii=False)
+            stream.write("\n")
+    except FileExistsError:
+        _fail(f"disposition already exists and cannot be replaced: {disposition_path}")
+    except OSError as exc:
+        _fail(f"could not write disposition {disposition_path}: {exc}")
+    print(f"Recorded coordinator disposition: {brief['subnode_id']} -> {args.outcome}")
+
+
 def _validate_counter(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
     primary_dir = Path(args.primary)
@@ -474,6 +555,24 @@ def _parser() -> argparse.ArgumentParser:
     validate.add_argument("--report", required=True)
     validate.set_defaults(handler=_validate)
 
+    disposition = subparsers.add_parser(
+        "disposition",
+        help="record one coordinator disposition for a validated report",
+    )
+    disposition.add_argument("--report", required=True)
+    disposition.add_argument("--outcome", choices=sorted(DISPOSITION_OUTCOMES), required=True)
+    disposition.add_argument("--terminal-lifecycle", choices=sorted(TERMINAL_LIFECYCLES), required=True)
+    disposition.add_argument("--terminal-seq", type=int, required=True)
+    disposition.add_argument("--terminal-at", required=True)
+    disposition.add_argument(
+        "--check",
+        action="append",
+        required=True,
+        help="independent check name (repeat; requires report_validation, source_recheck, and protected_target_check)",
+    )
+    disposition.add_argument("--reason", required=True)
+    disposition.set_defaults(handler=_disposition)
+
     counter = subparsers.add_parser(
         "validate-counter",
         help="validate two completed, independent subnode directories",

package/dist/templates/trellis/scripts/task.py

@@ -10,6 +10,7 @@ Usage:
     python3 task.py list-context <dir>          # List jsonl entries
     python3 task.py start <dir>                 # Set active task, record current branch
     python3 task.py current [--source] [--json] # Show active task
+    python3 task.py ownership <operation> ...   # Manage formal handoff task ownership
     python3 task.py finish                      # Clear active task
     python3 task.py set-branch <dir> <branch>   # Set git branch
     python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
@@ -81,6 +82,17 @@ from common.continuation_record import (
     seal as seal_continuity,
     status as continuity_status,
 )
+from common.ownership_record import (
+    OwnershipError,
+    archive as archive_ownership,
+    assert_task_mutation_allowed,
+    claim as claim_ownership,
+    consume as consume_ownership,
+    quiesce as quiesce_ownership,
+    retire as retire_ownership,
+    seal as seal_ownership,
+    status as ownership_status,
+)
 
 
 # =============================================================================
@@ -198,6 +210,12 @@ def cmd_start(args: argparse.Namespace) -> int:
         print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.trellis/tasks/01-31-my-task')")
         return 1
 
+    try:
+        assert_task_mutation_allowed(repo_root, full_path)
+    except (OwnershipError, OSError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 2
+
     # Context-manifest gate (#573): a seeded-but-uncurated implement/check
     # manifest means every sub-agent dispatched for this task runs with zero
     # spec context, and nothing downstream surfaces that to the main session.
@@ -282,15 +300,22 @@ def cmd_start(args: argparse.Namespace) -> int:
 def cmd_finish(args: argparse.Namespace) -> int:
     """Clear active task."""
     repo_root = get_repo_root()
-    active = clear_active_task(repo_root)
+    active = resolve_active_task(repo_root)
     current = active.task_path
 
     if not current:
         print(colored("No current task set", Colors.YELLOW))
         return 0
 
+    try:
+        assert_task_mutation_allowed(repo_root, repo_root / current)
+    except (OwnershipError, OSError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 2
+
     # Resolve task.json path before clearing
     task_json_path = repo_root / current / FILE_TASK_JSON
+    clear_active_task(repo_root)
 
     print(colored(f"✓ Cleared current task (was: {current})", Colors.GREEN))
     print(f"Source: {active.source}")
@@ -382,6 +407,54 @@ def cmd_continuity(args: argparse.Namespace) -> int:
         return 2
 
 
+def cmd_ownership(args: argparse.Namespace) -> int:
+    """Manage the task-bound formal handoff ownership record."""
+    repo_root = get_repo_root()
+    if args.ownership_command == "status":
+        try:
+            result = ownership_status(repo_root, args.task_id, args.handoff_id, args.core_digest)
+        except (OwnershipError, OSError) as exc:
+            print(json.dumps({"status": "withheld", "reason": str(exc)}, ensure_ascii=False, sort_keys=True))
+            return 2
+        print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+        return 0
+    if not getattr(args, "explicit_user_request", False):
+        print(colored("Error: ownership writes require --explicit-user-request", Colors.RED), file=sys.stderr)
+        return 2
+    try:
+        command = args.ownership_command
+        if command == "quiesce":
+            result = quiesce_ownership(
+                repo_root, args.task, args.handoff_id, args.core_digest, args.source_session_id
+            )
+        elif command == "seal":
+            result = seal_ownership(
+                repo_root, args.task_id, args.handoff_id, args.core_digest, args.expected_generation
+            )
+        elif command == "retire":
+            result = retire_ownership(
+                repo_root, args.task_id, args.handoff_id, args.core_digest,
+                args.expected_generation, args.archive_observation,
+            )
+        elif command == "claim":
+            result = claim_ownership(
+                repo_root, args.task_id, args.task, args.handoff_id, args.core_digest, args.expected_generation
+            )
+        elif command == "consume":
+            result = consume_ownership(
+                repo_root, args.task_id, args.handoff_id, args.core_digest, args.expected_generation
+            )
+        else:
+            result = archive_ownership(
+                repo_root, args.task_id, args.handoff_id, args.core_digest, args.expected_generation
+            )
+        print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+        return 0
+    except (OwnershipError, OSError) as exc:
+        print(json.dumps({"status": "withheld", "reason": str(exc)}, ensure_ascii=False, sort_keys=True))
+        return 2
+
+
 # =============================================================================
 # Command: list
 # =============================================================================
@@ -743,6 +816,45 @@ def main() -> int:
     continuity_clear.add_argument("--expected", required=True, help="The current record digest or absent")
     continuity_clear.add_argument("--explicit-user-request", action="store_true", help="Required write confirmation")
 
+    # ownership
+    p_ownership = subparsers.add_parser("ownership", help="Manage formal handoff task ownership")
+    ownership_sub = p_ownership.add_subparsers(dest="ownership_command", required=True)
+
+    def add_ownership_common(parser, *, expected=False):
+        parser.add_argument("--task-id", required=True, help="Task id bound to the handoff")
+        parser.add_argument("--handoff-id", required=True, help="Immutable handoff id")
+        parser.add_argument("--core-digest", required=True, help="Immutable handoff core digest")
+        if expected:
+            parser.add_argument("--expected-generation", required=True, type=int)
+        parser.add_argument("--explicit-user-request", action="store_true", help="Required write confirmation")
+
+    ownership_quiesce = ownership_sub.add_parser("quiesce", help="Begin source handoff quiescence")
+    ownership_quiesce.add_argument("--task", required=True, help="Current task path")
+    ownership_quiesce.add_argument("--source-session-id", required=True)
+    add_ownership_common(ownership_quiesce)
+
+    ownership_seal = ownership_sub.add_parser("seal", help="Seal the source ownership boundary")
+    add_ownership_common(ownership_seal, expected=True)
+
+    ownership_retire = ownership_sub.add_parser("retire", help="Retire source and expose handoff")
+    ownership_retire.add_argument("--archive-observation", required=True, choices=("not_required", "observed"))
+    add_ownership_common(ownership_retire, expected=True)
+
+    ownership_claim = ownership_sub.add_parser("claim", help="Claim a ready handoff as this session")
+    ownership_claim.add_argument("--task", required=True, help="Task path to bind to this session")
+    add_ownership_common(ownership_claim, expected=True)
+
+    ownership_consume = ownership_sub.add_parser("consume", help="Record target consumption")
+    add_ownership_common(ownership_consume, expected=True)
+
+    ownership_archive = ownership_sub.add_parser("archive", help="Record post-consume retention archive")
+    add_ownership_common(ownership_archive, expected=True)
+
+    ownership_status_parser = ownership_sub.add_parser("status", help="Show ownership status")
+    add_ownership_common(ownership_status_parser)
+    ownership_status_parser.add_argument("--json", action="store_true", help="Output machine-readable JSON")
+    ownership_status_parser.set_defaults(explicit_user_request=True)
+
     # finish
     subparsers.add_parser("finish", help="Clear active task")
 
@@ -824,6 +936,7 @@ def main() -> int:
         "start": cmd_start,
         "current": cmd_current,
         "continuity": cmd_continuity,
+        "ownership": cmd_ownership,
         "finish": cmd_finish,
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennixrv/trellis",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "inquirer": "^9.3.7",
     "undici": "^6.21.0",
     "zod": "^4.4.2",
-    "@pennixrv/trellis-core": "0.6.27"
+    "@pennixrv/trellis-core": "0.6.29"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",