pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/.skills/pirl-plan/assets/plan-template.md

@@ -0,0 +1,48 @@
+---
+schema: pirl-plan/v1
+content_language: en
+plan_set: {{plan_set}}
+task_id: {{task_id}}
+title: "<Task name>"
+layer: implement
+status: planned
+depends_on: []
+created_at: "{{created_at}}"
+target_repo: "<Path of the target repository, relative to the Hub root or absolute; . for the Hub itself>"
+source_request: "<Short version of the user's request>"
+planning_roles: [<planning-role>]
+implementation_roles: [<implementation-role>]
+verification_roles: [<verification-role>]
+---
+
+# {{task_id}}: <Task name>
+
+## What to do
+
+- REQ-01 | Source: <Request or file/symbol read> | Requirement: <Business behavior to achieve>
+- Scope: <Work to be done; write exclusions only when needed to avoid misunderstanding>.
+- Allowed paths: `<specific paths of source, documentation and tests under FUT, if any>`.
+- Standalone task outcome: <Output that can be accepted while later/parallel tasks are not yet implemented>.
+<If the specification has build/test/release goals: one line saying they belong to the user's build/test/release stage>.
+
+## How to do it
+
+1. <ROLE-01: which file/symbol to change, how and with what outcome; add steps when there is a real dependency>.
+<If there are tests: ROLE-01 writes/updates tests under FUT for which REQ and which affected functionality, and runs exactly those tests (file/class/name)>.
+2. <ROLE-02: after ROLE-01, reasons on the diff/source to conclude which QGs; runs no commands/tests>.
+
+<If depends_on is set: the concrete output to receive from each prerequisite task>.
+<If end-to-end criteria are assigned to another task: the owning task and the integration part to verify; not a QG of this task>.
+<Input conditions or decisions to stop at, if any>.
+Next step: the user names this Plan file for Implement once the Plan content
+fixes are complete; Implement carries out only this task within the scope above.
+
+## Participating roles
+
+- ROLE-01 | Type: implementation | Role: <implementation-role> | Responsible for: <Concrete work> | Input: <Information or dependent results> | Done when: <Source/documentation to deliver>
+- ROLE-02 | Type: verification | Role: <verification-role> | Responsible for: <QGs and the questions to answer> | Input: <ROLE-01's diff/source> | Done when: <PASS/FAIL/BLOCKED conclusion for each QG by reasoning with sources>
+- Planning | Roles: <the roles in planning_roles> | Execution: <separate agent, or the coordinator self-performing with the reason delegation was not possible; per role when they differ>
+
+## Required quality gates
+
+- QG-01 | Requirement: REQ-01 | Required logic: <Situation → where it is handled → outcome/state and failure branches; provable by reasoning on the source with the prerequisite inputs and this task's changes, without tests/builds/runs or later/parallel tasks>

package/bundled-framework/files/.skills/pirl-plan/references/plan-format.md

@@ -0,0 +1,65 @@
+# Plan file format
+
+The `pirl-plan` skill owns how a Plan file is laid out, named and stored. What each
+section must settle belongs to the
+[Plan contract](../../../.agents/instructions/plan.instructions.md).
+
+## Location and naming
+
+- Output directory: the directory the user names for the Plan; when the user
+  names none, the Hub root.
+- Package: `<output directory>/<request-slug>_<YYYYMMDD-HHmmss>/`. The
+  package directory name is the `plan_set`.
+- Task file: `<NN>-plan-<todo-slug>-<YYYYMMDD-HHmmss>.md`, where `NN` is the
+  task number (`T01` → `01`) and the timestamp is the package timestamp, shared
+  by every file of the package.
+- Slugs are ASCII kebab-case: lowercase letters, digits and single hyphens.
+- Timestamps use the machine's local time zone and carry its UTC offset, for
+  example `+07:00`.
+- Task IDs start at `T01` and are consecutive within the package.
+- Never overwrite an existing file. Review reports of the package are placed
+  per the [report format](../../pirl-review/references/review-format.md#location-and-naming).
+- Git ignores package directories anywhere in the Hub, by their name pattern
+  ([AGENTS.md](../../../AGENTS.md#git)); a package the user places outside the
+  Hub follows the Git rules of that location.
+
+## Frontmatter
+
+| Field | Value |
+| --- | --- |
+| `schema` | `pirl-plan/v1` |
+| `content_language` | `en` |
+| `plan_set` | The package directory name |
+| `task_id` | `T01`, `T02`, … |
+| `title` | Task name, quoted |
+| `layer` | `implement`: the layer that carries out the Plan |
+| `status` | `planned` at handoff; Implement later sets `awaiting_confirmation`, `implemented`, `blocked` or `failed`, equal to the Implementation Record's `status` |
+| `depends_on` | Task IDs of the same package; never the task itself, never a cycle |
+| `created_at` | ISO-8601 timestamp with a UTC offset, quoted |
+| `target_repo` | Path of the target repository, relative to the Hub root or absolute; `.` for the Hub itself; an existing directory ([AGENTS.md](../../../AGENTS.md#target-repository)) |
+| `source_request` | Short version of the user's request, quoted |
+| `planning_roles` | Roles registered for `plan` |
+| `implementation_roles` | Roles registered for `implement` |
+| `verification_roles` | Roles registered for `verify`, none of them in `implementation_roles` |
+
+Write the frontmatter in the YAML subset the validator reads: one
+`key: value` per line, inline lists such as `[code-analyst, code-reviewer]`,
+quoted strings when a value contains `:` or `#`.
+
+## Body
+
+- Exactly four level-two sections, in this order: `What to do`, `How to do it`,
+  `Participating roles`, `Required quality gates`. Add only details that change
+  how the work is done; do not add per-role reports or checklists as a fifth
+  section. Implement later adds one `Implementation Record` section below them.
+- Line forms: `REQ-NN | Source: … | Requirement: …`;
+  `ROLE-NN | Type: … | Role: … | Responsible for: … | Input: … | Done when: …`;
+  `QG-NN | Requirement: REQ-NN | Required logic: …`.
+- Write in English; keep IDs, data keys, symbols, commands and paths verbatim.
+
+## Placeholders in the template
+
+- `{{name}}`: computed values that `scripts/new_plan.py` fills in. When a file
+  is written without the script, fill them by the rules above.
+- `<…>`: content the coordinator writes from the settled decisions. A line of
+  the form `<If …: …>` stays only when its condition holds.

package/bundled-framework/files/.skills/pirl-plan/scripts/new_plan.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Create one Plan task file from the plan skill's template, with the computed values filled in.
+
+The layout, naming and location rules are owned by ../references/plan-format.md; this script fills only
+what a tool can compute (package name, task ID, file name, timestamp) and leaves every <...> placeholder
+to the coordinator. It never overwrites a file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[1]
+HUB = SKILL.parents[1]
+sys.path.insert(0, str(HUB / ".agents" / "evals"))
+from validate_layer_artifact import LayerArtifactError, read_frontmatter, resolve_path  # noqa: E402
+
+TEMPLATE = SKILL / "assets" / "plan-template.md"
+SLUG = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+PLAN_SET = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*_(\d{8}-\d{6})")
+TASK = re.compile(r"T(\d{2,})")
+
+
+def shown(path: Path, root: Path) -> str:
+    """A path as Plans and reports write it: relative to the Hub root when inside it, otherwise absolute."""
+
+    return path.relative_to(root).as_posix() if path.is_relative_to(root) else path.as_posix()
+
+
+def create(root: Path, todo_slug: str, request_slug: str | None, plan_set: str | None, out_dir: str | None) -> dict[str, str]:
+    if not SLUG.fullmatch(todo_slug):
+        raise LayerArtifactError("--todo-slug must be ASCII kebab-case")
+    base = resolve_path(out_dir, root) if out_dir else root
+    now = datetime.now().astimezone()
+    if request_slug is not None:
+        if not SLUG.fullmatch(request_slug):
+            raise LayerArtifactError("--request-slug must be ASCII kebab-case")
+        plan_set = f"{request_slug}_{now:%Y%m%d-%H%M%S}"
+        package = base / plan_set
+        if package.exists():
+            raise LayerArtifactError(f"{shown(package, root)} already exists; pass --plan-set to add a task to it")
+    else:
+        if not plan_set or not PLAN_SET.fullmatch(plan_set):
+            raise LayerArtifactError("--plan-set must have the form <request-slug>_<YYYYMMDD-HHmmss>")
+        package = base / plan_set
+        if not package.is_dir():
+            raise LayerArtifactError(f"{shown(package, root)} is not an existing Plan package")
+    stamp = PLAN_SET.fullmatch(plan_set).group(1)
+    numbers = [0]
+    for item in sorted(package.glob("*.md")) if package.is_dir() else []:
+        match = TASK.fullmatch(str(read_frontmatter(item)[0].get("task_id", "")))
+        if match:
+            numbers.append(int(match.group(1)))
+    number = max(numbers) + 1
+    task_id = f"T{number:02d}"
+    target = package / f"{number:02d}-plan-{todo_slug}-{stamp}.md"
+    if target.exists():
+        raise LayerArtifactError(f"{shown(target, root)} already exists")
+    text = (TEMPLATE.read_text(encoding="utf-8")
+            .replace("{{plan_set}}", plan_set)
+            .replace("{{task_id}}", task_id)
+            .replace("{{created_at}}", now.isoformat(timespec="seconds")))
+    package.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8", newline="\n")
+    return {"path": shown(target, root), "plan_set": plan_set, "task_id": task_id}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--todo-slug", required=True, help="ASCII kebab-case slug of this task")
+    start = parser.add_mutually_exclusive_group(required=True)
+    start.add_argument("--request-slug", help="ASCII kebab-case slug of the request; starts a new package")
+    start.add_argument("--plan-set", help="name of an existing package; adds the next task to it")
+    parser.add_argument("--out-dir", help="directory holding the package, relative to the Hub root or absolute; default: the Hub root")
+    parser.add_argument("--root", type=Path, default=HUB, help="Hub root (default: the Hub containing this script)")
+    args = parser.parse_args()
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    try:
+        result = {"passed": True, **create(args.root.resolve(), args.todo_slug, args.request_slug, args.plan_set, args.out_dir)}
+    except (LayerArtifactError, OSError) as exc:
+        result = {"passed": False, "errors": [str(exc)]}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-framework/files/.skills/pirl-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pirl-review
+description: Runs the Review layer of the PIRL framework. Checks one implementation run of a Plan task against the Plan's quality gates by reasoning on the source, without building or running tests, and writes a report with a Business verdict (findings, risks, blockers) and Evaluations of the Implement roles with the framework improvements applied. Use only when the user's own words ask to review the implementation of a named Plan task or to open a new Review round. Do not use to write or implement a Plan, for a general code review outside a Plan or to edit the framework itself.
+metadata:
+  id: .skills/pirl-review
+  kind: skill
+  layer: review
+  version: 1.1.2
+---
+
+# Review
+
+Carries out one Review round. The
+[Review contract](../../.agents/instructions/review.instructions.md) owns the
+decisions, the rounds and the exit conditions; the
+[router](../../.agents/instructions/layered-task-execution.instructions.md) owns
+the shared contracts; [AGENTS.md](../../AGENTS.md) owns the core rules, roles
+and target repository. This skill owns the order of the steps, the report
+format and the helper script. Where a step names a section, that section
+decides.
+
+## When to use
+
+- The user's own words ask for a Review of an implementation run, per the
+  [conditions for opening a layer](../../AGENTS.md#choosing-a-layer).
+- Not for writing a Plan ([`pirl-plan`](../pirl-plan/SKILL.md)), implementing or
+  repairing ([`pirl-implement`](../pirl-implement/SKILL.md)), a code review that no Plan
+  covers
+  ([standalone task](../../.agents/instructions/standalone-and-maintenance.instructions.md#standalone-tasks))
+  or [framework maintenance](../../.agents/instructions/standalone-and-maintenance.instructions.md#framework-maintenance).
+
+## Resources
+
+| Resource | Use |
+| --- | --- |
+| [`assets/review-template.md`](assets/review-template.md) | Template of one Review report |
+| [`references/review-format.md`](references/review-format.md) | Frontmatter fields, file naming and location, presentation rules |
+| [`scripts/new_review.py`](scripts/new_review.py) | Creates the report of the next round for a Plan task, with the round, `prior_review`, `plan_file` and timestamp filled in |
+| [`validate_layer_artifact.py`](../../.agents/evals/validate_layer_artifact.py) | Checks the report structure before the final response |
+| [`layer_record.py`](../../.agents/evals/layer_record.py) | Pins the framework version, finds the reviewed Implement record and writes the run's record |
+
+## Procedure
+
+Run the commands from the Hub root.
+
+1. **Open the run.** Apply the [core rules](../../AGENTS.md#core-rules) and
+   [CONTEXT.md](../../CONTEXT.md). Run
+   `python -B .agents/evals/layer_record.py start` and keep the returned
+   `framework_ref`
+   ([Timing and evaluator](../../.agents/instructions/layered-task-execution.instructions.md#timing-and-evaluator)).
+2. **Read the inputs**
+   ([Inputs and permissions](../../.agents/instructions/review.instructions.md#inputs-and-permissions)):
+   the Plan, its Implementation Record, the diff and source of the Plan's
+   `target_repo`, and earlier reports for the same task. Identify the snapshot
+   before concluding.
+3. **Round.** Decide whether this work is a new round or belongs to the current
+   one ([Report and rounds](../../.agents/instructions/review.instructions.md#report-and-rounds)).
+   A new round creates its report in the directory the user named, or by
+   default under the Hub root
+   ([format](references/review-format.md#location-and-naming)); the current
+   round edits its existing report:
+
+   ```powershell
+   python -B .skills/pirl-review/scripts/new_review.py --plan <Plan file> --todo-slug <todo-slug> [--out-dir <dir>]
+   ```
+
+4. **Team.** Pick `review_roles` by the "Select when" column
+   ([AI Agent roles at the Review layer](../../.agents/instructions/review.instructions.md#ai-agent-roles-at-the-review-layer));
+   delegate each role to a separate agent per the
+   [assignment principles](../../.agents/instructions/layered-task-execution.instructions.md#assignment-principles).
+5. **Business**
+   ([contract](../../.agents/instructions/review.instructions.md#business-prove-or-refute-each-suspicion)):
+   conclude each QG, keep only grounded FINDs, RISKs and BLOCKs, and write the
+   `Business` section.
+6. **Evaluations and self-evaluation.** `process-auditor`, in a separate agent,
+   evaluates the roles of the reviewed Implement run
+   ([Evaluations](../../.agents/instructions/review.instructions.md#evaluations-assessing-implement-roles))
+   and the Review run itself
+   ([Self-evaluation and improvement](../../.agents/instructions/layered-task-execution.instructions.md#self-evaluation-and-improvement)),
+   applies improvements and writes the `Evaluations` section. The reviewed
+   record is found with:
+
+   ```powershell
+   python -B .agents/evals/layer_record.py query --layer implement --plan-set <plan-set> --task <task-id>
+   ```
+
+7. **Validate** the report and fix until it passes:
+
+   ```powershell
+   python -B .agents/evals/validate_layer_artifact.py --kind review --path <report file>
+   ```
+
+8. **Write the record** of the round, with `evaluates` and `task.report_file`
+   set:
+
+   ```powershell
+   python -B .agents/evals/layer_record.py append --input <JSON file>
+   python -B .agents/evals/layer_record.py check
+   ```
+
+9. **Clean up** temporary resources
+   ([router](../../.agents/instructions/layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff)).
+10. **Report**
+    ([Finishing and next permissions](../../.agents/instructions/review.instructions.md#finishing-and-next-permissions),
+    [Reporting](../../.agents/instructions/layered-task-execution.instructions.md#reporting)).
+    Stop there: a repair run or a new round opens only when the user asks.

package/bundled-framework/files/.skills/pirl-review/assets/review-template.md

@@ -0,0 +1,92 @@
+---
+schema: pirl-review/v1
+content_language: en
+plan_file: "{{plan_file}}"
+task_id: {{task_id}}
+review_round: {{review_round}}
+prior_review: {{prior_review}}
+review_roles: [code-analyst, code-reviewer, business-analyst, solution-architect]
+repair_roles: []
+business_verdict: PASS
+verdict: PASS
+status: completed
+reviewed_at: "{{reviewed_at}}"
+implementation_target: "<diff/commit/paths reviewed>"
+---
+
+# Review {{review_round_padded}}: {{task_id}} — {{title}}
+
+## Business
+
+### Quality gates
+
+| QG | Result | Evidence |
+| --- | --- | --- |
+| QG-01 | <PASS / FAIL / BLOCKED> | <source/symbol, logic and the result of the check> |
+
+### Findings
+
+#### FIND-01
+
+| Field | Content |
+| --- | --- |
+| QG | QG-01 |
+| Impact | <realistic trigger and consequence> |
+| Source | <file/symbol or trusted contract> |
+| Cause | <the faulty mechanism> |
+| Challenge | <grounds that refute competing explanations> |
+| Roles | <role, ...> |
+| Target | `<file to handle>` |
+| Instructions | <concrete work for each role, in order> |
+| Disposition | <repair / replan> |
+
+### Risks
+
+#### RISK-01
+
+| Field | Content |
+| --- | --- |
+| QG | QG-02 |
+| Impact | <realistic exposure and limits> |
+| Source | <file/symbol> |
+| Cause | <the mechanism that creates the risk> |
+| Challenge | <why the risk stands while the QG still holds> |
+| Roles | <role, ...> |
+| Target | `<related file>` |
+| Instructions | <how to mitigate when assigned> |
+| Revisit when | <concrete condition> |
+
+### Blockers
+
+#### BLOCK-01
+
+| Field | Content |
+| --- | --- |
+| QG | QG-03 |
+| Missing | <mandatory input not yet available> |
+| Source | <evidence of what is missing> |
+| Cause | <the mechanism that blocks the conclusion> |
+| Owner | <role or provider of the input> |
+| Target | `<related file>` |
+| Instructions | <action to unblock> |
+| Disposition | <retry / escalate> |
+| Condition | <change needed before continuing> |
+
+### Next
+
+| Field | Content |
+| --- | --- |
+| Next | <owner/layer, input file and condition to continue> |
+
+## Evaluations
+
+### EVAL-01
+
+| Field | Content |
+| --- | --- |
+| Role | <Implement implementation or verification role> |
+| Result | <PASS / FAIL / BLOCKED> |
+| Issue | <the role's grounded wrong decision; or none> |
+| Cause | <instruction / ineffective_fix / input / execution with `issue_key`; or none> |
+| Improvement | <file and section edited, old → new version; or pending the user (safety); or not needed> |
+| Evidence | <Implementation Record, Implement record, sources/diff checked> |

package/bundled-framework/files/.skills/pirl-review/references/review-format.md

@@ -0,0 +1,70 @@
+# Review report format
+
+The `pirl-review` skill owns how a Review report is laid out, named, stored and
+presented. What each conclusion must prove, and when a new round opens, belongs
+to the [Review contract](../../../.agents/instructions/review.instructions.md).
+
+## Location and naming
+
+- Output directory: the directory the user names for the report; when the user
+  names none, the Hub root.
+- Report:
+  `<output directory>/<plan-set>/<task-id-lower>-<todo-slug>/round-<NN>-review-<todo-slug>-<YYYYMMDD-HHmmss>.md`,
+  where `NN` is the two-digit round number. When the Plan package also sits
+  under the Hub root, the report lands inside the package directory, next to
+  the Plan it reviews. Inside the Hub, the `<plan-set>/` directory is ignored by
+  Git like the Plan package ([AGENTS.md](../../../AGENTS.md#git)).
+- Slugs are ASCII kebab-case; timestamps use the machine's local
+  time zone and carry its UTC offset.
+- Every round has its own file; never overwrite or delete another round.
+
+## Frontmatter
+
+| Field | Value |
+| --- | --- |
+| `schema` | `pirl-review/v1` |
+| `content_language` | `en` |
+| `plan_file` | The reviewed Plan file: path relative to the Hub root, or absolute when it lives outside the Hub; quoted |
+| `task_id` | The Plan's `task_id` |
+| `review_round` | `1`, `2`, … |
+| `prior_review` | `null` in round 1; afterwards the report of the round just before, as a path like `plan_file` |
+| `review_roles` | Roles registered for `review`, in the order of the contract's role table |
+| `repair_roles` | Roles registered for `implement`; `[]` while a `replan` remains or nothing needs repair |
+| `business_verdict` | `PASS`, `FAIL` or `BLOCKED` |
+| `verdict` | Equal to `business_verdict` |
+| `status` | `completed` or `blocked` |
+| `reviewed_at` | ISO-8601 timestamp with a UTC offset, quoted |
+| `implementation_target` | The diff, commit or paths reviewed, including a shared snapshot |
+
+## Presentation rules
+
+Keep the two level-two sections `Business` and `Evaluations`; use level-three/
+four headings to divide the content inside. Present QGs as a three-column
+table; each FIND/RISK/BLOCK and EVAL has its own two-column `Field | Content`
+table under a heading containing its ID. The `Next` part uses a two-column
+table. Do not merge several fields into one long bullet or cram all fields of a
+finding/evaluation into one overly wide table.
+
+This is only presentation: keep all fields, IDs, conclusions, evidence and
+instructions; do not drop information to make a table shorter. In each cell,
+use `<br>` when you need to separate several sources or processing steps; keep
+paths, symbols and commands intact. Escape a `|` that belongs to cell content
+as `\|`, including inside inline code, so it does not create a column. This
+escape rule applies only to Markdown tables and does not change values in the
+frontmatter. Put a blank line before/after each table.
+
+Replace placeholders with actual content and choose one value for each status
+or disposition. Each QG has exactly one row in the Quality gates table. Record
+only FINDs/RISKs/BLOCKs that actually exist; a group with no items uses one
+short sentence under its heading, with no empty table or fake ID. Number each
+kind consecutively, keeping the order findings, risks, then blockers. EVALs
+cover the settled Implement team in the Implementation Record's order; do not
+add an inventory or a third level-two section that repeats the handoff.
+
+## Placeholders in the template
+
+- `{{name}}`: computed values that `scripts/new_review.py` fills in from the
+  Plan and the earlier rounds. When a report is written without the script,
+  fill them by the rules above.
+- `<…>` and the `a / b` alternatives: the coordinator writes the actual content
+  and keeps exactly one alternative.

package/bundled-framework/files/.skills/pirl-review/scripts/new_review.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Create the report of the next Review round for a Plan task from the review skill's template.
+
+The layout, naming and location rules are owned by ../references/review-format.md; this script fills only
+what a tool can compute (plan_file, task ID, round, prior_review, timestamp, title) and leaves every <...>
+placeholder to the coordinator. Work that belongs to the current round edits that round's report instead.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[1]
+HUB = SKILL.parents[1]
+sys.path.insert(0, str(HUB / ".agents" / "evals"))
+from validate_layer_artifact import PLAN_SCHEMA, LayerArtifactError, read_frontmatter, resolve_path  # noqa: E402
+
+TEMPLATE = SKILL / "assets" / "review-template.md"
+SLUG = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+ROUND = re.compile(r"round-(\d{2,})-review-.+\.md")
+
+
+def shown(path: Path, root: Path) -> str:
+    """A path as Plans and reports write it: relative to the Hub root when inside it, otherwise absolute."""
+
+    return path.relative_to(root).as_posix() if path.is_relative_to(root) else path.as_posix()
+
+
+def create(root: Path, plan: str, todo_slug: str, out_dir: str | None) -> dict[str, object]:
+    if not SLUG.fullmatch(todo_slug):
+        raise LayerArtifactError("--todo-slug must be ASCII kebab-case")
+    plan_path = resolve_path(plan, root)
+    if not plan_path.is_file():
+        raise LayerArtifactError(f"{plan} is not an existing Plan file (relative to the Hub root or absolute)")
+    metadata, _ = read_frontmatter(plan_path)
+    if metadata.get("schema") != PLAN_SCHEMA or not metadata.get("plan_set") or not metadata.get("task_id"):
+        raise LayerArtifactError(f"{plan} is not a {PLAN_SCHEMA} Plan with plan_set and task_id")
+    task_id = str(metadata["task_id"])
+    folder = (resolve_path(out_dir, root) if out_dir else root) / str(metadata["plan_set"]) / f"{task_id.lower()}-{todo_slug}"
+    rounds = sorted((int(m.group(1)), p) for p in (folder.glob("*.md") if folder.is_dir() else []) if (m := ROUND.fullmatch(p.name)))
+    number = rounds[-1][0] + 1 if rounds else 1
+    prior = json.dumps(shown(rounds[-1][1], root), ensure_ascii=False) if rounds else "null"
+    now = datetime.now().astimezone()
+    target = folder / f"round-{number:02d}-review-{todo_slug}-{now:%Y%m%d-%H%M%S}.md"
+    if target.exists():
+        raise LayerArtifactError(f"{shown(target, root)} already exists")
+    text = (TEMPLATE.read_text(encoding="utf-8")
+            .replace("{{plan_file}}", shown(plan_path, root))
+            .replace("{{task_id}}", task_id)
+            .replace("{{review_round_padded}}", f"{number:02d}")
+            .replace("{{review_round}}", str(number))
+            .replace("{{prior_review}}", prior)
+            .replace("{{reviewed_at}}", now.isoformat(timespec="seconds"))
+            .replace("{{title}}", str(metadata.get("title") or "<Task name>")))
+    folder.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8", newline="\n")
+    return {"path": shown(target, root), "review_round": number, "prior_review": json.loads(prior)}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--plan", required=True, help="the reviewed Plan file, relative to the Hub root or absolute")
+    parser.add_argument("--todo-slug", required=True, help="ASCII kebab-case slug of the reviewed task")
+    parser.add_argument("--out-dir", help="directory holding the report's package folder, relative to the Hub root or absolute; default: the Hub root")
+    parser.add_argument("--root", type=Path, default=HUB, help="Hub root (default: the Hub containing this script)")
+    args = parser.parse_args()
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    try:
+        result = {"passed": True, **create(args.root.resolve(), args.plan, args.todo_slug, args.out_dir)}
+    except (LayerArtifactError, OSError) as exc:
+        result = {"passed": False, "errors": [str(exc)]}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())