@hassangameryt/freeflow 0.3.0 → 0.4.0

package/skills/mode-contract/SKILL.md

@@ -1,84 +1,82 @@
 ---
 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-native mode control when available. In Pi:
 
 ```text
-/workflow conversation
-/workflow workflow
-/workflow strict-workflow
-/workflow reset
+/freeflow mode
+/freeflow mode conversation
+/freeflow mode workflow
+/freeflow mode strict-workflow
+/freeflow mode reset
 ```
 
-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.
+Pi handles these commands before the model runs. The three setting commands create a session override; `reset` clears it and returns to the configured default, including a personal override when present. `/freeflow mode` inspects or selects mode according to host UI support.
 
-Do not persist current mode, create repo state files, or edit config unless the user explicitly asks to change the repo default.
+For a natural-language request to change Pi session mode, direct the user to the native command. Do not claim runtime state changed until the host reports the new effective mode.
 
-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.
+Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
 
-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.
+## Change Defaults Separately
 
-Persist only explicit default requests, such as "make strict-workflow the default for this repo." Update `.freeflow/config.json` with only:
+A persistent default change is not a session-mode change. An unqualified personal default request targets `.freeflow/local.json`; changing the shared repository default requires explicit repository, team, or shared-default wording.
 
-```json
-{
-  "defaultMode": "strict-workflow"
-}
-```
+In Pi, use `/freeflow mode` or `/freeflow settings session` for a temporary mode override, `/freeflow settings` for personal overrides, and `/freeflow settings repo` for shared defaults. In another host, use its native settings when available or update only the explicitly selected valid layer while preserving unrelated settings.
 
-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/output-router/SKILL.md

@@ -1,32 +1,32 @@
 ---
 name: output-router
-description: Use after the workflow, interview-gate, or discover route is clear when choosing between native tools and Freeflow routed tools, retrieving repo/vault evidence, transforming bounded evidence, handling unknown-size or broad output, running likely-large/noisy commands, recovering vaulted output, configuring outputRouter/observedRouting/scriptTransform, or handling optional native read/bash safety-net routing.
+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. Native tools stay direct for known-small, exact, intentionally raw, or mutating work.
+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, Interview Gate, and Discover decide whether to answer, ask, discover, plan, or stop. Output Router starts after that route is clear.
+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/vault data: use `freeflow_search`.
+- 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, or edits: use native `read`, `bash`, `edit`, or `write`.
+- 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.
+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 and vaulted output that already exists.
+Use `freeflow_search` for repo files, explicit external local files, and vaulted output that already exists.
 
 Actions:
 
@@ -36,9 +36,9 @@ Actions:
 - `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/vault/file/output data.
+- `transform`: compute facts or deterministic subsets from repo/local/vault/file/output data.
 
-Use `source.kind="repo"` for the current checkout. Use `source.kind="vault"` for previous Freeflow outputs.
+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:
 
@@ -68,7 +68,7 @@ Prefer deterministic operations when enough:
 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/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.
@@ -121,7 +121,7 @@ Good batch cases:
 
 - run several bounded searches in parallel,
 - run independent checks and ask `queries[]` to extract facts from child evidence,
-- gather multiple repo/vault facts without injecting every child result.
+- gather multiple repo/local/vault facts without injecting every child result.
 
 Do not use batch for:
 
@@ -137,10 +137,12 @@ Child outputs remain in `details.result.steps`; exact child run output remains r
 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 or host access is intentionally needed.
+- `bash`: expected-small exact shell behavior, host access, cmux/Pi control probes, or bounded producer behavior is intentionally needed.
 - `edit` / `write`: mutations.
 
-Do not run broad native commands just to see what comes back. Likely-large native commands include repo-wide `rg`, `grep -R`, `find`, package scans, generated-artifact scans, logs, broad `git diff/log`, full tests/builds/lints/typechecks, and one-off scripts with unknown output size.
+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.
 
@@ -191,12 +193,14 @@ When line numbers are unknown, use `query` or `get` first. Use `expand` when a r
 
 Use `freeflow_status` to inspect effective config, vault writability/index state, script adapters, observed routing, and migration recommendations.
 
-Persist optional config only after an explicit setup branch/request:
+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.
-- `observedRouting`: explicit MCP servers and web/fetch/codeSearch producer persistence.
-- `scriptTransform`: enabled flag, languages, sandbox/network/limits/raw-script persistence.
+- `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 `references/safety-policy.md` before changing routing policy, reviewing router behavior, or handling exactness-sensitive output.
+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

@@ -37,4 +37,4 @@ Exactness-sensitive output includes:
 - 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/interview gates.
+- 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.