@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/review-work/scripts/check-brief.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Checks a work reviewer's pointer brief (references/work.md, "The Brief") before it is dispatched: every
+// required labelled line is present, every backticked path it points to exists, and every commit it names resolves.
+// It checks pointers only; whether they point to the right inputs is the initiator's judgment.
+// Usage: check-brief.mjs <brief> [--root <repository>] [--json]
+// Paths resolve against --root (default: the current directory); absolute paths are allowed, and a "#anchor" suffix is
+// ignored. Exit code 0 when the brief passes, 1 when it has problems, 2 on a usage error.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+const USAGE = "Usage: check-brief.mjs <brief> [--root <repository>] [--json]";
+
+// Lines every brief carries. "paths" lines must point to at least one existing file unless "none" is allowed and given.
+const REQUIRED = [
+  { label: "Review", kind: "number" },
+  { label: "Boundary", kind: "text" },
+  { label: "Reviewed state", kind: "commit" },
+  { label: "Method", kind: "paths" },
+  { label: "Agreement", kind: "paths" },
+  { label: "Docs", kind: "paths", none: true },
+  { label: "Review rules", kind: "paths", none: true },
+  { label: "Diff", kind: "range" },
+  { label: "Evidence", kind: "paths", none: true },
+  { label: "May run", kind: "text" },
+  { label: "Report", kind: "report" },
+];
+const OPTIONAL = [
+  { label: "Previous report", kind: "paths" },
+  { label: "Lenses", kind: "text" },
+  { label: "Notes", kind: "text" },
+];
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: { root: { type: "string" }, json: { type: "boolean", default: false } },
+  });
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const { values, positionals } = parsed;
+if (positionals.length !== 1) fail(USAGE);
+const briefPath = resolve(positionals[0]);
+if (!existsSync(briefPath)) fail(`no such brief: ${positionals[0]}`);
+const root = resolve(values.root ?? ".");
+
+// A labelled line is "Label: value" at the start of a line, optionally as a list item or in bold ("**Label:**").
+const known = [...REQUIRED, ...OPTIONAL];
+const lines = new Map();
+for (const raw of readFileSync(briefPath, "utf8").split("\n")) {
+  const match = raw.match(/^\s*(?:[-*]\s+)?(?:\*\*)?([A-Za-z ]+?):(?:\*\*)?\s*(.*)$/);
+  if (!match) continue;
+  const spec = known.find((each) => each.label.toLowerCase() === match[1].trim().toLowerCase());
+  if (spec && !lines.has(spec.label)) lines.set(spec.label, match[2].trim());
+}
+
+const problems = [];
+const problem = (label, message) => problems.push({ line: label, problem: message });
+
+const commitOf = (ref) => {
+  try {
+    return execFileSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+const unquote = (value) => value.replace(/^`|`$/g, "").trim();
+const pathsIn = (value) => [...value.matchAll(/`([^`]+)`/g)].map((match) => match[1].replace(/#.*$/, "").trim());
+const at = (path) => (isAbsolute(path) ? path : resolve(root, path));
+
+function check(spec, value) {
+  if (!value) return problem(spec.label, "is empty");
+  if (spec.none && /^none\.?$/i.test(value)) return;
+  if (spec.kind === "number") {
+    const round = Number(value.match(/\d+/)?.[0]);
+    if (![1, 2, 3].includes(round)) problem(spec.label, `must be 1, 2 or 3, not "${value}"`);
+  } else if (spec.kind === "commit") {
+    const ref = unquote(value.split(/\s+/)[0]);
+    if (!commitOf(ref)) problem(spec.label, `names no commit in ${root}: ${ref}`);
+  } else if (spec.kind === "range") {
+    const range = unquote(value.split(/\s+/)[0]);
+    const ends = range.split(/\.{2,3}/);
+    if (ends.length !== 2 || !ends[0] || !ends[1]) return problem(spec.label, `must be <base>..<head>, not "${value}"`);
+    for (const end of ends) if (!commitOf(end)) problem(spec.label, `names no commit in ${root}: ${end}`);
+  } else if (spec.kind === "paths") {
+    const paths = pathsIn(value);
+    if (!paths.length)
+      return problem(spec.label, `points to no path; write each path in backticks${spec.none ? ', or "none"' : ""}`);
+    for (const path of paths)
+      if (!existsSync(at(path))) problem(spec.label, `points to a path that does not exist: ${path}`);
+  } else if (spec.kind === "report") {
+    const [path] = pathsIn(value);
+    if (!path) return problem(spec.label, "names no report path in backticks");
+    if (!existsSync(dirname(at(path)))) problem(spec.label, `is in a folder that does not exist: ${dirname(path)}`);
+  }
+}
+
+for (const spec of REQUIRED) {
+  if (!lines.has(spec.label)) problem(spec.label, "is missing");
+  else check(spec, lines.get(spec.label));
+}
+for (const spec of OPTIONAL) if (lines.has(spec.label)) check(spec, lines.get(spec.label));
+const round = Number(lines.get("Review")?.match(/\d+/)?.[0]);
+if ((round === 2 || round === 3) && !lines.has("Previous report"))
+  problem("Previous report", `is missing; Review ${round} needs the previous report and its adjudication`);
+
+const ok = problems.length === 0;
+if (values.json) {
+  console.log(JSON.stringify({ command: "check-brief", brief: briefPath, root, ok, problems }, null, 2));
+} else if (ok) {
+  console.log(`Brief passes: ${positionals[0]}`);
+} else {
+  console.log(`Brief refused: ${positionals[0]}`);
+  for (const each of problems) console.log(`- ${each.line}: ${each.problem}`);
+}
+process.exit(ok ? 0 : 1);

package/skills/review-work/scripts/review-packet.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Prefills a work reviewer's pointer brief (references/work.md, "The Brief") from the repository and the task folder,
+// then runs check-brief.mjs on it, so the brief points at the requirements, the right diff and the prior report
+// without being assembled by hand. It also reports the review gate's triggers the diff shows and the review-round
+// budget. Lines it cannot fill (the Boundary, unless given) stay empty, so check-brief refuses the brief until the
+// initiator fills them.
+// Usage: review-packet.mjs --review <1|2|3> --base <ref> [--head <ref>] [--task <task folder>] [--out <brief.md>]
+//                          [--boundary <text>] [--agreement <path>]... [--evidence <path>]... [--may-run <text>]
+//                          [--root <repository>] [--json]
+// With --task, the brief is written to <task>/scratch/reviews/R<n>-brief.md, the report path is R<n>-report.md beside
+// it, the agreement defaults to the task's record.md, and Review 2 or 3 takes its diff from the previous brief's
+// reviewed state and points to R<n-1>-report.md. Docs come from Write Docs' docs-check.mjs --covering on the changed
+// files. Exit code: check-brief's (0 passes, 1 has problems); 2 on a usage or Git error.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const USAGE =
+  "Usage: review-packet.mjs --review <1|2|3> --base <ref> [--head <ref>] [--task <task folder>] [--out <brief.md>] [--boundary <text>] [--agreement <path>]... [--evidence <path>]... [--may-run <text>] [--root <repository>] [--json]";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CHECK_BRIEF = join(HERE, "check-brief.mjs");
+const DOCS_CHECK = resolve(HERE, "../../write-docs/scripts/docs-check.mjs");
+const SKILL = resolve(HERE, "../SKILL.md");
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let values;
+try {
+  ({ values } = parseArgs({
+    options: {
+      review: { type: "string" },
+      base: { type: "string" },
+      head: { type: "string", default: "HEAD" },
+      task: { type: "string" },
+      out: { type: "string" },
+      boundary: { type: "string" },
+      agreement: { type: "string", multiple: true, default: [] },
+      evidence: { type: "string", multiple: true, default: [] },
+      "may-run": { type: "string" },
+      root: { type: "string" },
+      json: { type: "boolean", default: false },
+    },
+  }));
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const round = Number(values.review);
+if (![1, 2, 3].includes(round) || !values.base) fail(USAGE);
+if (!values.task && !values.out) fail(`give --task or --out for where the brief goes\n${USAGE}`);
+
+const git = (cwd, args) =>
+  execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+let root;
+try {
+  root = resolve(git(resolve(values.root ?? "."), ["rev-parse", "--show-toplevel"]).trim());
+} catch {
+  fail("not inside a Git repository");
+}
+const commitOf = (ref) => {
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).trim();
+  } catch {
+    return null;
+  }
+};
+const head = commitOf(values.head);
+if (!head) fail(`no such commit: ${values.head}`);
+if (!commitOf(values.base)) fail(`no such commit: ${values.base}`);
+
+// Paths in the brief: relative to the repository when inside it, absolute otherwise.
+const show = (path) => {
+  const relativePath = relative(root, resolve(path));
+  return relativePath.startsWith("..") ? resolve(path) : relativePath;
+};
+const tick = (paths) => paths.map((path) => `\`${show(path)}\``).join(", ");
+
+const task = values.task ? resolve(values.task) : null;
+const reviews = task ? join(task, "scratch", "reviews") : dirname(resolve(values.out));
+const briefPath = values.out ? resolve(values.out) : join(reviews, `R${round}-brief.md`);
+const reportPath = join(task ? reviews : dirname(briefPath), `R${round}-report.md`);
+const notes = [];
+
+// Review 2 or 3 reviews the range since the previous review's reviewed state.
+let diffBase = values.base;
+let previousReport = null;
+if (round > 1) {
+  const previousBrief = join(reviews, `R${round - 1}-brief.md`);
+  const reviewed = existsSync(previousBrief)
+    ? /^\s*(?:[-*]\s+)?(?:\*\*)?Reviewed state:(?:\*\*)?\s*`?([0-9a-fA-F]{7,40}|\S+?)`?(\s|$)/m.exec(
+        readFileSync(previousBrief, "utf8"),
+      )?.[1]
+    : null;
+  if (reviewed && commitOf(reviewed)) diffBase = reviewed;
+  else notes.push(`no previous brief with a Reviewed state at ${show(previousBrief)}: the diff starts at --base`);
+  const candidate = join(reviews, `R${round - 1}-report.md`);
+  if (existsSync(candidate)) previousReport = candidate;
+  else notes.push(`no previous report at ${show(candidate)}: add its path and adjudication to "Previous report"`);
+}
+
+const agreement = values.agreement.length
+  ? values.agreement
+  : task && existsSync(join(task, "record.md"))
+    ? [join(task, "record.md")]
+    : [];
+if (!agreement.length) notes.push("no agreement found: pass --agreement (the record, or the accepted requirements)");
+
+const changed = git(root, ["-c", "core.quotePath=false", "diff", "--name-only", diffBase, head])
+  .split("\n")
+  .filter(Boolean);
+
+// Developer docs covering the changed files.
+let docs = [];
+if (changed.length && existsSync(DOCS_CHECK)) {
+  const run = spawnSync(
+    process.execPath,
+    [DOCS_CHECK, ...changed.flatMap((path) => ["--covering", path]), "--root", root, "--json"],
+    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (run.status === 0)
+    docs = [...new Set(JSON.parse(run.stdout).paths.flatMap((entry) => entry.documents.map((doc) => doc.path)))];
+  else notes.push("docs-check could not run: fill Docs by hand");
+}
+
+// The project's Review Rules, when it keeps them in a file.
+const rules = git(root, ["ls-files"])
+  .split("\n")
+  .filter((path) => /(^|\/)(REVIEW\.md|review-rules\.md|REVIEW_RULES\.md)$/i.test(path));
+
+// The project's declared checks, for "May run".
+let mayRun = values["may-run"] ?? "";
+if (!mayRun && existsSync(join(root, "package.json"))) {
+  try {
+    const scripts = Object.keys(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).scripts ?? {});
+    const declared = ["test", "check", "lint", "typecheck"].filter((name) => scripts.includes(name));
+    if (declared.length)
+      mayRun = `the project's declared checks: ${declared.map((name) => `\`npm ${name === "test" ? "test" : `run ${name}`}\``).join(", ")}`;
+  } catch {
+    // An unreadable package.json leaves May run for the initiator.
+  }
+}
+if (!mayRun) notes.push('fill "May run": the declared checks, or "nothing"');
+
+// Review gate triggers the diff shows; the agreement's own review triggers and Review Rules paths need a reader.
+const TRIGGERS = [
+  [
+    "security, authentication, authorization or secrets",
+    /(^|[/_.-])(auth[nz]?|oauth|login|passwords?|secrets?|credentials?|tokens?|permissions?|crypto|sessions?)([/_.-]|$)|authenticat|authoriz|(^|\/)\.env/i,
+  ],
+  ["possible data loss or a migration of stored data", /(migrat|schema|\.sql$|database|(^|\/)db\/|storage|persist)/i],
+  [
+    "CI or release files",
+    /(^\.github\/workflows\/|^\.gitlab-ci|^\.circleci\/|(^|\/)release|CHANGELOG|^scripts\/release)/i,
+  ],
+  [
+    "a public interface",
+    /(^package\.json$|(^|\/)bin\/|\.d\.ts$|(^|\/)SKILL\.md$|command-surface|(^|\/)index\.[cm]?[jt]s$|\.proto$|openapi|(^|\/)api\/)/i,
+  ],
+];
+const triggers = TRIGGERS.flatMap(([trigger, pattern]) => {
+  const paths = changed.filter((path) => pattern.test(path));
+  return paths.length ? [{ trigger, paths: paths.slice(0, 10), more: Math.max(0, paths.length - 10) }] : [];
+});
+const budget =
+  round === 1
+    ? "Review 1 of at most 3: the first selected independent review, broad by default."
+    : round === 2
+      ? "Review 2 of at most 3: a focused follow-up on the range since Review 1; if it stays Blocking, adjudicate and diagnose before any Review 3."
+      : "Review 3 of 3: exceptional, separately authorized and final; if it stays Blocking, rethink the approach rather than correct again.";
+
+const lines = [
+  `Review: ${round}`,
+  `Boundary: ${values.boundary ?? ""}`,
+  `Reviewed state: ${head.slice(0, 12)}`,
+  `Method: ${tick([SKILL, join(dirname(SKILL), "references", "work.md")])}`,
+  `Agreement: ${tick(agreement)}`,
+  `Docs: ${docs.length ? tick(docs) : "none"}`,
+  `Review rules: ${rules.length ? tick(rules) : "none"}`,
+  `Diff: ${commitOf(diffBase).slice(0, 12)}..${head.slice(0, 12)}`,
+  `Evidence: ${values.evidence.length ? tick(values.evidence) : "none"}`,
+  `May run: ${mayRun}`,
+  ...(round > 1 ? [`Previous report: ${previousReport ? tick([previousReport]) : ""}`] : []),
+  `Report: ${tick([reportPath])}`,
+];
+mkdirSync(dirname(briefPath), { recursive: true });
+writeFileSync(briefPath, `${lines.join("\n")}\n`);
+mkdirSync(dirname(reportPath), { recursive: true });
+
+const check = spawnSync(process.execPath, [CHECK_BRIEF, briefPath, "--root", root, "--json"], { encoding: "utf8" });
+let checked;
+try {
+  checked = JSON.parse(check.stdout);
+} catch {
+  fail(`check-brief failed: ${(check.stderr || check.stdout).trim()}`);
+}
+
+const result = {
+  command: "review-packet",
+  root,
+  brief: briefPath,
+  review: round,
+  diff: `${diffBase}..${values.head}`,
+  changedFiles: changed.length,
+  gateTriggers: triggers,
+  gateNotDetected: ["anything the work agreement names for review", "paths the Review Rules mark sensitive"],
+  budget,
+  notes,
+  checkBrief: { ok: checked.ok, problems: checked.problems },
+};
+if (values.json) console.log(JSON.stringify(result, null, 2));
+else {
+  console.log(`Brief: ${briefPath}`);
+  console.log(lines.map((line) => `  ${line}`).join("\n"));
+  console.log(`Changed files: ${changed.length}.`);
+  console.log(
+    triggers.length
+      ? `Gate triggers in the diff:\n${triggers.map((each) => `- ${each.trigger}: ${each.paths.join(", ")}${each.more ? ` and ${each.more} more` : ""}`).join("\n")}`
+      : "Gate triggers in the diff: none detected by path.",
+  );
+  console.log(`Not detected here: ${result.gateNotDetected.join("; ")}.`);
+  console.log(`Round budget: ${budget}`);
+  for (const note of notes) console.log(`Note: ${note}`);
+  console.log(
+    checked.ok
+      ? "check-brief: passes. Dispatch this brief."
+      : `check-brief: refused. Fill these, then rerun check-brief:\n${checked.problems.map((each) => `- ${each.line}: ${each.problem}`).join("\n")}`,
+  );
+}
+process.exit(checked.ok ? 0 : 1);

package/skills/setup-freeflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: "Use when installing, activating or turning off Freeflow in a repository, changing or repairing its repository or personal configuration (.freeflow/config.json, .freeflow/local.json), or checking whether the current host is loading Freeflow's guidance and skills."
 ---
 
 # Setup Freeflow
@@ -9,21 +9,28 @@ Create or repair the smallest valid layered setup. Keep repository activation, p
 
 - `.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.
+- Runtime delivery depends on the current host's installed and trusted adapter. Configuration does not prove runtime delivery.
 
 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.
+## Routes
+
+| Situation | Go to |
+| --- | --- |
+| Activating, or changing shared or personal setup | Establish Mutation Authority, then Inspect The Layers, then the section for that layer |
+| Repository config invalid, or conflicting with accepted source truth or repository instructions | [Discuss Work](../discuss-work/SKILL.md), before replacing or reinterpreting it |
+| Whether the host delivers Freeflow, or which host action refreshes it | Hosts, below |
+| Cognitive Routing or Tool Execution values | Their explicit settings surface (on Pi, `/freeflow settings`), only when the user requests them |
 
 ## Establish Mutation Authority
 
 Classify the current state before editing:
 
-- **Unconfigured:** repository config is missing or invalid, so Freeflow is not 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 or an invalid local config blocks runtime. No Freeflow guidance is effective. An explicit request governs the selected enablement, configuration, or repair.
-- **Effective:** Freeflow core guidance, the Interaction Contract, and base skills are effective. An explicit setup or repair request may be carried out within its authority; optional capability behavior remains independently gated.
+- **Unconfigured:** repository config is missing or invalid, so repository activation is absent and Freeflow is not effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config requires specific authorization and resolving the source conflict.
+- **Configured but ineffective:** valid repository activation exists, but effective `enabled` is `false` or an invalid local config blocks runtime. No Freeflow guidance is effective. An explicit request governs the selected enablement, configuration, or repair.
+- **Effective:** Freeflow core guidance, the Interaction Contract, and base skills are effective; obey them. An explicit setup or repair request may be carried out within its authority; optional capability behavior remains independently gated.
 
-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.
+User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available, do not claim their state changed until the host reports it, and verify the resulting source and effective state afterward.
 
 ## Inspect The Layers
 
@@ -36,6 +43,14 @@ Before editing:
 
 A valid repository config establishes activation. A missing local config inherits repository settings. An invalid existing local config blocks effective Freeflow instead of falling back silently.
 
+Resolve each configurable value in this order:
+
+```text
+host session override -> personal override -> repository value -> built-in default
+```
+
+Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow enablement, and Cognitive Routing has its own host-managed session control. Effective Freeflow requires a valid repository config, a missing or valid local config, session-resolved `enabled: true`, and the prompt files the host delivers (Hosts, below).
+
 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
@@ -46,30 +61,62 @@ For a new setup, write the minimal activation boundary:
 {}
 ```
 
-Add `enabled: false` only when the user explicitly requests Freeflow to be disabled. Add optional capability configuration only when the user explicitly requests it.
+Missing core keys use the built-in default `enabled: true`. Add `enabled: false` only when the user explicitly requests Freeflow to be disabled. Add optional capability configuration only when the user explicitly requests it. Do not add task state, phase, file inventories, plans, version metadata, activation paths, empty optional sections, host instruction copies, or generated workflow text.
 
-If repository config is invalid or conflicts with accepted source truth, use [Decision Gate](../decision-gate/SKILL.md) before replacing or reinterpreting it.
+These keys are unsupported in either config file and make it invalid until repaired: `defaultMode`, `interactionContract`, `skills`, `contextVirtualization`, and `conversationHistory`. The user deletes them wherever present; setup never migrates or removes them automatically.
 
-Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface.
+Do not create or append Freeflow instructions in `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or another host-owned instruction surface, including to compensate for unavailable or unconfirmed delivery. Existing repo instructions remain live source truth within host precedence. They are not activation markers, but they can conflict with Freeflow behavior: name a conflict and ask through Discuss Work before changing setup or behavior when it would alter the next action, rather than overwriting them to make Freeflow appear active. Do not install repo-local hooks, CLI commands, lint rules, global standards, documentation inventories, or state files during setup.
 
 ## Add Personal Overrides Only When Requested
 
-Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`, `contextVirtualization`, or `conversationHistory`. Omitted values inherit from repository config and built-in defaults. Configure optional Cognitive Routing values only through its explicit settings surface.
+Use `.freeflow/local.json` for an explicitly selected per-checkout override of `enabled`:
 
-In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared settings. Prefer those controls when available.
+```json
+{
+  "enabled": false
+}
+```
+
+Omitted values inherit from repository config and built-in defaults; local precedence is per property, not whole-file replacement. Configure optional Cognitive Routing values only through its explicit settings surface.
 
-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.
+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: prefer the host's safe settings path, `.git/info/exclude`, or an existing ignore rule. 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.
 
+## Hosts
+
+When Freeflow is effective, host adapters deliver `runtime/prompts/core.md`, `interaction-contract.md` and `working-method.md`, the base Freeflow skill surface, and compact current capability state; on Pi also `tool-execution.md` and `cognitive-routing.md` while those capabilities are effective, with their skills and tools. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions. Context Virtualization and Conversation History are removed.
+
+### Pi
+
+The Pi extension reads both config layers before each agent turn. When Freeflow is enabled it always delivers the core prompt, Interaction Contract and Working Method together, keeping the existing system prompt. Runtime State is refreshed at session start, after context reconstruction or loss, and when displayed state changes; unchanged state remains in the provider context. Skill and capability bodies stay discoverable rather than delivered as hidden persistent messages.
+
+Settings scopes:
+
+```text
+/freeflow settings          personal overrides
+/freeflow settings session  temporary Freeflow and Cognitive Routing session controls
+/freeflow settings repo     shared repository settings
+```
+
+Session settings can temporarily inherit, enable, or disable Freeflow and override Cognitive Routing profiles and delegation; one reset action clears them. They persist in the active Pi session branch, never write either config file, and cannot bypass missing or invalid repository activation. The personal settings path uses omission to inherit, refuses to overwrite invalid or tracked local config, and establishes local Git exclusion when needed. These user-operated controls update state before the next model turn and reload Pi resources when supported.
+
+A config written during setup is visible to the adapter on the next agent turn. After first activation, tell the user to run `/reload` so Pi refreshes skills and resources fully; without it, core runtime context loads on the next turn but resource discovery waits. Confirm automatic delivery through current extension status or runtime evidence.
+
+### Codex And Claude Code
+
+The packaged runtime hook reads the same two layers. At supported `SessionStart` boundaries (startup, resume, clear, and compact) it loads `core.md`, `interaction-contract.md` and `working-method.md`, each unless `prompts` (`core`, `interactionContract`, `workingMethod`; each a boolean, on by default, personal overriding shared per prompt) turns it off, and emits a compact active Runtime State. It does not process submitted prompts, persist session controls, inject skill bodies, or inspect Pi-only capabilities.
+
+After first-time setup, tell the user to trigger the least disruptive supported host-native lifecycle boundary: resume, clear, compact, or a new session or startup, as available. Name the exact control the current host supports; do not prescribe Pi's `/reload`.
+
 ## Establish Same-Turn Context
 
 After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
 - read the [Interaction Contract](../../runtime/prompts/interaction-contract.md);
-- read [Workflow](../workflow/SKILL.md) when Freeflow is effective.
+- read the [core guidance](../../runtime/prompts/core.md) and the [Working Method](../../runtime/prompts/working-method.md) when Freeflow is effective.
 
-These direct reads establish same-turn guidance; they do 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.
+These direct reads establish same-turn guidance; they do not prove that a lifecycle adapter ran, and no further adapter invocation has occurred yet. After first activation, name the exact host-native lifecycle action for automatic delivery and resource refresh (Hosts, above), and state what applies before that boundary.
 
 ## Verify And Report
 
@@ -78,10 +125,16 @@ Verify:
 - repository config parses and is the required activation boundary;
 - local config is missing or valid, personal, untracked, and ignored when applicable;
 - effective `enabled`, core guidance, and optional capability values have the expected sources;
-- no repo-owned host instructions or unrelated files changed.
+- no repo-owned host instructions or unrelated files changed, and running setup again would change nothing.
 
 After verification supports a setup result, silently self-review the final observed or changed state before accepting, reusing, or reporting it. Correct clear local issues within the existing setup authority and re-verify the affected boundary; stop on ambiguity, route change, or an out-of-envelope correction.
 
+Classify automatic runtime delivery from evidence:
+
+- **confirmed:** trustworthy evidence shows the current host adapter ran for the current lifecycle;
+- **unavailable:** the adapter, plugin or hook is absent, disabled, denied, untrusted, or unsupported;
+- **unconfirmed:** the adapter may be installed and trusted, but the host exposes no trustworthy evidence that it ran. Installed and trusted registration establishes availability for the next lifecycle action, not delivery.
+
 Report separately:
 
 1. shared repository activation;