@pennixrv/trellis 0.7.0-beta.32 → 0.7.0-beta.34

package/dist/templates/trellis/scripts/common/task_store.py

@@ -294,6 +294,12 @@ def _parse_meta_pairs(pairs: list[str] | None) -> dict[str, str] | None:
                 file=sys.stderr,
             )
             return None
+        try:
+            from .task_planning import validate_meta_value
+            validate_meta_value(key, value)
+        except ValueError as exc:
+            print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+            return None
         meta[key] = value
     return meta
 
@@ -662,7 +668,7 @@ def cmd_create(args: argparse.Namespace) -> int:
     if getattr(args, "no_start", False):
         print(
             colored(
-                "Skipped session activation (--no-start); run task.py start when ready.",
+                "Skipped session activation (--no-start); run task.py select to plan, start only when authorized.",
                 Colors.YELLOW,
             ),
             file=sys.stderr,
@@ -1934,6 +1940,12 @@ def cmd_set_meta(args: argparse.Namespace) -> int:
         return 1
     key = args.key
     value = args.value
+    from .task_planning import invalidate_plan, validate_meta_value
+    try:
+        validate_meta_value(key, value)
+    except ValueError as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 1
 
     if not key:
         print(colored("Error: Missing arguments", Colors.RED))
@@ -1959,6 +1971,13 @@ def cmd_set_meta(args: argparse.Namespace) -> int:
     meta = data.get("meta")
     if not isinstance(meta, dict):
         meta = {}
+    if key in {"execution_class", "delivery_mode"} and meta.get(key) != value and "planning" in meta:
+        try:
+            invalidate_plan(data)
+        except ValueError as exc:
+            print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+            return 1
+        meta = data["meta"]
     meta[key] = value
     data["meta"] = meta
     if not write_json(task_json, data):

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

@@ -632,6 +632,29 @@ def _validate_disposition_data(
     _require_text(disposition.get("decided_at"), "disposition.decided_at", max_len=128)
 
 
+def _validate_unit_plan(brief: dict[str, Any], task_dir: Path, repo_root: Path) -> None:
+    """New dispatch admission only; historical report readers remain compatible."""
+    plan = brief.get("unit_plan")
+    if not isinstance(plan, dict):
+        _fail("new evidence unit requires unit_plan")
+    reference = _require_text(plan.get("plan_ref"), "unit_plan.plan_ref", max_len=1024)
+    locator = reference.partition("#")[0]
+    relative = Path(locator)
+    if relative.is_absolute() or ".." in relative.parts or "\\" in locator:
+        _fail("unit_plan.plan_ref must be a repository-relative task document")
+    document = repo_root / relative
+    lexical_task = _task_lexical_from_resolved(task_dir, repo_root)
+    _assert_no_subpath_symlinks(lexical_task, document)
+    if not document.is_file() or document.suffix != ".md":
+        _fail("unit_plan.plan_ref must identify a regular document in this task")
+    if document.stat().st_size > MAX_REPORT_BYTES:
+        _fail("unit_plan.plan_ref document exceeds the byte limit")
+    _require_text(document.read_text(encoding="utf-8"), "unit_plan.plan_ref document", max_len=MAX_REPORT_BYTES)
+    _require_text(plan.get("sizing_rationale"), "unit_plan.sizing_rationale")
+    if len(brief["scope"]) > 1:
+        _require_text(plan.get("grouping_rationale"), "unit_plan.grouping_rationale")
+
+
 def _init(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
     task_dir = resolve_task_dir(args.task, repo_root)
@@ -659,6 +682,7 @@ def _init(args: argparse.Namespace) -> None:
     brief["role_id"] = "subnode"
     brief["report_path"] = _relative_to_repo(node_dir / "report.json", repo_root)
     _validate_brief_data(brief, task_dir, node_dir, repo_root)
+    _validate_unit_plan(brief, task_dir, repo_root)
     for directory in (task_dir / "subnodes", task_dir / "subnodes" / work_id, node_dir):
         if directory.is_symlink():
             _fail(f"refusing symlinked artifact directory: {directory}")
@@ -709,6 +733,7 @@ def _queue_init(args: argparse.Namespace) -> None:
         subnode_id = _require_id(brief.get("subnode_id"), "brief.subnode_id")
         if brief_task_dir != task_dir:
             _fail(f"queue item {subnode_id} brief belongs to another task")
+        _validate_unit_plan(brief, task_dir, repo_root)
         if brief.get("work_id") != work_id:
             _fail(f"queue item {subnode_id} brief belongs to another work")
         if subnode_id in seen:
@@ -764,6 +789,13 @@ def _queue_claim(args: argparse.Namespace) -> None:
     item = next((candidate for candidate in items if candidate["subnode_id"] == subnode_id), None)
     if item is None:
         _fail(f"subnode is not listed in the queue: {subnode_id}")
+    for previous in items:
+        if previous is item:
+            break
+        previous_claim = task_dir / "subnodes" / args.work_id / previous["subnode_id"] / "dispatch-claim.json"
+        _assert_no_subpath_symlinks(task_dir, previous_claim)
+        if not previous_claim.is_file():
+            _fail(f"FIFO requires claiming earlier unit first: {previous['subnode_id']}")
     claim_path = task_dir / "subnodes" / args.work_id / subnode_id / "dispatch-claim.json"
     _assert_no_subpath_symlinks(task_dir, claim_path)
     claim = {

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

@@ -8,7 +8,10 @@ Usage:
     python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
     python3 task.py validate <dir>              # Validate jsonl files
     python3 task.py list-context <dir>          # List jsonl entries
-    python3 task.py start <dir>                 # Set active task, record current branch
+    python3 task.py select <dir>                # Select an existing task without starting it
+    python3 task.py plan seal <dir>             # Seal the current material plan
+    python3 task.py plan approve <dir> --revision N --basis "approval"
+    python3 task.py start <dir>                 # Start an approved task, record current branch
     python3 task.py replan <dir> "<reason>"     # Return an in-progress task to planning
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py ownership <operation> ...   # Manage formal handoff task ownership
@@ -59,7 +62,10 @@ from common.io import (
     read_json_checked,
     write_json,
 )
-from common.task_utils import resolve_task_dir, run_task_hooks
+from common.task_utils import is_within_tasks_dir, resolve_task_dir, run_task_hooks
+from common.task_planning import (
+    PlanningError, approve_plan, invalidate_plan, require_start_approval, seal_plan,
+)
 from common.tasks import iter_active_tasks, children_progress
 from common.workflow_selection import WORKFLOW_ID_RE, workflow_md_for_task
 
@@ -194,6 +200,58 @@ def _record_start_state(
         )
 
 
+def _active_task_target(task_input: str, repo_root: Path) -> tuple[Path, dict]:
+    """Resolve a live task and enforce the native mutation boundary."""
+    target = resolve_task_dir(task_input, repo_root)
+    if target is None or not is_within_tasks_dir(target, repo_root):
+        raise PlanningError("target must be a direct active task directory")
+    task_json = target / FILE_TASK_JSON
+    if task_json.is_symlink():
+        raise PlanningError("refusing symlinked task.json")
+    data, reason = read_json_checked(task_json)
+    if data is None:
+        raise PlanningError(describe_json_read_failure(task_json, reason)[0])
+    if data.get("status") not in {"planning", "in_progress"}:
+        raise PlanningError("target task must be planning or in_progress")
+    assert_task_mutation_allowed(repo_root, target)
+    return target, data
+
+
+def cmd_select(args: argparse.Namespace) -> int:
+    """Bind context only; Channel drain is owned by the coordinator procedure."""
+    repo_root = get_repo_root()
+    try:
+        target, _data = _active_task_target(args.dir, repo_root)
+        active = set_active_task(target.relative_to(repo_root.resolve()).as_posix(), repo_root)
+        if not active:
+            raise PlanningError("failed to select current task")
+    except (PlanningError, OwnershipError, OSError, ValueError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 1
+    print(colored(f"✓ Task selected without starting: {active.task_path}", Colors.GREEN))
+    return 0
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    try:
+        target, data = _active_task_target(args.dir, repo_root)
+        if data.get("status") != "planning":
+            raise PlanningError("plan seal/approve requires planning; use replan for a material change")
+        if args.plan_command == "seal":
+            revision = seal_plan(data, target)
+        else:
+            approve_plan(data, target, args.revision, args.basis)
+            revision = args.revision
+        if not write_json(target / FILE_TASK_JSON, data):
+            raise PlanningError("could not write planning record")
+    except (PlanningError, OwnershipError, OSError, ValueError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 1
+    print(colored(f"✓ Plan {args.plan_command}: revision {revision}", Colors.GREEN))
+    return 0
+
+
 def cmd_start(args: argparse.Namespace) -> int:
     """Set active task."""
     repo_root = get_repo_root()
@@ -223,6 +281,19 @@ def cmd_start(args: argparse.Namespace) -> int:
         print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
         return 2
 
+    # Reject before writing either the session pointer or task status. The
+    # manifest override below never supplies implementation authorization.
+    try:
+        if not is_within_tasks_dir(full_path, repo_root) or (full_path / FILE_TASK_JSON).is_symlink():
+            raise PlanningError("start requires a direct active task with regular task.json")
+        task_data, reason = read_json_checked(full_path / FILE_TASK_JSON)
+        if task_data is None:
+            raise PlanningError(describe_json_read_failure(full_path / FILE_TASK_JSON, reason)[0])
+        require_start_approval(task_data, full_path)
+    except (PlanningError, OSError, ValueError) as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 1
+
     # 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.
@@ -340,6 +411,12 @@ def cmd_replan(args: argparse.Namespace) -> int:
         )
         return 1
 
+    try:
+        invalidate_plan(data)
+    except PlanningError as exc:
+        print(colored(f"Error: {exc}", Colors.RED), file=sys.stderr)
+        return 1
+
     event = {
         "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "task": full_path.relative_to(repo_root).as_posix(),
@@ -803,6 +880,9 @@ def show_usage() -> None:
 
 Usage:
   python3 task.py create <title> --description <desc>  Create new task directory (both required, non-empty)
+  python3 task.py select <dir>                       Select context without starting
+  python3 task.py plan seal <dir>                    Seal the current material plan
+  python3 task.py plan approve <dir> --revision N --basis "approval"
   python3 task.py create <title> --description <desc> --package <pkg>   Create task for a specific package
   python3 task.py create <title> --description <desc> --parent <dir>    Create task as child of parent
   python3 task.py create <title> --description <desc> --no-start        Create without making it active in this session
@@ -964,6 +1044,18 @@ def main() -> int:
     p_listctx = subparsers.add_parser("list-context", help="List context entries")
     p_listctx.add_argument("dir", help="Task directory")
 
+    p_select = subparsers.add_parser("select", help="Select a task without changing its phase")
+    p_select.add_argument("dir", help="Existing active task directory")
+
+    p_plan = subparsers.add_parser("plan", help="Seal or record later approval of a material plan")
+    plan_sub = p_plan.add_subparsers(dest="plan_command", required=True)
+    p_seal = plan_sub.add_parser("seal", help="Seal the current material plan revision")
+    p_seal.add_argument("dir", help="Planning task directory")
+    p_approve = plan_sub.add_parser("approve", help="Record actual later user approval")
+    p_approve.add_argument("dir", help="Planning task directory")
+    p_approve.add_argument("--revision", type=int, required=True)
+    p_approve.add_argument("--basis", required=True, help="Short non-sensitive basis for real approval")
+
     # start
     p_start = subparsers.add_parser("start", help="Set active task")
     p_start.add_argument("dir", help="Task directory")
@@ -1124,6 +1216,8 @@ def main() -> int:
         "add-context": cmd_add_context,
         "validate": cmd_validate,
         "list-context": cmd_list_context,
+        "select": cmd_select,
+        "plan": cmd_plan,
         "start": cmd_start,
         "replan": cmd_replan,
         "current": cmd_current,

package/dist/templates/trellis/workflow.md

@@ -22,6 +22,36 @@ target or explicit inspection. Native protected writes retain owner identity
 and ownership checks. Never repeat or re-answer consumed pre-compaction user
 input; handle genuinely new input normally. No recovery cache or extra waiter.
 
+## Plan Approval And Task Selection
+
+Classify task meta explicitly as `execution_class=direct|planned` and
+`delivery_mode=change_bearing|analysis_only`; an unclassified old planning task
+needs this once before start. Direct small work and eligible analysis-only work
+retain their existing shortest paths. Existing in-progress tasks are not reset.
+
+For planned/change-bearing work, close decisions and required task artifacts,
+run native `task.py plan seal <task>`, present that material plan, and stop before
+implementation. Only a later explicit user approval for THIS task's CURRENT
+sealed revision authorizes `task.py plan approve <task> --revision <n> --basis
+"<short non-sensitive actual approval basis>"`, then `task.py start`. Initial
+delivery requests, parent-task approval, and design answers do not qualify.
+`--allow-empty-context` overrides only context manifests, never approval.
+The native record enforces structure; chat authenticity remains agent-owned.
+
+Material scope, owner, risk, public behavior, or acceptance changes require
+`task.py replan` and a newly sealed, presented, subsequently approved revision.
+Resealing a sealed planning task declares a new material revision. Wording,
+formatting, progress, and execution evidence do not automatically invalidate it.
+Generic create/set-meta cannot prefill the reserved `meta.planning` record.
+
+Use native `task.py select <task>` for context-only selection: no phase/branch
+change, after_start hook, or implementation authority. `create --no-start`
+deliberately keeps the prior pointer. Save the old checkpoint before switching;
+with live Channel work, pause refills and drain all already dispatched units and
+reservations according to `trellis-channel`'s multi-target procedure, preserving
+pending units and the old phase. Do not kill/retry or automatically restart a
+user-stopped task. Ordinary continue/compaction retains the checkpoint fast path.
+
 ## Trellis System
 
 ### Developer Identity
@@ -54,7 +84,10 @@ Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `t
 ```bash
 # Task lifecycle
 python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
-python3 ./.trellis/scripts/task.py start <name>          # set active task (session-scoped when available)
+python3 ./.trellis/scripts/task.py select <name>         # context only, preserve phase
+python3 ./.trellis/scripts/task.py plan seal <name>      # current material plan
+python3 ./.trellis/scripts/task.py plan approve <name> --revision <n> --basis "<actual approval>"
+python3 ./.trellis/scripts/task.py start <name>          # begin only when start gates pass
 python3 ./.trellis/scripts/task.py replan <name> "<reason>" # return material ambiguity to planning
 python3 ./.trellis/scripts/task.py current --source      # show active task and source
 python3 ./.trellis/scripts/task.py finish                # clear active task (triggers after_finish hooks)
@@ -247,6 +280,7 @@ If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declar
 Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; run the Planning Seal closure pass before asking for review. If `decision-needed` items or an unsealed decision graph remain, load `pennix-decision-grill`, batch only independent frontier questions, and stay in planning. Answers returned by the current continuation must be persisted and fed back into the same planning loop.
 Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
 Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
+Planned/change-bearing start requires native plan seal and matching later approval of this task's current material revision. Selecting context does not approve it.
 [/workflow-state:planning]
 
 <!-- Per-turn breadcrumb: shown throughout Phase 1 when Codex uses its default
@@ -261,6 +295,7 @@ If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declar
 Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; run the Planning Seal closure pass before asking for review. If `decision-needed` items or an unsealed decision graph remain, load `pennix-decision-grill`, batch only independent frontier questions, and stay in planning. Answers returned by the current continuation must be persisted and fed back into the same planning loop.
 Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
 Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
+Planned/change-bearing start requires native plan seal and matching later approval of this task's current material revision. Selecting context does not approve it.
 [/workflow-state:planning-inline]
 
 ### Phase 2: Execute
@@ -294,6 +329,7 @@ Dispatch prompt starts with `Active task: <task path from task.py current>`. Rea
 Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
 If implementation discovers a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return to the planning frontier; native questions are planning-only.
 Do not dispatch implement/check sub-agents in inline mode.
+Explicit Channel independent-evidence subnodes remain available under the selected workflow; required independent evidence cannot be replaced by main-session pass claims.
 Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills.
 [/workflow-state:in_progress-inline]
 
@@ -506,7 +542,8 @@ Skip this step. Context is loaded directly by the `trellis-before-dev` skill in
 
 This step applies only to change-bearing tasks. An eligible analysis-only task stays in `planning` and, after its evidence work is complete, continues directly to Phase 3.3 without running `task.py start`.
 
-After the Planning Seal closure pass and artifact review, flip the task status to `in_progress`:
+After the Planning Seal closure pass, artifact review, and applicable native
+plan seal/approve gates described above, flip the task status to `in_progress`:
 
 ```bash
 python3 ./.trellis/scripts/task.py start <task-dir>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennixrv/trellis",
-  "version": "0.7.0-beta.32",
+  "version": "0.7.0-beta.34",
   "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.7.0-beta.32"
+    "@pennixrv/trellis-core": "0.7.0-beta.34"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",