ob-guardrails-project

name	ob-guardrails-project
description	Project-specific rules and constraints extracted from ARCHITECTURE.md and project config files. Load this skill before implementing any change to understand boundaries, conventions, and constraints for this codebase.
license	MIT

Project Guardrails

Auto-generated by /make-guardrails. Regenerate with the same command when architecture or conventions change.

Architecture Constraints

• FSD one-way dependency flow: TUI layers must only import from layers below: app → widgets → features → entities → shared. A layer may never import from a layer above it.
  • app/ may import from any layer.
  • widgets/ may import from features/, entities/, shared/.
  • features/ may import from entities/, shared/.
  • entities/ may import from shared/ only.
  • shared/ has no internal imports from other FSD layers.
• src/core/ must NOT import from src/daemon/, src/app/, or any FSD UI layer. Core is runtime-agnostic.
• src/daemon/ may import from src/core/ and src/shared/ but NOT from src/app/ or FSD UI layers (widgets/features/entities).
• src/client/ (CLI) consumes IPC only — it must not import daemon internals directly.
• UI must use Inversify DI: Components use useInject<T>(TYPES.XxxService) instead of importing daemon functions directly. Service interfaces are in src/shared/services/types.ts, IPC implementations in src/shared/services/.
• Dictionary dispatch over switch/case: Use Record<string, () => void> for command handling, not nested if/else or switch statements.
• No src/tui/ or src/board/ directories — these are deleted. All TUI code lives in the FSD layers (app/, widgets/, features/, entities/, shared/).
• IPC contract lives in src/types.ts — it is the single source of truth for all IPC request/response shapes (IpcRequest, IpcResponse, LoopOptions, LoopMeta).
• Inversify DI container bindings in src/shared/container/index.ts — service interfaces bound to IPC implementations, not daemon internals.

File Organization

• No god-files: Each file must have one clear responsibility. Do NOT create dumping-ground files like constants.ts, types.ts, config.ts, or utils.ts that collect unrelated things.
  • Magic numbers live in src/shared/config/constants.ts (project-scoped name).
  • Filesystem paths live in src/shared/config/paths.ts.
  • User-facing strings live in src/shared/i18n/en.json.
  • Shared domain + IPC types in src/types.ts (single file, IPC contract specific).
  • Domain entity types separated by entity: src/entities/loops/, src/entities/tasks/, src/entities/projects/.
• Split by domain or feature, not by technical concern. E.g. user-constants.ts, order-types.ts rather than a global constants.ts.
• A file that imports from 5+ unrelated modules is a sign it should be split.

Naming Conventions

• TypeScript strict, ESM only: "type": "module" in package.json.
• File naming: .ts for logic, .tsx for React/Ink components.
• Test files: *.test.ts for logic tests, *.test.tsx for Ink component tests, all in the tests/ directory.
• Shell commands must be prefixed with rtk in agent contexts (see AGENTS.md / openspec config).
• Conventional commits: feat:, fix:, docs:, chore:, archive: prefix on commit messages.
• Trunk-based on main: feature branches fork from main.

Code Style

• TypeScript strict mode ("strict": true in tsconfig.json). All source code.
• ESM only ("type": "module"). Use export/import, not require.
• Linter: ESLint 9 + typescript-eslint recommended config (eslint.config.js).
  • no-console: off (console is allowed).
  • @typescript-eslint/no-unused-vars: error, with argsIgnorePattern: "^_", varsIgnorePattern: "^_".
  • ecmaVersion: 2022, sourceType: "module".
• Ignored paths: dist/, node_modules/, coverage/, eslint.config.js.
• No comments unless absolutely necessary (from CONTRIBUTING.md).
• Follow existing conventions — do not introduce new patterns without reason.
• Decorators: experimentalDecorators: true, useDefineForClassFields: false (for InversifyJS).

Testing

• Framework: Vitest 3 with globals: true.
• Location: tests/ directory.
• Naming: *.test.ts for logic, *.test.tsx for Ink components.
• Coverage: v8 provider, 90% threshold on lines, functions, branches, and statements.
• Coverage excludes: src/cli.ts, src/types.ts, src/daemon/index.ts, src/tui/**, src/board/**.
• background-cli.test.ts is excluded from default pnpm test runs (run with pnpm test:all manually if needed).
• TUI testing with ink-testing-library: Use render(), lastFrame(), stdin.write().
  • Wrap absolute/100% layouts in a sized <Box>.
  • Type chars one-at-a-time with await delay() between them.
  • await after stdin.write() for async key handling (esc, ctrl combos).
• Test isolation: Use LOOP_CLI_HOME env var to isolate daemon state per test.
• Pre-existing test failures: tests/cli.test.ts, tests/loop-controller.test.ts, and tests/projects.test.ts have known pre-existing failures. Confirm failures are pre-existing before touching assertions.
• New/changed TUI components must ship with a .test.tsx even though src/tui/** is coverage-excluded.

Build & Deployment

• Package manager: pnpm (version 10.x via packageManager field). Use pnpm, not npm or yarn.
• Dev runner: tsx (replaces Bun). pnpm run dev runs tsx src/cli.ts.
• Build: pnpm run build = tsc -p tsconfig.build.json + copy entry.js and esm-loader.js to dist/.
• Node >= 20 required for CLI, daemon, and TUI.
• Gate order: typecheck → lint → test → build. Always run all four before claiming done.
  • pnpm run typecheck = tsc --noEmit
  • pnpm run lint = eslint src/ tests/
  • pnpm run test = vitest run --exclude '**/background-cli.test.ts'
  • pnpm run build = tsc -p tsconfig.build.json + copy
• Distribution: Published to npm as loop-task. bin field points at dist/entry.js.
• Docker: node:20-slim base image, volume mount ~/.loop-cli.
• Gate in agent context: Every change must pass rtk npx tsc --noEmit → rtk pnpm lint → rtk pnpm test (from openspec/config.yaml).

Data & State

• All persistence is filesystem-based under ~/.loop-cli/ (overridable via LOOP_CLI_HOME).
• State files: loops.json, tasks.json, projects.json — JSON arrays.
• Write strategy: All state writes use writeFileAtomic() (temp-then-rename) for crash safety.
• Synchronous writes to preserve immediate-disk-state-on-pause semantics.
• No schema versioning: Future LoopMeta shape changes risk breaking persisted JSON. Corrupted files are silently skipped.
• Chain context is ephemeral: In-memory only per loop iteration. Never persisted to disk or exposed via IPC.
• Log rotation: 1 MB max per file, 3 generations (.{1}, .{2}, .{3}).
• Daemon PID file (daemon.pid) and code signature (daemon.sig) recreated on each daemon start.

Security

• Trust boundary: Local machine/user only. No network listener by default.
• No authentication: Daemon trusts local socket connections.
• No secrets handling: Loop metadata and logs are plain files. Never read or output .env files.
• HTTP API is unauthenticated: Binds to 0.0.0.0 by default. Securing access is the user's responsibility at the network layer (VPN/SSH tunnel/firewall).
• Input validation: Duration parsing (parseDuration), max-runs (parseMaxRuns), command emptiness, quote balancing (parseCommandLine) in loop-config.ts.
• IPC robustness: Malformed JSON requests answered with error response, not crash.
• Child processes inherit daemon's environment — do not inject secrets via env.

Dependencies

• Package manager: pnpm (specified as pnpm@10.30.3 in packageManager field).
• Lockfile: pnpm-lock.yaml. Do not commit package-lock.json.
• Key dependencies are pinned by major: Commander 13, execa 9, Ink 7, React 19, Vitest 3, ESLint 9, TypeScript 5.8.
• Overrides: picocolors: 1.1.0 (pinned via pnpm overrides).
• Dev only: tsx for dev runner, ink-testing-library for component tests.
• No @opentui/* packages — removed in favor of Ink 7.
• No Bun runtime dependency — tsx replaces Bun for dev.

Git Workflow

• Trunk-based on main: Feature branches fork from main.
• Conventional commits: feat:, fix:, docs:, chore:, archive: prefix.
• PR process: Fork → feature branch → typecheck + lint + test + build → open PR.
• Platform: GitHub (from opencode-onboard.json: platform.backlog: "github", platform.repo: "github").
• Max concurrent agents: 2 (from opencode-onboard.json: agents.maxConcurrent).

Domain-Specific Rules

• Board-first product direction: Loop management actions should prefer the board (TUI) over adding more CLI commands. Only new and run are CLI-facing.
• Keyboard-only UI: No mouse. All interaction via keystrokes. The command input is always-focused at the bottom.
• 4 primary colors only: brand (amber), loop (blue), task (purple), project (green) + 4 semantic + grays. No decorative colors outside this set.
• Command-first input model: Single always-focused command palette with fuzzy autocomplete via ink-combobox. All actions discoverable.
• Panel focus via isFocused prop — not Ink's native useFocus().
• Ctrl+Enter detection via input.includes("\n") with input.length === 1 guard to prevent newline injection.
• Spread scheduling: computePhase(loopId, intervalMs) = hash(loopId) % intervalMs distributes loop start times.
• Chunked abortable sleep: SLEEP_CHUNK_MS = 200ms for responsive pause/resume/trigger.
• opencode-onboard.json is the team config (shared, git-tracked). .opencode/opencode-onboard.user.json is user-local override (gitignored). Tier models: plan, build, fast.