pi-monofold 0.8.0 → 0.10.0

package/README.md

@@ -86,7 +86,7 @@ pi -e npm:pi-monofold
 1. Install the extension (see [Install](#install)).
 2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
 3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
-4. Use `/monofold:focus` or `ctrl+shift+m` to switch focus presets when `focusPresets` are configured.
+4. Use `/monofold:focus`, `ctrl+shift+m`, or `shift+ctrl+f` to switch focus presets when `focusPresets` are configured.
 5. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
 
 Example command flows: [docs/examples.md](./docs/examples.md).
@@ -100,11 +100,12 @@ Example command flows: [docs/examples.md](./docs/examples.md).
 | `/monofold:config` | Add or change workspaces and project workspaces |
 | `/monofold:git` | Run guarded git status, commit, push, or commit+push |
 | `/monofold:focus` | Select the active focus preset from a TUI list |
+| `/monofold:focus-prev` | Cycle Active Focus backward through `focusPresets` YAML order |
 | `/monofold:guide` | Interactive guide for common flows |
 | `/monofold:init` | Create or update `.pi/monofold.yaml` |
 | `/monofold:update` | Migrate legacy config and optionally request config edits |
 
-Default focus shortcut: `ctrl+shift+m` cycles Active Focus forward through `focusPresets` YAML order. No backward focus shortcut ships in the MVP.
+Default focus shortcuts: `ctrl+shift+m` cycles Active Focus forward and `shift+ctrl+f` cycles backward through `focusPresets` YAML order. Both wrap at the start/end of the list.
 
 When Active Focus is set, Pi Monofold injects the active preset's `contextFiles` into each agent turn under **Focus Context Injection** and recomposes the manifest so active Workspace Targets are shown first while non-active targets are collapsed to one-line summaries. Tag-based target inference in `monofold_read`, `monofold_write`, and `monofold_git` also prefers Workspace Targets that belong to the active preset when a tag query would otherwise match multiple candidates; explicit `targetId` / workspace name selectors and uniquely matching targets are unchanged. If multiple in-focus targets still tie, the existing workspace selection flow applies. The MVP uses provisional context-injection caps that are intentionally temporary and exposed as constants for future tuning:
 
@@ -112,7 +113,7 @@ When Active Focus is set, Pi Monofold injects the active preset's `contextFiles`
 - Max **6,000** characters per file, with `… [truncated]` appended when a file is cut.
 - Max **12,000** injected file-content characters per turn; remaining files are skipped and a warning is surfaced once for that turn.
 
-Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Full reference: [docs/usage.md](./docs/usage.md).
+Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Use `monofold_list` as the first-line Active Focus health check (preset, route override, unresolved targets, and warnings). Full reference: [docs/usage.md](./docs/usage.md).
 
 ## Safe read defaults
 

package/focus-decision-note.ts

@@ -0,0 +1,122 @@
+import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
+
+type TagMatchableWorkspace = {
+  tags: string[];
+};
+
+export type FocusDecisionNoteDestination = {
+  targetTags: string[];
+  path: string;
+};
+
+export type FocusDecisionNoteValidationWorkspace = TagMatchableWorkspace & {
+  targetId: string;
+  name?: string;
+  capabilities: readonly string[];
+};
+
+const DECISION_NOTE_DESTINATION_KEYS = new Set(["targetTags", "path"]);
+
+/** Parses and validates an optional decisionNoteDestination from preset config. */
+export function parseDecisionNoteDestination(itemLabel: string, value: unknown): FocusDecisionNoteDestination | undefined {
+  if (value === undefined) return undefined;
+  const destLabel = `${itemLabel}.decisionNoteDestination`;
+  if (!isRecord(value)) throw new Error(`${destLabel} must be an object`);
+  assertKnownKeys(destLabel, value, DECISION_NOTE_DESTINATION_KEYS);
+  const targetTags = uniqueStrings(asStringArray(`${destLabel}.targetTags`, value.targetTags));
+  if (targetTags.length === 0) {
+    throw new Error(`${destLabel}.targetTags must contain at least one non-empty string`);
+  }
+  if (typeof value.path !== "string" || value.path.trim() === "") {
+    throw new Error(`${destLabel}.path must be a non-empty string`);
+  }
+  assertWorkspaceInternalRelative(`${destLabel}.path`, value.path.trim());
+  return { targetTags, path: value.path.trim() };
+}
+
+function assertWorkspaceInternalRelative(label: string, value: string): void {
+  const normalized = value.replace(/\\/g, "/");
+  if (normalized.startsWith("/") || normalized.split("/").includes("..")) {
+    throw new Error(`${label} must be a workspace-internal relative path: ${value}`);
+  }
+}
+
+/** Formats a decision-note destination for manifest and status output. */
+export function formatDecisionNoteDestinationLabel(
+  workspaceLabel: string,
+  destination: FocusDecisionNoteDestination,
+): string {
+  return `${workspaceLabel}:${destination.path}`;
+}
+
+function matchesTargetTags(workspace: TagMatchableWorkspace, targetTags: string[]): boolean {
+  if (targetTags.length === 0) return false;
+  return targetTags.every((tag) => workspace.tags.includes(tag));
+}
+
+/** Validates a preset decision-note destination against configured workspaces. */
+export function validateDecisionNoteDestinationAgainstWorkspaces(
+  presetLabel: string,
+  destination: FocusDecisionNoteDestination,
+  workspaces: FocusDecisionNoteValidationWorkspace[],
+): void {
+  const destLabel = `${presetLabel}.decisionNoteDestination`;
+  const matches = workspaces.filter((workspace) => matchesTargetTags(workspace, destination.targetTags));
+  if (matches.length === 0) {
+    throw new Error(
+      `${destLabel}.targetTags [${destination.targetTags.join(", ")}] matches no workspace target`,
+    );
+  }
+  if (matches.length > 1) {
+    const labels = matches
+      .map((workspace) => (workspace.name ? `${workspace.targetId} (${workspace.name})` : workspace.targetId))
+      .join(", ");
+    throw new Error(
+      `${destLabel}.targetTags [${destination.targetTags.join(", ")}] is ambiguous across workspaces: ${labels}`,
+    );
+  }
+  const workspace = matches[0]!;
+  if (!workspace.capabilities.includes("read")) {
+    throw new Error(
+      `${destLabel} requires read on ${workspace.targetId}, but matched capabilities [${workspace.capabilities.join(", ")}]`,
+    );
+  }
+}
+
+/** Finds the single workspace that matches a decision-note destination, if any. */
+export function findDecisionNoteWorkspace<T extends FocusDecisionNoteValidationWorkspace>(
+  workspaces: T[],
+  destination: FocusDecisionNoteDestination,
+): T | undefined {
+  const matches = workspaces.filter((workspace) => matchesTargetTags(workspace, destination.targetTags));
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+let warnedDecisionNoteKey: string | null = null;
+
+/** Clears per-activation decision-note warning deduplication (for tests and focus changes). */
+export function resetDecisionNoteWarningState(): void {
+  warnedDecisionNoteKey = null;
+}
+
+/** Emits one actionable warning per focus activation for unavailable decision-note destinations. */
+export function warnUnavailableDecisionNoteDestination(
+  presetId: string,
+  destination: FocusDecisionNoteDestination,
+  workspaceLabel: string,
+  reason: "missing-workspace" | "missing-file",
+  warn: (message: string) => void,
+): void {
+  const key = `${presetId}:${reason}:${destination.targetTags.join(",")}:${destination.path}`;
+  if (warnedDecisionNoteKey === key) return;
+  warnedDecisionNoteKey = key;
+  if (reason === "missing-workspace") {
+    warn(
+      `Focus preset "${presetId}" decisionNoteDestination [${destination.targetTags.join(", ")}] → ${destination.path} matches no configured workspace. Fix targetTags or add the workspace, then reload Pi.`,
+    );
+    return;
+  }
+  warn(
+    `Focus preset "${presetId}" decisionNoteDestination ${workspaceLabel}:${destination.path} is unavailable. Create the file or fix the path, then reload Pi.`,
+  );
+}