@llm4ts/flow 0.15.1 → 0.16.1

package/dist/StoryPlan.js

@@ -0,0 +1,242 @@
+// The epic-level plan of the parallel story executor (ADR 0013): stories
+// with a declared dependency graph and declared file ownership. Dependencies
+// are declared here, up front, never discovered by a running coder.
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { PlanParseError, StoryPlanInvalid } from "./FlowError.js";
+import { stableHash } from "./Plan.js";
+export const StoryPlanVersion = 1;
+export class Story extends Schema.Class("Story")({
+    /** Kebab-case, unique within the plan; names the branch and the worktree. */
+    id: Schema.String,
+    title: Schema.String,
+    description: Schema.String,
+    /** Story ids this one waits for; they are merged before this one starts. */
+    dependsOn: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.succeed([])), Schema.withDecodingDefaultKey(Effect.succeed([]))),
+    /** Repo-relative path prefixes (files or directories) the story may create or change. */
+    owned: Schema.Array(Schema.String),
+    /** Path prefixes fed as context and forbidden to change. */
+    sharedReadOnly: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.succeed([])), Schema.withDecodingDefaultKey(Effect.succeed([]))),
+    /** What dependents may rely on: routes, exports, contracts. */
+    provides: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.succeed([])), Schema.withDecodingDefaultKey(Effect.succeed([])))
+}) {
+}
+export class StoryPlan extends Schema.Class("StoryPlan")({
+    epicId: Schema.String,
+    /** The epic as the operator phrased it. */
+    epic: Schema.String,
+    stories: Schema.Array(Story)
+}) {
+    story(id) {
+        return this.stories.find((story) => story.id === id);
+    }
+}
+/** A path prefix in canonical form: no `./`, no trailing slash, forward slashes. */
+export const normalizePath = (path) => path
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^(\.\/)+/, "")
+    .replace(/\/+$/, "");
+/** Whether `path` is `prefix` itself or lies under it. */
+export const pathWithin = (path, prefix) => {
+    const target = normalizePath(path);
+    const root = normalizePath(prefix);
+    return root.length === 0 || target === root || target.startsWith(`${root}/`);
+};
+const overlapping = (left, right) => pathWithin(left, right) || pathWithin(right, left);
+/**
+ * Every violation of the plan's invariants, in one pass — an operator fixing
+ * a hand-edited plan wants the whole list, not a rerun per finding.
+ */
+export const storyPlanViolations = (plan) => {
+    const violations = [];
+    const ids = new Set();
+    for (const story of plan.stories) {
+        if (ids.has(story.id)) {
+            violations.push(`duplicate story id '${story.id}'`);
+        }
+        ids.add(story.id);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(story.id)) {
+            violations.push(`story id '${story.id}' is not kebab-case`);
+        }
+        if (story.owned.length === 0) {
+            violations.push(`story '${story.id}' owns no paths`);
+        }
+        for (const dependency of story.dependsOn) {
+            if (dependency === story.id) {
+                violations.push(`story '${story.id}' depends on itself`);
+            }
+            else if (!plan.stories.some((candidate) => candidate.id === dependency)) {
+                violations.push(`story '${story.id}' depends on unknown story '${dependency}'`);
+            }
+        }
+        for (const owned of story.owned) {
+            for (const shared of story.sharedReadOnly) {
+                if (overlapping(owned, shared)) {
+                    violations.push(`story '${story.id}' both owns '${owned}' and declares '${shared}' shared read-only`);
+                }
+            }
+        }
+    }
+    for (let index = 0; index < plan.stories.length; index += 1) {
+        const left = plan.stories[index];
+        if (left === undefined) {
+            continue;
+        }
+        for (const right of plan.stories.slice(index + 1)) {
+            for (const leftPath of left.owned) {
+                for (const rightPath of right.owned) {
+                    if (overlapping(leftPath, rightPath)) {
+                        violations.push(`stories '${left.id}' and '${right.id}' both own '${normalizePath(leftPath)}' / '${normalizePath(rightPath)}'`);
+                    }
+                }
+            }
+        }
+    }
+    for (const cycle of cycles(plan)) {
+        violations.push(`dependency cycle: ${cycle.join(" -> ")}`);
+    }
+    return violations;
+};
+const cycles = (plan) => {
+    const found = [];
+    const state = new Map();
+    const visit = (id, trail) => {
+        const mark = state.get(id);
+        if (mark === "done") {
+            return;
+        }
+        if (mark === "visiting") {
+            const start = trail.indexOf(id);
+            found.push([...trail.slice(start), id]);
+            return;
+        }
+        state.set(id, "visiting");
+        for (const dependency of plan.story(id)?.dependsOn ?? []) {
+            // A self-edge is already reported as "depends on itself".
+            if (dependency !== id && plan.story(dependency) !== undefined) {
+                visit(dependency, [...trail, id]);
+            }
+        }
+        state.set(id, "done");
+    };
+    for (const story of plan.stories) {
+        visit(story.id, []);
+    }
+    return found;
+};
+export const validateStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.validate")(function* (plan) {
+    const violations = storyPlanViolations(plan);
+    return violations.length === 0 ? plan : yield* StoryPlanInvalid.make({ violations });
+});
+/**
+ * Stories grouped by the earliest wave they can run in (all dependencies in
+ * earlier waves). Assumes a valid plan; a cycle leaves its members out.
+ */
+export const topologicalWaves = (plan) => {
+    const waves = [];
+    const placed = new Set();
+    let remaining = plan.stories.map((story) => story.id);
+    while (remaining.length > 0) {
+        const wave = remaining.filter((id) => (plan.story(id)?.dependsOn ?? []).every((dependency) => placed.has(dependency)));
+        if (wave.length === 0) {
+            break;
+        }
+        waves.push(wave);
+        for (const id of wave) {
+            placed.add(id);
+        }
+        remaining = remaining.filter((id) => !placed.has(id));
+    }
+    return waves;
+};
+/** Stories that may start now: not yet touched, every dependency done. Plan order. */
+export const readyStories = (plan, progress) => plan.stories.filter((story) => !progress.done.has(story.id) &&
+    !progress.failed.has(story.id) &&
+    !progress.skipped.has(story.id) &&
+    !progress.running.has(story.id) &&
+    story.dependsOn.every((dependency) => progress.done.has(dependency)));
+/** Every story that transitively depends on `id`, in plan order. */
+export const dependentsOf = (plan, id) => {
+    const blocked = new Set([id]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const story of plan.stories) {
+            if (!blocked.has(story.id) && story.dependsOn.some((dependency) => blocked.has(dependency))) {
+                blocked.add(story.id);
+                grew = true;
+            }
+        }
+    }
+    return plan.stories
+        .map((story) => story.id)
+        .filter((candidate) => candidate !== id && blocked.has(candidate));
+};
+/** Stable over the story entry's content — a changed entry means a fresh branch. */
+export const storyHash = (story) => stableHash(JSON.stringify({
+    id: story.id,
+    title: story.title,
+    description: story.description,
+    dependsOn: [...story.dependsOn],
+    owned: [...story.owned].map(normalizePath),
+    sharedReadOnly: [...story.sharedReadOnly].map(normalizePath),
+    provides: [...story.provides]
+}));
+export const storyPlanFenceInfo = "json storyplan";
+const fencePattern = /```json[ \t]+storyplan[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*```/;
+/** The raw JSON of the first ```json storyplan fenced block, if any. */
+export const storyPlanBlock = (markdown) => fencePattern.exec(markdown)?.[1];
+/**
+ * Decodes the story plan embedded in its markdown file. Decoding only —
+ * `validateStoryPlan` checks the graph invariants separately, so a parse
+ * failure and an invalid plan are told apart.
+ */
+export const parseStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.parse")(function* (markdown) {
+    const block = storyPlanBlock(markdown);
+    if (block === undefined) {
+        return yield* PlanParseError.make({
+            message: "no ```json storyplan fenced block in the story plan markdown"
+        });
+    }
+    return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(StoryPlan))(block).pipe(Effect.mapError((error) => PlanParseError.make({ message: `invalid story plan block: ${String(error)}` })));
+});
+const list = (items) => items.length === 0 ? "none" : items.join(", ");
+/**
+ * The operator-facing markdown: a readable summary per story plus the
+ * fenced block that is the source of truth. Editing the block and rerunning
+ * is the approval and the re-plan path.
+ */
+export const renderStoryPlan = Effect.fn("@llm4ts/flow/StoryPlan.render")(function* (plan) {
+    const encoded = yield* Schema.encodeEffect(StoryPlan)(plan).pipe(Effect.mapError((error) => PlanParseError.make({ message: `story plan not encodable: ${String(error)}` })));
+    const waves = topologicalWaves(plan);
+    const lines = [
+        `# Epic: ${plan.epicId}`,
+        "",
+        plan.epic.trim(),
+        "",
+        "## Waves",
+        "",
+        ...waves.map((wave, index) => `${index + 1}. ${wave.join(", ")}`),
+        "",
+        "## Stories",
+        ""
+    ];
+    for (const story of plan.stories) {
+        lines.push(`### ${story.id} — ${story.title}`, "", story.description.trim(), "", `- depends on: ${list(story.dependsOn)}`, `- owned: ${list(story.owned)}`, `- shared read-only: ${list(story.sharedReadOnly)}`, `- provides: ${list(story.provides)}`, "");
+    }
+    lines.push("## Plan block", "", "Edit this block to change the plan; the prose above is regenerated from it.", "", "```" + storyPlanFenceInfo, JSON.stringify(encoded, null, 2), "```", "");
+    return lines.join("\n");
+});
+export const makeStoryPlanStore = (files) => {
+    const save = (path, plan) => Effect.flatMap(renderStoryPlan(plan), (markdown) => files.writeAtomic(path, markdown));
+    const load = (path) => Effect.flatMap(files.read(path), (contents) => contents === undefined ? Effect.succeed(undefined) : parseStoryPlan(contents));
+    return {
+        save,
+        load,
+        recoverOrCreate: (path, create) => Effect.flatMap(load(path), (stored) => stored === undefined
+            ? Effect.tap(create, (plan) => save(path, plan))
+            : Effect.succeed(stored))
+    };
+};
+//# sourceMappingURL=StoryPlan.js.map

package/dist/StoryPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoryPlan.js","sourceRoot":"","sources":["../src/StoryPlan.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,7 @@
     "./Package": "./dist/Package.js",
     "./PageSpec": "./dist/PageSpec.js",
     "./Patterns": "./dist/Patterns.js",
+    "./Perimeter": "./dist/Perimeter.js",
     "./Persistence": "./dist/Persistence.js",
     "./Plan": "./dist/Plan.js",
     "./PlanExecution": "./dist/PlanExecution.js",
@@ -56,6 +57,8 @@
     "./ReviewCache": "./dist/ReviewCache.js",
     "./Reviewer": "./dist/Reviewer.js",
     "./SpecChecks": "./dist/SpecChecks.js",
+    "./Stories": "./dist/Stories.js",
+    "./StoryPlan": "./dist/StoryPlan.js",
     "./Survey": "./dist/Survey.js",
     "./TransientRetry": "./dist/TransientRetry.js",
     "./Usage": "./dist/Usage.js",
@@ -86,7 +89,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "0.15.1"
+    "@llm4ts/core": "0.16.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"

package/src/BoardSync.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
+import * as Semaphore from "effect/Semaphore"
 import { quoteWiql, type AzureDevOpsToolShape } from "./AzureDevOpsTool.ts"
 import { FlowAborted, type FlowError } from "./FlowError.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
@@ -138,6 +139,10 @@ export const makeLocalBoardSync = (
 ): BoardSyncShape => {
   const jsonPath = join(directory, "board.json")
   const markdownPath = join(directory, "board.md")
+  // Every mutation is load → change → save; stories running in parallel
+  // (ADR 0013) mutate the board at the same time, and without the permit
+  // the last save wins and the others' transitions vanish.
+  const lock = Semaphore.makeUnsafe(1)
 
   const load: Effect.Effect<Board, FlowError> = loadVersioned(
     files,
@@ -155,29 +160,33 @@ export const makeLocalBoardSync = (
     id: string,
     transform: (item: BoardItem) => BoardItem
   ): Effect.Effect<void, FlowError> =>
-    Effect.gen(function* () {
-      const board = yield* load
-      if (!board.items.some((item) => item.id === id)) {
-        return yield* FlowAborted.make({ message: `board has no item '${id}' — plan it first` })
-      }
-      yield* save(
-        Board.make({
-          ...board,
-          items: board.items.map((item) => (item.id === id ? transform(item) : item))
-        })
-      )
-    })
+    lock.withPermit(
+      Effect.gen(function* () {
+        const board = yield* load
+        if (!board.items.some((item) => item.id === id)) {
+          return yield* FlowAborted.make({ message: `board has no item '${id}' — plan it first` })
+        }
+        yield* save(
+          Board.make({
+            ...board,
+            items: board.items.map((item) => (item.id === id ? transform(item) : item))
+          })
+        )
+      })
+    )
 
   return {
     plan: (items) =>
-      Effect.gen(function* () {
-        const board = yield* load
-        const known = new Map(board.items.map((item) => [item.id, item] as const))
-        // Known ids keep their lived state — re-planning must never demote a
-        // converted page back to "planned".
-        const merged = [...board.items, ...items.filter((item) => !known.has(item.id))]
-        yield* save(Board.make({ title: board.title, items: merged }))
-      }),
+      lock.withPermit(
+        Effect.gen(function* () {
+          const board = yield* load
+          const known = new Map(board.items.map((item) => [item.id, item] as const))
+          // Known ids keep their lived state — re-planning must never demote a
+          // converted page back to "planned".
+          const merged = [...board.items, ...items.filter((item) => !known.has(item.id))]
+          yield* save(Board.make({ title: board.title, items: merged }))
+        })
+      ),
     start: (id) => update(id, (item) => BoardItem.make({ ...item, status: "active" })),
     complete: (id, result) => update(id, (item) => applyResult(item, "done", result)),
     fail: (id, reason) =>

package/src/FlowContext.ts

@@ -1,6 +1,9 @@
 import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
 import type { ConnectorCapabilities } from "@llm4ts/core/Models"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { FlowError } from "./FlowError.ts"
 import type { FlowEventsShape } from "./FlowEvents.ts"
 import type { GitToolShape } from "./GitTool.ts"
 import type { GitHubToolShape } from "./GitHubTool.ts"
@@ -16,6 +19,13 @@ export interface FlowContextShape {
   readonly userPrompt: string
   readonly workDir: string
   readonly workspace: string
+  /**
+   * The same seats rebound to another directory (a story worktree, ADR
+   * 0013): every CLI seat launched there, git rooted there, the run's
+   * events and cost tracking shared. Absent when the runner cannot rebind
+   * (an embedded context built by hand).
+   */
+  readonly contextFor?: (workDir: string) => Effect.Effect<FlowContextShape, FlowError, Scope.Scope>
 }
 
 export class FlowContext extends Context.Service<FlowContext, FlowContextShape>()(

package/src/FlowError.ts

@@ -124,6 +124,74 @@ export class BudgetExceeded extends Schema.TaggedErrorClass<BudgetExceeded>()("B
   }
 }
 
+/** A story plan that failed deterministic validation — every violation, not the first (ADR 0013). */
+export class StoryPlanInvalid extends Schema.TaggedErrorClass<StoryPlanInvalid>()(
+  "StoryPlanInvalid",
+  {
+    violations: Schema.Array(Schema.String)
+  }
+) {
+  get message(): string {
+    return `story plan invalid:\n${this.violations.map((violation) => `- ${violation}`).join("\n")}`
+  }
+}
+
+/** A story branch changed paths outside the story's declared `owned` set. */
+export class PerimeterViolation extends Schema.TaggedErrorClass<PerimeterViolation>()(
+  "PerimeterViolation",
+  {
+    story: Schema.String,
+    outside: Schema.Array(Schema.String),
+    sharedReadOnly: Schema.Array(Schema.String)
+  }
+) {
+  get message(): string {
+    const lines = [`story '${this.story}' changed paths outside its perimeter:`]
+    for (const path of this.sharedReadOnly) {
+      lines.push(`- ${path} (shared read-only: revert it, or request it as a dedicated story)`)
+    }
+    for (const path of this.outside) {
+      lines.push(`- ${path} (not in the story's owned paths)`)
+    }
+    return lines.join("\n")
+  }
+}
+
+/** The coder ended a story with `BLOCKED_ON:` — unplanned work belongs to another story. */
+export class MissingDependency extends Schema.TaggedErrorClass<MissingDependency>()(
+  "MissingDependency",
+  {
+    story: Schema.String,
+    need: Schema.String
+  }
+) {
+  get message(): string {
+    return `story '${this.story}' is blocked on unplanned work: ${this.need}`
+  }
+}
+
+/** A story branch did not merge cleanly into the epic branch; the merge was aborted. */
+export class MergeConflict extends Schema.TaggedErrorClass<MergeConflict>()("MergeConflict", {
+  branch: Schema.String,
+  into: Schema.String,
+  paths: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    const where = this.paths.length === 0 ? "" : `: ${this.paths.join(", ")}`
+    return `merging '${this.branch}' into '${this.into}' conflicted${where}`
+  }
+}
+
+/** One story failed; carries the story id so a fail-fast run names its cause. */
+export class StoryFailed extends Schema.TaggedErrorClass<StoryFailed>()("StoryFailed", {
+  story: Schema.String,
+  reason: Schema.String
+}) {
+  get message(): string {
+    return `story '${this.story}' failed: ${this.reason}`
+  }
+}
+
 export const FlowError = Schema.Union([
   PersistenceError,
   PlanParseError,
@@ -136,6 +204,11 @@ export const FlowError = Schema.Union([
   FlowLlmError,
   FlowCapabilityDenied,
   ColumnNotFound,
-  BudgetExceeded
+  BudgetExceeded,
+  StoryPlanInvalid,
+  PerimeterViolation,
+  MissingDependency,
+  MergeConflict,
+  StoryFailed
 ])
 export type FlowError = typeof FlowError.Type

package/src/GitTool.ts

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { Capabilities, type Capability } from "@llm4ts/core/Capability"
 import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
-import { ProcessError, type FlowError } from "./FlowError.ts"
+import { MergeConflict, ProcessError, type FlowError } from "./FlowError.ts"
 import type { FlowEventsShape } from "./FlowEvents.ts"
 import { guarded } from "./CapabilityGuard.ts"
 
@@ -56,8 +56,26 @@ export interface GitToolShape {
   readonly push: (remote: string, branch: string) => Effect.Effect<void, FlowError>
   readonly checkpoint: Effect.Effect<string, FlowError>
   readonly rollback: (checkpoint: string) => Effect.Effect<void, FlowError>
+  /** Checks an EXISTING branch out into a new worktree at `path`. */
   readonly addWorktree: (path: string, branch: string) => Effect.Effect<void, FlowError>
-  readonly removeWorktree: (path: string) => Effect.Effect<void, FlowError>
+  /** Creates `branch` at `startPoint` and checks it out into a new worktree at `path`. */
+  readonly addWorktreeNewBranch: (
+    path: string,
+    branch: string,
+    startPoint: string
+  ) => Effect.Effect<void, FlowError>
+  /** `force` also removes a worktree holding untracked or modified files. */
+  readonly removeWorktree: (path: string, force?: boolean) => Effect.Effect<void, FlowError>
+  readonly branchExists: (name: string) => Effect.Effect<boolean, FlowError>
+  readonly deleteBranch: (name: string) => Effect.Effect<void, FlowError>
+  /** Whether `commit` is reachable from `of` — a merged story branch is an ancestor of the epic head. */
+  readonly isAncestor: (commit: string, of: string) => Effect.Effect<boolean, FlowError>
+  /**
+   * Merges `branch` into the checked-out branch with a merge commit. A
+   * conflict fails typed with the conflicting paths and leaves the tree as it
+   * was (the merge is aborted), so the next merge can proceed.
+   */
+  readonly merge: (branch: string, message: string) => Effect.Effect<void, FlowError>
 }
 
 const nonInteractiveEnvironment = Object.freeze({
@@ -287,7 +305,59 @@ export const makeGitTool = (
       write("git rollback", runOrFail(["reset", "--hard", checkpoint]).pipe(Effect.asVoid)),
     addWorktree: (path, branch) =>
       write("git worktree add", runOrFail(["worktree", "add", path, branch]).pipe(Effect.asVoid)),
-    removeWorktree: (path) =>
-      write("git worktree remove", runOrFail(["worktree", "remove", path]).pipe(Effect.asVoid))
+    addWorktreeNewBranch: (path, branch, startPoint) =>
+      write(
+        "git worktree add -b",
+        runOrFail(["worktree", "add", "-b", branch, path, startPoint]).pipe(Effect.asVoid)
+      ),
+    removeWorktree: (path, force = false) =>
+      write(
+        "git worktree remove",
+        runOrFail(["worktree", "remove", ...(force ? ["--force"] : []), path]).pipe(Effect.asVoid)
+      ),
+    branchExists: (name) =>
+      read(
+        "git branchExists",
+        Effect.map(verifiedRef(`refs/heads/${name}`), (found) => found !== undefined)
+      ),
+    deleteBranch: (name) =>
+      write("git branch -D", runOrFail(["branch", "-D", name]).pipe(Effect.asVoid)),
+    isAncestor: (commit, of) =>
+      read(
+        "git merge-base --is-ancestor",
+        Effect.flatMap(run(["merge-base", "--is-ancestor", commit, of]), (result) =>
+          result.exitCode === 0
+            ? Effect.succeed(true)
+            : result.exitCode === 1
+              ? Effect.succeed(false)
+              : Effect.fail(
+                  ProcessError.make({
+                    message: `git merge-base --is-ancestor ${commit} ${of}`,
+                    detail: problem(result)
+                  })
+                )
+        )
+      ),
+    merge: (branch, message) =>
+      write(
+        "git merge",
+        Effect.gen(function* () {
+          const result = yield* run(["merge", "--no-ff", "-m", message, branch])
+          if (result.exitCode === 0) {
+            return
+          }
+          const into = yield* runOrFail(["rev-parse", "--abbrev-ref", "HEAD"])
+          const unmerged = yield* run(["diff", "--name-only", "--diff-filter=U"])
+          const paths = text(unmerged.stdout)
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+          // Abort regardless of the outcome so the epic tree is clean for the
+          // next story; a merge that failed before starting has nothing to
+          // abort and git says so, which is not a second failure.
+          yield* run(["merge", "--abort"])
+          return yield* MergeConflict.make({ branch, into, paths })
+        })
+      )
   }
 }

package/src/Perimeter.ts

@@ -0,0 +1,49 @@
+// The story perimeter check (ADR 0013): a story branch may only change what
+// the story owns. Enforced after the fact on the branch's changed files —
+// the prompt states the rule, this is what makes it true.
+import * as Effect from "effect/Effect"
+import { PerimeterViolation } from "./FlowError.ts"
+import { pathWithin, type Story } from "./StoryPlan.ts"
+
+export interface PerimeterCheck {
+  /** Changed paths under a `sharedReadOnly` prefix — the worse class, reported first. */
+  readonly sharedReadOnly: ReadonlyArray<string>
+  /** Changed paths under neither `owned` nor `sharedReadOnly`. */
+  readonly outside: ReadonlyArray<string>
+}
+
+export const checkPerimeter = (
+  changedPaths: ReadonlyArray<string>,
+  story: Story
+): PerimeterCheck => {
+  const sharedReadOnly: Array<string> = []
+  const outside: Array<string> = []
+  for (const path of changedPaths) {
+    if (story.owned.some((prefix) => pathWithin(path, prefix))) {
+      continue
+    }
+    if (story.sharedReadOnly.some((prefix) => pathWithin(path, prefix))) {
+      sharedReadOnly.push(path)
+    } else {
+      outside.push(path)
+    }
+  }
+  return { sharedReadOnly, outside }
+}
+
+export const isWithinPerimeter = (check: PerimeterCheck): boolean =>
+  check.sharedReadOnly.length === 0 && check.outside.length === 0
+
+export const enforcePerimeter = Effect.fn("@llm4ts/flow/Perimeter.enforce")(function* (
+  changedPaths: ReadonlyArray<string>,
+  story: Story
+): Effect.fn.Return<void, PerimeterViolation> {
+  const check = checkPerimeter(changedPaths, story)
+  if (!isWithinPerimeter(check)) {
+    return yield* PerimeterViolation.make({
+      story: story.id,
+      outside: check.outside,
+      sharedReadOnly: check.sharedReadOnly
+    })
+  }
+})