@pennixrv/trellis 0.7.0-beta.8 → 0.7.0-beta.9

package/dist/migrations/manifests/0.7.0-beta.9.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.7.0-beta.9",
+  "description": "Pennix v0.7 beta planning and evidence governance",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Features:**\n- Require complex analysis to use normal planning and a sealed decision chain.\n- Add evidence units and schema-v2 subnode reports with coordinator-only acceptance.",
+  "migrations": [],
+  "notes": "Run npm install -g @pennixrv/trellis@beta then trellis update. No --migrate required."
+}

package/dist/templates/common/bundled-skills/trellis-channel/references/subnode-work.md

@@ -50,12 +50,15 @@ and its status; the Codex supervisor projects that reply into the durable
 Channel message and `done` events. The durable JSON file carries the
 reviewable result.
 
-The subnode copies identity, scope, and lens from `brief.json`. The minimal
+The subnode copies identity, scope, and lens from `brief.json`. Schema version 2
+requires one `scope_assessment` entry for every brief scope item, structured
+findings with evidence references, and typed uncertainties or corrections when
+present. Schema version 1 is retired and the validator rejects it. The minimal
 complete report is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "task_id": "task-id-from-brief",
   "work_id": "work-id-from-brief",
   "subnode_id": "subnode-id-from-brief",
@@ -63,6 +66,14 @@ complete report is:
   "status": "complete",
   "scope": ["exact scope copied from brief"],
   "lens": "exact lens copied from brief",
+  "scope_assessment": [
+    {
+      "scope": "exact scope item from brief",
+      "status": "covered",
+      "conclusion": "What this scope establishes.",
+      "evidence_ids": ["stable-evidence-id"]
+    }
+  ],
   "evidence": [
     {
       "id": "stable-evidence-id",
@@ -70,12 +81,30 @@ complete report is:
       "summary": "What this independently reviewable evidence establishes."
     }
   ],
-  "findings": ["Bounded conclusion."],
+  "findings": [
+    {
+      "id": "finding-id",
+      "conclusion": "Bounded conclusion.",
+      "evidence_ids": ["stable-evidence-id"]
+    }
+  ],
   "uncertainties": [],
   "corrections": []
 }
 ```
 
+Append a checkpoint marker to `worklog.md` when a material unit is complete or
+blocked. It is a bounded recovery projection, not coordinator acceptance:
+
+```text
+<!-- trellis-checkpoint: {"id":"checkpoint-1","covered_scope":["exact scope item"],"evidence_ids":["stable-evidence-id"],"conclusion_or_blocker":"Current conclusion or blocker.","unknowns":[],"safe_resume_point":"Next safe action."} -->
+```
+
+The validator returns `review_concern` for missing or incomplete checkpoint
+coverage and for inconclusive scope assessments so the coordinator can inspect
+them. Identity, schema, path, and malformed-structure failures remain hard
+errors. A concern is never automatic acceptance or rejection.
+
 For `blocked`, `incomplete`, or `error`, include the same base fields plus a
 `completed_scope` list (empty when no assigned scope started) and a non-empty
 `blocker` string. Never use

package/dist/templates/common/commands/continue.md

@@ -24,13 +24,13 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
 `get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
 
-- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → complete the PRD's bounded evidence work, verify its acceptance criteria and no-change boundary, then commit task artifacts and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
+- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → first confirm the task still satisfies the bounded evidence-only eligibility rule; then complete the PRD's evidence work, verify its acceptance criteria and no-change boundary, and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
 - `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
 - `status=planning` + a recorded `decision-needed` or unsealed decision chain → return to the planning frontier and load `pennix-decision-gates` when independent material questions can be batched.
 - `status=in_progress` + a material unresolved decision → record the reason and run `task.py replan <task> "<reason>"`; do not ask a native question during implementation.
 - `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
 - `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**
-- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
+- `status=planning` + required artifacts complete + required jsonl curated or inline mode → run the Planning Seal closure pass, then **1.4** (ask for start review; only run `task.py start` after user confirms)
 - `status=in_progress` + implementation not started → **2.1**
 - `status=in_progress` + implementation done, not yet checked → **2.2**
 - `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit)

package/dist/templates/common/skills/brainstorm.md

@@ -12,6 +12,8 @@ While any user-owned product, scope, UX, compatibility, risk, or acceptance deci
 
 When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Do not require a second planning approval or run `task.py start`: perform the declared research, audit, or design work while status remains `planning`, record the evidence, verify acceptance criteria and the boundary, commit task artifacts, and archive directly. If the evidence recommends a protected-target change, record it and create a separate change-bearing task before doing it.
 
+This exception is eligible only for a bounded evidence deliverable with no material user decision, design or implementation plan, cross-owner coordination, security or deployment change, release or credential action, or protected downstream task. Calling work "research", deferring source edits, or working in an audit/root repository does not make it analysis-only. If any of those conditions apply, use the normal complex planning and implementation-approval path.
+
 All other tasks follow the planning and implementation approval gates below.
 
 ## Non-Negotiable Evidence Rule
@@ -24,6 +26,10 @@ Do not ask the user to confirm facts that the repository can answer. Ask only fo
 
 Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
 
+## Evidence Units For Read-Heavy Work
+
+When research, audit, review, or investigation is too large to leave one independently useful conclusion in the current bounded session, split it into evidence units. Each unit must have one question or scope, a minimal evidence range, a destination artifact, and a stop condition; write its facts, conclusion or blocker, unknowns, and recovery point before starting another unit. Size units so one normal context window can finish and persist one useful result; do not promise an exact token or time limit. Routine navigation and transient tool output do not need an artifact. Create a child task only when the unit has an independent owner, lifecycle, and acceptance contract.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -54,10 +60,10 @@ Use a concise title from the user's request. Both the title and `--description`
    - product intent still needed from the user
    - scope or risk decisions still needed from the user
    - likely out-of-scope items
-4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off, then stop the turn for native input.
-5. After each answer batch, update `prd.md`, record the selected decisions, recheck evidence and conflicts, and repeat from step 2. Do not create a second Trellis lifecycle for the same decision chain.
+4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off. Yield only while the answer is unavailable.
+5. When the host returns the current continuation's answer, immediately persist it in `prd.md` or the decision artifact, recheck evidence and conflicts, recalculate the frontier, and continue the same planning loop. Do not create a second Trellis lifecycle for the same decision chain. Stop only for a new unresolved frontier, a real capability or authority block, or a final sealed summary awaiting implementation approval.
 6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
+7. Run the requirement convergence gate, then the PRD convergence pass. Finish with one Planning Seal closure pass.
 8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
 9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If implementation reveals a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return through this planning flow; do not open a popup during implementation.
 
@@ -140,6 +146,8 @@ Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evi
 
 The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
 
+The Planning Seal closure pass must reconcile `task.json`, `prd.md`, `design.md`, `implement.md`, research, decision records, and manifests; verify the actual modification targets and branches, ordered dependencies and release steps, validation and rollback, dynamic-fact dispositions and replan triggers, and that every material decision has an owner and a fixed outcome. Remove static ambiguity before implementation: no `TBD`, `TODO`, `decision-needed`, unowned option, unspecified branch, open implementation path, validation gap, or conditional acceptance may remain. A material discovery invalidates the seal and returns to planning; implementation may consume only a sealed plan.
+
 ## Artifact Rules
 
 `prd.md` records requirements and acceptance:

package/dist/templates/copilot/prompts/brainstorm.prompt.md

@@ -12,6 +12,10 @@ For every non-trivial task, the user must respond at least once after the initia
 
 While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, keep the task in planning. First inventory evidence and decision dependencies. If at least two independent material decisions remain and `pennix-decision-gates` is available, delegate one bounded batch of up to three frontier questions; otherwise ask the single highest-value question. Do not edit product code, dispatch implementation, or run `task.py start` until the decision chain is sealed.
 
+## Analysis-Only Exception
+
+When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Keep status `planning`, record and verify the evidence, commit task artifacts, and archive directly; do not run `task.py start` or wait for a second implementation approval. This exception is eligible only when there is no material user decision, design or implementation plan, cross-owner coordination, security or deployment change, release or credential action, or protected downstream task. Otherwise use normal complex planning.
+
 ## Non-Negotiable Evidence Rule
 
 If a question can be answered by exploring the codebase, explore the codebase instead.
@@ -22,6 +26,10 @@ Do not ask the user to confirm facts that the repository can answer. Ask only fo
 
 Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
 
+## Evidence Units For Read-Heavy Work
+
+When research, audit, review, or investigation is too large for one independently useful conclusion in the current session, split it into evidence units. Each unit has one question or scope, a minimal evidence range, a destination artifact, and a stop condition; persist facts, conclusion or blocker, unknowns, and a recovery point before starting another unit. Size each unit for one normal context window without promising an exact token or time limit.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -52,10 +60,10 @@ Use a concise title from the user's request. Both the title and `--description`
    - product intent still needed from the user
    - scope or risk decisions still needed from the user
    - likely out-of-scope items
-4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off, then stop the turn for native input.
-5. After each answer batch, update `prd.md`, record the selected decisions, recheck evidence and conflicts, and repeat from step 2. Do not create a second Trellis lifecycle for the same decision chain.
+4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off. Yield only while the answer is unavailable.
+5. When the host returns the current continuation's answer, persist it in `prd.md` or the decision artifact, recheck evidence and conflicts, recalculate the frontier, and continue the same planning loop. Stop only for a new unresolved frontier, a real capability or authority block, or a final sealed summary awaiting implementation approval.
 6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
+7. Run the requirement convergence gate, then the PRD convergence pass. Finish with one Planning Seal closure pass.
 8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
 9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If implementation reveals a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return through this planning flow; do not open a popup during implementation.
 
@@ -95,6 +103,8 @@ Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evi
 
 The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
 
+The Planning Seal closure pass reconciles `task.json`, `prd.md`, `design.md`, `implement.md`, research, decision records, and manifests; verifies targets, branches, dependencies, release, validation, rollback, dynamic-fact dispositions, and replan triggers; and fixes every material decision to an owner and outcome. No `TBD`, `TODO`, `decision-needed`, unowned option, unspecified branch, open implementation path, validation gap, or conditional acceptance may remain. Any material discovery invalidates the seal and returns to planning.
+
 ## Artifact Rules
 
 `prd.md` records requirements and acceptance:

package/dist/templates/trellis/agents/subnode.md

@@ -49,10 +49,17 @@ sandbox claim.
 4. Write `report.json` only when you are ready to stop. Its status is one of
    `complete`, `blocked`, `incomplete`, or `error`; it is always
    **pending coordinator review**, never accepted/rejected/deferred.
-5. A complete report includes independently checkable evidence. A non-complete
-   report explains completed scope and the blocker or error. Include the exact
-   identity, scope, and lens required by the artifact helper.
-6. Finish with one short final assistant reply that states the status and report
+5. Use report schema version 2. Include one `scope_assessment` for each brief
+   scope item, structured findings with `id`, `conclusion`, and `evidence_ids`,
+   and typed `uncertainties` or `corrections` when present. A complete report
+   includes independently checkable evidence; a non-complete report explains
+   completed scope and the blocker or error. Include the exact identity, scope,
+   and lens required by the artifact helper.
+6. Append a checkpoint marker to `worklog.md` after each material unit using
+   the exact `trellis-checkpoint` JSON fields documented by `subnode-work`.
+   Missing or incomplete checkpoint coverage becomes a coordinator review
+   concern; it does not become acceptance.
+7. Finish with one short final assistant reply that states the status and report
    path. Do not place the report JSON in the reply and do not run
    `trellis channel send`: the supervisor routes this final reply into the
    durable Channel message and `done` events.

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

@@ -22,10 +22,12 @@ from common.task_utils import is_within_tasks_dir, resolve_task_dir
 from common.tasks import load_task
 
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 MAX_DRAFT_BYTES = 64 * 1024
 MAX_REPORT_BYTES = 128 * 1024
+MAX_WORKLOG_BYTES = 128 * 1024
 ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+CHECKPOINT_RE = re.compile(r"^<!-- trellis-checkpoint: (?P<payload>\{.*\}) -->$", re.MULTILINE)
 SECRET_PATTERNS = (
     re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
     re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),
@@ -305,7 +307,7 @@ def _validate_brief_file(
     return brief, raw, brief_path, node_dir, task_dir
 
 
-def _validate_evidence(value: Any) -> set[tuple[str, str]]:
+def _validate_evidence(value: Any) -> set[str]:
     if not isinstance(value, list):
         _fail("report.evidence must be a list")
     identities: set[tuple[str, str]] = set()
@@ -319,13 +321,100 @@ def _validate_evidence(value: Any) -> set[tuple[str, str]]:
         if identity in identities:
             _fail("report.evidence contains a duplicate evidence identity")
         identities.add(identity)
-    return identities
+    return {evidence_id for evidence_id, _locator in identities}
+
+
+def _validate_id_list(value: Any, field: str) -> list[str]:
+    if not isinstance(value, list):
+        _fail(f"{field} must be a list")
+    result = []
+    for index, item in enumerate(value):
+        result.append(_require_text(item, f"{field}[{index}]", max_len=128))
+    if len(result) != len(set(result)):
+        _fail(f"{field} must not contain duplicates")
+    return result
+
+
+def _validate_typed_notes(value: Any, field: str) -> None:
+    if not isinstance(value, list):
+        _fail(f"report.{field} must be a list")
+    for index, item in enumerate(value):
+        if not isinstance(item, dict):
+            _fail(f"report.{field}[{index}] must be an object")
+        _require_id(item.get("id"), f"report.{field}[{index}].id")
+        _require_text(item.get("type"), f"report.{field}[{index}].type", max_len=64)
+        _require_text(item.get("detail"), f"report.{field}[{index}].detail")
+        _validate_id_list(item.get("evidence_ids", []), f"report.{field}[{index}].evidence_ids")
+
+
+def _validate_checkpoint(node_dir: Path, evidence_ids: set[str], scope: list[str]) -> list[str]:
+    worklog_path = node_dir / "worklog.md"
+    if worklog_path.is_symlink():
+        _fail(f"refusing symlinked worklog: {worklog_path}")
+    try:
+        raw = worklog_path.read_bytes()
+    except FileNotFoundError:
+        _fail(f"worklog does not exist: {worklog_path}")
+    except OSError as exc:
+        _fail(f"could not read worklog {worklog_path}: {exc}")
+    if len(raw) > MAX_WORKLOG_BYTES:
+        _fail(f"worklog exceeds the {MAX_WORKLOG_BYTES} byte limit: {worklog_path}")
+    _reject_obvious_secrets(raw, "worklog")
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        _fail(f"worklog is not UTF-8: {worklog_path}")
+    matches = list(CHECKPOINT_RE.finditer(text))
+    if not matches:
+        return ["missing_worklog_checkpoint"]
+    concerns: list[str] = []
+    checkpoint_ids: set[str] = set()
+    for match in matches:
+        try:
+            checkpoint = json.loads(match.group("payload"))
+        except json.JSONDecodeError:
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        if not isinstance(checkpoint, dict):
+            concerns.append("malformed_worklog_checkpoint")
+            continue
+        try:
+            checkpoint_id = _require_id(checkpoint.get("id"), "worklog checkpoint.id")
+            if checkpoint_id in checkpoint_ids:
+                concerns.append("duplicate_worklog_checkpoint")
+            checkpoint_ids.add(checkpoint_id)
+            covered_scope = _require_text_list(
+                checkpoint.get("covered_scope"),
+                "worklog checkpoint.covered_scope",
+                allow_empty=True,
+            )
+            for item in covered_scope:
+                if item not in scope:
+                    concerns.append("checkpoint_scope_outside_brief")
+            checkpoint_evidence = _validate_id_list(
+                checkpoint.get("evidence_ids"), "worklog checkpoint.evidence_ids"
+            )
+            if any(item not in evidence_ids for item in checkpoint_evidence):
+                concerns.append("checkpoint_evidence_unresolved")
+            _require_text(
+                checkpoint.get("conclusion_or_blocker"),
+                "worklog checkpoint.conclusion_or_blocker",
+            )
+            _require_text_list(
+                checkpoint.get("unknowns"),
+                "worklog checkpoint.unknowns",
+                allow_empty=True,
+            )
+            _require_text(checkpoint.get("safe_resume_point"), "worklog checkpoint.safe_resume_point")
+        except ArtifactError:
+            concerns.append("malformed_worklog_checkpoint")
+    return sorted(set(concerns))
 
 
 def _validate_report_data(
     report: dict[str, Any],
     brief: dict[str, Any],
-) -> set[tuple[str, str]]:
+) -> tuple[set[str], list[str]]:
     if report.get("schema_version") != SCHEMA_VERSION:
         _fail(f"report.schema_version must be {SCHEMA_VERSION}")
     for field in ("task_id", "work_id", "subnode_id", "role_id"):
@@ -339,11 +428,52 @@ def _validate_report_data(
     if status not in {"complete", "blocked", "incomplete", "error"}:
         _fail("report.status must be complete, blocked, incomplete, or error")
     evidence = _validate_evidence(report.get("evidence"))
-    for field in ("findings", "uncertainties", "corrections"):
-        if not isinstance(report.get(field), list):
-            _fail(f"report.{field} must be a list")
+    assessment = report.get("scope_assessment")
+    if not isinstance(assessment, list) or len(assessment) != len(brief["scope"]):
+        _fail("report.scope_assessment must contain one item for every brief scope item")
+    concerns: list[str] = []
+    for index, item in enumerate(assessment):
+        if not isinstance(item, dict):
+            _fail(f"report.scope_assessment[{index}] must be an object")
+        if item.get("scope") != brief["scope"][index]:
+            _fail(f"report.scope_assessment[{index}].scope does not match brief.scope")
+        if item.get("status") not in {"covered", "inconclusive", "not-started"}:
+            _fail(f"report.scope_assessment[{index}].status is invalid")
+        _require_text(item.get("conclusion"), f"report.scope_assessment[{index}].conclusion")
+        assessment_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.scope_assessment[{index}].evidence_ids"
+        )
+        if any(value not in evidence for value in assessment_evidence):
+            concerns.append("scope_assessment_evidence_unresolved")
+        if item["status"] != "covered":
+            concerns.append("incomplete_scope_coverage")
+        if item["status"] == "covered" and not assessment_evidence:
+            concerns.append("covered_scope_without_evidence")
+    findings = report.get("findings")
+    if not isinstance(findings, list):
+        _fail("report.findings must be a list")
+    finding_ids: set[str] = set()
+    for index, item in enumerate(findings):
+        if not isinstance(item, dict):
+            _fail(f"report.findings[{index}] must be an object")
+        finding_id = _require_id(item.get("id"), f"report.findings[{index}].id")
+        if finding_id in finding_ids:
+            _fail("report.findings contains duplicate ids")
+        finding_ids.add(finding_id)
+        _require_text(item.get("conclusion"), f"report.findings[{index}].conclusion")
+        finding_evidence = _validate_id_list(
+            item.get("evidence_ids"), f"report.findings[{index}].evidence_ids"
+        )
+        if not finding_evidence:
+            concerns.append("finding_without_evidence")
+        if any(value not in evidence for value in finding_evidence):
+            concerns.append("finding_evidence_unresolved")
+    _validate_typed_notes(report.get("uncertainties"), "uncertainties")
+    _validate_typed_notes(report.get("corrections"), "corrections")
     if status == "complete" and not evidence:
         _fail("a complete report requires at least one evidence item")
+    if status == "complete" and not findings:
+        _fail("a complete report requires at least one finding")
     if status != "complete":
         _require_text_list(
             report.get("completed_scope"),
@@ -351,13 +481,13 @@ def _validate_report_data(
             allow_empty=True,
         )
         _require_text(report.get("blocker"), "report.blocker")
-    return evidence
+    return evidence, sorted(set(concerns))
 
 
 def _validate_report_file(
     value: str,
     repo_root: Path,
-) -> tuple[dict[str, Any], set[tuple[str, str]], dict[str, Any], Path]:
+) -> tuple[dict[str, Any], set[str], dict[str, Any], Path, list[str]]:
     report_path, node_dir, _task_dir = _resolve_artifact_file(value, "report.json", repo_root)
     brief_path = node_dir / "brief.json"
     brief, _brief_raw, _brief_path, _brief_node, _brief_task = _validate_brief_file(
@@ -368,8 +498,9 @@ def _validate_report_file(
         _fail("brief.report_path does not point to the report being validated")
     report, raw = _read_json_object(report_path, MAX_REPORT_BYTES, "report")
     _reject_obvious_secrets(raw, "report")
-    evidence = _validate_report_data(report, brief)
-    return report, evidence, brief, node_dir
+    evidence, concerns = _validate_report_data(report, brief)
+    concerns.extend(_validate_checkpoint(node_dir, evidence, brief["scope"]))
+    return report, evidence, brief, node_dir, sorted(set(concerns))
 
 
 def _validate_disposition_data(
@@ -466,13 +597,20 @@ def _init(args: argparse.Namespace) -> None:
 
 def _validate(args: argparse.Namespace) -> None:
     repo_root = get_repo_root()
-    report, _evidence, _brief, _node_dir_value = _validate_report_file(args.report, repo_root)
+    report, _evidence, _brief, _node_dir_value, concerns = _validate_report_file(args.report, repo_root)
+    if concerns:
+        print(json.dumps({
+            "status": "review_concern",
+            "subnode_id": report["subnode_id"],
+            "concerns": concerns,
+        }))
+        return
     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)
+    report, _evidence, brief, node_dir, _concerns = _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}")
@@ -514,10 +652,10 @@ def _validate_counter(args: argparse.Namespace) -> None:
         primary_dir = repo_root / primary_dir
     if not counter_dir.is_absolute():
         counter_dir = repo_root / counter_dir
-    primary_report, primary_evidence, primary_brief, primary_node = _validate_report_file(
+    primary_report, primary_evidence, primary_brief, primary_node, _primary_concerns = _validate_report_file(
         str(primary_dir / "report.json"), repo_root
     )
-    counter_report, counter_evidence, counter_brief, counter_node = _validate_report_file(
+    counter_report, counter_evidence, counter_brief, counter_node, _counter_concerns = _validate_report_file(
         str(counter_dir / "report.json"), repo_root
     )
     if primary_node == counter_node:

package/dist/templates/trellis/workflow.md

@@ -167,6 +167,8 @@ Phase 3: Finish  → verify, update spec, commit, and wrap up
 
 An analysis-only task is eligible only when `task.json.meta.delivery_mode = "analysis_only"` exactly and its `prd.md` names the evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems. Task creation consent authorizes that bounded evidence work, not protected-target changes.
 
+The exception is invalid when the work still needs a material user decision, design or implementation plan, cross-owner coordination, security or deployment change, release or credential action, or a protected downstream task. "Research" and a deferred source edit do not override this classification; use normal complex planning when any condition applies.
+
 Keep an eligible analysis-only task in `planning`: write its research, audit, or design evidence; verify its acceptance criteria and boundary; commit task artifacts; then archive directly. Do not run `task.py start`, configure implementation context, or wait for a second implementation approval. If the evidence recommends a protected-target change, record the recommendation and create a separate change-bearing task before doing it.
 
 ### Planning Artifacts
@@ -177,6 +179,8 @@ Keep an eligible analysis-only task in `planning`: write its research, audit, or
 - `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`.
 - Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
 
+For read-heavy research, audit, review, or investigation, split work that cannot persist one useful conclusion in the current bounded session into evidence units. Each unit records one question or scope, minimal evidence, destination, stop condition, conclusion or blocker, unknowns, and recovery point before the next unit begins. Size for one normal context window, without an exact token or time promise; routine navigation needs no record.
+
 ### Parent / Child Task Trees
 
 Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.
@@ -230,7 +234,7 @@ Preserve existing task fields and artifacts. If the correct status cannot be det
 [workflow-state:planning]
 Load `trellis-brainstorm`; stay in planning.
 If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declared evidence work now. Do not wait for a start review or run `task.py start`; when the PRD boundary and acceptance evidence pass, commit task artifacts and archive directly. A protected-target recommendation requires a separate change-bearing task.
-Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`. If `decision-needed` items or an unsealed decision graph remain, load `pennix-decision-gates`, batch only independent frontier questions, and stay in planning.
+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-gates`, 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.
 [/workflow-state:planning]
@@ -244,7 +248,7 @@ Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research mani
 [workflow-state:planning-inline]
 Load `trellis-brainstorm`; stay in planning.
 If `task.json.meta.delivery_mode = "analysis_only"` exactly, complete the declared evidence work now. Do not wait for a start review or run `task.py start`; when the PRD boundary and acceptance evidence pass, commit task artifacts and archive directly. A protected-target recommendation requires a separate change-bearing task.
-Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`. If `decision-needed` items or an unsealed decision graph remain, load `pennix-decision-gates`, batch only independent frontier questions, and stay in planning.
+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-gates`, 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`.
 [/workflow-state:planning-inline]
@@ -389,6 +393,8 @@ The brainstorm skill will guide you to:
 - Split large scopes into a parent task plus child tasks when the deliverables can be verified independently
 - Keep `prd.md` focused on requirements and acceptance criteria
 - For complex tasks, produce `design.md` and `implement.md` before implementation starts
+- For read-heavy work, split long investigation into evidence units and persist each unit's conclusion or recovery point before continuing
+- Before review or `task.py start`, run the Planning Seal closure pass across all task artifacts and lock targets, branches, dependencies, release, validation, rollback, dynamic-fact handling, and every material decision
 
 When considering a parent/child split:
 - Use a parent task when one request contains several independently verifiable deliverables.
@@ -490,7 +496,7 @@ 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 artifact review, flip the task status to `in_progress`:
+After the Planning Seal closure pass and artifact review, flip the task status to `in_progress`:
 
 ```bash
 python3 ./.trellis/scripts/task.py start <task-dir>
@@ -513,6 +519,7 @@ If `task.py start` errors with a session-identity message (no context key from h
 | `research/` has artifacts (complex tasks) | recommended |
 | `design.md` exists (complex tasks) | ✅ |
 | `implement.md` exists (complex tasks) | ✅ |
+| Planning Seal closure pass recorded; static decisions and implementation paths are locked | ✅ |
 
 [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 

package/package.json

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