@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/review-artifact/references/reviewer-prompt.md

@@ -0,0 +1,148 @@
+# Independent Artifact Reviewer Contract
+
+Use this when preparing an independent review of a durable artifact.
+
+The reviewer did not produce the artifact. Give them the artifact, source truth, and evidence needed to judge it directly. The reviewer reports review items without editing.
+
+## Required Context
+
+Provide:
+
+- artifact path, 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;
+- the artifact-specific schema or format contract when one exists;
+- upstream and downstream artifacts in dependency order;
+- known evidence gaps;
+- review number and, for a follow-up, prior items, adjudication, revisions, and new evidence.
+
+For an artifact package, identify upstream authority and which work remains provisional or dependent.
+
+## Reviewer Prompt
+
+```md
+# Independent Artifact Review
+
+Review an artifact you did not produce. Inspect the complete artifact and source evidence directly. Report review items without editing. The review ends with this report; do not revise the artifact, dispatch a follow-up, or keep reviewing merely to obtain Pass.
+
+A pass is valid. Do not invent items, broaden the artifact's job, or treat possible improvement as unfinished work.
+
+## Artifact And Intended Use
+
+- Artifact: [path]
+- Type: [working record | spec | PRD | issue | API contract | technical design | migration contract | plan | decision record | ADR | handoff | other]
+- Reviewed state: [revision, hash, or other identity]
+- Intended use: [decision or future action this artifact must support]
+- Dependency order: [upstream -> downstream, or standalone]
+
+## Accepted Outcome And Non-Goals
+
+- Outcome: [accepted outcome]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
+- Owner decisions: [settled decisions or none]
+- Unresolved questions: [questions or none]
+
+## Source Truth
+
+- [code, tests, policies, ADRs, established behavior, upstream artifacts]
+
+## Evidence And Known Gaps
+
+- Supporting evidence: [evidence or none]
+- Known gaps: [gaps or none]
+
+## Review Scope
+
+- Review number: [1 | 2 | 3]
+- Material lenses: [source alignment | fitness and sufficiency | decision clarity | evidence and acceptance | behavior and failure contract | dependency integrity | scope and minimality | clarity and continuity]
+
+For Review 2 or 3:
+- Prior items and adjudication: [Accepted | Rejected | Open]
+- Revisions and new evidence: [bounded changes and evidence]
+- Affected dependencies: [dependencies or none]
+- Remaining risk: [narrow unresolved scope]
+
+## Judge The Artifact By Its Job
+
+- **Working Record:** accurate living task memory with 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:** 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:** 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.
+
+## Check
+
+Apply only the selected lenses:
+
+- The artifact agrees with accepted requirements, owner decisions, and live facts.
+- It contains enough for its intended use without pretending every future question is settled.
+- Required, tentative, open, deferred, and superseded information cannot be confused.
+- Load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
+- Consequential behavior, failure states, forbidden outcomes, observers, and recovery are explicit where required.
+- Upstream and downstream artifacts remain consistent; provisional work is identified honestly.
+- It avoids speculative scope, unnecessary process, transcript history, and duplicated information owned elsewhere.
+- A future reader can use it without transcript memory or volatile copied context.
+
+Do not demand exhaustive edge cases. A possible condition is not an Issue unless the artifact's intended use requires it, evidence shows it matters, or omission creates material risk. Use Question when expected behavior is undefined, Needs evidence when support is missing, and Improvement for useful content not required by this boundary.
+
+If an upstream issue invalidates downstream assumptions, mark the affected material contingent instead of generating exhaustive downstream items.
+
+For Review 2 or 3, inspect only accepted revisions, affected dependencies, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior revision; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another revision. Review 3 is final for this cycle; do not recommend Review 4.
+
+## Classify Review Items
+
+- **Blocking Issue:** supported defect or risk that must be resolved before the artifact guides its intended use.
+- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirement, or owner decision is unclear.
+- **Needs evidence:** a load-bearing claim or condition cannot be established.
+- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize revision.
+
+A Blocking Issue must include its exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
+
+## Determine The Judgment
+
+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.
+
+## Output
+
+Review type: independent
+Review number: [1 | 2 | 3]
+Artifact: [reviewed artifact]
+Intended use: [reviewed boundary]
+Reviewed state: [state identity]
+Judgment: Pass | Non-blocking | Inconclusive | Blocking
+Reasoning: [concise evidence-backed judgment]
+Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
+
+### Review Items
+
+#### Issues — Blocking
+- [location, issue, violated source or responsibility, evidence, consequence, smallest safe correction]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [concern, missing evidence, evidence needed]
+
+#### Improvements
+- [improvement, benefit, supporting evidence]
+
+Dependencies affected: [dependencies or none]
+Evidence gaps: [unproved claims or none]
+```
+
+## Calibration
+
+Use a high evidence bar, not a high item count. Lead with the few items that can change the artifact's fitness judgment. Prior review, artifact length, author confidence, or polished language does not establish fitness.
+
+The review is evidence for adjudication, not authority over source truth, owner decisions, revisions, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: review-work
+description: Use when reviewing implementation or integrated work, whether reviewing work you produced or acting as an independent reviewer.
+---
+
+# Review Work
+
+Judge whether work is correct, suitable, and sufficiently evidenced for its intended boundary.
+
+Review provides judgment. [Verify Work](../verify-work/SKILL.md) establishes what direct evidence proves. Review may challenge whether that evidence is sufficient, but it does not replace verification or authorize changes.
+
+## Choose The Review Role
+
+Choose the role before reviewing:
+
+- **Self-review:** you produced the work. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority and re-verify. 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 work, 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:
+
+- the accepted outcome, requirements, and non-goals;
+- the implementation, diff, or integrated work product;
+- relevant Specs, Plans, tests, policies, ADRs, and established behavior;
+- verification evidence and known gaps;
+- risks and interactions material to the future action this review protects.
+
+Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Read [the security risk lens](references/security-risk-lens.md) when the work changes a security-relevant boundary.
+
+## Review Proportionately
+
+Apply only lenses that can materially change the result:
+
+- **Alignment and correctness:** accepted behavior is implemented without invention or omission.
+- **Regression and integration:** affected callers, states, and components remain correct together.
+- **Failure and risk:** relevant errors, recovery, permissions, data, and compatibility behave safely.
+- **Evidence:** verification supports the claims and exercised the required boundary.
+- **Design and minimality:** complexity and coordination are justified by requirements or observed failures.
+- **Maintainability:** the work can be understood and changed without hidden policy or fragile coupling.
+
+A pass is valid. Do not invent items, report preferences or hypothetical completeness, reopen intentional deferrals, or treat ordinary reversible choices as issues.
+
+A possible edge case is not an Issue merely because it can be imagined:
+
+```text
+Required failure path is missing -> Issue
+Unsettled expected behavior -> Question
+Plausible concern without reachability or consequence evidence -> Needs evidence
+Useful resilience outside this boundary -> Improvement or omit
+Repeated related corrections -> diagnose the shared cause
+```
+
+## Classify Independent Review Items
+
+- **Blocking Issue:** a supported defect, regression, omission, or risk that must be resolved before crossing the reviewed boundary.
+- **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 plausible concern cannot be established from available evidence.
+- **Improvement:** a materially useful enhancement not required by this boundary. It does not affect judgment or authorize implementation.
+
+A Blocking Issue must name the exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
+
+Use the most consequential applicable judgment:
+
+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 work passes.
+
+## Adjudicate And Route
+
+After independent review, the receiving active agent adjudicates each item against the work, source truth, and evidence:
+
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, 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:** proceed.
+- **Non-blocking:** proceed with explicit deferrals.
+- **Inconclusive:** gather the missing evidence or decision.
+- **Blocking:** do not cross the boundary; re-enter the narrowest owning activity, defer, or stop.
+
+Review findings are evidence, not commands. They do not authorize edits. Accepted implementation corrections leave review and return to [Execute Work](../execute-work/SKILL.md); they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+
+When correction authority is not already explicit, ask once for either:
+
+- the accepted corrections plus one warranted focused follow-up review; or
+- the accepted corrections alone when direct evidence can settle the changed boundary.
+
+Then wait for the user's response. Do not correct or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded correction or review.
+
+Verify authorized corrections. Run a follow-up only when the changed boundary still needs independent judgment and that dispatch is authorized. Do not change tests, Specs, policies, or accepted behavior merely to satisfy a reviewer or obtain Pass.
+
+## Limit The Review Cycle
+
+For one independently reviewed work state and boundary:
+
+1. Review 1 is the normal broad review.
+2. Review 2, when needed and authorized, focuses on accepted corrections, affected interactions, 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 work may proceed, remain blocked, re-enter another owner, defer, or stop.
+
+After Review 2 is adjudicated Blocking, stop before proposing another correction or Review 3. Classify its relationship to the prior correction:
+
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior correction, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another patch.
+- If it is an independent clear local defect with a supported cause, return directly to its owning activity 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 correction boundary are understood, not a third attempt to discover the cause through patches. Workflow may later establish a new cycle only for a materially new reviewed state and boundary; local fixes, 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 the 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, remaining open items, and authorized or proposed next route.
+
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.

package/skills/review-work/references/reviewer-prompt.md

@@ -0,0 +1,134 @@
+# Independent Work Reviewer Contract
+
+Use this when preparing an independent review of implementation or integrated work.
+
+The reviewer did not produce the work. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the author's summary, reasoning, or claimed result.
+
+## Required Context
+
+Provide:
+
+- the work and future action covered by the review;
+- accepted outcome, requirements, and non-goals;
+- relevant specs, plans, tests, policies, ADRs, and established behavior;
+- the implementation, changed files, or diff range;
+- verification evidence and known gaps;
+- only the review lenses material to this boundary;
+- review number and, for a follow-up, prior items, adjudication, corrections, and new evidence.
+
+When state transitions or proof integrity matter, also provide the invariant or state owner, affecting paths, observing mechanism, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, and fidelity limits.
+
+## Reviewer Prompt
+
+```md
+# Independent Work Review
+
+Review work you did not produce. Inspect the supplied work, source truth, and evidence directly. Report review items without editing. The review ends with this report; do not fix items, dispatch a follow-up, or keep reviewing merely to obtain Pass.
+
+A pass is valid. Do not invent items, broaden scope, or treat possible improvement as unfinished work.
+
+## Boundary
+
+[Work and future action this review covers.]
+
+## Accepted Outcome And Non-Goals
+
+- Outcome: [required result]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
+
+## Source Truth
+
+- [specs, plans, tests, policies, ADRs, and established behavior]
+
+## Work Product
+
+- Reviewed state: [commit, tree, diff, or other identity]
+- Work: [diff range, changed files, implementation, or integrated result]
+
+## Verification Evidence
+
+- Checks and results: [commands, observations, and results]
+- Known gaps: [gaps or none]
+- When relevant: [state owner, affecting paths, observer, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, fidelity limits]
+
+## Review Scope
+
+- Review number: [1 | 2 | 3]
+- Material lenses: [alignment and correctness | regression and integration | failure and risk | evidence | design and minimality | maintainability]
+
+For Review 2 or 3:
+- Prior items and adjudication: [Accepted | Rejected | Open]
+- Clarifications: [settled decisions or none]
+- Corrections and new evidence: [changes and verification]
+- Remaining risk: [narrow unresolved scope]
+
+## Check
+
+Apply only the selected lenses:
+
+- The work satisfies accepted behavior without invention or omission.
+- Affected callers, states, and components remain correct together.
+- Relevant failure paths and material risks are handled safely.
+- Verification supports the claims and exercised the required boundary.
+- Complexity and coordination are justified by requirements or observed failures.
+- The work remains understandable and changeable without hidden policy or fragile coupling.
+
+Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed.
+
+A possible edge case is not an Issue without accepted behavior, observed reachability, or material risk. Use Question when expected behavior is unclear, Needs evidence when reachability or consequence is unsupported, and Improvement for useful resilience not required by the boundary.
+
+For Review 2 or 3, inspect only accepted corrections, affected interactions, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior correction; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another patch. Review 3 is final for this cycle; do not recommend Review 4.
+
+## Classify Review Items
+
+- **Blocking Issue:** supported defect or risk that must be resolved before crossing this boundary.
+- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirement, or owner decision is unclear.
+- **Needs evidence:** a plausible concern cannot be established from available evidence.
+- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize implementation.
+
+A Blocking Issue must include its exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
+
+## Determine The Judgment
+
+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.
+
+## Output
+
+Review type: independent
+Review number: [1 | 2 | 3]
+Boundary: [reviewed work and future action]
+Reviewed state: [state identity]
+Judgment: Pass | Non-blocking | Inconclusive | Blocking
+Reasoning: [concise evidence-backed judgment]
+Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
+
+### Review Items
+
+#### Issues — Blocking
+- [location, issue, violated source, evidence, consequence, smallest safe correction]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [concern, missing evidence, evidence needed]
+
+#### Improvements
+- [improvement, benefit, supporting evidence]
+
+Evidence gaps: [unproved claims or none]
+```
+
+## Calibration
+
+Use a high evidence bar, not a high item count. Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or author confidence does not establish correctness.
+
+The review is evidence for adjudication, not authority over source truth, owner decisions, corrections, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/references/security-risk-lens.md

@@ -0,0 +1,67 @@
+# Security Risk Lens
+
+Read this when work changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, dependencies, external integrations, execution, or failure behavior with security consequences.
+
+This lens helps frame review. It does not replace repo security policy, threat modeling, specialist review, or stack-specific hardening guidance.
+
+## Establish Authority
+
+Identify:
+
+- assets and data requiring protection;
+- actors, roles, tenants, and privilege levels;
+- trust boundaries and external systems;
+- accepted security/privacy policy and threat model;
+- compatibility and failure behavior that security controls must preserve.
+
+Security-sensitive product behavior remains user-owned. Do not invent access, retention, logging, or fail-open/closed policy during review.
+
+## Trace The Paths
+
+Review the affected path from boundary to effect:
+
+- authentication: who or what is this actor;
+- authorization: may this actor perform this operation on this resource;
+- input: validation, canonicalization, size, encoding, and injection surfaces;
+- output: escaping, disclosure, error detail, and side channels;
+- data: collection, transport, storage, isolation, retention, deletion, and audit;
+- secrets: source, scope, rotation, exposure, and logging;
+- execution: shell, file, URL, template, deserialization, plugin, or code-loading boundaries;
+- dependencies: provenance, permissions, known risk, update impact, and transitive behavior;
+- failure: partial state, retries, lockout, rate limits, rollback, and fail-open/closed behavior.
+
+Look for confused-deputy and cross-tenant paths, not only malformed input.
+
+## Evidence
+
+Prefer evidence at the real boundary:
+
+- tests proving allowed and denied roles/resources;
+- negative input and injection cases;
+- dependency or configuration inspection tied to the shipped artifact;
+- logs or traces demonstrating no secret/sensitive leakage;
+- failure-path tests for partial authorization, retry, and recovery;
+- specialist analysis for cryptography, sandboxing, identity protocols, or high-impact threats.
+
+A generic scanner pass cannot prove authorization logic or policy correctness. A unit test cannot prove deployed headers, identity configuration, or infrastructure permissions.
+
+Do not copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. Use the smallest sanitized evidence that supports the review item.
+
+## Review Item Calibration
+
+Treat supported exploitable behavior, policy violation, unintended privilege or data exposure, unsafe failure semantics, secret leakage, or a missing required control as an Issue.
+
+Classify the Issue against the accepted security policy and reviewed boundary:
+
+- **Blocking:** crossing the boundary would remain unsafe, non-compliant, or contrary to a required control.
+- **Non-blocking:** the security issue is real but can be deferred safely without violating the accepted boundary.
+
+Use **Question** when security behavior or accepted risk remains undecided. Use **Needs evidence** when a control may exist but the available test or environment cannot establish it.
+
+Treat materially useful defense-in-depth beyond the accepted boundary as an Improvement. Do not turn theoretical hardening, preference, or hypothetical completeness into an Issue.
+
+Do not omit an observed security issue merely because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
+
+## Route
+
+When security evidence changes the path, use [Workflow](../../workflow/SKILL.md) to choose what follows. Use [Diagnose Failure](../../diagnose-failure/SKILL.md) for unknown exploitability or root cause, [Decision Gate](../../decision-gate/SKILL.md) for missing policy or accepted-risk decisions, [Design For Depth](../../design-for-depth/SKILL.md) when trust decisions spread across callers, and [Launch Work](../../launch-work/SKILL.md) when the concern affects production rollout.

package/skills/setup-freeflow/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: setup-freeflow
+description: Use when activating Freeflow in a repository, repairing its repository or personal configuration, or checking whether the current host is delivering Freeflow context.
+---
+
+# Setup Freeflow
+
+Create or repair the smallest valid layered setup. Keep repository activation, personal overrides, and host runtime delivery as separate facts.
+
+- `.freeflow/config.json` is the required shared repository activation config.
+- `.freeflow/local.json` is an optional per-checkout personal override. It cannot activate Freeflow by itself.
+- Runtime delivery depends on the current host's installed and trusted adapter.
+
+Answer setup questions and delivery checks read-only. An explicit action request authorizes the smallest selected setup change under the state rules below. When repository config is missing, first activation authorizes minimal shared config; it does not authorize personal overrides, optional capabilities, replacement of invalid config, or edits to repo-owned host instructions.
+
+Read [the activation contract](references/activation-contract.md) before changing setup state. Read [host setup](references/host-setup.md) when runtime delivery, lifecycle, or host trust matters. Read [Output Router setup](references/output-router-setup.md) only when the user explicitly requests it during setup or repair; later tuning belongs to [Output Router](../output-router/SKILL.md).
+
+## Establish Mutation Authority
+
+Classify the current state before editing:
+
+- **Unconfigured:** repository config is missing or invalid, so no Freeflow mode is effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
+- **Configured but ineffective:** valid repository activation exists, but Freeflow is disabled, Skills are dormant, or invalid local config blocks runtime. No mode is effective. An explicit request governs the selected enablement, configuration, or repair; any dormant resolved mode does not.
+- **Effective:** Freeflow Skills report an effective mode. Obey it. Conversation remains read-only; Workflow or Strict Workflow allows agent-performed mutation only for the separately requested setup or repair.
+
+User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available and do not claim their state changed until the host reports it.
+
+## Inspect The Layers
+
+Before editing:
+
+1. inspect `.freeflow/config.json` and `.freeflow/local.json` independently;
+2. identify which requested values are shared repository state and which are personal overrides;
+3. inspect repo instructions only when a conflict would change setup behavior;
+4. identify the host and available delivery evidence when runtime status matters.
+
+A valid repository config establishes activation. A missing local config inherits shared values. An invalid existing local config blocks effective Freeflow instead of falling back silently.
+
+If setup is already valid and no change was requested, preserve it and report the effective sources. Do not rewrite config merely to normalize formatting or materialize defaults.
+
+## Configure Shared Activation
+
+For a new default setup, write:
+
+```json
+{
+  "defaultMode": "workflow"
+}
+```
+
+During first activation, an explicitly requested `conversation` or `strict-workflow` mode becomes the shared repository default. Preserve valid existing settings and add no unrequested keys or empty sections.
+
+If repository config is invalid or conflicts with accepted source truth, use [Decision Gate](../decision-gate/SKILL.md) before replacing or reinterpreting it.
+
+Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface.
+
+## Add Personal Overrides Only When Requested
+
+Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`, `interactionContract`, `skills.enabled`, or `defaultMode`. Omitted values inherit from repository config and built-in defaults.
+
+In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared settings. Prefer those controls when available.
+
+Before writing local config in a Git checkout, verify it is untracked and ignored. Do not modify shared ignore policy merely to store a personal preference; use the host's safe settings path or local Git exclusion. Refuse to overwrite a tracked local config.
+
+If local config is invalid, report that it blocks effective runtime. Repair or remove it only with authorization; never discard it and fall back silently.
+
+## Keep Optional Setup Explicit
+
+Do not ask an automatic capabilities question. Configure Output Router only when explicitly requested, using [Output Router setup](references/output-router-setup.md). Preserve valid existing capability config during idempotent setup.
+
+## Establish Same-Turn Context
+
+After successful verification, apply newly effective context directly for the remainder of the setup turn:
+
+- read the [Interaction Contract](../../runtime/interaction-contract.md) when it is effective;
+- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective;
+- read an explicitly configured capability skill only when runtime state says it is effective.
+
+This direct read establishes same-turn guidance; it does not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
+
+## Verify And Report
+
+Verify:
+
+- repository config parses and contains a valid `defaultMode`;
+- local config is missing or valid, personal, untracked, and ignored when applicable;
+- effective `enabled`, Interaction Contract, Skills, and configured default values have the expected sources;
+- Skills-disabled mode remains resolved but dormant;
+- optional capability config changed only when requested;
+- no repo-owned host instructions or unrelated files changed.
+
+Report separately:
+
+1. shared repository activation;
+2. personal override state and effective sources;
+3. effective capability state;
+4. same-turn direct context reads;
+5. automatic runtime delivery as **confirmed**, **unavailable**, or **unconfirmed**.