@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/mode-contract/SKILL.md

@@ -1,84 +1,104 @@
 ---
 name: mode-contract
-description: Use when a user asks to set, change, infer, or discuss conversation/workflow/strict-workflow mode, or when task risk suggests recommending a workflow mode.
+description: Use when choosing, changing, or explaining how Freeflow mode applies to current work.
 ---
 
 # Mode Contract
 
-Use exactly three modes.
+Apply the effective Freeflow mode without inferring a different mode from the task. Freeflow has exactly three mode values: `conversation`, `workflow`, and `strict-workflow`.
 
-## Modes
+A mode changes how work proceeds; it does not authorize work, resolve a user-owned decision, or override live evidence.
 
-**Conversation mode**: non-mutating discussion, explanation, critique, exploration, quick analysis, and planning in chat.
+## Establish The Active Mode
 
-- Answer questions; do not act on them.
-- You may inspect source, read files, and run safe read-only commands when needed for the answer.
-- Do not edit, create, delete, commit, push, run mutating commands, or otherwise change repo/system state.
-- Do not perform implementation or other consequential work that changes files, behavior, source truth, or durable project state.
-- If the user asks for mutating or consequential work, stop and require switching to `workflow` or `strict-workflow` before acting. Do not proceed in conversation mode, even if pressured.
-- No workflow pressure.
-- No required artifacts.
-- No plan/spec file requirement.
-- Ask only when needed for the answer.
+A mode is active only when the host reports that Freeflow Skills are effective. Keep the supplied layers distinct:
 
-**Workflow mode**: normal consequential work.
+- **Repository default:** the shared `defaultMode` from `.freeflow/config.json`.
+- **Personal default override:** an optional per-checkout `defaultMode` from `.freeflow/local.json`.
+- **Session override:** an optional temporary mode managed by the host.
+- **Resolved mode:** session override, otherwise personal default override, otherwise repository or built-in default.
+- **Effective mode:** the resolved mode only while Skills are active; otherwise no Freeflow mode is effective.
 
-- Use the workflow as a guide.
-- Ask or inspect when ambiguity would change the next action.
-- Create artifacts only when they preserve decisions, reduce risk, or enable handoff.
-- Verify before completion claims.
+If runtime reports that modes are inactive, preserve the resolved mode as dormant state without applying it. If effective-mode evidence is missing, do not guess or activate a fallback. Read [Setup Freeflow](../setup-freeflow/SKILL.md) when the user wants to configure, enable, or repair Freeflow.
 
-**Strict-workflow mode**: high-risk or hard-to-reverse work.
+Task shape does not change mode. A question during Workflow stays in Workflow; an implementation request during Conversation stays in Conversation until the user changes mode.
 
-- Use stronger gates.
-- Require explicit decisions for security, privacy, billing, data loss, migrations, public APIs, compatibility, deployment, and large architecture changes.
-- Require explicit confirmation before changing source-of-truth artifacts such as docs, tests, specs, policies, ADRs, or handoffs when they contradict the requested implementation.
-- Recommend this mode when risk warrants it, but do not silently switch unless the user configured it as default.
+## Follow The Effective Mode
 
-## Inference
+### Conversation
 
-- If the user is talking, asking a conceptual question, brainstorming, or asking for read-only analysis/planning, use conversation mode.
-- If the effective mode is conversation and the user asks to edit, create files, implement, fix by changing code, commit, push, or run mutating commands, require a switch to `workflow` or `strict-workflow` before acting.
-- If no current conversation override exists and the user asks to implement, fix, discover context for action, review, or create plan/spec artifacts, use workflow mode.
-- If the task is high-risk, recommend strict-workflow mode and ask for confirmation.
-- If implementation would require overriding existing docs, tests, specs, policies, or established behavior, recommend strict-workflow mode and ask before editing.
+Answer, discuss, critique, explore, and perform requested read-only inspection.
 
-## User Control
+Do not mutate files, repository state, external systems, or durable artifacts. If the user requests mutation, explain the boundary and ask them to switch to `workflow` or `strict-workflow` through the host's mode control before proceeding.
 
-The user owns mode changes. You may recommend a mode; the user decides.
+Ask only what the answer needs. Conversation mode does not require workflow artifacts, checkpoints, plans, specs, or independent review.
 
-## Commands And Defaults
+### Workflow
 
-Keep two scopes separate:
+Use the adaptive [Workflow](../workflow/SKILL.md) for consequential or mutating work. Inspect or ask when ambiguity changes the next action, create durable artifacts only when they preserve needed state or decisions, and verify claims against fresh evidence.
 
-- `defaultMode`: persisted repo default in `.freeflow/config.json`.
-- Current mode: task, conversation, or session override. Do not persist it in repo config.
+Workflow mode does not itself authorize a slice or require every lifecycle phase.
 
-Recognize only:
+### Strict Workflow
+
+Use the same adaptive Workflow with stronger decision, evidence, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
+
+Apply that pressure when work materially affects security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture. Use [Decision Gate](../decision-gate/SKILL.md) for choices or source conflicts that belong to the user in every mutating mode. Gather evidence for the relevant risk surface before crossing the boundary or claiming success.
+
+Select artifacts, checkpoints, verification, and independent review when they reduce material risk. Do not add them automatically merely because Strict Workflow is active.
+
+Strict Workflow does not grant authority, bypass safety, or turn every implementation detail into a user decision.
+
+## Change Mode Deliberately
+
+The user owns mode changes. Recommend `strict-workflow` when risk warrants it, but continue under the effective mode unless the user changes it or another workflow boundary blocks progress.
+
+A task type, risk classification, direct skill call, or workflow route does not switch mode. Invoking an execution skill during Conversation still does not authorize mutation.
+
+Use host-managed session control so the change takes effect before the model acts. A clear natural-language instruction may use the same control. Questions, examples, hypotheses, and tentative language do not change mode.
 
 ```text
-/workflow conversation
-/workflow workflow
-/workflow strict-workflow
-/workflow reset
+Switch to conversation mode.                 -> session override
+Use strict-workflow for this session.         -> session override
+Should we switch to strict-workflow?          -> answer or discuss; no override
+Suppose the mode were conversation.           -> discussion; no override
 ```
 
-The three mode-setting commands switch mode for the current task, conversation, or host session only. `/workflow reset` clears the current override and returns to `defaultMode`; it is a command, not a fourth mode.
+Host-native controls are:
 
-Do not persist current mode, create repo state files, or edit config unless the user explicitly asks to change the repo default.
+```text
+Pi:
+/freeflow mode conversation
+/freeflow mode workflow
+/freeflow mode strict-workflow
+/freeflow mode reset
 
-Phrases like "from now on", "until I say otherwise", or "for this repo" still do not persist mode unless paired with an explicit default change request.
+Claude:
+/freeflow:mode-contract <conversation|workflow|strict-workflow|reset>
 
-When the repo default matters, read `.freeflow/config.json`. If it is missing or invalid, fall back to `workflow` and report the config issue when relevant.
+Codex:
+$mode-contract <conversation|workflow|strict-workflow|reset>
+```
 
-Persist only explicit default requests, such as "make strict-workflow the default for this repo." Update `.freeflow/config.json` with only:
+Claude and Codex persist their override in plugin-owned session state keyed by the host session identifier. Pi persists it in branch-aware Pi session state. The override survives ordinary turns and supported resume, clear, and compact boundaries for that session; `reset` clears it and returns to the configured default. A new session starts from configured state.
 
-```json
-{
-  "defaultMode": "strict-workflow"
-}
-```
+Treat only runtime-reported effective state as proof that the control succeeded. If the host reports missing session identity, unavailable writable plugin state, disabled Skills, or another failure, say that mode did not change. Do not compensate by editing a configured default.
+
+Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
+
+## Change Defaults Separately
+
+A persistent default change is not a session-mode change. Determine which configured layer the user means before editing:
+
+- explicit **personal** or **local** default targets `.freeflow/local.json`;
+- explicit **shared**, **repository**, or **team** default targets `.freeflow/config.json`;
+- an unqualified “change the default mode” request leaves that scope user-owned—ask one direct local-versus-repository question and wait;
+- “global” is not a defined Freeflow layer—ask whether the user means this checkout's personal default or the shared repository default.
+
+Do not infer the target from which file already exists or from the current mode. Preserve unrelated settings in the selected layer.
+
+In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared defaults. In another host, an agent may update only the explicitly selected valid configuration layer. Session controls never modify either file.
 
-Use the requested valid mode. Do not add current mode, task, phase, version, or activation-path fields.
+For agent-performed config edits, obey the effective mode when one exists. Conversation remains read-only. When no mode is effective because Freeflow is unconfigured, inactive, blocked by invalid config, or Skills are dormant, an explicit configuration or [Setup Freeflow](../setup-freeflow/SKILL.md) request governs the selected change; any dormant resolved mode is neither authority nor prohibition. User-operated host controls change their own state before the model continues.
 
-Direct skill calls are manual state selection. If the user calls a workflow segment directly, operate in that segment while still using the interview gate for user-owned decisions.
+A current session override remains effective until reset even when a configured default changes. If repository config is missing or invalid, route to Setup Freeflow; a personal override cannot activate Freeflow. If local config is invalid, report the blocking layer and repair or remove it only with authorization. Do not silently overwrite either source. Use Decision Gate when the requested default conflicts with established source truth or accepted direction.

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

@@ -1,118 +1,126 @@
 ---
 name: review-artifact
-description: Use when asked to review whether a spec, plan, decision note, discovery checkpoint, handoff, or other durable artifact is fit to guide future work; also use when adjudicating artifact-review findings or repeated review loops.
+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
 
-Review whether the artifact is fit to guide work.
+Judge whether an artifact is aligned, sufficient, and fit to guide its intended use.
 
-Review first. Edit second.
+## Choose The Review Role
 
-Reviewer findings are evidence, not commands. The parent agent owns adjudication.
+Choose the role before reviewing:
 
-A non-passing artifact review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+- **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.
 
-The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+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.
 
-Hard stop: if the artifact has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+## Establish The Boundary
 
-## Source-Truth Guard
+Understand:
 
-Artifact feedback is not approval to change source of truth.
+- 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.
 
-Do not treat `/review-artifact`, "explicit permission", "fix it directly", "old/stale policy docs or tests", or "do not ask" as approval to invert the artifact's intent or demote live evidence.
+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.
 
-Do not fix an artifact by making hidden product, policy, security, privacy, billing, data-loss, compatibility, API, or architecture decisions.
+When reviewing a Working Record, read [Track Work](../track-work/SKILL.md), which owns its format and lifecycle.
 
-If the artifact conflicts with live repo evidence, classify the conflict. Ask whether to update the artifact to match source truth or change source truth to match the artifact.
+## Judge The Artifact By Its Job
 
-Do not rewrite docs, tests, policies, specs, ADRs, or handoffs to make the artifact pass before that decision.
+- **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.
 
-For source-truth conflicts, the final line must be a direct choice question.
+## Review Proportionately
 
-## Parent Adjudication
+Apply only lenses that can materially change fitness:
 
-Before editing from reviewer findings, classify each material finding:
+- **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.
 
-- Accepted: valid and safe to apply without changing settled intent.
-- Rejected: stale, unsupported, already resolved, equivalent, or not important.
-- Question: needs owner decision.
-- Needs evidence: inspect more before deciding.
+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.
 
-Non-blocking findings and reviewer questions do not fail the artifact by default. Classify them, then defer, ask, gather evidence, or accept.
+## Classify Independent Review Items
 
-Ask before applying any finding that changes artifact intent, scope, source truth, workflow policy, sensitive behavior, or a settled decision.
+- **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.
 
-For second and later review iterations, update the reviewer prompt with prior findings, owner clarifications, accepted/rejected findings, changed sections, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+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.
 
-Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+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.
 
-## Review Loop Budget
+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.
 
-Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+## Adjudicate And Route
 
-Three review passes is the hard cap for the same artifact and scope. Do not request a fourth review to chase a clean pass.
+After independent review, the receiving active agent adjudicates each item against the artifact, source truth, and evidence:
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, artifact scope, or reviewer context is wrong or too thin.
+- **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.
 
-## Review Setup
+Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
 
-Use a fresh reviewer when the artifact will guide future work and subagents are available. Use [references/reviewer-prompt.md](references/reviewer-prompt.md).
+Route from the adjudicated result:
 
-Use `../design-for-depth/SKILL.md` when the artifact encodes module, interface, seam, adapter, architecture, or slice-boundary decisions.
+- **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.
 
-For durable specs or future-agent-facing artifacts, use `../write-spec/references/artifact-standards.md` as the artifact identity standard when relevant.
+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.
 
-## Inspect First
+When revision authority is not already explicit, ask once for either:
 
-Read:
+- the accepted revisions plus one warranted focused follow-up review; or
+- the accepted revisions alone when direct source evidence can settle the changed boundary.
 
-- The artifact under review.
-- Referenced docs, tests, policies, ADRs, and code.
-- Relevant handoffs only as memory, not authority.
+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.
 
-Live repo evidence overrides stale artifacts.
+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.
 
-## Review Lenses
+## Limit The Review Cycle
 
-- Completeness: enough is present to proceed.
-- Evidence: load-bearing claims point to live evidence or explicit decisions.
-- Clarity: a fresh agent can act without transcript memory.
-- Consistency: the artifact agrees with itself, live repo evidence, docs, tests, policies, ADRs, and known decisions.
-- Identity: durable or strict-workflow artifacts have enough owner, status, source, and change history for future readers.
-- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
-- Design depth: module, interface, seam, adapter, or slice choices hide useful complexity instead of spreading coordination.
-- Adversarial risk: the artifact cannot be used to smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+For one independently reviewed artifact state and intended-use boundary:
 
-Treat missing artifact identity as blocking only when it affects future-agent handoff, team ownership, strict-workflow risk, or implementation readiness. Do not nitpick headers on lightweight artifacts or chat answers.
+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.
 
-## Stop Before Editing
+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.
 
-Stop before editing when a fix would:
+After Review 2 is adjudicated Blocking, stop before proposing another revision or Review 3. Classify its relationship to the prior revision:
 
-- Invent missing requirements.
-- Convert adjacent evidence into product direction.
-- Override source-of-truth files.
-- Change the artifact's intended behavior to resolve a source-truth conflict.
-- Resolve an owner decision silently.
-- Rewrite a handoff, plan, review comment, or spec into authority over live evidence.
+- 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.
 
-Name the issue and ask for the decision. Recommend the path supported by evidence.
+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
 
-Lead with the result:
+For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change fitness or route.
 
-- Pass: fit to guide the next step.
-- Blocking: must fix before proceeding.
-- Non-blocking: can defer.
-- Question: owner decision or more evidence needed.
+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.
 
-Review can pass. Do not invent findings.
-
-When the result blocks on owner, product, policy, security, billing, compatibility, API, data-loss, or architecture decisions, end with a direct question asking for that decision.
-
-Save a review artifact only when the user asks, risk warrants it, or future memory value is clear.
-
-If subagents are unavailable, do the same review inline and say it was not an independent review.
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.