@basou/core 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -132,6 +132,10 @@ declare const ManifestSchema: z.ZodObject<{
                 "en+ja": "en+ja";
             }>>;
         }, z.core.$loose>>>;
+        instructions: z.ZodOptional<z.ZodEnum<{
+            hub: "hub";
+            self: "self";
+        }>>;
     }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** Inferred runtime type for {@link ManifestSchema}. */
@@ -3612,6 +3616,15 @@ type RepoVisibility = "public" | "private" | "future-public";
 type RepoLanguage = "en" | "ja" | "en+ja";
 /** A published surface a repo emits: a deployed website or a package registry. */
 type PublishKind = "web" | "npm";
+/**
+ * Where a repo's agent instruction files live (the instruction-source axis),
+ * independent of visibility / language / publishes. `hub` is basou's native,
+ * generated hub-and-spoke topology (canonical in the anchor, gitignored symlinks
+ * in each repo); `self` is the additive opt-in where the canonical AGENTS.md is a
+ * regular committed file in the repo itself and basou stays hands-off about its
+ * content. See {@link instructionMode} for the default (absent => `hub`).
+ */
+type RepoInstructions = "hub" | "self";
 /**
  * One published surface. Its visibility and language are INDEPENDENT of the
  * source repo's: a private repo commonly publishes a public website. Both are
@@ -3632,7 +3645,24 @@ type RepoEntry = {
     language?: RepoLanguage | undefined;
     /** Published surfaces this repo emits (opt-in; absent for a repo that publishes nothing). */
     publishes?: PublishTarget[] | undefined;
+    /**
+     * Instruction-source mode. Absent => `hub` (basou's native generated topology),
+     * so an existing roster's behavior is unchanged. `self` opts the repo out of
+     * generation: its AGENTS.md is a hand-authored committed file and basou stays
+     * hands-off. Resolve the effective mode with {@link instructionMode}.
+     */
+    instructions?: RepoInstructions | undefined;
 };
+/**
+ * The effective instruction-source mode for a repo: the declared `instructions`,
+ * defaulting to `hub` when absent. The default is the single guarantee that an
+ * existing roster (which has no `instructions` field) keeps basou's current
+ * hub-and-spoke behavior byte-for-byte — every generator branches on this, never
+ * on the raw optional field, so "absent => hub" is decided in exactly one place.
+ */
+declare function instructionMode(entry: {
+    instructions?: RepoInstructions | undefined;
+}): RepoInstructions;
 type RosterDriftSummary = {
     declaredCount: number;
     capturedCount: number;
@@ -3815,6 +3845,13 @@ type RepoGitignoreFacts = {
     path: string;
     /** Declared visibility; undefined when the operator has not set it yet. */
     visibility?: RepoVisibility | undefined;
+    /**
+     * True when this repo declares `instructions: self`: its instruction files are
+     * committed and SHARED, so they must NOT be gitignored — the repo is skipped
+     * (reported as `self`, never an addition) regardless of visibility. Absent =>
+     * the default `hub` behavior, unchanged.
+     */
+    self?: boolean | undefined;
     /** False when the repo path could not be resolved / is not a usable git repo. */
     reachable: boolean;
     /** Existing `.gitignore` lines, trimmed; an empty array when there is no `.gitignore`. */
@@ -3830,21 +3867,30 @@ type GitignorePlanSummary = {
     plans: RepoGitignorePlan[];
     /** Repo paths skipped because visibility is unset (cannot decide safely). */
     unknown: string[];
+    /**
+     * `instructions: self` repo paths, skipped by design: their instruction files
+     * are committed and shared, so they are never gitignored. Reported (not
+     * silently dropped) and do NOT block the `ok` verdict — being skipped is the
+     * intended terminal state, not a gap.
+     */
+    self: string[];
     /** Repo paths that could not be resolved / are not usable git repos. */
     unreachable: string[];
     /**
      * True only when nothing needs adding AND every repo was judgeable and
      * reachable — so a clean verdict is never claimed while some repos were
-     * skipped (unset visibility) or could not be inspected (unreachable).
+     * skipped (unset visibility) or could not be inspected (unreachable). A `self`
+     * repo does not block it (it is intentionally not gitignored).
      */
     ok: boolean;
 };
 /**
  * Compute the {@link GitignorePlanSummary}: for each public-facing, reachable
  * repo, the `required` patterns that are not already present in its `.gitignore`
- * (compared by trimmed exact line). Private repos require nothing; unset
- * visibility is reported as `unknown` and unreachable repos as `unreachable`.
- * `ok` is true when no repo needs any addition.
+ * (compared by trimmed exact line). Private repos require nothing; a `self` repo
+ * is reported as `self` (its committed instruction files are shared, never
+ * gitignored); unset visibility is reported as `unknown` and unreachable repos as
+ * `unreachable`. `ok` is true when no repo needs any addition.
  */
 declare function planGitignore(input: {
     repos: RepoGitignoreFacts[];
@@ -3902,6 +3948,13 @@ type RepoPresetFacts = {
     path: string;
     /** True when this repo IS the project anchor (its own AGENTS.md is hand-maintained; skipped). */
     isAnchor: boolean;
+    /**
+     * True when this repo declares `instructions: self`: its AGENTS.md is
+     * hand-authored and basou stays hands-off — no preset block is ever written
+     * (reported as `self`, skipped like an anchor). Absent => the default `hub`
+     * behavior, unchanged.
+     */
+    self?: boolean | undefined;
     /** False when the repo path could not be resolved / is not a usable git repo. */
     reachable: boolean;
     /** Declared fields (the render input). */
@@ -3971,14 +4024,16 @@ type PresetPlanSummary = {
     collisions: PresetCollision[];
     /** Repos that resolve to the anchor (their own AGENTS.md is hand-maintained; skipped). */
     anchors: string[];
+    /** `instructions: self` repos: hands-off, skipped (basou never writes their AGENTS.md). */
+    self: string[];
     /** Repo paths that could not be resolved / are not usable git repos. */
     unreachable: string[];
     /**
      * True only when nothing needs writing AND there are no marker conflicts, no
      * unreadable canonicals, no collisions, no unreachable repos, and no
      * undeclared repos — so a clean "all in sync" verdict is never claimed while
-     * some repo was skipped or unjudgeable. Anchors do not block it (they are
-     * intentionally not generated).
+     * some repo was skipped or unjudgeable. Anchors and `self` repos do not block
+     * it (they are intentionally not generated).
      */
     ok: boolean;
 };
@@ -4068,6 +4123,115 @@ declare function planRename(input: {
     oldIsAnchor?: boolean;
 }): RenamePlan;
 
+/**
+ * Retrofit an existing repo's hand-authored `AGENTS.md` into the project's
+ * "saddle" topology. The greenfield flow (`project new` → `project derive`)
+ * assumes the canonical instruction file is born in the anchor at
+ * `agents/<repo>/AGENTS.md`; but a repo that was developed BEFORE adoption
+ * carries its instructions as a plain regular file at `<repo>/AGENTS.md`. The
+ * other generators never relocate it — `project symlinks` is non-destructive and
+ * skips an occupied path, `project preset` would create a near-empty canonical
+ * beside the orphaned prose. Retrofit is the one missing migration step: it moves
+ * that regular file to the anchor canonical and leaves a symlink in its place, so
+ * the prose is preserved at the single source of truth and `project derive` can
+ * finish the wiring (CLAUDE.md / Copilot spokes, `.gitignore`, the preset block).
+ *
+ * Pure: it CLASSIFIES already-gathered facts (is the file a regular file? does the
+ * destination canonical already exist?) into one action. The realpath / lstat /
+ * move / symlink I/O is the caller's job. Non-destructive by contract: it only
+ * relocates a genuine regular-file AGENTS.md into a FREE canonical slot; an
+ * existing canonical (which would be clobbered), an already-wired symlink, an
+ * absent file, the anchor itself, or an unreachable/undeclared repo all yield a
+ * refuse/skip — never a move.
+ */
+/**
+ * On-disk state of the repo's own `AGENTS.md` (the file to relocate), as seen by
+ * `lstat` (never following the link). `regular-file` is the only relocatable
+ * state; `symlink` means it is already wired, `absent` means there is nothing to
+ * move, and `blocked` means the path could not be inspected (a non-ENOENT error)
+ * so it must not be mistaken for relocatable.
+ */
+type RetrofitAgentsState = "regular-file" | "symlink" | "absent" | "blocked";
+/** The single action retrofit will take for the repo. */
+type RetrofitAction = "relocate" | "skip" | "refuse";
+/** Why {@link classifyRetrofit} chose its action (machine-stable; the caller renders prose). */
+type RetrofitReason = 
+/** relocate: a regular-file AGENTS.md with a free destination canonical. */
+"ok"
+/** refuse: the repo is not in the declared roster. */
+ | "not-declared"
+/**
+ * refuse: the repo declares `instructions: self` — its AGENTS.md is a
+ * hand-authored committed file that stays in the repo, so there is no anchor
+ * canonical to relocate it to (retrofit does not apply).
+ */
+ | "self"
+/** refuse: the path is the project anchor (it owns the canonical directly — nothing to relocate). */
+ | "anchor"
+/** refuse: the path does not resolve / is not a git repo. */
+ | "unreachable"
+/** refuse: the AGENTS.md path could not be inspected (a non-ENOENT lstat error). */
+ | "blocked"
+/** refuse: the destination canonical already exists (relocating would clobber it). */
+ | "canonical-exists"
+/** skip: AGENTS.md is already a symlink (likely already wired — idempotent). */
+ | "already-symlink"
+/** skip: there is no AGENTS.md to relocate. */
+ | "absent";
+/** The gathered facts for the one repo being retrofitted. Pure inputs — no I/O. */
+type RetrofitFacts = {
+    /** The repo's roster path (relative to the anchor), echoed in the report. */
+    path: string;
+    /** True when the path is declared in the manifest roster. */
+    declared: boolean;
+    /**
+     * True when the declared entry uses `instructions: self` — its AGENTS.md stays
+     * in the repo, so retrofit (which relocates it to the anchor canonical) does
+     * not apply. Absent/false => the default `hub` behavior, unchanged.
+     */
+    self?: boolean | undefined;
+    /** True when the path resolves to the anchor itself. */
+    isAnchor: boolean;
+    /** False when the path does not resolve / is not a git repo. */
+    reachable: boolean;
+    /** The repo basename used for the anchor canonical `agents/<canonicalName>/AGENTS.md`. */
+    canonicalName: string;
+    /** On-disk state of the repo's own `AGENTS.md`. */
+    agentsState: RetrofitAgentsState;
+    /** True when the destination canonical already exists (moving would clobber it). */
+    canonicalExists: boolean;
+    /**
+     * The repo's spoke instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`)
+     * that are regular files — they would block clean wiring (`project symlinks`
+     * skips an occupied path), so they are surfaced as a manual checklist. Never
+     * moved by retrofit (they are spokes to AGENTS.md, not separate canonicals).
+     */
+    regularSpokes: string[];
+};
+/** The classified outcome for the repo. */
+type RetrofitPlan = {
+    path: string;
+    action: RetrofitAction;
+    reason: RetrofitReason;
+    /** The repo basename used for the canonical (echoed for the report). */
+    canonicalName: string;
+    /** The anchor-relative destination `agents/<canonicalName>/AGENTS.md`; set only when `action` is `relocate`. */
+    canonicalPath?: string;
+    /** Spoke instruction files that are regular files (reported, never moved). */
+    regularSpokes: string[];
+};
+/**
+ * Classify the retrofit facts into one action. Refusals are checked first, in a
+ * fixed precedence so the outcome is deterministic when several guardrails could
+ * apply: undeclared → anchor → self → unreachable → uninspectable AGENTS.md. Then
+ * the idempotent skips (already a symlink, or absent — nothing to move). Only a
+ * genuine regular-file AGENTS.md reaches the relocate decision, and even then a
+ * pre-existing destination canonical refuses (relocating would clobber it).
+ * `regularSpokes` is echoed in every outcome (it is advisory, relevant whenever a
+ * relocate or skip leaves the operator to tidy the spokes).
+ */
+declare function classifyRetrofit(facts: RetrofitFacts): RetrofitPlan;
+
 /**
  * Plan the agent instruction-file symlinks a declared repo needs (the
  * generation step that follows `basou project gitignore` in the "saddle"
@@ -4127,12 +4291,24 @@ type RepoSymlinkFacts = {
      * it never links to itself). An anchor entry is skipped entirely.
      */
     isAnchor: boolean;
+    /**
+     * True when this repo declares `instructions: self`: its canonical AGENTS.md is
+     * a regular committed file in the repo itself, so only the CLAUDE.md / Copilot
+     * spokes are generated (never the AGENTS.md hub link), `canonicalPresent` means
+     * "the repo's own AGENTS.md is present" (an absent one is `selfAgentsMissing`,
+     * not `missingCanonical`), and the repo is excluded from anchor-canonical
+     * collision detection (it shares no anchor canonical). Absent => the default
+     * `hub` behavior, unchanged.
+     */
+    self?: boolean | undefined;
     /** False when the repo path could not be resolved / is not a usable git repo. */
     reachable: boolean;
     /**
-     * Whether the anchor's canonical source for this repo
-     * (`<anchor>/agents/<repo>/AGENTS.md`) exists. Without it the hub link would
-     * dangle, so no links are planned (reported as a missing canonical instead).
+     * For a `hub` repo: whether the anchor's canonical source
+     * (`<anchor>/agents/<repo>/AGENTS.md`) exists — without it the hub link would
+     * dangle, so no links are planned (reported as `missingCanonical` instead). For
+     * a `self` repo: whether the repo's OWN AGENTS.md exists — without it the
+     * spokes would dangle, so none are planned (reported as `selfAgentsMissing`).
      */
     canonicalPresent: boolean;
     /**
@@ -4182,15 +4358,22 @@ type SymlinkPlanSummary = {
     conflicts: SymlinkConflict[];
     /** Repo paths whose anchor canonical (`agents/<repo>/AGENTS.md`) is absent, so nothing can be wired. */
     missingCanonical: string[];
+    /**
+     * `self` repo paths whose own AGENTS.md is absent, so the spokes would dangle
+     * and none are planned. Distinct from `missingCanonical` (which is the anchor
+     * canonical a `hub` repo links to): the operator authors a `self` repo's
+     * AGENTS.md by hand, then re-runs.
+     */
+    selfAgentsMissing: string[];
     /** Repo paths that could not be resolved / are not usable git repos. */
     unreachable: string[];
     /** Groups of distinct repos that resolve to the same canonical (ambiguous; not auto-wired). */
     collisions: SymlinkCollision[];
     /**
      * True only when nothing needs creating AND there are no conflicts, no missing
-     * canonicals, no unreachable repos, and no collisions — so a clean "all wired"
-     * verdict is never claimed while some repo was blocked, ambiguous, or could not
-     * be inspected.
+     * canonicals, no self repos missing their AGENTS.md, no unreachable repos, and
+     * no collisions — so a clean "all wired" verdict is never claimed while some
+     * repo was blocked, ambiguous, or could not be inspected.
      */
     ok: boolean;
 };
@@ -4211,6 +4394,12 @@ type SymlinkPlanSummary = {
  *   {@link SymlinkCollision} and neither is auto-wired (silent sharing of one
  *   canonical is surfaced, not actioned).
  *
+ * A `self` repo (its `self` flag set by the caller) carries only its spoke files
+ * (CLAUDE.md / Copilot → its own AGENTS.md), is excluded from collision
+ * detection, and routes an absent own-AGENTS.md to `selfAgentsMissing` rather
+ * than `missingCanonical`. Otherwise it flows through the same create/conflict
+ * logic as a hub repo.
+ *
  * `ok` is true only when there is genuinely nothing to do and every repo was
  * judgeable, reachable, and unambiguous.
  */
@@ -4244,6 +4433,13 @@ type RepoWiringFacts = {
     path: string;
     /** Declared visibility; undefined when the operator has not set it yet. */
     visibility?: RepoVisibility | undefined;
+    /**
+     * True when this repo declares `instructions: self`: its instruction files are
+     * committed BY DESIGN (shared in its own git history), so a tracked file is
+     * never a privacy risk — the repo is reported as `self` and excluded from the
+     * risk / unknown verdicts. Absent => the default `hub` behavior, unchanged.
+     */
+    self?: boolean | undefined;
     /** False when the repo path could not be resolved / is not a usable git repo. */
     reachable: boolean;
     /** Per instruction-file facts (omitted/empty when unreachable). */
@@ -4265,6 +4461,12 @@ type WiringSummary = {
     risks: WiringRisk[];
     /** Repo paths whose visibility is unset, so the privacy verdict cannot be judged. */
     unknown: string[];
+    /**
+     * `instructions: self` repo paths: their instruction files are committed by
+     * design, so they carry no privacy risk and do not need a visibility verdict.
+     * Reported (not silently dropped) and do NOT block `ok`.
+     */
+    self: string[];
     /** Repos missing one or more instruction files (a wiring gap a later generate slice fills). */
     incomplete: {
         repo: string;
@@ -4280,8 +4482,11 @@ type WiringSummary = {
  * public-facing repo that TRACKS an instruction file is a {@link WiringRisk}
  * (its git history can expose the private canonical it points at); a repo with
  * unset visibility cannot be judged (`unknown`); a repo missing instruction
- * files is `incomplete` (a wiring gap, not a privacy problem). `ok` is true only
- * when nothing is at risk, every repo is judgeable, and every repo is reachable.
+ * files is `incomplete` (a wiring gap, not a privacy problem). A `self` repo is
+ * reported as `self` and bypasses the risk / unknown verdicts entirely — its
+ * instruction files are committed by design — though a genuinely missing one is
+ * still surfaced as `incomplete`. `ok` is true only when nothing is at risk,
+ * every repo is judgeable, and every repo is reachable.
  */
 declare function summarizeWiring(facts: RepoWiringFacts[]): WiringSummary;
 
@@ -5622,4 +5827,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FederatedRoot, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadFederatedOptions, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type Markers, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, PROTOCOL_END, PROTOCOL_START, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type ProcessRunner, type PublishKind, type PublishTarget, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoLanguage, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookSilentReason, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLinkState, type ViewRepoFact, type ViewStrayUnknown, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FederatedRoot, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadFederatedOptions, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type Markers, type MeasureAvailability, type NoteAddedEvent, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, PROTOCOL_END, PROTOCOL_START, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type ProcessRunner, type PublishKind, type PublishTarget, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoInstructions, type RepoLanguage, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type RetrofitAction, type RetrofitAgentsState, type RetrofitFacts, type RetrofitPlan, type RetrofitReason, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookSilentReason, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLinkState, type ViewRepoFact, type ViewStrayUnknown, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifyRetrofit, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findErrorCode, findReviewGaps, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, instructionMode, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderWithMarkers, replayEvents, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };

package/dist/index.js

@@ -4582,6 +4582,7 @@ var ImportConfigSchema = z9.looseObject({
 var RepoVisibilitySchema = z9.enum(["public", "private", "future-public"]);
 var RepoLanguageSchema = z9.enum(["en", "ja", "en+ja"]);
 var PublishKindSchema = z9.enum(["web", "npm"]);
+var RepoInstructionsSchema = z9.enum(["hub", "self"]);
 var PublishTargetSchema = z9.looseObject({
   kind: PublishKindSchema,
   visibility: RepoVisibilitySchema.optional(),
@@ -4591,7 +4592,8 @@ var RepoEntrySchema = z9.looseObject({
   path: SourceRootSchema,
   visibility: RepoVisibilitySchema.optional(),
   language: RepoLanguageSchema.optional(),
-  publishes: z9.array(PublishTargetSchema).optional()
+  publishes: z9.array(PublishTargetSchema).optional(),
+  instructions: RepoInstructionsSchema.optional()
 });
 var WorkspaceMetaSchema = z9.looseObject({
   id: WorkspaceIdSchema,
@@ -5365,12 +5367,17 @@ function isPublicFacing(v) {
 function planGitignore(input) {
   const plans = [];
   const unknown = [];
+  const self = [];
   const unreachable = [];
   for (const repo of input.repos) {
     if (!repo.reachable) {
       unreachable.push(repo.path);
       continue;
     }
+    if (repo.self === true) {
+      self.push(repo.path);
+      continue;
+    }
     if (repo.visibility === void 0) {
       unknown.push(repo.path);
       continue;
@@ -5388,6 +5395,7 @@ function planGitignore(input) {
   return {
     plans,
     unknown,
+    self,
     unreachable,
     ok: plans.length === 0 && unknown.length === 0 && unreachable.length === 0
   };
@@ -5476,7 +5484,8 @@ function summarizePresetPlan(facts) {
   }
   const byCanonical = /* @__PURE__ */ new Map();
   for (const f of deduped) {
-    if (f.isAnchor || !f.reachable || f.canonicalName === void 0 || !isRenderable(f)) continue;
+    if (f.isAnchor || f.self === true || !f.reachable || f.canonicalName === void 0 || !isRenderable(f))
+      continue;
     const repos = byCanonical.get(f.canonicalName) ?? [];
     repos.push(f.path);
     byCanonical.set(f.canonicalName, repos);
@@ -5495,12 +5504,17 @@ function summarizePresetPlan(facts) {
   const markerConflicts = [];
   const unreadable = [];
   const anchors = [];
+  const self = [];
   const unreachable = [];
   for (const f of deduped) {
     if (f.isAnchor) {
       anchors.push(f.path);
       continue;
     }
+    if (f.self === true) {
+      self.push(f.path);
+      continue;
+    }
     if (!f.reachable) {
       unreachable.push(f.path);
       continue;
@@ -5546,6 +5560,7 @@ function summarizePresetPlan(facts) {
     unreadable,
     collisions,
     anchors,
+    self,
     unreachable,
     ok: plans.length === 0 && markerConflicts.length === 0 && unreadable.length === 0 && collisions.length === 0 && unreachable.length === 0 && undeclared.length === 0
   };
@@ -5628,7 +5643,35 @@ function planRename(input) {
   };
 }
 
+// src/project/retrofit.ts
+var CANONICAL_FILE = "AGENTS.md";
+function classifyRetrofit(facts) {
+  const base = {
+    path: facts.path,
+    canonicalName: facts.canonicalName,
+    regularSpokes: facts.regularSpokes
+  };
+  if (!facts.declared) return { ...base, action: "refuse", reason: "not-declared" };
+  if (facts.isAnchor) return { ...base, action: "refuse", reason: "anchor" };
+  if (facts.self === true) return { ...base, action: "refuse", reason: "self" };
+  if (!facts.reachable) return { ...base, action: "refuse", reason: "unreachable" };
+  if (facts.agentsState === "blocked") return { ...base, action: "refuse", reason: "blocked" };
+  if (facts.agentsState === "symlink")
+    return { ...base, action: "skip", reason: "already-symlink" };
+  if (facts.agentsState === "absent") return { ...base, action: "skip", reason: "absent" };
+  if (facts.canonicalExists) return { ...base, action: "refuse", reason: "canonical-exists" };
+  return {
+    ...base,
+    action: "relocate",
+    reason: "ok",
+    canonicalPath: `agents/${facts.canonicalName}/${CANONICAL_FILE}`
+  };
+}
+
 // src/project/roster.ts
+function instructionMode(entry) {
+  return entry.instructions ?? "hub";
+}
 function summarizeRosterDrift(input) {
   const captured = new Set((input.sourceRoots ?? []).map(normalizeRelativePath));
   const declared = /* @__PURE__ */ new Map();
@@ -5691,7 +5734,7 @@ function summarizeSymlinkPlan(facts) {
   }
   const byCanonical = /* @__PURE__ */ new Map();
   for (const f of deduped) {
-    if (f.isAnchor || !f.reachable || !f.canonicalPresent || f.canonicalName === void 0) {
+    if (f.isAnchor || f.self === true || !f.reachable || !f.canonicalPresent || f.canonicalName === void 0) {
       continue;
     }
     const repos = byCanonical.get(f.canonicalName) ?? [];
@@ -5709,6 +5752,7 @@ function summarizeSymlinkPlan(facts) {
   const plans = [];
   const conflicts = [];
   const missingCanonical = [];
+  const selfAgentsMissing = [];
   const unreachable = [];
   for (const f of deduped) {
     if (f.isAnchor) continue;
@@ -5717,7 +5761,8 @@ function summarizeSymlinkPlan(facts) {
       continue;
     }
     if (!f.canonicalPresent) {
-      missingCanonical.push(f.path);
+      if (f.self === true) selfAgentsMissing.push(f.path);
+      else missingCanonical.push(f.path);
       continue;
     }
     if (collidingPaths.has(f.path)) continue;
@@ -5744,9 +5789,10 @@ function summarizeSymlinkPlan(facts) {
     plans,
     conflicts,
     missingCanonical,
+    selfAgentsMissing,
     unreachable,
     collisions,
-    ok: plans.length === 0 && conflicts.length === 0 && missingCanonical.length === 0 && unreachable.length === 0 && collisions.length === 0
+    ok: plans.length === 0 && conflicts.length === 0 && missingCanonical.length === 0 && selfAgentsMissing.length === 0 && unreachable.length === 0 && collisions.length === 0
   };
 }
 
@@ -5757,6 +5803,7 @@ function isPublicFacing2(v) {
 function summarizeWiring(facts) {
   const risks = [];
   const unknown = [];
+  const self = [];
   const incomplete = [];
   const unreachable = [];
   for (const f of facts) {
@@ -5764,7 +5811,9 @@ function summarizeWiring(facts) {
       unreachable.push(f.path);
       continue;
     }
-    if (isPublicFacing2(f.visibility)) {
+    if (f.self === true) {
+      self.push(f.path);
+    } else if (isPublicFacing2(f.visibility)) {
       for (const file of f.instructionFiles) {
         if (file.tracked) risks.push({ repo: f.path, visibility: f.visibility, file: file.name });
       }
@@ -5778,6 +5827,7 @@ function summarizeWiring(facts) {
     repos: facts,
     risks,
     unknown,
+    self,
     incomplete,
     unreachable,
     ok: risks.length === 0 && unknown.length === 0 && unreachable.length === 0
@@ -7644,6 +7694,7 @@ export {
   chainEvents,
   chainRawJsonLines,
   classifyFilesBySourceRoot,
+  classifyRetrofit,
   classifySuspect,
   claudeCodeAdapterMetadata,
   claudeTranscriptToImportPayload,
@@ -7669,6 +7720,7 @@ export {
   getSnapshot,
   importSessionFromJson,
   inspectChainTail,
+  instructionMode,
   isGitNotFound,
   isImportDerivedSource,
   isLazyExpired,