@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/output-router/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: output-router
+description: Use after the Workflow, Decision Gate, or Discuss route is clear when choosing between native tools and Freeflow routed tools, retrieving repo/local/vault evidence, transforming bounded evidence, handling unknown-size or broad output, running likely-large/noisy commands, recovering vaulted output, tuning outputRouter/observedRouting/scriptTransform after setup, or handling optional native read/bash safety-net routing.
+---
+
+# Output Router
+
+Choose how evidence moves into context.
+
+Freeflow tools are the safe first choice for unknown-size, exploratory, repo-wide, generated/log-adjacent, structured, or likely noisy output, including broad `rg`/`find`/`git`/help/docs scans. Native tools stay direct for known-small, exact, intentionally raw, or mutating work. A post-hoc cap such as `head`, `sed -n`, `tail`, or `wc` does not make a broad producer known-small.
+
+Output Router does not classify the task. Workflow, Decision Gate, or Discuss decides whether to answer, ask, explore, plan, or stop. Output Router starts after that route is clear.
+
+## First Decision
+
+Ask what kind of data you need:
+
+- Existing repo, explicit local, or vault data: use `freeflow_search`.
+- New command or script-produced output: use `freeflow_run`.
+- Several independent Freeflow operations: use `freeflow_batch`.
+- Config/status/vault/script-adapter facts: use `freeflow_status`.
+- Enabled MCP/web/fetch/code-search output: call the host tool directly; Pi observed routing runs after the host result when configured.
+- Known whole file, intentionally exact shell behavior, cmux/Pi control probes, explicit fallback after a routed-source limitation, or edits: use native `read`, `bash`, `edit`, or `write`.
+
+When unsure how much output will return, use Freeflow first. Bound the producer before using native tools; do not rely on trimming the output after a broad command runs.
+
+## `freeflow_search`: Existing Data
+
+Use `freeflow_search` for repo files, explicit external local files, and vaulted output that already exists.
+
+Actions:
+
+- `locate`: find likely paths/output ids first. Use before reading when you only need candidates.
+- `query`: return the best focused evidence packets for a search question.
+- `get`: user gave exact-ish text/code/snippet or asks “where is this?” Find the best match and return source coordinates plus matched content.
+- `retrieve`: you already know the path/outputId and line range. Return those exact lines. Do not use this as search.
+- `expand`: widen a previous evidence packet.
+- `explain`: explain a previous routed decision or vault output/recoverability.
+- `transform`: compute facts or deterministic subsets from repo/local/vault/file/output data.
+
+Use `source.kind="repo"` for the current checkout. Use `source.kind="local"` for external local docs/files with an explicit absolute `root` and optional relative `path`; do not put local roots in shared config. Use `source.kind="vault"` for previous Freeflow outputs.
+
+Vault search patterns:
+
+- Unknown output id: `source.kind="vault"` without `outputId`, plus `query` and optional `filters`.
+- Known output id and unknown line: `action="query"` or `get` with `source.outputId`.
+- Known output id and known line range: `action="retrieve"` with `lineRange`.
+- Metadata-only result: use `action="explain"`; do not claim raw recovery.
+
+Use `preserve="full"` only when exact fidelity matters. It still means exact-under-caps, not unlimited context injection.
+
+## `freeflow_search action=transform`: Processing Existing Data
+
+Use transform when raw data is too large/structured and you need computed facts.
+
+Good transform cases:
+
+- logs: status counts, error rates, slow examples,
+- JSON/CSV: counts, groupings, top values, extracted fields,
+- test/build/typecheck output already in the vault,
+- MCP/web/fetch/code-search payloads already routed into the vault,
+- deterministic regex filtering, match counts, grouping, dedupe, topN, URL/citation extraction, line/size stats.
+
+Prefer deterministic operations when enough:
+
+- `regexFilter`, `countMatches`, `jsonExtract`, `groupByRegex`, `dedupe`, `topN`, `extractUrls`, `extractCitations`, `lineStats`, `sizeStats`.
+
+Use scripts only when deterministic operations cannot express the fact:
+
+- `operation.kind="script"` runs a sandboxed transform over vault sources.
+- `script` without `operation` runs the processing-engine script path over repo/local/vault sources.
+- Sandboxed scripts require `scriptTransform.enabled=true` and a proof-backed adapter.
+- Raw script code is not persisted; metadata stores hashes/labels/limits.
+- No sandboxed script path may silently fall back to host shell execution.
+
+Unsafe unsandboxed processing is local-only, explicit per call, and only through the processing script policy. It must say `unsafe/unsandboxed`. Never put that opt-in in shared config.
+
+## `freeflow_run`: New Output
+
+Use `freeflow_run` when the producer creates new output and routed evidence is enough.
+
+Base producers are mutually exclusive:
+
+- `command`: shell command through the host-approved runner.
+- `script`: sandboxed code-as-producer with no repo/home/env/network/vault access.
+
+Use `command` for:
+
+- tests, builds, lint, typecheck, CI-like checks,
+- broad shell search with unknown output size,
+- commands likely to print logs, JSON, status, or diagnostics,
+- commands whose exact raw output may need recovery.
+
+Use `script` for:
+
+- generating data with code when no repo/home/env/network access is needed,
+- safe code-as-producer execution through the same sandbox engine as transforms,
+- stdout/stderr capture that should route like command output.
+
+Do not use `freeflow_run script` when the code needs repo files, environment variables, network, package imports, or host filesystem access. Use a host command intentionally, or transform an explicitly captured source.
+
+Run modifiers:
+
+- `goal`: tell the router why the run exists, e.g. `verification`, `diagnosis`, `build`, `log analysis`.
+- `filters`: deterministic line filtering over captured stdout/stderr/combined.
+- `scriptFilter`: sandboxed script over already captured stdout/stderr/combined. It never reruns the base producer.
+- `preserve="full"`: request exact output under caps with vault recovery over cap.
+
+Run storage:
+
+- Default `hybrid-dedupe` stores exact output when exactness-sensitive and metadata-only for small non-sensitive successes.
+- Failures, verification/test/build/typecheck/diagnosis output, `preserve="full"`, filters, script filters, reducers, script producers, and large/noisy output are exactness-sensitive.
+- Exact duplicates may store current metadata pointing to a previous exact `outputId`.
+- Plain metadata-only records get rerun guidance, not exact recovery claims.
+
+## `freeflow_batch`: Independent Freeflow Work
+
+Use `freeflow_batch` when several Freeflow-owned `run` or `search` steps can happen independently.
+
+Good batch cases:
+
+- run several bounded searches in parallel,
+- run independent checks and ask `queries[]` to extract facts from child evidence,
+- gather multiple repo/local/vault facts without injecting every child result.
+
+Do not use batch for:
+
+- sequenced workflows,
+- arbitrary external tool orchestration,
+- mutating work,
+- steps where one child needs another child’s output.
+
+Child outputs remain in `details.result.steps`; exact child run output remains recoverable by child `outputId`.
+
+## Native Tools
+
+Use native tools when direct behavior is the point:
+
+- `read`: known whole file or exact direct file content is intended.
+- `bash`: expected-small exact shell behavior, host access, cmux/Pi control probes, or bounded producer behavior is intentionally needed.
+- `edit` / `write`: mutations.
+
+Native `bash`/`read` remain valid for known-small exact checks, cmux/Pi control probes, exact file reads, or explicit fallback after a routed-source limitation; name the limitation and keep the fallback narrow.
+
+Do not run broad native commands just to see what comes back. `head`, `sed -n`, `tail`, `wc`, or similar output caps bound visible text, not producer scope or relevance. Likely-large native commands include repo-wide `rg`, `grep -R`, `find`, package scans, generated-artifact scans, docs/help scans, logs, broad `git diff/log`, full tests/builds/lints/typechecks, and one-off scripts with unknown output size.
+
+If native read/bash safety net is enabled, large/noisy native output may be replaced with labeled Freeflow-routed output. It must include an `outputId` and recovery instructions. If safety-net routing fails, native output passes through with a warning.
+
+## Observed Routing
+
+For enabled Pi MCP/web/fetch/code-search producers, call the host tool directly. Freeflow observes the completed result after host execution.
+
+Observed routing:
+
+- is off by default,
+- is explicit per producer/server,
+- does not grant permissions or block host tools,
+- can persist exact output, metadata-only, or nothing depending on config,
+- fails open with original host output if routing fails.
+
+Mutating MCP/tool calls still require normal workflow/interview judgment before the host call. Observed routing is not permission approval.
+
+## Hard Rules
+
+- Do not pretend routed output is native output.
+- Do not silently shorten native output.
+- Capture raw output before transforming it.
+- Keep raw source recovery separate from transformed/reduced output recovery.
+- Treat `preserve="full"` as exact fidelity under caps, not unlimited context injection.
+- Preserve exact failure and verification evidence lines.
+- Keep `toolStatus`, `execution.status`, and `routing.status` separate.
+- Metadata-only records must never claim exact raw recovery.
+- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
+- Do not write removed `capture` or `providers` config.
+- Do not offer `redacted`; it is future-only.
+
+## Recovery Pattern
+
+For routed run/native/observed/transform output, recover exact text with:
+
+```json
+{
+  "action": "retrieve",
+  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "stdout|stderr|combined|raw" },
+  "lineRange": { "start": 1, "end": 20 },
+  "preserve": "full"
+}
+```
+
+When line numbers are unknown, use `query` or `get` first. Use `expand` when a returned evidence packet is too narrow. Use `explain` when recoverability is unclear.
+
+## Config
+
+Use `freeflow_status` to inspect effective config, vault writability/index state, script adapters, observed routing, and migration recommendations.
+
+Use `../setup-freeflow/SKILL.md` for installation, invalid-config repair, or the initial optional-capabilities branch. After valid setup, Output Router owns explicit operational tuning requested through its capability surface.
+
+Persist operational config only after an explicit tuning request or a previously accepted setup branch:
+
+- `outputRouter`: `enabled`, `profile`, `postToolRouting`, `storagePolicy`, thresholds, vault root/retention, generated paths, noisy command hints.
+- `outputRouter.observedRouting`: explicit MCP servers and web/fetch/codeSearch producer persistence.
+- `outputRouter.scriptTransform`: enabled flag, languages, sandbox/network/limits/raw-script persistence.
+
+Minimal setup stays only `defaultMode`. Missing optional sections mean built-in defaults.
+
+Read [the safety policy](references/safety-policy.md) before changing routing policy, reviewing router behavior, or handling exactness-sensitive output.

package/skills/output-router/references/safety-policy.md

@@ -0,0 +1,40 @@
+# Output Router Safety Policy
+
+Reference-only policy for exactness-sensitive output routing. Pi runtime context does not load this whole file by default; the active `output-router` skill carries the compact rules. Read this file before changing routing policy, reviewing router behavior, or handling a new exactness-sensitive output class.
+
+## Main Rule
+
+Do not silently summarize, compress, or replace exactness-sensitive output.
+
+Exactness-sensitive output includes:
+
+- user-requested exact/full output,
+- small native outputs where direct output is expected,
+- verification output needed for completion claims,
+- failure evidence needed for diagnosis,
+- source-truth conflict evidence,
+- security, privacy, billing, data-loss, permissions, or public API evidence,
+- failed, timed-out, or cancelled run output,
+- script-producer output,
+- filtered, script-filtered, reduced, or transformed output where raw source matters,
+- anything marked `preserve: full`.
+
+## Required Behavior
+
+- Capture raw evidence before transformation whenever output is routed.
+- Label every transformed native or observed result as Freeflow-routed output.
+- Include an `outputId` and exact recovery instructions when exact recovery exists.
+- Preserve exact failure and verification evidence lines; do not paraphrase them.
+- Pass small native outputs through unchanged unless explicit config and thresholds route them.
+- For huge exactness-sensitive output, use vaulting and exact chunk retrieval instead of lossy summarization.
+- If post-tool native safety-net routing fails, fail open: return the native output unchanged when possible and include a warning.
+- Keep raw source recovery separate from transformed/reduced output recovery.
+- Metadata-only records must never claim exact raw recovery. Duplicate metadata may point to a prior exact `outputId`; plain metadata-only records get rerun or explanation guidance.
+
+## Non-Goals
+
+- This policy does not enable post-tool routing by itself.
+- This policy does not authorize model-assisted summarization inside the router runtime.
+- This policy does not authorize unsandboxed script execution.
+- This policy does not require Pi runtime context to inject the full reference every turn.
+- This policy does not replace host permissions, sandboxing, approvals, or workflow/decision gates.

package/skills/release-work/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: release-work
+description: Use when preparing, publishing, or verifying a versioned software release.
+---
+
+# Release Work
+
+Prepare or publish a traceable versioned artifact whose source, version, contents, and destination identity agree.
+
+A commit is not a release. A tag does not prove which artifact was built. A successful local build does not prove registry contents. A published artifact is not a production deployment.
+
+## Establish Authority And Source
+
+Loading this skill, preparing release options, or approving a general implementation Plan does not authorize a version change, remote tag, release record, registry publication, deprecation, yank, or replacement. Execute only release stages explicitly requested or separately approved. Before editing, read the repository's release policy, versioning scheme, package metadata, changelog convention, release automation, supported branches, signing or provenance requirements, and latest published versions.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when the route depends on an unresolved choice about:
+
+- whether to release and which channel or audience receives it;
+- compatibility or breaking-change classification;
+- version when policy and evidence do not decide it;
+- credentials, registry, signing, provenance, or remote-tag behavior;
+- yanking, deprecating, replacing, or republishing an artifact;
+- release branches, history rewriting, or recovery from partial publication.
+
+Do not impose semantic versioning when the project uses another scheme. Read [release evidence](references/release-evidence.md) when version, source, artifact, tag, publication, or recovery identity matters.
+
+## Define The Release Contract
+
+Before changing release state, establish:
+
+```text
+Release target and audience:
+Source commit / branch:
+Version and compatibility basis:
+Artifacts and supported platforms:
+Release notes / migration guidance:
+Required checks and selected reviews:
+Signing / provenance / checksums:
+Publication destination and channel:
+Failure and recovery behavior:
+Post-publication verification:
+Approved preparation and publication stages:
+```
+
+Classify consumer-observable impact rather than diff size. A small change can be breaking; a large internal refactor may preserve compatibility.
+
+When consumers must move before a contract can be removed, read [Migration Work](../migration-work/SKILL.md). An additive replacement release may precede migration; a breaking removal release must wait for the accepted migration and removal proof.
+
+## Prepare The Release
+
+For approved preparation work:
+
+- confirm the intended source is a coherent, freshly verified checkpoint and any selected review is resolved;
+- reconcile version declarations, lockfiles, generated metadata, and release notes through repository-supported tooling;
+- write release notes for consumers: behavior, compatibility, migration, security impact, and known limitations—not a raw commit dump;
+- run the canonical build or package process from the intended source state;
+- inspect the exact artifacts that would be published;
+- keep credentials and signing material out of prompts, logs, diffs, and artifacts.
+
+Do not hand-edit generated artifacts or duplicate version truth when the repository has a canonical generator. Return required branch, commit, public-documentation, or migration work to [Workflow](../workflow/SKILL.md) unless it is included in the approved release scope.
+
+## Preflight The Exact Release
+
+Before any irreversible remote action, verify:
+
+- source commit, branch, and working-tree expectations;
+- version is valid, unused, and consistent with repository policy;
+- required tests, builds, package or install checks, and compatibility checks;
+- artifact contents, entry points, names, sizes, checksums, licenses, and provenance;
+- release notes and migration guidance match observable consumer impact;
+- tag, registry, channel, and release destination identity;
+- credentials and permissions work without exposing secrets;
+- retry behavior cannot create conflicting tags or duplicate releases.
+
+Use [Verify Work](../verify-work/SKILL.md) to state what each check proves. A dry run proves only the boundaries it exercises; name signing, registry, propagation, or publication behavior that remains unverified.
+
+## Publish Only The Approved Stage
+
+Create remote tags, release records, or registry publications only when explicitly requested or approved for the inspected release contract.
+
+Use the repository's canonical order. Stop when source, version, tag, artifact, signing mode, channel, or destination identity diverges.
+
+Do not silently:
+
+- overwrite an existing version;
+- force-move a release tag;
+- publish from a dirty or different source state;
+- substitute a registry, channel, artifact, or signing mode;
+- retry an ambiguous publication without inspecting remote state.
+
+If publication partially fails or acknowledgement is lost, identify which external effects committed before choosing retry, repair, deprecation, replacement, or stop. Do not assume a network error means nothing was published.
+
+## Verify From The Consumer Boundary
+
+When publication is in scope, verify the actual public artifact when possible:
+
+- tag resolves to the intended commit;
+- published version, channel, and destinations are correct;
+- checksums, signatures, provenance, and contents match the inspected artifact;
+- a clean install, download, or launch path works for supported targets;
+- release notes and migration links resolve;
+- no unexpected artifact, credential, local configuration, or private file was published.
+
+Do not call the release complete because the publish command exited successfully. Unavailable propagation or consumer evidence leaves the corresponding claim unverified.
+
+## Report Completion Precisely
+
+Report:
+
+- approved release stage and status;
+- version, source commit, tag, channel, and destinations;
+- compatibility basis and migration guidance;
+- checks, artifact identity, and selected-review status;
+- publication and consumer-side verification;
+- partial failures, recovery actions, and residual risk;
+- any deferred commit, migration, launch, or documentation work.
+
+A prepared release is not published. A published release is not deployed. Use [Launch Work](../launch-work/SKILL.md) only when production deployment or rollout is separately requested or approved.

package/skills/release-work/references/release-evidence.md

@@ -0,0 +1,78 @@
+# Release Evidence
+
+Read this when version, source, artifact, tag, publication, or recovery identity matters.
+
+## Version Basis
+
+Use the repository's declared scheme. For semantic versioning, classify consumer-observable impact:
+
+- **Major:** supported consumers must change or accepted behavior is removed/incompatible.
+- **Minor:** backward-compatible capability is added.
+- **Patch:** backward-compatible defect correction.
+
+Prerelease channels, date versions, train versions, and application builds may use different policy. Do not impose SemVer universally.
+
+When compatibility is uncertain, inspect supported consumers and ask rather than selecting the smallest bump.
+
+## Identity Chain
+
+A trustworthy release can connect:
+
+```text
+source commit
+-> freshly verified release state
+-> version metadata
+-> build invocation and environment
+-> artifact digest / signature / provenance
+-> immutable tag or release record
+-> registry or distribution entry
+-> consumer-side install evidence
+```
+
+Name missing links instead of implying reproducibility.
+
+## Release Notes
+
+Write for consumers:
+
+- added or changed behavior;
+- fixed user-visible defects;
+- deprecated and removed contracts;
+- security impact without unsafe disclosure;
+- migration and compatibility requirements;
+- known limitations and unsupported targets.
+
+Commit history can support notes but does not replace curation.
+
+## Artifact Inspection
+
+Check as relevant:
+
+- included and excluded files;
+- executable entry points and permissions;
+- generated code and source maps;
+- dependency and lockfile state;
+- licenses and notices;
+- platform/architecture variants;
+- debug, test, local config, credentials, and private files;
+- deterministic digest or signed provenance.
+
+Use the package manager or build system's dry-run/list command when available.
+
+## Publication Failure Contract
+
+Before publication, know:
+
+- which step first creates irreversible remote state;
+- whether a version/tag can be retried idempotently;
+- how to detect a committed but unacknowledged publish;
+- whether repair, deprecation, yank, or replacement is supported;
+- who owns consumer communication.
+
+Network failure after a remote commit is ambiguous. Inspect remote state before retrying.
+
+## Consumer Verification
+
+Prefer a clean environment that does not reuse the local checkout or cache unexpectedly.
+
+Verify the actual public artifact by version or digest. A successful local build cannot prove registry contents, install metadata, signatures, or distribution propagation.

package/skills/review-artifact/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: review-artifact
+description: Use when reviewing a Working Record, spec, PRD, issue, API contract, technical design, migration contract, plan, decision record, ADR, handoff, or other durable artifact for fitness to guide its intended use.
+---
+
+# Review Artifact
+
+Judge whether an artifact is aligned, sufficient, and fit to guide its intended use.
+
+## Choose The Review Role
+
+Choose the role before reviewing:
+
+- **Self-review:** you produced the artifact. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
+- **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
+
+Reading this skill does not create independence. If you produced the artifact, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
+
+## Establish The Boundary
+
+Understand:
+
+- artifact type, current state, and intended use;
+- accepted outcome, requirements, and non-goals;
+- owner decisions and unresolved questions;
+- relevant code, tests, policies, ADRs, and established behavior;
+- upstream and downstream artifacts;
+- evidence gaps and prior review when applicable.
+
+Review the complete current artifact, not only its summary, change description, or author's reasoning. Review upstream authority before dependent artifacts. If an upstream issue invalidates downstream assumptions, mark affected material contingent instead of generating exhaustive findings against an unresolved basis.
+
+When reviewing a Working Record, read [Track Work](../track-work/SKILL.md), which owns its format and lifecycle.
+
+## Judge The Artifact By Its Job
+
+- **Working Record:** living task memory with accurate current state, recoverable slices and decisions, compact evidence pointers, and one next useful action.
+- **Spec or durable content artifact:** accepted content, behavior, boundaries, evidence, and uncertainty needed for its stated use.
+- **Plan:** an inspectable ordered strategy with scope, dependencies, assumptions, checks, and stop conditions.
+- **Decision record or ADR:** decision, owner, alternatives, rationale, consequences, and revisit or supersession conditions.
+- **Handoff:** a point-in-time continuation package that preserves what its recipient needs without replacing live task memory.
+- **Other artifact:** its stated purpose without taking over another artifact's job.
+
+## Review Proportionately
+
+Apply only lenses that can materially change fitness:
+
+- **Source alignment:** agrees with accepted requirements, owner decisions, and live facts.
+- **Fitness and sufficiency:** contains enough for its intended use without pretending every future question is settled.
+- **Decision clarity:** required, tentative, open, deferred, and superseded information cannot be confused.
+- **Evidence and acceptance:** load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
+- **Behavior and failure contract:** consequential states, forbidden outcomes, observers, and recovery are explicit where required.
+- **Dependency integrity:** upstream and downstream artifacts remain consistent; provisional work is identified honestly.
+- **Scope and minimality:** avoids speculative design, unnecessary process, and hypothetical completeness.
+- **Clarity and continuity:** a future reader can use it without transcript memory or volatile copied context.
+
+A pass is valid. Do not invent items, require exhaustive edge cases, report wording or filename preferences, reopen intentional deferrals, or demand evidence needed only for a later boundary.
+
+## Classify Independent Review Items
+
+- **Blocking Issue:** a supported defect, inconsistency, omission, or risk that must be resolved before the artifact guides its intended use.
+- **Non-blocking Issue:** a real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirements, or an owner decision is unclear.
+- **Needs evidence:** a load-bearing claim or condition cannot be established.
+- **Improvement:** a materially useful enhancement not required by this boundary. It does not affect judgment or authorize revision.
+
+A Blocking Issue must name the exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
+
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
+
+Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the artifact passes.
+
+## Adjudicate And Route
+
+After independent review, the receiving active agent adjudicates each item against the artifact, source truth, and evidence:
+
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, outside the artifact's job, or based on a source misread.
+- **Open:** a question or evidence gap prevents acceptance or rejection.
+
+Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
+
+Route from the adjudicated result:
+
+- **Pass:** use the artifact for its intended purpose.
+- **Non-blocking:** use it with explicit deferrals.
+- **Inconclusive:** gather the missing evidence or decision.
+- **Blocking:** do not use the artifact across the blocked boundary; re-enter its narrowest owner, defer, or stop.
+
+Review findings are evidence, not commands. They do not authorize revision. Accepted revisions leave review and return to the artifact's owning skill; they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+
+When revision authority is not already explicit, ask once for either:
+
+- the accepted revisions plus one warranted focused follow-up review; or
+- the accepted revisions alone when direct source evidence can settle the changed boundary.
+
+Then wait for the user's response. Do not revise or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded revision or review.
+
+Run a follow-up only when the changed boundary or affected dependencies still need independent judgment and that dispatch is authorized. Do not revise source truth, accepted intent, or owner decisions merely to satisfy a reviewer or obtain Pass.
+
+## Limit The Review Cycle
+
+For one independently reviewed artifact state and intended-use boundary:
+
+1. Review 1 is the normal broad review.
+2. Review 2, when needed and authorized, focuses on accepted revisions, affected dependencies, and remaining risk.
+3. Review 3 is exceptional, authorized separately, and final for that cycle.
+
+The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the artifact may be used, remain blocked, re-enter its owner, defer, or stop.
+
+After Review 2 is adjudicated Blocking, stop before proposing another revision or Review 3. Classify its relationship to the prior revision:
+
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior revision, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another revision.
+- If it is an independent clear local defect with a supported cause, return directly to the artifact's owner and state why diagnosis is unnecessary.
+
+A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and revision boundary are understood, not a third attempt to discover the cause through revisions. Workflow may later establish a new cycle only for a materially new artifact state and intended-use boundary; local edits, a different reviewer, or renamed scope do not reset it.
+
+## Report
+
+For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change fitness or route.
+
+For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, affected dependencies, remaining open items, and authorized or proposed next route.
+
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.