type: meta

slug: ai-os-foundation

base_branch: feat/ai-os-foundation

gate0_mode: strict

preset: codex-cursor


type: goal

text: AI OS foundation in overdeck: modules/ namespace + deck.module.json contract (schema_version 1, install.mode in-place|artifact); history-preserving filter-repo imports in order monitor→security→systray→harness on ONE feature branch through the PR gate; modules/workstation (curated secret-free agent-CLI config: claude, codex, cursor-agent, opencode, gemini, kiro, pi, antigravity); bin/deckctl (bootstrap/doctor/status/sync/install, bash, fail-closed, bats-tested); harness runs ONLY from pinned harness-rooted artifact at ~/.local/opt/overdeck/harness/<rev> (subtree-split, current symlink); cutover.sh per module (6 fail-closed phases incl. state migration to ~/.local/state/overdeck/<name>, worktree teardown, archive-rename-then-symlink, ref-sweep assertion) executed by MAIN session after the engine exits.


type: methodology

text: Spec is source of truth: docs/specs/2026-07-28-ai-os-foundation-design.md (advisor-reviewed 2 rounds, all blockers fixed). Imports operate on scratch clones ONLY — old checkouts + services stay live until cutover. Every script fail-closed, idempotent, both-branch tested. modules/** stays OUT of root gates (pnpm workspace, typecheck/test, slopgate, jscpd) and is UNGATED in CI this sub-project. gitleaks over filtered history is a merge precondition. git bundle of each source repo before any migration. Task 0 = machine-wide ref-sweep inventory + gate0 surface-derivation check.


type: intent

text: One modular, expandable AI OS under overdeck holding all unpublished dev tooling; new workstation = clone + deckctl bootstrap; later sub-projects extend runner offload (debian1/2) and make Botmaster a comms adapter announcing GOLIVE progress.


type: direction

verbatim: it should be modular and allow easy expansion, and allow me to easily copy my AI OS and workstation preferences and settings across future workstations


verbatim: i also will want to have normal generic namings, e.g. "mega-plan-harness" = harness, "systray-ai" = systray. etc. i want to recommend the rest of the names


verbatim: specifically botmaster, i still want to keep the original cloudflare ocntrol i have the cloudflare control of botmaster, that should stay on cloudflare, but i do want to incorporate botmaster into overdeck


verbatim: systray's ui is a native cinnamon gui , so probably not a good target to dedup. but you should see what is


verbatim: also cursor is "cursor-agent" since he regular cursor is the ide not agents


type: deferred

text: Botmaster comms adapter + repo migration into modules/bots

reason: user: 'this is lower priority'


text: Runner-offload expansion to debian1/2 beyond existing controller/

reason: later sub-project (roadmap §2)


text: tui-kit un-vendor in deck-tui; folding modules into root gates; per-module CI wiring

reason: advisor: gate-scope coherence — roadmap items, one module at a time


note: cutover.sh MUST NOT run as an engine task — main session runs it from the live checkout after the engine exits. Old checkouts/services stay untouched through all engine waves.


note: harness artifact = harness-rooted subtree split cloned from LOCAL overdeck at commit-ish (feature branch OK, never origin). ~/.harness (HARNESS_HOME) stays put — inventory only.


type: task

seat: coder

tier: medium

desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 1 (Module contract schema) for the full contract. JSON Schema for deck.module.json per spec Module contract section. Acceptance: tests/os/schema.test.sh -> PASS. Commit only: spec/deck-module.schema.json tests/os/schema.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 2 (ref-sweep inventory) for the full contract. Machine-wide old-path reference sweep script + committed inventory + --assert mode. Acceptance: tests/os/ref-sweep.test.sh -> PASS. Commit only: tools/ref-sweep.sh tools/ref-inventory.json tests/os/ref-sweep.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 3 (monitor install.sh --dry-run) for the full contract. Add mutate-nothing --dry-run mode printing DRY-RUN: lines, exit 0. Acceptance: tests/os/monitor-dryrun.test.sh -> PASS. Commit only: modules/monitor/install.sh tests/os/monitor-dryrun.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 4 (deckctl core) for the full contract. Dispatcher bin/deckctl + doctor + status subcommands, fail-closed. Acceptance: tests/os/deckctl-core.test.sh -> PASS. Commit only: bin/deckctl lib/deckctl/doctor.sh lib/deckctl/status.sh tests/os/deckctl-core.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 5 (harness module manifest + units) for the full contract. Manifest artifact-mode + bootstrap/health + repoint systemd units to %h/.local/opt/overdeck/harness/current, never the checkout. Acceptance: bash -n scripts + manifest validates vs schema + grep -c 'Projects/mega-plan-harness' modules/harness/systemd/* == 0. Commit only: modules/harness/deck.module.json modules/harness/bootstrap.sh modules/harness/health.sh modules/harness/systemd/harnessd.service modules/harness/systemd/harnessd-daily.service modules/harness/systemd/harnessd-daily.timer

verify: bash -n modules/harness/install.sh modules/harness/health.sh modules/harness/cutover.sh && jq -e . modules/harness/module.json >/dev/null && [ "$(grep -rc 'Projects/mega-plan-harness' modules/harness/systemd/ | awk -F: '{s+=$2} END {print s+0}')" = 0 ]


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 6 (systray module manifest + unit) for the full contract. Manifest in-place + bootstrap/health + unit ExecStart to module dir. Acceptance: bash -n scripts + manifest validates + unit ExecStart path check clean. Commit only: modules/systray/deck.module.json modules/systray/bootstrap.sh modules/systray/health.sh modules/systray/systemd/systray-ai.service

verify: bash -n modules/systray/install.sh modules/systray/health.sh && jq -e . modules/systray/module.json >/dev/null && grep -q ExecStart modules/systray/systemd/systray-ai.service


tier: low

desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 7 (monitor module manifest) for the full contract. Manifest kind config, health = bash -n all scripts + install.sh --dry-run exit 0, bootstrap no-op. Acceptance: manifest validates + modules/monitor/health.sh exits 0. Commit only: modules/monitor/deck.module.json modules/monitor/health.sh modules/monitor/bootstrap.sh

verify: jq -e . modules/monitor/module.json >/dev/null && bash modules/monitor/health.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 8 (security module manifest) for the full contract. Manifest kind cli, health propagates check.sh. Acceptance: manifest validates + modules/security/health.sh exits 0. Commit only: modules/security/deck.module.json modules/security/health.sh modules/security/bootstrap.sh

verify: jq -e . modules/security/module.json >/dev/null && bash modules/security/health.sh


tier: high

desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 9 (deckctl install artifact) for the full contract. subtree-split from LOCAL checkout, clone to ~/.local/opt/overdeck/<name>/<rev>, state symlinks, health-gated atomic current flip, prune keeps 2 never dereferences symlinks. Acceptance: tests/os/deckctl-install.test.sh -> PASS. Commit only: lib/deckctl/install.sh tests/os/deckctl-install.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 10 (workstation module + deckctl sync) for the full contract. Per-agent manifests (claude codex cursor-agent opencode gemini kiro pi antigravity), deny.list, sync pull/apply/diff with fail-closed secret refusal; under-sync over over-sync. Acceptance: tests/os/deckctl-sync.test.sh -> PASS. Commit only: modules/workstation/deck.module.json modules/workstation/manifest/ modules/workstation/deny.list lib/deckctl/sync.sh tests/os/deckctl-sync.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 11 (cutover scripts) for the full contract. cutover-lib 6 fail-closed phases per spec Cutover section + rollback + --rollback + engine-refusal guard; four thin per-module wrappers. NEVER run these against the real system in this task - fixture/sandbox tests only. Acceptance: tests/os/cutover.test.sh -> PASS. Commit only: lib/deckctl/cutover-lib.sh modules/harness/cutover.sh modules/systray/cutover.sh modules/monitor/cutover.sh modules/security/cutover.sh tests/os/cutover.test.sh


desc: Read docs/plans/2026-07-28-ai-os-foundation.md Task 12 (deckctl bootstrap) for the full contract. doctor -> per-module bootstrap/sync-apply/install/units/health, idempotent resume-on-rerun. Acceptance: tests/os/deckctl-bootstrap.test.sh -> PASS. Commit only: lib/deckctl/bootstrap.sh tests/os/deckctl-bootstrap.test.sh


note: gate0 surface verified: changed package.json manifests in task diff + allowlisted root scripts (lib/gates.sh:433,918). No engine task touches any package.json -> modules/** exclusion holds; no scoping change needed.