@jawache/flow 0.1.2 → 0.3.0

package/dist/types/language/domain.d.ts

@@ -58,17 +58,21 @@ export declare function isScopable(kind: EntrySpec["kind"], m: string): boolean;
  * The host-written record of one session × agent, as a classifier sees it.
  *
  * Every field is something a HARNESS wrote, not something the session said. `agentType` is the
- * strongest of them — the sidecar the host writes beside every subagent transcript — and it is
- * what a classifier should key on when it exists.
+ * strongest of them — the agent type the host puts in the hook message for every call a subagent
+ * makes — and it is what a classifier should key on when it exists.
  */
 export interface SessionFacts {
-    /** The head of this session's transcript: the brief it was started with, verbatim. */
+    /** The head of this session's own transcript: the brief it was started with, verbatim. */
     head: string;
     /** True when this is a spawned subagent rather than the parent session. */
     subagent: boolean;
-    /** The host's own agent type for this spawn, from the sidecar it wrote. Absent on a parent. */
+    /** The agent type the host started this spawn as, from its hook message. Absent on a parent. */
     agentType?: string | undefined;
-    /** The human-readable label the spawning agent gave this subagent. Absent on a parent. */
+    /**
+     * @deprecated Always undefined: a category that reads it never matches. It came from the sidecar
+     * file, which is no longer read, and the hook message carries no description. Kept so a config
+     * that names it still compiles.
+     */
     description?: string | undefined;
 }
 /** A category's recognizer: host-written facts in, a yes or no out. */
@@ -130,17 +134,37 @@ export type TurnAction = {
  */
 export interface Ctx {
     readonly moment: Moment;
-    /** write/touch: the would-be file. */
+    /**
+     * write/touch: the would-be file.
+     *
+     * `existed` says whether a file was at `path` before this change, and it is set only where the
+     * tree can no longer say so. A shell command's change is judged AFTER it has landed, when
+     * `ctx.fs.exists(path)` answers yes to every file it created; at commit every staged file is on
+     * disk, and "before" is the last commit. Absent, ask `ctx.fs`: at write the tree is still the
+     * one from before the change.
+     */
     readonly file?: {
         readonly path: string;
         readonly content: string;
+        readonly existed?: boolean | undefined;
     } | undefined;
     /** command: the line about to run. */
     readonly command?: string | undefined;
+    /**
+     * command: that line parsed as bash — one entry per simple command, nested ones included, in
+     * the order they appear. `null` when the line does not parse: read it as "cannot tell".
+     */
+    readonly commands?: readonly ShellCommand[] | null | undefined;
     /** commit: the staged paths. */
     readonly staged?: readonly string[] | undefined;
     /** turn-end: what the actor did this turn, in order. */
     readonly turn?: readonly TurnAction[] | undefined;
+    /**
+     * Every moment: the category names that match the session making this change — the categories
+     * some bound entry names, whose recognizer said yes to the host-written evidence about it. Empty
+     * when it matches none, which is not "every category".
+     */
+    readonly actor: readonly string[];
     exec(cmd: string): Promise<ExecResult>;
     readonly fs: {
         read(path: string): Promise<string>;
@@ -160,7 +184,7 @@ export type Check = (ctx: Ctx) => Verdict | Promise<Verdict>;
  * The two verdict constructors — INTERNAL to flow, and deliberately not part of its public surface.
  *
  * A check has exactly one way to answer and it is `ctx.ok()` / `ctx.fail(detail)`. That is the
- * spelling the fourteen core checks are written in, the spelling a repo's own check is written in,
+ * spelling the fifteen core checks are written in, the spelling a repo's own check is written in,
  * and the only one flow/index.ts exports. These exist because something has to BUILD the ctx that
  * carries them — the canned one a `.test()` case runs through, and the live one the adapter makes
  * — and that is flow's own job, not a config author's. Exporting both would put two spellings of
@@ -177,6 +201,140 @@ export declare const verdict: {
  * no way to grow a fourth capability that a `.test()` case has no means of recording.
  */
 export type World = Pick<Ctx, "exec" | "fs" | "git">;
+/** One heredoc a command is fed. `quoted` is a delimiter in quotes or after a backslash. */
+export interface ShellHeredoc {
+    readonly body: string;
+    readonly quoted: boolean;
+}
+/** One `$( … )` or backtick substitution the shell runs: the command inside, and which spelling. */
+export interface ShellSubstitution {
+    readonly text: string;
+    readonly backtick: boolean;
+    /** The commands it runs, nested ones included, as `ctx.commands` lists them. */
+    readonly commands: readonly ShellCommand[];
+    /**
+     * The index in its command's `args` of the argument this substitution ends, when only plain text
+     * comes before it there — `-m "$( … )"`, `-m"$( … )"`, `--message="$( … )"` — or null.
+     */
+    readonly argument: number | null;
+    /** That plain text: `""` for an argument that is the substitution alone, `-m` for `-m"$( … )"`. Null with `argument`. */
+    readonly prefix: string | null;
+}
+/** One redirect on a command: its operator (`>`, `>>`, `<`, `2>&1`'s `>&` …) and its target word. */
+export interface ShellRedirect {
+    readonly operator: string;
+    readonly target: string;
+}
+/** One simple command in a parsed line — the fields docs/user/reference/ctx.md promises. */
+export interface ShellCommand {
+    /** The program that runs, after any `FOO=1` assignment and any wrapper. */
+    readonly program: string;
+    /** Its arguments as the program receives them, quotes removed. */
+    readonly args: readonly string[];
+    /** `program` and `args` joined by single spaces. */
+    readonly text: string;
+    readonly heredocs: readonly ShellHeredoc[];
+    /** What the shell runs while building this command's arguments and unquoted heredocs. */
+    readonly substitutions: readonly ShellSubstitution[];
+    /** Its redirects, and those of every group or loop it sits in. A heredoc or here-string is not one. */
+    readonly redirects: readonly ShellRedirect[];
+    /** Inside a substitution, a `<( … )`, a `bash -c` or `eval` string, or a heredoc or here-string fed to a shell. */
+    readonly nested: boolean;
+}
+/**
+ * One piece of a word as the line writes it: text the shell passes as is (quoted, escaped or plain),
+ * a variable it expands (`$NAME`, `${NAME}`), a leading unquoted `~`, or something only running
+ * the line could tell — a substitution, a special parameter, a `${…}` with an operation in it.
+ */
+export type ShellWordPiece = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "variable";
+    readonly name: string;
+} | {
+    readonly kind: "tilde";
+} | {
+    readonly kind: "unknown";
+};
+/** A word as the line writes it, piece by piece, so a reader expands `$F` and leaves `'$F'` alone. */
+export type ShellWord = readonly ShellWordPiece[];
+/**
+ * THE SAME PARSE, IN THE ORDER IT RUNS — for a reader that follows the line the way the shell does:
+ * where a `cd` leaves it, what a variable the line set holds, what a `for` loop's body is given.
+ * Not on ctx, and not public: `ctx.commands` is exactly these steps' commands (`stepCommands`), so
+ * the two can never disagree about what a line runs.
+ */
+export type ShellStep = {
+    readonly kind: "command";
+    readonly command: ShellCommand;
+    /**
+     * Its words as written — wrappers first, no here-string — and where the program starts among
+     * them: `words.slice(0, at)` are the wrappers stepped past (`xargs -a list …`), and the rest
+     * are the program and the arguments it is given. A here-string's text is stdin, not a word.
+     */
+    readonly words: readonly ShellWord[];
+    readonly at: number;
+    /** Whether a `NAME=value` assignment stands in front of it, as its env: `FOO=1 rm`. Not one of its words. */
+    readonly assigned: boolean;
+    /** `command.redirects` with each target as written, so a reader expands `< $F` and leaves `< '$F'` alone. */
+    readonly redirects: readonly StepRedirect[];
+    /** The substitutions that build its words, which run before it does. */
+    readonly before: readonly ShellStep[];
+}
+/**
+ * `NAME=value` on its own, or as an argument of `export`, `declare`, `local`, `readonly` or
+ * `typeset`, which sets a shell variable. In front of a command it is that command's env, and not a step.
+ */
+ | {
+    readonly kind: "assign";
+    readonly name: string;
+    readonly value: ShellWord;
+}
+/** A subshell, a substitution, or a script handed to another shell: a `cd` or a variable set inside stays inside. */
+ | {
+    readonly kind: "scope";
+    readonly body: readonly ShellStep[];
+}
+/** `for name in values; do body; done`: the body runs once per value. `values` is empty when the line lists none. */
+ | {
+    readonly kind: "for";
+    readonly name: string;
+    readonly values: readonly ShellWord[];
+    readonly body: readonly ShellStep[];
+};
+/**
+ * Every command in the steps, nested ones included, in the order they appear in the line: a
+ * command before the commands its own substitutions run, which is the order `ctx.commands` keeps.
+ */
+export declare function stepCommands(steps: readonly ShellStep[]): ShellCommand[];
+/** A redirect on a step: its operator, and its target as written. A redirect with no target has one unknown piece. */
+export interface StepRedirect {
+    readonly operator: string;
+    readonly target: ShellWord;
+}
+/** Whether the program, without its path, is a wrapper the parse steps past to the program that runs. */
+export declare function isWrapper(program: string): boolean;
+/**
+ * A program's name without its path, the ONE way flow reads it: `/usr/bin/git` and `git` are both
+ * `git`. A word ending in `/` names a directory, and gives "".
+ */
+export declare function programName(program: string): string;
+/**
+ * Parse one shell command line as bash: every simple command in it, nested ones included, in the
+ * order they appear — or `null` when the line, or any script nested inside it, does not parse.
+ */
+export declare function parseCommandLine(line: string): ShellCommand[] | null;
+/** The same parse as its steps, in the order the shell runs them — or `null` when it does not parse. */
+export declare function parseShellSteps(line: string): readonly ShellStep[] | null;
+/**
+ * The line as written, less the body of every heredoc in it — the subject a `banCommands` rule
+ * with `wholeLine` matches. The opener and the terminator line stay, and so does everything else,
+ * newlines included. A heredoc a shell reads, directly or through a pipeline, holds commands, and
+ * its body stays; so does a body inside a string the parse reads again (`bash -c`, `eval`), which
+ * is part of that string. `null` when the line does not parse.
+ */
+export declare function elideHeredocBodies(line: string): string | null;
 /**
  * THE ctx builder — the one place a check's world is assembled, and there must only ever be one.
  *
@@ -197,7 +355,8 @@ export declare function makeCtx(moment: Moment, facts: Partial<Ctx>, world: Worl
  * WHY IT IS A VALUE AND NOT A THROW: a check factory runs while the config module is evaluating, so
  * a throw there is a module that will not import, and the reader gets one fault with a stack trace
  * instead of every fault with its entry named. Marked instead, the load collects it beside the
- * grammar's own refusals and the engine blocks every gated moment with the same text — which is the
+ * grammar's own refusals, and the same text answers every gated moment — the engine's `guard`
+ * refuses with it, and the live hook rail passes it to the agent with each call — which is the
  * shape every other load failure already has.
  *
  * WHY IT EXISTS AT ALL: an option can be well-TYPED and still be nonsense — the class that bit here
@@ -263,24 +422,35 @@ export type Case =
 string | {
     readonly command: string;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly path: string;
     readonly content: string;
+    /** The change landed before it was judged, as a shell command's does: `ctx.file.existed`. */
+    readonly existed?: boolean;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly staged: readonly string[];
+    /** The staged paths the last commit does not have. Each file's `ctx.file.existed` says so. */
+    readonly added?: readonly string[];
+    /**
+     * Staged deletions, by path, each with its content as the last commit has it. An entry that
+     * fires at `delete` as well as `commit` is asked about each one, as a delete.
+     */
+    readonly deleted?: Readonly<Record<string, string>>;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly actions: readonly TurnAction[];
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 };
 /** The cases an entry carries: what must pass it, and what must be blocked by it. */
 export interface Cases {
     readonly pass?: readonly Case[];
     readonly block?: readonly Case[];
 }
-/** Does this cases block prove anything? An entry whose answer is no does not load. */
-export declare function hasCases(cases: Cases | undefined): boolean;
 /** What a recorded world was reached for and could not answer. */
 export interface Unanswered {
     readonly kind: "exec" | "read";
@@ -391,6 +561,29 @@ type DeadScope = "flow: every moment this entry fires at carries no path, so .on
  * the other order, and the load's `dead-scope` refusal is what catches it. Both halves, always.
  */
 type Scoping<At extends Moment, Verb, Scopable extends Moment = PathMoment> = [Extract<At, Scopable>] extends [never] ? (dead: DeadScope) => never : Verb;
+/**
+ * `.on(…)` / `.ignore(…)` as a call that takes at least one glob — the compile-time half of the
+ * empty-scope rule.
+ *
+ * Not `(glob: string, ...more: string[])`, and that is the whole design: a shipped pack scopes with
+ * `.on(...repo.files)`, a list whose length is the repo's to choose, and a spread of `string[]`
+ * into a first-required parameter is refused whether the list is empty or not. So the call infers
+ * the arguments it was given, and only the arguments KNOWN to be none — a literal `.on()` — land
+ * on a required parameter that was not passed: tsc's arity error, whose "an argument for
+ * 'atLeastOneGlob' was not provided" note is the advice. A spread list that turns out empty is the
+ * load's `empty-scope` refusal to catch. Both halves, always.
+ */
+type Globs<Next> = <G extends readonly string[]>(...globs: G extends readonly [] ? [atLeastOneGlob: string] : G) => Next;
+/** What the second form of a breadcrumb's prose becomes once the first was said. The TEXT is the diagnostic. */
+type DoubleProse<Said extends string> = `flow: this breadcrumb already said .${Said}(…) — its note is exactly one of .text(…) and .file(…)`;
+/**
+ * `.text(…)` / `.file(…)`, or the refusal once the OTHER form was said — the compile-time half of
+ * the double-prose rule. The same form said twice is `Once`'s job, not this one.
+ *
+ * A wrong-argument refusal rather than a `never`, for the reason `Scoping` gives: the sentence lands
+ * in the diagnostic, on the line of the second form.
+ */
+type Prose<Spoken extends string, Other extends "text" | "file", Verb> = Other extends Spoken ? (both: DoubleProse<Other>) => never : Verb;
 /** Anything a pack may file under an entry name. The one shape `definePack` walks. */
 export interface Sentence<S extends EntrySpec = EntrySpec> {
     readonly spec: S;
@@ -402,8 +595,8 @@ export interface EntryGroup {
 export interface GuardrailSentence<Spoken extends GuardrailKey = never, At extends GuardrailMoment = GuardrailMoment> extends Sentence<GuardrailSpec> {
     readonly at: Once<Spoken, "at", <M extends GuardrailMoment[]>(...moments: M) => GuardrailSentence<Spoken | "at", M[number]>>;
     readonly for: Once<Spoken, "for", (...categories: Category[]) => GuardrailSentence<Spoken | "for", At>>;
-    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => GuardrailSentence<Spoken | "on", At>>>;
-    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => GuardrailSentence<Spoken | "ignore", At>>>;
+    readonly on: Once<Spoken, "on", Scoping<At, Globs<GuardrailSentence<Spoken | "on", At>>>>;
+    readonly ignore: Once<Spoken, "ignore", Scoping<At, Globs<GuardrailSentence<Spoken | "ignore", At>>>>;
     readonly check: Once<Spoken, "check", (check: Check) => GuardrailSentence<Spoken | "check", At>>;
     readonly message: Once<Spoken, "message", (message: string) => GuardrailSentence<Spoken | "message", At>>;
     readonly disabled: Once<Spoken, "disabled", (reason?: string) => GuardrailSentence<Spoken | "disabled", At>>;
@@ -413,10 +606,10 @@ export interface GuardrailSentence<Spoken extends GuardrailKey = never, At exten
 export interface BreadcrumbSentence<Spoken extends BreadcrumbKey = never, At extends BreadcrumbMoment = BreadcrumbMoment> extends Sentence<BreadcrumbSpec> {
     readonly at: Once<Spoken, "at", <M extends BreadcrumbMoment[]>(...moments: M) => BreadcrumbSentence<Spoken | "at", M[number]>>;
     readonly for: Once<Spoken, "for", (...categories: Category[]) => BreadcrumbSentence<Spoken | "for", At>>;
-    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "on", At>, BriefScopeMoment>>;
-    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "ignore", At>, BriefScopeMoment>>;
-    readonly text: Once<Spoken, "text", (text: string) => BreadcrumbSentence<Spoken | "text", At>>;
-    readonly file: Once<Spoken, "file", (path: string) => BreadcrumbSentence<Spoken | "file", At>>;
+    readonly on: Once<Spoken, "on", Scoping<At, Globs<BreadcrumbSentence<Spoken | "on", At>>, BriefScopeMoment>>;
+    readonly ignore: Once<Spoken, "ignore", Scoping<At, Globs<BreadcrumbSentence<Spoken | "ignore", At>>, BriefScopeMoment>>;
+    readonly text: Once<Spoken, "text", Prose<Spoken, "file", (text: string) => BreadcrumbSentence<Spoken | "text", At>>>;
+    readonly file: Once<Spoken, "file", Prose<Spoken, "text", (path: string) => BreadcrumbSentence<Spoken | "file", At>>>;
     readonly disabled: Once<Spoken, "disabled", (reason?: string) => BreadcrumbSentence<Spoken | "disabled", At>>;
     readonly description: Once<Spoken, "description", (description: string) => BreadcrumbSentence<Spoken | "description", At>>;
 }
@@ -538,6 +731,19 @@ export interface Settings {
      * it two ways.
      */
     readonly grammars?: readonly Grammar[];
+    /**
+     * Globs for the IGNORED paths the snapshot records as well. The snapshot is git's view of the
+     * tree — tracked files, and untracked ones git does not ignore — so a shell write to an ignored
+     * file is never seen unless a glob here brings it back. `.env` is the usual one.
+     */
+    readonly snapshotInclude?: readonly string[];
+    /**
+     * What is put back when a rule refuses a write that has already landed: `"refused"` (the default)
+     * writes back only the files a rule refused, `"all"` every file that call changed. While another
+     * agent's call overlaps it, only the refused files are put back whatever this says — that call's
+     * writes can be in the same diff.
+     */
+    readonly revert?: "refused" | "all";
 }
 /**
  * One hand-built tree-sitter grammar, as `registerDynamicLanguage` wants it.
@@ -598,11 +804,11 @@ interface OverrideChain<Kind extends EntrySpec["kind"], Spoken extends OverrideK
     readonly binding: OverrideBinding;
     readonly at: Once<Spoken, "at", (...moments: (Kind extends "guardrail" ? GuardrailMoment : BreadcrumbMoment)[]) => OverrideChain<Kind, Spoken | "at">>;
     readonly for: Once<Spoken, "for", (...categories: Category[]) => OverrideChain<Kind, Spoken | "for">>;
-    readonly on: Once<Spoken, "on", (...globs: string[]) => OverrideChain<Kind, Spoken | "on">>;
-    readonly ignore: Once<Spoken, "ignore", (...globs: string[]) => OverrideChain<Kind, Spoken | "ignore">>;
+    readonly on: Once<Spoken, "on", Globs<OverrideChain<Kind, Spoken | "on">>>;
+    readonly ignore: Once<Spoken, "ignore", Globs<OverrideChain<Kind, Spoken | "ignore">>>;
     readonly message: Kind extends "guardrail" ? Once<Spoken, "message", (message: string) => OverrideChain<Kind, Spoken | "message">> : never;
-    readonly text: Kind extends "breadcrumb" ? Once<Spoken, "text", (text: string) => OverrideChain<Kind, Spoken | "text">> : never;
-    readonly file: Kind extends "breadcrumb" ? Once<Spoken, "file", (path: string) => OverrideChain<Kind, Spoken | "file">> : never;
+    readonly text: Kind extends "breadcrumb" ? Once<Spoken, "text", Prose<Spoken, "file", (text: string) => OverrideChain<Kind, Spoken | "text">>> : never;
+    readonly file: Kind extends "breadcrumb" ? Once<Spoken, "file", Prose<Spoken, "text", (path: string) => OverrideChain<Kind, Spoken | "file">>> : never;
     readonly disabled: Once<Spoken, "disabled", (reason?: string) => OverrideChain<Kind, Spoken | "disabled">>;
     readonly description: Once<Spoken, "description", (description: string) => OverrideChain<Kind, Spoken | "description">>;
 }
@@ -649,7 +855,7 @@ export interface Overlaid {
  */
 export declare function overlay(base: EntrySpec, spoken: Readonly<Record<string, unknown>>, prior?: Readonly<Record<string, "pack" | "override">>): Overlaid;
 /** The closed vocabulary of refusals. Every load failure is exactly one of these. */
-export declare const REFUSAL_CODES: readonly ["not-a-pack", "missing-parameter", "unknown-entry", "unknown-key", "unknown-moment", "missing-mandatory", "undeclared-category", "no-cases", "duplicate-id", "dead-scope", "bad-check-options"];
+export declare const REFUSAL_CODES: readonly ["not-a-pack", "missing-parameter", "unknown-entry", "unknown-key", "unknown-moment", "missing-mandatory", "undeclared-category", "no-block-cases", "duplicate-id", "dead-scope", "bad-check-options", "empty-scope", "double-prose"];
 export type RefusalCode = (typeof REFUSAL_CODES)[number];
 /** One reason the config will not load. */
 export interface Refusal {

package/dist/types/packs/docs.d.ts

@@ -1,20 +1,9 @@
-/**
- * Two documentation audiences, one folder, nothing replicated.
- *
- * Every repo documents for exactly two readers who want opposite things: the end user wants the
- * least possible cognitive load, and the agent wants almost nothing in context. So `docs/` has
- * exactly two doors and everything inside follows its door's rules.
- *
- * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index —
- * `docs/user/index.html` for people and `docs/agent/README.md` as a list of pointers. The two
- * guardrails below refuse anything else at the top of the folder, so a repo with a different shape
- * either moves its pages or does not bind this pack.
- */
+/** The two facts about a repo's docs folder the pack cannot know: where it is, and what may sit loose in it. */
 export interface Doors {
     /**
      * The documentation folder, as a path from the repo root. Defaults to `docs`.
      *
-     * Both guardrails and both breadcrumbs are scoped to it, so a repo whose pages live in
+     * Its guardrail and both breadcrumbs are scoped to it, so a repo whose pages live in
      * `documentation/` names that here and keeps every rule.
      */
     readonly root?: string;
@@ -26,6 +15,21 @@ export interface Doors {
      */
     readonly allow?: readonly string[];
 }
+/**
+ * Two documentation audiences, one folder, nothing replicated.
+ *
+ * Every repo documents for exactly two readers who want opposite things: the end user wants the
+ * least possible cognitive load, and the agent wants almost nothing in context. So `docs/` has
+ * exactly two doors and everything inside follows its door's rules.
+ *
+ * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index — an index
+ * file under `docs/user/` for people and `docs/agent/README.md` as a list of pointers. The user
+ * pages are markdown, and each one is one of the four kinds of the Diátaxis method
+ * (https://diataxis.fr): a tutorial, a how-to guide, a reference or an explanation. The
+ * breadcrumbs say so as guidance and refuse nothing, so how `docs/user/` is foldered inside stays
+ * the repo's choice. The guardrail below refuses anything else at the top of the folder, so a repo
+ * with a different shape either moves its pages or does not bind this pack.
+ */
 export declare const docs: import("../index.ts").Pack<{
     /**
      * Without it, an agent writing under `docs/` has no way to know there are two audiences. User
@@ -45,5 +49,4 @@ export declare const docs: import("../index.ts").Pack<{
      * drawer, and neither audience's rules can be applied to what is in it.
      */
     docsShape: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
-    noMarkdownInUserDocs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
 }, Doors | undefined>;

package/dist/types/packs/flow.d.ts

@@ -8,9 +8,10 @@ export interface Home {
      * list nobody reviews, and here it decides what two rules watch: the nudge when you edit the
      * guard, and the refusal to delete it. Both name it and neither defaults.
      *
-     * The engine derives the REPAIR surface from the config's imports directly (`configSurface`),
-     * because it is asked in the broken state and can only read text. This is the same fact asked
-     * at a moment where the config loads, so it is stated once, here, and typed.
+     * The engine reads the same folders out of the config's imports (`guardPaths`), for the
+     * weaken-after-block report, because that report must answer while the config will not load
+     * and text is all it can read then. This is the same fact asked at a moment where the config
+     * loads, so it is stated once, here, and typed.
      */
     readonly packs: readonly string[];
     /**
@@ -27,8 +28,9 @@ export interface Home {
 /**
  * flow's own orientation and self-protection, as a pack any repo binds.
  *
- * Every guarded repo wants these three: a note saying what is steering you, a nudge when you edit
- * the steering itself, and a refusal when a command would delete it.
+ * Every guarded repo wants these four: a note saying what is steering you, a nudge when you edit
+ * the steering itself, a refusal when a command would delete it, and a refusal when an agent runs
+ * `flow uninstall`, which removes the guard without deleting a file the delete refusal watches.
  *
  * @setup A `flow.config.ts` at the repo root and a folder for the packs the repo writes itself —
  * whatever it is called, named here as the `packs` parameter. `flow init` writes both.
@@ -47,4 +49,12 @@ export declare const flow: import("../index.ts").Pack<{
      */
     editingTheGuardrails: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
     noDeleteGuardrails: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "delete">;
+    /**
+     * Without it, an agent that hit a guardrail could take the whole guard off with one command.
+     * `flow uninstall` removes the commit gate, unsets `core.hooksPath` and removes flow's hook
+     * registrations from inside its own process, so no shell command deletes a file that
+     * `noDeleteGuardrails` watches, and that refusal never fires. A person in their own terminal
+     * has no hooks in front of them, so this refusal never reaches them.
+     */
+    noUninstall: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
 }, Home>;

package/dist/types/packs/git.d.ts

@@ -1,30 +1,14 @@
-/**
- * The working-tree paths a command line would discard OUTRIGHT, or [] when it is safe to run.
- *
- * Deliberately narrow — false negatives beat blocking real work. Every path here is one the
- * command line itself declares: the `--` pathspec form of checkout, the restore forms that touch
- * the tree, and `reset --hard` / `clean -f`, whose target is the tree itself.
- *
- * The BARE form of checkout — `git checkout <thing>` with no `--` — is not here and cannot be:
- * whether `<thing>` is a path or a branch is a fact about the repo, not about the string, and this
- * function is pure. `checkoutBarePaths` below names the candidates and the check asks git.
- */
-export declare function discardPaths(command: string): string[];
-/**
- * The words a bare `git checkout` might be aiming at — candidates, not answers.
- *
- * `git checkout <path>` discards that path exactly as `git checkout -- <path>` does, and until F3
- * only the second was refused. The comment above this rule claimed the narrowing was deliberate
- * ("branch switching passes"), and it was — but it bought that pass by missing the form a person
- * actually types, which the F3 builder proved on itself by running `git checkout adapter/claude.ts`
- * over an hour of uncommitted work and watching the guard allow it.
- *
- * An invocation carrying `--` is skipped: `discardPaths` already has it, and everything before the
- * `--` there is a tree-ish by definition.
- */
-export declare function checkoutBarePaths(command: string): string[];
+import { type Ctx } from "../index.ts";
 /** Of some porcelain lines, the paths with real uncommitted work. */
 export declare function dirtyIn(porcelain: string, includeUntracked: boolean): string[];
+/**
+ * Each way a command line writes a commit or a ref the commit gate never runs on, or [] when it
+ * writes none: `git commit --no-verify` or `-n`, `-c core.hooksPath=…` before any subcommand, and
+ * git's plumbing that writes commits and refs directly (`commit-tree`, `update-ref`,
+ * `hash-object -w`). The git commands are read from the parse, so a `git commit -n` inside a quoted
+ * argument or a heredoc body is not one.
+ */
+export declare function gateSkips(facts: Pick<Ctx, "command" | "commands">): string[];
 /** Does this header line speak Conventional Commits for the given type set? */
 export declare function isConventional(header: string, types: readonly string[]): boolean;
 /**
@@ -95,9 +79,20 @@ export declare const git: import("../index.ts").Pack<{
      * that has no undo.
      */
     orientation: import("../index.ts").BreadcrumbSentence<"text" | "at" | "description", "session">;
+    /**
+     * Claude Code tells every agent to end a commit or a pull request with a line crediting Claude,
+     * and an agent follows the harness's instruction over the repo's. Without this, the credit lands
+     * in history, where removing it means rewriting commits that may already be shared.
+     */
     noAiAttributionInCommits: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     noGitDiscard: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     noForcePush: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    /**
+     * The commit gate is a hook, and git has ways to commit without running it. A commit made that
+     * way holds content no rule judged, and flow treats a commit that already exists as judged: a
+     * later `git switch` to it puts its files in place unread.
+     */
+    noGateSkip: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     conventionalCommitFormat: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     noShellSubstitutionInProse: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     node: {

package/dist/types/packs/justfile.d.ts

@@ -25,13 +25,13 @@ export interface Catalogue {
     /** The folder holding the code behind the recipes. Defaults to `tools`. */
     readonly tools?: string;
     /**
-     * Commands this repo has a recipe for, as a map from the command's pattern to the recipe that
+     * Commands this repo has a recipe for, as a map from the command, in words, to the recipe that
      * replaces it — `{ "npm run build": "just build" }`.
      *
      * OPTIONAL, and with no map there is no entry at all: which raw command a repo has wrapped is a
      * fact only that repo has, and a rule with an empty list would be one more armed entry matching
-     * nothing. The patterns are regular expressions over the command line, so `npx vitest\\b` is a
-     * pattern and `npx vitest` is one too.
+     * nothing. Each key is a command as `banCommands` names one: a program and its arguments, so
+     * `"npx vitest"` refuses `npx vitest run` and `npx --yes vitest`, and passes `npx vitest-preview`.
      *
      * The catalogue's whole promise is that the recipe is the thing to reach for; a breadcrumb says
      * so once a session, and this refuses the raw command by name for the ones that matter.

package/dist/types/packs/secrets.d.ts

@@ -45,9 +45,25 @@ export interface Seam {
     readonly dx?: string;
     /**
      * Seals every env file in place, leaving the public prefixes plaintext. Defaults to dotenvx's
-     * own `dotenvx encrypt`, excluding the prefixes above by name.
+     * own `dotenvx encrypt`, excluding the prefixes above by name, and passing `--no-native` when
+     * `custody` is `"file"`.
      */
     readonly encrypt?: string;
+    /**
+     * Where the private key that decrypts the env files is kept. Defaults to `"native"`.
+     *
+     * `"native"` is the OS secret store: the macOS Keychain, Windows Credential Manager or Linux
+     * Secret Service. dotenvx 2.25 and later write the key there by default, and no file in the repo
+     * holds it. A machine without the key in its store decrypts nothing.
+     *
+     * `"file"` is `.env.keys`, beside the env files and never committed. You copy it by hand to every
+     * machine that runs the code. dotenvx writes it only when `dotenvx encrypt` is passed
+     * `--no-native`.
+     *
+     * The orientation tells the agent which of the two this repo uses, and where to look when a
+     * decrypt comes back empty.
+     */
+    readonly custody?: "native" | "file";
 }
 /**
  * Env files committed encrypted, decrypted through one seam, and the local-only files kept out of
@@ -63,9 +79,14 @@ export interface Seam {
  * ephemera that must never be committed (`.env.keys`, `.dev.vars`, `.env.*.local`), and runtime
  * secrets set per environment on the platform.
  *
- * @install dotenvx — https://dotenvx.com. It is what encrypts the committed files and what runs a
- * command with them decrypted, and with nothing else in place every sentence below names it
- * directly. The two command parameters are for a repo that has wrapped it in recipes of its own.
+ * The private key that decrypts the committed files is kept in one of two places, named by
+ * `custody`: the OS secret store, which is dotenvx's default, or a `.env.keys` file copied by hand
+ * to every machine.
+ *
+ * @install dotenvx 2.25 or later — https://dotenvx.com. It is what encrypts the committed files
+ * and what runs a command with them decrypted, and with nothing else in place every sentence below
+ * names it directly. 2.25 is the first release that keeps the key in the OS secret store by
+ * default. The two command parameters are for a repo that has wrapped it in recipes of its own.
  * @setup `.env.keys`, `.dev.vars` and `.env.*.local` in `.gitignore` — the rules below refuse them
  * in a commit, and an ignore entry is what stops anyone reaching that refusal.
  *
@@ -96,6 +117,13 @@ export interface Seam {
  * Bound, that repo hands over `dx: "just dx"` and `encrypt: "just env-encrypt"`. The third job is
  * nobody's parameter — no sentence in this pack names it — and it is here because an env seam
  * wants it.
+ *
+ * These recipes leave the key's place to dotenvx. Run with no terminal attached, as an agent runs
+ * them, it writes a new key to the OS secret store; in a terminal it asks. A repo bound with
+ * `custody: "file"` adds `--no-native` to the `dotenvx encrypt` line, so dotenvx writes the key to
+ * `.env.keys`. The switch matters only the first time a file is sealed, when its key is created.
+ * `dotenvx run` needs no switch in either case: it reads `.env.keys` before it looks in the OS
+ * secret store.
  * @adopt A repo with no `.env*` at all binds this for `noSecretsInCommits` alone, which is worth
  * having in a repo that has never held a secret, and turns `envEncrypted` off BY NAME in its
  * config with the reason on the record — an entry sitting dead is not the same as one opted out of.