@savvy-web/silk-effects 3.2.5 → 3.3.0

package/index.d.ts

@@ -7484,11 +7484,16 @@ declare class PnpmWorkspace {
 /**
  * Handler for shell script files.
  *
- * Removes executable bit by default (security best practice).
+ * Removes the executable bit by default: Silk repos invoke shell scripts via
+ * `bash <script>`, so the bit is never needed at runtime, and normalizing the
+ * mode keeps diffs clean. Committed `.sh` files landing as `100644` is
+ * intentional, not mode drift.
  *
  * @remarks
- * By default, excludes `.claude/scripts/` which need to remain executable
- * for lint-staged hooks to work.
+ * The default excludes `.claude/scripts/` as a consumer escape-hatch
+ * convention: a repo that needs a script to stay executable across commits
+ * can place it there (or pass its own `exclude` list). Nothing in Silk itself
+ * requires the directory to exist.
  *
  * @example
  * ```typescript
@@ -8625,7 +8630,7 @@ declare const MARKDOWNLINT_TEMPLATE: {
   readonly fix: true;
   readonly gitignore: true;
   readonly noBanner: true;
-  readonly ignores: readonly ["**/.git", "**/node_modules", "**/.cache", "**/coverage", "**/.coverage", "**/dist", "**/CHANGELOG.md", "**/.claude/plans", "**/docs/superpowers", "**/__test__/**/fixtures/**", "**/__fixtures__/**"];
+  readonly ignores: readonly ["**/.git", "**/node_modules", "**/.cache", "**/coverage", "**/.coverage", "**/dist", "**/CHANGELOG.md", "**/.claude/plans", "**/docs/superpowers", "**/__test__/**/fixtures/**", "**/__fixtures__/**", "**/.repos"];
   readonly customRules: readonly ["@savvy-web/silk/changesets/markdownlint"];
   readonly config: {
     readonly default: true;
@@ -8787,6 +8792,341 @@ declare namespace index_d_exports$2 {
   export { BaseHandlerOptions, Biome, BiomeOptions, Command$1 as Command, CreateConfigOptions, DEFAULT_CONFIG_PATH, Filter, HUSKY_HOOK_PATH, Handler, LegacySavvyLintHygieneDef, LintStagedConfig, LintStagedEntry, LintStagedHandler, MARKDOWNLINT_CONFIG, MARKDOWNLINT_CONFIG_PATH, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE, Markdown, MarkdownOptions, POST_CHECKOUT_HOOK_PATH, POST_COMMIT_HOOK_PATH, POST_MERGE_HOOK_PATH, PackageJson, PackageJsonOptions, PackageManager, PnpmWorkspace, PnpmWorkspaceContent, PnpmWorkspaceOptions, Preset, PresetExtendOptions, PresetType, SavvyLintSectionDef, ShellScripts, ShellScriptsOptions, ToolSearchResult, TypeScript, TypeScriptCompiler, TypeScriptOptions, WorkspacePackageInfo, Yaml, YamlOptions, createConfig, generateManagedContent, getWorkspacePackagePaths, getWorkspacePackages, getWorkspaceRoot, isWorkspacePackagePath, resetWorkspaceCache, savvyLintBlock };
 }
 //#endregion
+//#region src/repos/constants.d.ts
+/**
+ * Directory vendored reference repos live under, relative to the repo root.
+ * @public
+ */
+declare const REPOS_DIR = ".repos";
+/**
+ * Path of the committed vendored-repos manifest, relative to the repo root.
+ * @public
+ */
+declare const MANIFEST_PATH = ".repos/config.json";
+/**
+ * Maximum notes per vendored repo; enforced at write time to force
+ * consolidation into orientation.
+ * @public
+ */
+declare const NOTE_LIMIT = 10;
+//#endregion
+//#region src/repos/errors.d.ts
+/** @internal */
+declare const ReposConfigErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ReposConfigError";
+} & Readonly<A>;
+/**
+ * The .repos/config.json manifest is missing, unreadable, or invalid.
+ * @public
+ */
+declare class ReposConfigError extends ReposConfigErrorBase<{
+  readonly path: string;
+  readonly reason: string;
+  readonly kind: "missing" | "invalid";
+}> {
+  get message(): string;
+}
+/** @internal */
+declare const GitSubmoduleErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "GitSubmoduleError";
+} & Readonly<A>;
+/**
+ * A git submodule operation failed.
+ * @public
+ */
+declare class GitSubmoduleError extends GitSubmoduleErrorBase<{
+  readonly command: string;
+  readonly cwd: string;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+/** @internal */
+declare const RepoNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "RepoNotFoundError";
+} & Readonly<A>;
+/**
+ * The named repo is not present in the manifest.
+ * @public
+ */
+declare class RepoNotFoundError extends RepoNotFoundErrorBase<{
+  readonly name: string;
+}> {
+  get message(): string;
+}
+/** @internal */
+declare const NoteNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "NoteNotFoundError";
+} & Readonly<A>;
+/**
+ * The note id does not exist on the named repo.
+ * @public
+ */
+declare class NoteNotFoundError extends NoteNotFoundErrorBase<{
+  readonly name: string;
+  readonly id: string;
+}> {
+  get message(): string;
+}
+//#endregion
+//#region src/repos/schemas/manifest.d.ts
+/**
+ * A vendored-repo manifest key: non-empty, contains no `/` or `\`, and is
+ * never `.` or `..` — safe to join onto a filesystem path segment
+ * (`.repos/<name>`) without escaping the `.repos/` directory.
+ * @public
+ */
+declare const RepoName: Schema.refine<string, typeof Schema.String>;
+/** @public */
+type RepoName = typeof RepoName.Type;
+/**
+ * An agent-appended note: a discovered answer stamped with the pin it was written against.
+ * @public
+ */
+declare const RepoNote: Schema.Struct<{
+  id: typeof Schema.String;
+  date: typeof Schema.String;
+  ref: typeof Schema.String;
+  note: Schema.filter<typeof Schema.String>;
+}>;
+/** @public */
+type RepoNote = typeof RepoNote.Type;
+/**
+ * Curated per-repo orientation: layout, entry points, where to start.
+ * @public
+ */
+declare const RepoOrientation: Schema.Struct<{
+  layout: Schema.optional<typeof Schema.String>;
+  keyPaths: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+  startHere: Schema.optional<typeof Schema.String>;
+}>;
+/** @public */
+type RepoOrientation = typeof RepoOrientation.Type;
+/**
+ * One vendored repo: mechanical intent (url/ref/sparse) plus the agent brief.
+ * @public
+ */
+declare const RepoEntry: Schema.Struct<{
+  url: Schema.filter<typeof Schema.String>;
+  ref: Schema.filter<typeof Schema.String>;
+  purpose: Schema.filter<typeof Schema.String>;
+  sparse: Schema.optional<Schema.Array$<typeof Schema.String>>;
+  orientation: Schema.optional<Schema.Struct<{
+    layout: Schema.optional<typeof Schema.String>;
+    keyPaths: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    startHere: Schema.optional<typeof Schema.String>;
+  }>>;
+  notes: Schema.optional<Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    date: typeof Schema.String;
+    ref: typeof Schema.String;
+    note: Schema.filter<typeof Schema.String>;
+  }>>>;
+}>;
+/** @public */
+type RepoEntry = typeof RepoEntry.Type;
+/**
+ * The committed .repos/config.json manifest.
+ * @public
+ */
+declare const ReposManifestFile: Schema.Struct<{
+  repos: Schema.filter<Schema.Record$<typeof Schema.String, Schema.Struct<{
+    url: Schema.filter<typeof Schema.String>;
+    ref: Schema.filter<typeof Schema.String>;
+    purpose: Schema.filter<typeof Schema.String>;
+    sparse: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    orientation: Schema.optional<Schema.Struct<{
+      layout: Schema.optional<typeof Schema.String>;
+      keyPaths: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+      startHere: Schema.optional<typeof Schema.String>;
+    }>>;
+    notes: Schema.optional<Schema.Array$<Schema.Struct<{
+      id: typeof Schema.String;
+      date: typeof Schema.String;
+      ref: typeof Schema.String;
+      note: Schema.filter<typeof Schema.String>;
+    }>>>;
+  }>>>;
+}>;
+/** @public */
+type ReposManifestFile = typeof ReposManifestFile.Type;
+//#endregion
+//#region src/repos/schemas/reports.d.ts
+/**
+ * Status of one vendored repo: gitlink presence and dirtiness, plus notes
+ * that no longer match the pinned ref.
+ * @public
+ */
+declare const RepoStatusEntry: Schema.Struct<{
+  name: typeof Schema.String;
+  ref: typeof Schema.String;
+  purpose: typeof Schema.String;
+  present: typeof Schema.Boolean;
+  commit: Schema.NullOr<typeof Schema.String>;
+  dirty: typeof Schema.Boolean;
+  staleNoteIds: Schema.Array$<typeof Schema.String>;
+}>;
+/** @public */
+type RepoStatusEntry = typeof RepoStatusEntry.Type;
+/**
+ * Status across all vendored repos in the manifest.
+ * @public
+ */
+declare const ReposStatusReport: Schema.Struct<{
+  repos: Schema.Array$<Schema.Struct<{
+    name: typeof Schema.String;
+    ref: typeof Schema.String;
+    purpose: typeof Schema.String;
+    present: typeof Schema.Boolean;
+    commit: Schema.NullOr<typeof Schema.String>;
+    dirty: typeof Schema.Boolean;
+    staleNoteIds: Schema.Array$<typeof Schema.String>;
+  }>>;
+  clean: typeof Schema.Boolean;
+}>;
+/** @public */
+type ReposStatusReport = typeof ReposStatusReport.Type;
+/**
+ * Result of reconciling working-tree submodules with the manifest: missing
+ * repos initialized, sparse-checkout patterns re-applied, already-present
+ * repos left alone, and stale locks cleared.
+ * @public
+ */
+declare const ReposSyncReport: Schema.Struct<{
+  initialized: Schema.Array$<typeof Schema.String>;
+  sparseApplied: Schema.Array$<typeof Schema.String>;
+  upToDate: Schema.Array$<typeof Schema.String>;
+  clearedLocks: Schema.Array$<typeof Schema.String>;
+}>;
+/** @public */
+type ReposSyncReport = typeof ReposSyncReport.Type;
+/**
+ * Result of re-pinning a vendored repo to a new ref.
+ * @public
+ */
+declare const ReposPinResult: Schema.Struct<{
+  name: typeof Schema.String;
+  ref: typeof Schema.String;
+  oldCommit: Schema.NullOr<typeof Schema.String>;
+  newCommit: typeof Schema.String;
+  commitMessage: typeof Schema.String;
+  staleNoteIds: Schema.Array$<typeof Schema.String>;
+}>;
+/** @public */
+type ReposPinResult = typeof ReposPinResult.Type;
+/**
+ * Result of adding a new vendored repo to the manifest.
+ * @public
+ */
+declare const ReposAddResult: Schema.Struct<{
+  name: typeof Schema.String;
+  ref: typeof Schema.String;
+  path: typeof Schema.String;
+}>;
+/** @public */
+type ReposAddResult = typeof ReposAddResult.Type;
+/**
+ * Result of an agent-note mutation against a vendored repo.
+ * @public
+ */
+declare const ReposNoteResult: Schema.Struct<{
+  name: typeof Schema.String;
+  op: Schema.Literal<["add", "remove", "promote"]>;
+  id: typeof Schema.String;
+  noteCount: typeof Schema.Number;
+}>;
+/** @public */
+type ReposNoteResult = typeof ReposNoteResult.Type;
+//#endregion
+//#region src/repos/services/config-store.d.ts
+/** @internal */
+interface ReposConfigStoreShape {
+  readonly exists: (root: string) => Effect.Effect<boolean>;
+  readonly read: (root: string) => Effect.Effect<ReposManifestFile, ReposConfigError>;
+  readonly write: (root: string, manifest: ReposManifestFile) => Effect.Effect<void, ReposConfigError>;
+}
+/** @internal */
+declare const ReposConfigStoreBase: Context.TagClass<ReposConfigStore, "@savvy-web/silk-effects/ReposConfigStore", ReposConfigStoreShape>;
+/**
+ * Reads, validates, and writes the .repos/config.json manifest.
+ * @public
+ */
+declare class ReposConfigStore extends ReposConfigStoreBase {}
+/**
+ * Live layer over the platform FileSystem.
+ * @public
+ */
+declare const ReposConfigStoreLive: Layer.Layer<ReposConfigStore, never, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/repos/services/manager.d.ts
+/**
+ * Minimum age (in milliseconds) a `.lock` file must reach before `sync` will
+ * remove it. An ACTIVE git process can legitimately hold
+ * `index.lock`/`shallow.lock` for the duration of its own run; removing a
+ * young lock out from under it would corrupt the submodule. Ten minutes
+ * comfortably exceeds any single shallow fetch/checkout this manager
+ * performs, while still reclaiming locks abandoned by a process that was
+ * killed or crashed. A lock younger than this is left in place — the
+ * subsequent git operation fails naturally if it is genuinely contested,
+ * and that failure already propagates.
+ * @public
+ */
+declare const STALE_LOCK_MAX_AGE_MS: number;
+/**
+ * The full contractual surface of {@link ReposManager}. All five methods are
+ * implemented against real git plumbing and the manifest store: `status`
+ * reports drift, `sync` reconciles the working tree with the manifest,
+ * `add` vendors a new repo, `pin` re-pins an existing entry to a new ref,
+ * and `note` adds, removes, or promotes an agent note.
+ * @internal
+ */
+interface ReposManagerShape {
+  readonly status: (root: string) => Effect.Effect<ReposStatusReport, ReposConfigError | GitSubmoduleError>;
+  readonly sync: (root: string) => Effect.Effect<ReposSyncReport, ReposConfigError | GitSubmoduleError>;
+  readonly add: (root: string, options: {
+    readonly url: string;
+    readonly ref: string;
+    readonly purpose: string;
+    readonly name?: string;
+    readonly sparse?: ReadonlyArray<string>;
+  }) => Effect.Effect<ReposAddResult, ReposConfigError | GitSubmoduleError>;
+  readonly pin: (root: string, name: string, ref: string) => Effect.Effect<ReposPinResult, ReposConfigError | GitSubmoduleError | RepoNotFoundError>;
+  readonly note: (root: string, name: string, op: {
+    readonly op: "add";
+    readonly note: string;
+  } | {
+    readonly op: "remove";
+    readonly id: string;
+  } | {
+    readonly op: "promote";
+    readonly id: string;
+    readonly into: "layout" | "startHere";
+  }) => Effect.Effect<ReposNoteResult, ReposConfigError | RepoNotFoundError | NoteNotFoundError>;
+}
+/** @internal */
+declare const ReposManagerBase: Context.TagClass<ReposManager, "@savvy-web/silk-effects/ReposManager", ReposManagerShape>;
+/**
+ * Drives the vendored `.repos/` submodules over git: reports status
+ * (presence, dirtiness, stale notes), reconciles the working tree with the
+ * manifest, vendors new entries (`add`), re-pins existing entries to a new
+ * ref (`pin`), and adds, removes, or promotes agent notes (`note`).
+ * @public
+ */
+declare class ReposManager extends ReposManagerBase {}
+/**
+ * Live implementation of {@link ReposManager}.
+ *
+ * @remarks
+ * Mirrors `TurboInspector`: the `CommandExecutor` is captured once at layer
+ * construction and discharged onto each git invocation via
+ * `Effect.provideService`, so the public method effects stay at `R = never`.
+ * @public
+ */
+declare const ReposManagerLive: Layer.Layer<ReposManager, never, ReposConfigStore | CommandExecutor.CommandExecutor | FileSystem.FileSystem | Path.Path>;
+declare namespace index_d_exports$3 {
+  export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NOTE_LIMIT, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive, ReposConfigStoreShape, ReposManager, ReposManagerBase, ReposManagerLive, ReposManagerShape, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS };
+}
+//#endregion
 //#region src/schemas/BiomeConfig.d.ts
 /**
  * Result of a Biome schema URL sync or check operation.
@@ -10556,9 +10896,9 @@ declare class TurboInspector extends TurboInspector_base {}
  * @since 0.7.0
  */
 declare const TurboInspectorLive: Layer.Layer<TurboInspector, never, ToolDiscovery | CommandExecutor.CommandExecutor | FileSystem.FileSystem>;
-declare namespace index_d_exports$3 {
+declare namespace index_d_exports$4 {
   export { AffectedResult, AffectedResultType, CacheDiagnosis, CacheDiagnosisType, DryRunParseError, GlobalHashSummary, GraphNode, MissExplanation, NotATurboRepoError, PackageCacheStatus, TaskGraphResult, TaskGraphResultType, TurboCache, TurboDigest, TurboDryRun, TurboDryRunType, TurboDryTask, TurboDryTaskType, TurboEnvVars, TurboError, TurboExecError, TurboGlobalCacheInputs, TurboInspector, TurboInspectorLive, TurboNotInstalledError };
 }
 //#endregion
-export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, type BiomeSyncOptions, type BiomeSyncResult, ChangesetConfig, ChangesetConfigError, type ChangesetConfigFile, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, type ChangesetMode, index_d_exports as Changesets, CheckResult, type CheckResultDefinition, type CommentStyle, index_d_exports$1 as Commitlint, type CommitlintPlugin, type CommitlintUserConfig, ConfigDiscovery, ConfigDiscoveryLive, type ConfigDiscoveryOptions, type ConfigLocation, ConfigNotFoundError, type ConfigSource, index_d_exports$2 as Lint, ManagedSection, ManagedSectionLive, type PromptConfig, type PromptSettings, PublishTargetBindingError, PublishabilityDetectorAdaptiveLive, type PublishablePackage, type RawPackageJson, type RawPublishConfig, type RawPublishTargets, type RawTargetObject, type RawTargetValue, ResolutionPolicy, type ResolutionPolicyDefinition, ResolvedTool, type RuleApplicability, type RuleConfigTuple, type RuleSeverity, type RulesConfig, SavvyBaseSection, SavvyHooksSection, SectionBlock, SectionDefinition, SectionDiff, type SectionDiffDefinition, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, type SilkChangesetConfigFile, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, type SourceRequirementDefinition, SyncResult, type SyncResultDefinition, TagFormatError, TagStrategy, TagStrategyLive, type TagStrategyType, type TargetBinding, type TargetGroupBinding, type TargetsBinding, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, index_d_exports$3 as Turbo, VersionExtractor, type VersionExtractorDefinition, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, type VersioningStrategyResult, type VersioningStrategyType, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };
+export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, type BiomeSyncOptions, type BiomeSyncResult, ChangesetConfig, ChangesetConfigError, type ChangesetConfigFile, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, type ChangesetMode, index_d_exports as Changesets, CheckResult, type CheckResultDefinition, type CommentStyle, index_d_exports$1 as Commitlint, type CommitlintPlugin, type CommitlintUserConfig, ConfigDiscovery, ConfigDiscoveryLive, type ConfigDiscoveryOptions, type ConfigLocation, ConfigNotFoundError, type ConfigSource, index_d_exports$2 as Lint, ManagedSection, ManagedSectionLive, type PromptConfig, type PromptSettings, PublishTargetBindingError, PublishabilityDetectorAdaptiveLive, type PublishablePackage, type RawPackageJson, type RawPublishConfig, type RawPublishTargets, type RawTargetObject, type RawTargetValue, index_d_exports$3 as Repos, ResolutionPolicy, type ResolutionPolicyDefinition, ResolvedTool, type RuleApplicability, type RuleConfigTuple, type RuleSeverity, type RulesConfig, SavvyBaseSection, SavvyHooksSection, SectionBlock, SectionDefinition, SectionDiff, type SectionDiffDefinition, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, type SilkChangesetConfigFile, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, type SourceRequirementDefinition, SyncResult, type SyncResultDefinition, TagFormatError, TagStrategy, TagStrategyLive, type TagStrategyType, type TargetBinding, type TargetGroupBinding, type TargetsBinding, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, index_d_exports$4 as Turbo, VersionExtractor, type VersionExtractorDefinition, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, type VersioningStrategyResult, type VersioningStrategyType, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -21,6 +21,7 @@ import { SectionBlock } from "./schemas/SectionBlock.js";
 import { SectionDefinition, ShellSectionDefinition } from "./schemas/SectionDefinition.js";
 import { SavvyBaseSection, SavvyHooksSection, savvyBasePreamble, savvyHooksHygiene, savvyToolSection } from "./schemas/SavvySections.js";
 import { lint_exports } from "./lint/index.js";
+import { repos_exports } from "./repos/index.js";
 import { ToolCommand } from "./utils/ToolCommand.js";
 import { ResolutionPolicy, SourceRequirement, ToolSource, VersionExtractor } from "./schemas/ToolResults.js";
 import { ResolvedTool } from "./schemas/ResolvedTool.js";
@@ -35,4 +36,4 @@ import { SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive } from "./services/Sil
 import { ToolDiscovery, ToolDiscoveryLive } from "./services/ToolDiscovery.js";
 import { turbo_exports } from "./turbo/index.js";
 
-export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, changesets_exports as Changesets, CheckResult, commitlint_exports as Commitlint, ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError, lint_exports as Lint, ManagedSection, ManagedSectionLive, PublishTargetBindingError, PublishabilityDetectorAdaptiveLive, ResolutionPolicy, ResolvedTool, SavvyBaseSection, SavvyHooksSection, SectionBlock, SectionDefinition, SectionDiff, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, SyncResult, TagFormatError, TagStrategy, TagStrategyLive, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, turbo_exports as Turbo, VersionExtractor, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };
+export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, changesets_exports as Changesets, CheckResult, commitlint_exports as Commitlint, ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError, lint_exports as Lint, ManagedSection, ManagedSectionLive, PublishTargetBindingError, PublishabilityDetectorAdaptiveLive, repos_exports as Repos, ResolutionPolicy, ResolvedTool, SavvyBaseSection, SavvyHooksSection, SectionBlock, SectionDefinition, SectionDiff, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, SyncResult, TagFormatError, TagStrategy, TagStrategyLive, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, turbo_exports as Turbo, VersionExtractor, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };

package/lint/cli/templates/markdownlint.gen.js

@@ -26,7 +26,8 @@ const MARKDOWNLINT_TEMPLATE = {
 		"**/.claude/plans",
 		"**/docs/superpowers",
 		"**/__test__/**/fixtures/**",
-		"**/__fixtures__/**"
+		"**/__fixtures__/**",
+		"**/.repos"
 	],
 	customRules: ["@savvy-web/silk/changesets/markdownlint"],
 	config: {

package/lint/handlers/ShellScripts.js

@@ -4,11 +4,16 @@ import { Filter } from "../utils/Filter.js";
 /**
 * Handler for shell script files.
 *
-* Removes executable bit by default (security best practice).
+* Removes the executable bit by default: Silk repos invoke shell scripts via
+* `bash <script>`, so the bit is never needed at runtime, and normalizing the
+* mode keeps diffs clean. Committed `.sh` files landing as `100644` is
+* intentional, not mode drift.
 *
 * @remarks
-* By default, excludes `.claude/scripts/` which need to remain executable
-* for lint-staged hooks to work.
+* The default excludes `.claude/scripts/` as a consumer escape-hatch
+* convention: a repo that needs a script to stay executable across commits
+* can place it there (or pass its own `exclude` list). Nothing in Silk itself
+* requires the directory to exist.
 *
 * @example
 * ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "3.2.5",
+	"version": "3.3.0",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",

package/repos/constants.js

@@ -0,0 +1,20 @@
+//#region src/repos/constants.ts
+/**
+* Directory vendored reference repos live under, relative to the repo root.
+* @public
+*/
+const REPOS_DIR = ".repos";
+/**
+* Path of the committed vendored-repos manifest, relative to the repo root.
+* @public
+*/
+const MANIFEST_PATH = ".repos/config.json";
+/**
+* Maximum notes per vendored repo; enforced at write time to force
+* consolidation into orientation.
+* @public
+*/
+const NOTE_LIMIT = 10;
+
+//#endregion
+export { MANIFEST_PATH, REPOS_DIR };

package/repos/errors.js

@@ -0,0 +1,50 @@
+import { Data } from "effect";
+
+//#region src/repos/errors.ts
+/** @internal */
+const ReposConfigErrorBase = Data.TaggedError("ReposConfigError");
+/**
+* The .repos/config.json manifest is missing, unreadable, or invalid.
+* @public
+*/
+var ReposConfigError = class extends ReposConfigErrorBase {
+	get message() {
+		return `repos manifest ${this.kind} at ${this.path}: ${this.reason}`;
+	}
+};
+/** @internal */
+const GitSubmoduleErrorBase = Data.TaggedError("GitSubmoduleError");
+/**
+* A git submodule operation failed.
+* @public
+*/
+var GitSubmoduleError = class extends GitSubmoduleErrorBase {
+	get message() {
+		return `git command failed in ${this.cwd}: ${this.command}\n${this.reason}`;
+	}
+};
+/** @internal */
+const RepoNotFoundErrorBase = Data.TaggedError("RepoNotFoundError");
+/**
+* The named repo is not present in the manifest.
+* @public
+*/
+var RepoNotFoundError = class extends RepoNotFoundErrorBase {
+	get message() {
+		return `no vendored repo named "${this.name}" in the manifest`;
+	}
+};
+/** @internal */
+const NoteNotFoundErrorBase = Data.TaggedError("NoteNotFoundError");
+/**
+* The note id does not exist on the named repo.
+* @public
+*/
+var NoteNotFoundError = class extends NoteNotFoundErrorBase {
+	get message() {
+		return `no note "${this.id}" on vendored repo "${this.name}"`;
+	}
+};
+
+//#endregion
+export { GitSubmoduleError, GitSubmoduleErrorBase, NoteNotFoundError, NoteNotFoundErrorBase, RepoNotFoundError, RepoNotFoundErrorBase, ReposConfigError, ReposConfigErrorBase };

package/repos/index.js

@@ -0,0 +1,43 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { MANIFEST_PATH, REPOS_DIR } from "./constants.js";
+import { GitSubmoduleError, GitSubmoduleErrorBase, NoteNotFoundError, NoteNotFoundErrorBase, RepoNotFoundError, RepoNotFoundErrorBase, ReposConfigError, ReposConfigErrorBase } from "./errors.js";
+import { RepoEntry, RepoName, RepoNote, RepoOrientation, ReposManifestFile } from "./schemas/manifest.js";
+import { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport } from "./schemas/reports.js";
+import { ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive } from "./services/config-store.js";
+import { ReposManager, ReposManagerBase, ReposManagerLive, STALE_LOCK_MAX_AGE_MS } from "./services/manager.js";
+
+//#region src/repos/index.ts
+var repos_exports = /* @__PURE__ */ __exportAll({
+	GitSubmoduleError: () => GitSubmoduleError,
+	GitSubmoduleErrorBase: () => GitSubmoduleErrorBase,
+	MANIFEST_PATH: () => MANIFEST_PATH,
+	NOTE_LIMIT: () => 10,
+	NoteNotFoundError: () => NoteNotFoundError,
+	NoteNotFoundErrorBase: () => NoteNotFoundErrorBase,
+	REPOS_DIR: () => REPOS_DIR,
+	RepoEntry: () => RepoEntry,
+	RepoName: () => RepoName,
+	RepoNotFoundError: () => RepoNotFoundError,
+	RepoNotFoundErrorBase: () => RepoNotFoundErrorBase,
+	RepoNote: () => RepoNote,
+	RepoOrientation: () => RepoOrientation,
+	RepoStatusEntry: () => RepoStatusEntry,
+	ReposAddResult: () => ReposAddResult,
+	ReposConfigError: () => ReposConfigError,
+	ReposConfigErrorBase: () => ReposConfigErrorBase,
+	ReposConfigStore: () => ReposConfigStore,
+	ReposConfigStoreBase: () => ReposConfigStoreBase,
+	ReposConfigStoreLive: () => ReposConfigStoreLive,
+	ReposManager: () => ReposManager,
+	ReposManagerBase: () => ReposManagerBase,
+	ReposManagerLive: () => ReposManagerLive,
+	ReposManifestFile: () => ReposManifestFile,
+	ReposNoteResult: () => ReposNoteResult,
+	ReposPinResult: () => ReposPinResult,
+	ReposStatusReport: () => ReposStatusReport,
+	ReposSyncReport: () => ReposSyncReport,
+	STALE_LOCK_MAX_AGE_MS: () => STALE_LOCK_MAX_AGE_MS
+});
+
+//#endregion
+export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive, ReposManager, ReposManagerBase, ReposManagerLive, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, repos_exports };

package/repos/schemas/manifest.js

@@ -0,0 +1,73 @@
+import { Schema } from "effect";
+
+//#region src/repos/schemas/manifest.ts
+/**
+* A vendored-repo manifest key: non-empty, contains no `/` or `\`, and is
+* never `.` or `..` — safe to join onto a filesystem path segment
+* (`.repos/<name>`) without escaping the `.repos/` directory.
+* @public
+*/
+const RepoName = Schema.String.pipe(Schema.pattern(/^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/), Schema.annotations({ identifier: "RepoName" }));
+/**
+* An agent-appended note: a discovered answer stamped with the pin it was written against.
+* @public
+*/
+const RepoNote = Schema.Struct({
+	id: Schema.String,
+	date: Schema.String,
+	ref: Schema.String,
+	note: Schema.String.pipe(Schema.minLength(1))
+});
+/**
+* Curated per-repo orientation: layout, entry points, where to start.
+* @public
+*/
+const RepoOrientation = Schema.Struct({
+	layout: Schema.optional(Schema.String),
+	keyPaths: Schema.optional(Schema.Record({
+		key: Schema.String,
+		value: Schema.String
+	})),
+	startHere: Schema.optional(Schema.String)
+});
+/**
+* One vendored repo: mechanical intent (url/ref/sparse) plus the agent brief.
+* @public
+*/
+const RepoEntry = Schema.Struct({
+	url: Schema.String.pipe(Schema.minLength(1)),
+	ref: Schema.String.pipe(Schema.minLength(1)),
+	purpose: Schema.String.pipe(Schema.minLength(1)),
+	sparse: Schema.optional(Schema.Array(Schema.String)),
+	orientation: Schema.optional(RepoOrientation),
+	notes: Schema.optional(Schema.Array(RepoNote))
+});
+/**
+* Bad-key guard for {@link ReposManifestFile}.
+*
+* @remarks
+* `Schema.Record`'s key schema has "pick matching keys" semantics: a key
+* that fails to decode against the key schema is silently OMITTED from the
+* decoded record rather than failing the decode (Effect Schema issue-free
+* by design, since a record's key schema is also used to select entries out
+* of a wider object). That is the opposite of what a manifest guard needs —
+* a bad key must REJECT the whole decode, not vanish. So `repos` decodes
+* with a permissive `Schema.String` key (nothing is dropped) and this
+* filter walks every key against {@link RepoName} itself, failing loudly
+* and naming the offending key.
+*/
+const isRepoName = Schema.is(RepoName);
+/**
+* The committed .repos/config.json manifest.
+* @public
+*/
+const ReposManifestFile = Schema.Struct({ repos: Schema.Record({
+	key: Schema.String,
+	value: RepoEntry
+}).pipe(Schema.filter((repos) => {
+	const badKey = Object.keys(repos).find((key) => !isRepoName(key));
+	return badKey === void 0 ? void 0 : `every repos key must be a valid RepoName (non-empty, no "/" or "\\", not "." or ".."); got ${JSON.stringify(badKey)}`;
+})) });
+
+//#endregion
+export { RepoEntry, RepoName, RepoNote, RepoOrientation, ReposManifestFile };

package/repos/schemas/reports.js

@@ -0,0 +1,71 @@
+import { Schema } from "effect";
+
+//#region src/repos/schemas/reports.ts
+/**
+* Status of one vendored repo: gitlink presence and dirtiness, plus notes
+* that no longer match the pinned ref.
+* @public
+*/
+const RepoStatusEntry = Schema.Struct({
+	name: Schema.String,
+	ref: Schema.String,
+	purpose: Schema.String,
+	present: Schema.Boolean,
+	commit: Schema.NullOr(Schema.String),
+	dirty: Schema.Boolean,
+	staleNoteIds: Schema.Array(Schema.String)
+});
+/**
+* Status across all vendored repos in the manifest.
+* @public
+*/
+const ReposStatusReport = Schema.Struct({
+	repos: Schema.Array(RepoStatusEntry),
+	clean: Schema.Boolean
+});
+/**
+* Result of reconciling working-tree submodules with the manifest: missing
+* repos initialized, sparse-checkout patterns re-applied, already-present
+* repos left alone, and stale locks cleared.
+* @public
+*/
+const ReposSyncReport = Schema.Struct({
+	initialized: Schema.Array(Schema.String),
+	sparseApplied: Schema.Array(Schema.String),
+	upToDate: Schema.Array(Schema.String),
+	clearedLocks: Schema.Array(Schema.String)
+});
+/**
+* Result of re-pinning a vendored repo to a new ref.
+* @public
+*/
+const ReposPinResult = Schema.Struct({
+	name: Schema.String,
+	ref: Schema.String,
+	oldCommit: Schema.NullOr(Schema.String),
+	newCommit: Schema.String,
+	commitMessage: Schema.String,
+	staleNoteIds: Schema.Array(Schema.String)
+});
+/**
+* Result of adding a new vendored repo to the manifest.
+* @public
+*/
+const ReposAddResult = Schema.Struct({
+	name: Schema.String,
+	ref: Schema.String,
+	path: Schema.String
+});
+/**
+* Result of an agent-note mutation against a vendored repo.
+* @public
+*/
+const ReposNoteResult = Schema.Struct({
+	name: Schema.String,
+	op: Schema.Literal("add", "remove", "promote"),
+	id: Schema.String,
+	noteCount: Schema.Number
+});
+
+//#endregion
+export { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport };

package/repos/services/config-store.js

@@ -0,0 +1,86 @@
+import { MANIFEST_PATH, REPOS_DIR } from "../constants.js";
+import { ReposConfigError } from "../errors.js";
+import { ReposManifestFile } from "../schemas/manifest.js";
+import { Context, Effect, Layer, Schema } from "effect";
+import { FileSystem, Path } from "@effect/platform";
+
+//#region src/repos/services/config-store.ts
+const _tag = Context.Tag("@savvy-web/silk-effects/ReposConfigStore");
+/** @internal */
+const ReposConfigStoreBase = _tag();
+/**
+* Reads, validates, and writes the .repos/config.json manifest.
+* @public
+*/
+var ReposConfigStore = class extends ReposConfigStoreBase {};
+/**
+* Live layer over the platform FileSystem.
+* @public
+*/
+const ReposConfigStoreLive = Layer.effect(ReposConfigStore, Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const manifestPath = (root) => path.join(root, MANIFEST_PATH);
+	const exists = (root) => fs.exists(manifestPath(root)).pipe(Effect.orElseSucceed(() => false));
+	const read = (root) => Effect.gen(function* () {
+		if (!(yield* fs.exists(manifestPath(root)).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: `stat failed: ${String(cause)}`,
+			kind: "invalid"
+		}))))) return yield* Effect.fail(new ReposConfigError({
+			path: manifestPath(root),
+			reason: "no such file",
+			kind: "missing"
+		}));
+		const text = yield* fs.readFileString(manifestPath(root)).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: String(cause),
+			kind: "invalid"
+		})));
+		const json = yield* Effect.try({
+			try: () => JSON.parse(text),
+			catch: (cause) => new ReposConfigError({
+				path: manifestPath(root),
+				reason: `invalid JSON: ${String(cause)}`,
+				kind: "invalid"
+			})
+		});
+		return yield* Schema.decodeUnknown(ReposManifestFile)(json).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: String(cause),
+			kind: "invalid"
+		})));
+	});
+	const write = (root, manifest) => Effect.gen(function* () {
+		const dir = path.join(root, REPOS_DIR);
+		yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: `mkdir failed: ${String(cause)}`,
+			kind: "invalid"
+		})));
+		const encoded = yield* Schema.encode(ReposManifestFile)(manifest).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: String(cause),
+			kind: "invalid"
+		})));
+		const tmpPath = `${manifestPath(root)}.tmp`;
+		yield* fs.writeFileString(tmpPath, `${JSON.stringify(encoded, null, "	")}\n`).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: String(cause),
+			kind: "invalid"
+		})));
+		yield* fs.rename(tmpPath, manifestPath(root)).pipe(Effect.mapError((cause) => new ReposConfigError({
+			path: manifestPath(root),
+			reason: `rename failed: ${String(cause)}`,
+			kind: "invalid"
+		})));
+	});
+	return {
+		exists,
+		read,
+		write
+	};
+}));
+
+//#endregion
+export { ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive };

package/repos/services/manager.js

@@ -0,0 +1,384 @@
+import { MANIFEST_PATH, REPOS_DIR } from "../constants.js";
+import { GitSubmoduleError, NoteNotFoundError, RepoNotFoundError, ReposConfigError } from "../errors.js";
+import { RepoName } from "../schemas/manifest.js";
+import { ReposConfigStore } from "./config-store.js";
+import { Clock, Context, Effect, Layer, Option, Schema, Stream } from "effect";
+import { Command, CommandExecutor, FileSystem, Path } from "@effect/platform";
+import { createHash } from "node:crypto";
+
+//#region src/repos/services/manager.ts
+/**
+* Lock files git leaves behind when a submodule fetch is interrupted; `sync`
+* clears these before attempting to (re)initialize a submodule.
+*/
+const STALE_LOCKS = ["index.lock", "shallow.lock"];
+/**
+* Minimum age (in milliseconds) a `.lock` file must reach before `sync` will
+* remove it. An ACTIVE git process can legitimately hold
+* `index.lock`/`shallow.lock` for the duration of its own run; removing a
+* young lock out from under it would corrupt the submodule. Ten minutes
+* comfortably exceeds any single shallow fetch/checkout this manager
+* performs, while still reclaiming locks abandoned by a process that was
+* killed or crashed. A lock younger than this is left in place — the
+* subsequent git operation fails naturally if it is genuinely contested,
+* and that failure already propagates.
+* @public
+*/
+const STALE_LOCK_MAX_AGE_MS = 10 * 6e4;
+const _tag = Context.Tag("@savvy-web/silk-effects/ReposManager");
+/** @internal */
+const ReposManagerBase = _tag();
+/**
+* Drives the vendored `.repos/` submodules over git: reports status
+* (presence, dirtiness, stale notes), reconciles the working tree with the
+* manifest, vendors new entries (`add`), re-pins existing entries to a new
+* ref (`pin`), and adds, removes, or promotes agent notes (`note`).
+* @public
+*/
+var ReposManager = class extends ReposManagerBase {};
+/**
+* Live implementation of {@link ReposManager}.
+*
+* @remarks
+* Mirrors `TurboInspector`: the `CommandExecutor` is captured once at layer
+* construction and discharged onto each git invocation via
+* `Effect.provideService`, so the public method effects stay at `R = never`.
+* @public
+*/
+const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
+	const configStore = yield* ReposConfigStore;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const executor = yield* CommandExecutor.CommandExecutor;
+	const runGit = (cwd, args) => Effect.scoped(Effect.gen(function* () {
+		const process = yield* executor.start(Command.workingDirectory(Command.make("git", ...args), cwd));
+		const [exitCode, stdout, stderr] = yield* Effect.all([
+			process.exitCode,
+			process.stdout.pipe(Stream.decodeText(), Stream.runFold("", (acc, chunk) => acc + chunk)),
+			process.stderr.pipe(Stream.decodeText(), Stream.runFold("", (acc, chunk) => acc + chunk))
+		], { concurrency: 3 });
+		if (exitCode !== 0) return yield* Effect.fail(new GitSubmoduleError({
+			command: `git ${args.join(" ")}`,
+			cwd,
+			reason: stderr.trim().length > 0 ? stderr.trim() : `exit code ${exitCode}`
+		}));
+		return stdout.trim();
+	})).pipe(Effect.catchAll((cause) => Effect.fail(cause instanceof GitSubmoduleError ? cause : new GitSubmoduleError({
+		command: `git ${args.join(" ")}`,
+		cwd,
+		reason: String(cause)
+	}))));
+	const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
+	const status = (root) => Effect.gen(function* () {
+		const manifest = yield* configStore.read(root);
+		const repos = yield* Effect.forEach(Object.entries(manifest.repos), ([name, entry]) => Effect.gen(function* () {
+			const repoPath = path.join(root, REPOS_DIR, name);
+			const present = yield* isPresent(repoPath);
+			const lsTree = yield* runGit(root, [
+				"ls-tree",
+				"HEAD",
+				"--",
+				`${REPOS_DIR}/${name}`
+			]);
+			const commit = lsTree.length > 0 ? lsTree.split(/\s+/)[2] ?? null : null;
+			let dirty = false;
+			if (present) dirty = (yield* runGit(repoPath, ["status", "--porcelain"])).length > 0;
+			const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== entry.ref).map((note) => note.id);
+			return {
+				name,
+				ref: entry.ref,
+				purpose: entry.purpose,
+				present,
+				commit,
+				dirty,
+				staleNoteIds
+			};
+		}));
+		return {
+			repos,
+			clean: repos.every((entry) => entry.present && !entry.dirty && entry.staleNoteIds.length === 0)
+		};
+	});
+	const sync = (root) => Effect.gen(function* () {
+		const manifest = yield* configStore.read(root);
+		const initialized = [];
+		const sparseApplied = [];
+		const upToDate = [];
+		const clearedLocks = [];
+		for (const [name, entry] of Object.entries(manifest.repos)) {
+			const repoPath = path.join(root, REPOS_DIR, name);
+			const moduleDir = path.join(root, ".git", "modules", REPOS_DIR, name);
+			let clearedAnyLock = false;
+			for (const lock of STALE_LOCKS) {
+				const lockPath = path.join(moduleDir, lock);
+				const info = yield* fs.stat(lockPath).pipe(Effect.option);
+				if (Option.isNone(info)) continue;
+				const mtime = info.value.mtime;
+				if (Option.isNone(mtime)) continue;
+				if ((yield* Clock.currentTimeMillis) - mtime.value.getTime() < 6e5) continue;
+				if (yield* fs.remove(lockPath).pipe(Effect.match({
+					onSuccess: () => true,
+					onFailure: () => false
+				}))) clearedAnyLock = true;
+			}
+			if (clearedAnyLock) clearedLocks.push(name);
+			if (!(yield* isPresent(repoPath))) {
+				yield* runGit(root, [
+					"submodule",
+					"update",
+					"--init",
+					"--depth",
+					"1",
+					"--",
+					`${REPOS_DIR}/${name}`
+				]);
+				initialized.push(name);
+			} else upToDate.push(name);
+			if (entry.sparse && entry.sparse.length > 0) {
+				yield* runGit(repoPath, [
+					"sparse-checkout",
+					"set",
+					"--no-cone",
+					...entry.sparse
+				]);
+				sparseApplied.push(name);
+			}
+		}
+		return {
+			initialized,
+			sparseApplied,
+			upToDate,
+			clearedLocks
+		};
+	});
+	/** Last path segment of a repo URL, with a trailing `.git` stripped. */
+	const repoSlug = (url) => {
+		const last = url.split("/").filter((segment) => segment.length > 0).pop() ?? url;
+		return last.endsWith(".git") ? last.slice(0, -4) : last;
+	};
+	/**
+	* Fetch `ref` shallow into a submodule. Tags need the explicit
+	* `fetch origin tag <ref>` form; branches/commits fall back to a plain
+	* `fetch origin <ref>`.
+	*/
+	const fetchRef = (sub, ref) => runGit(sub, [
+		"fetch",
+		"--depth",
+		"1",
+		"origin",
+		"tag",
+		ref
+	]).pipe(Effect.orElse(() => runGit(sub, [
+		"fetch",
+		"--depth",
+		"1",
+		"origin",
+		ref
+	])));
+	const add = (root, options) => Effect.gen(function* () {
+		const name = options.name ?? repoSlug(options.url);
+		yield* Schema.decodeUnknown(RepoName)(name).pipe(Effect.mapError(() => new ReposConfigError({
+			path: MANIFEST_PATH,
+			reason: `invalid repo name "${name}": must be non-empty, contain no "/" or "\\", and not be "." or ".."`,
+			kind: "invalid"
+		})));
+		const manifest = yield* configStore.read(root).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? Effect.succeed({ repos: {} }) : Effect.fail(error)));
+		if (manifest.repos[name]) return yield* Effect.fail(new ReposConfigError({
+			path: MANIFEST_PATH,
+			reason: `"${name}" is already vendored — use pin to change its ref`,
+			kind: "invalid"
+		}));
+		const repoPath = `${REPOS_DIR}/${name}`;
+		const subPath = path.join(root, repoPath);
+		yield* runGit(root, [
+			"submodule",
+			"add",
+			"--depth",
+			"1",
+			options.url,
+			repoPath
+		]);
+		yield* runGit(root, [
+			"config",
+			"-f",
+			".gitmodules",
+			`submodule.${repoPath}.shallow`,
+			"true"
+		]);
+		yield* fetchRef(subPath, options.ref);
+		yield* runGit(subPath, [
+			"checkout",
+			"--detach",
+			"FETCH_HEAD"
+		]);
+		if (options.sparse && options.sparse.length > 0) yield* runGit(subPath, [
+			"sparse-checkout",
+			"set",
+			"--no-cone",
+			...options.sparse
+		]);
+		const entry = {
+			url: options.url,
+			ref: options.ref,
+			purpose: options.purpose,
+			...options.sparse && options.sparse.length > 0 ? { sparse: options.sparse } : {}
+		};
+		yield* configStore.write(root, { repos: {
+			...manifest.repos,
+			[name]: entry
+		} });
+		yield* runGit(root, [
+			"add",
+			".gitmodules",
+			MANIFEST_PATH,
+			repoPath
+		]);
+		return {
+			name,
+			ref: options.ref,
+			path: repoPath
+		};
+	});
+	const pin = (root, name, ref) => Effect.gen(function* () {
+		const manifest = yield* configStore.read(root);
+		const entry = manifest.repos[name];
+		if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+		const repoPath = `${REPOS_DIR}/${name}`;
+		const subPath = path.join(root, repoPath);
+		const oldCommit = yield* runGit(subPath, ["rev-parse", "HEAD"]).pipe(Effect.orElseSucceed(() => null));
+		yield* fetchRef(subPath, ref);
+		yield* runGit(subPath, [
+			"checkout",
+			"--detach",
+			"FETCH_HEAD"
+		]);
+		const newCommit = yield* runGit(subPath, ["rev-parse", "HEAD"]);
+		yield* configStore.write(root, { repos: {
+			...manifest.repos,
+			[name]: {
+				...entry,
+				ref
+			}
+		} });
+		yield* runGit(root, [
+			"add",
+			MANIFEST_PATH,
+			repoPath
+		]);
+		const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== ref).map((note) => note.id);
+		return {
+			name,
+			ref,
+			oldCommit,
+			newCommit,
+			commitMessage: `chore(repos): pin ${name} to ${ref}`,
+			staleNoteIds
+		};
+	});
+	const note = (root, name, op) => Effect.gen(function* () {
+		const manifest = yield* configStore.read(root);
+		const entry = manifest.repos[name];
+		if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+		const notes = entry.notes ?? [];
+		if (op.op === "add") {
+			if (notes.length >= 10) return yield* Effect.fail(new ReposConfigError({
+				path: MANIFEST_PATH,
+				reason: `note limit (${10}) reached for ${name}; promote or remove notes first`,
+				kind: "invalid"
+			}));
+			const existingIds = new Set(notes.map((existing) => existing.id));
+			const hash = createHash("sha256").update(op.note).digest("hex");
+			let id;
+			for (let len = 4; len <= hash.length; len += 4) {
+				const candidate = `n-${hash.slice(0, len)}`;
+				if (!existingIds.has(candidate)) {
+					id = candidate;
+					break;
+				}
+			}
+			if (id === void 0) {
+				let counter = 2;
+				let candidate = `n-${hash}-${counter}`;
+				while (existingIds.has(candidate)) {
+					counter += 1;
+					candidate = `n-${hash}-${counter}`;
+				}
+				id = candidate;
+			}
+			const millis = yield* Clock.currentTimeMillis;
+			const date = new Date(millis).toISOString().slice(0, 10);
+			const newNote = {
+				id,
+				date,
+				ref: entry.ref,
+				note: op.note
+			};
+			const updatedNotes = [...notes, newNote];
+			const updatedEntry = {
+				...entry,
+				notes: updatedNotes
+			};
+			yield* configStore.write(root, { repos: {
+				...manifest.repos,
+				[name]: updatedEntry
+			} });
+			return {
+				name,
+				op: "add",
+				id,
+				noteCount: updatedNotes.length
+			};
+		}
+		const target = notes.find((existing) => existing.id === op.id);
+		if (!target) return yield* Effect.fail(new NoteNotFoundError({
+			name,
+			id: op.id
+		}));
+		const updatedNotes = notes.filter((existing) => existing.id !== op.id);
+		if (op.op === "remove") {
+			const updatedEntry = {
+				...entry,
+				notes: updatedNotes
+			};
+			yield* configStore.write(root, { repos: {
+				...manifest.repos,
+				[name]: updatedEntry
+			} });
+			return {
+				name,
+				op: "remove",
+				id: op.id,
+				noteCount: updatedNotes.length
+			};
+		}
+		const updatedOrientation = {
+			...entry.orientation,
+			[op.into]: target.note
+		};
+		const updatedEntry = {
+			...entry,
+			orientation: updatedOrientation,
+			notes: updatedNotes
+		};
+		yield* configStore.write(root, { repos: {
+			...manifest.repos,
+			[name]: updatedEntry
+		} });
+		return {
+			name,
+			op: "promote",
+			id: op.id,
+			noteCount: updatedNotes.length
+		};
+	});
+	return ReposManager.of({
+		status,
+		sync,
+		add,
+		pin,
+		note
+	});
+}));
+
+//#endregion
+export { ReposManager, ReposManagerBase, ReposManagerLive, STALE_LOCK_MAX_AGE_MS };