docks-kit 0.2.0 → 0.4.0

package/SoT/.codex/AGENTS.md

@@ -1,75 +0,0 @@
-# AGENTS.md
-
-## Research Before Implementation
-
-Before writing or modifying code that uses an API, hook, method, or config surface you have not verified in this session, research current documentation first.
-
-Research workflow:
-1. Prefer official documentation and primary sources for the specific library, framework, or API.
-2. If a local docs or MCP tool is available, use it before broad web search.
-3. Only then proceed to implementation.
-
-Research when:
-- Installing or configuring a dependency.
-- Using an API, hook, method, or pattern not verified in this session.
-- Upgrading or migrating between versions.
-- Any task where relying on memory could cause stale syntax or behavior.
-
-Do not:
-- Assume API signatures, method names, or config options from memory.
-- Generate framework code without checking current docs first.
-- Skip research because the library seems familiar.
-
-<constraint>
-Research the codebase before editing. Never change code you have not read.
-</constraint>
-
-## Agentic Harness Heuristics
-
-Model-agnostic operating rules for coding-agent work.
-
-1. Persistence. Keep going until the user's request is actually handled. Only yield when the problem is solved or a concrete blocker is identified. Resolve in the fewest useful tool loops — once you can answer the core request with evidence, answer. Before ending a turn, check the last paragraph: if it is a plan, a question you can answer yourself, or a promise of work not done, do that work now.
-2. Default to parallel. When multiple reads, searches, inspections, or independent checks can run without depending on each other, run them together.
-3. Multi-pass search. First-pass search often misses — vary the wording before concluding something does not exist.
-4. Trace symbols. Before modifying a symbol, trace its definition and usages. Do not infer behavior from one call site.
-5. Linter-loop 3-strike rule. Do not loop more than 3 times fixing the same lint/test failure without reassessing the diagnosis.
-6. Read-before-edit TTL. If you have not read a file recently, re-read it before editing. User edits can make cached context stale.
-7. Big-file rule. For files over 1000 lines, prefer targeted search plus scoped reads over whole-file reads.
-8. Task hygiene. Track meaningful deliverables, not operational sub-steps. Mark work complete as soon as it is done.
-9. Literal-instruction rule. Treat explicit user requirements as checklists with success criteria. Do not silently broaden scope.
-10. Context hygiene. Prefer a fresh session at task boundaries over carrying stale context; preserve useful state before quality decays. Never stop, summarize, or suggest a new session on account of context limits.
-11. Autonomy calibration. For minor choices (naming, formatting, defaults, equivalent approaches), pick a reasonable option and note it — do not ask. Ask first only for scope changes, destructive actions, or decisions that change the deliverable. When the user is describing a problem or asking a question rather than requesting a change, the deliverable is your assessment — report findings and stop; do not apply fixes until asked.
-12. Capability triggering. Search or fetch current documentation when the answer depends on current or version-specific information. When work fans out across independent items, parallelize or delegate; never delegate work you can complete directly. For verification, prefer a fresh-context check over self-critique. On long tasks, keep running notes and re-read them between phases.
-
-<constraint>
-Treat these heuristics as protocol. If a turn violates an applicable rule, self-correct before continuing.
-</constraint>
-
-## Engineering Discipline
-
-- Prefer the repository's existing patterns and helpers over new abstractions.
-- Keep edits scoped to the user's request and the surrounding ownership boundary.
-- Add abstractions only when they remove real complexity or match an established local pattern.
-- Preserve user changes. Never revert unrelated dirty work unless explicitly asked.
-- Verify with the narrowest useful command first, then broaden if risk warrants it.
-- Surface any test or verification you could not run.
-- Before the first tool call, state in one or two sentences what you are about to do; give a brief progress update every few execution steps.
-- Concise teammate tone: no status tics, no log-style updates; reference file paths instead of dumping contents; lead with what changed and why, not a "Summary" heading.
-- The final message is for a reader who did not watch the work: outcome first, complete sentences. Shorten by dropping detail, never by compressing into fragments or arrow chains.
-
-<constraint>
-No secrets in committed config. Treat plugin marketplaces, installers, and downloaded artifacts as untrusted until verified.
-</constraint>
-
-## Agentic Engineering Discipline
-
-1. **State assumptions; push back when warranted.** If a requirement is ambiguous in a way that changes the deliverable, surface the ambiguity and propose 1–2 concrete interpretations in your first message — do not silently pick one. Surface inconsistencies instead of guessing past them; present tradeoffs when approaches genuinely differ; push back when the request looks wrong.
-2. **Minimum code that solves the stated problem.** No speculative features, no abstractions without a second caller, no broad exception handling around internally-trusted calls, no dead code left behind after a refactor, no comments that restate what the code says.
-3. **Surgical changes only.** Do not modify code, comments, or formatting outside the explicit scope of the request. Surface unrelated issues as follow-ups — do not fix inline.
-4. **State how success will be verified before implementing.** Name the test, build, smoke check, or diff inspection that will prove the change works. Prefer executable criteria — a test that fails before and passes after, a command with expected output — and keep each change small enough that its diff is reviewable in one sitting.
-5. **Review scope follows the pipeline.** In pipeline reviews with a downstream filter, report every issue found with confidence and severity — filtering happens downstream. In ad-hoc reviews, flag only gaps that affect correctness or the stated requirements; treat the rest as optional.
-6. **Ground every progress claim in evidence.** Before reporting progress or completion, audit each claim against a tool result from this session — show the test output, the command and what it returned. If something is unverified, say so explicitly; if tests fail, say so with the output.
-
-<constraint>
-Treat the six rules above as preventive (during generation), not remedial (after the fact). Self-correct if a turn drifts.
-</constraint>

package/SoT/.codex/agents/.gitkeep

@@ -1 +0,0 @@
-

package/SoT/.codex/config.toml

@@ -1,45 +0,0 @@
-model = "gpt-5.6-sol"
-model_reasoning_effort = "xhigh"
-plan_mode_reasoning_effort = "xhigh"
-model_reasoning_summary = "detailed"
-model_verbosity = "medium"
-personality = "pragmatic"
-web_search = "live"
-project_doc_max_bytes = 131072
-approval_policy = "on-request"
-sandbox_mode = "workspace-write"
-approvals_reviewer = "auto_review"
-
-[sandbox_workspace_write]
-network_access = true
-
-[features]
-memories = true
-
-[memories]
-dedicated_tools = true
-max_rollout_age_days = 30
-
-[agents]
-max_threads = 12
-max_depth = 2
-
-[tui]
-status_line_use_colors = true
-status_line = [
-  "model-with-reasoning",
-  "current-dir",
-  "git-branch",
-  "context-used",
-  "five-hour-limit",
-  "weekly-limit",
-]
-
-[plugins."docks@docks"]
-enabled = true
-
-[plugins."session-relay@docks"]
-enabled = true
-
-[plugins."effect-kit@docks"]
-enabled = true

package/SoT/.codex/plugins/marketplace.json

@@ -1,50 +0,0 @@
-{
-  "name": "docks",
-  "interface": {
-    "displayName": "DocksDocks"
-  },
-  "plugins": [
-    {
-      "name": "docks",
-      "source": {
-        "source": "git-subdir",
-        "url": "https://github.com/DocksDocks/docks.git",
-        "path": "./plugins/docks",
-        "ref": "main"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    },
-    {
-      "name": "session-relay",
-      "source": {
-        "source": "git-subdir",
-        "url": "https://github.com/DocksDocks/docks.git",
-        "path": "./plugins/session-relay",
-        "ref": "main"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    },
-    {
-      "name": "effect-kit",
-      "source": {
-        "source": "git-subdir",
-        "url": "https://github.com/DocksDocks/docks.git",
-        "path": "./plugins/effect-kit",
-        "ref": "main"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}

package/SoT/.codex/rules/docks.rules

@@ -1,116 +0,0 @@
-prefix_rule(pattern=["pwd"], decision="allow")
-prefix_rule(pattern=["ls"], decision="allow")
-prefix_rule(pattern=["cat"], decision="allow")
-prefix_rule(pattern=["head"], decision="allow")
-prefix_rule(pattern=["tail"], decision="allow")
-prefix_rule(pattern=["wc"], decision="allow")
-prefix_rule(pattern=["nl"], decision="allow")
-prefix_rule(pattern=["grep"], decision="allow")
-prefix_rule(pattern=["sort"], decision="allow")
-prefix_rule(pattern=["uniq"], decision="allow")
-prefix_rule(pattern=["diff"], decision="allow")
-prefix_rule(pattern=["which"], decision="allow")
-prefix_rule(pattern=["date"], decision="allow")
-prefix_rule(pattern=["basename"], decision="allow")
-prefix_rule(pattern=["dirname"], decision="allow")
-prefix_rule(pattern=["realpath"], decision="allow")
-prefix_rule(pattern=["readlink"], decision="allow")
-prefix_rule(pattern=["jq"], decision="allow")
-prefix_rule(pattern=["tree"], decision="allow")
-prefix_rule(pattern=["cut"], decision="allow")
-prefix_rule(pattern=["tr"], decision="allow")
-prefix_rule(pattern=["echo"], decision="allow")
-prefix_rule(pattern=["printf"], decision="allow")
-prefix_rule(pattern=["printenv"], decision="allow")
-prefix_rule(pattern=["uname"], decision="allow")
-prefix_rule(pattern=["file"], decision="allow")
-prefix_rule(pattern=["stat"], decision="allow")
-prefix_rule(pattern=["du"], decision="allow")
-prefix_rule(pattern=["id"], decision="allow")
-prefix_rule(pattern=["whoami"], decision="allow")
-
-prefix_rule(pattern=["git", "status"], decision="allow")
-prefix_rule(pattern=["git", "diff"], decision="allow")
-prefix_rule(pattern=["git", "log"], decision="allow")
-prefix_rule(pattern=["git", "show"], decision="allow")
-prefix_rule(pattern=["git", "blame"], decision="allow")
-prefix_rule(pattern=["git", "rev-parse"], decision="allow")
-prefix_rule(pattern=["git", "ls-files"], decision="allow")
-prefix_rule(pattern=["git", "grep"], decision="allow")
-prefix_rule(pattern=["git", "ls-tree"], decision="allow")
-prefix_rule(pattern=["git", "branch", "--show-current"], decision="allow")
-prefix_rule(pattern=["git", "branch", "-vv"], decision="allow")
-prefix_rule(pattern=["git", "mv"], decision="allow")
-
-prefix_rule(pattern=["gh", "pr", "view"], decision="allow")
-prefix_rule(pattern=["gh", "pr", "list"], decision="allow")
-prefix_rule(pattern=["gh", "pr", "diff"], decision="allow")
-prefix_rule(pattern=["gh", "pr", "status"], decision="allow")
-prefix_rule(pattern=["gh", "pr", "checks"], decision="allow")
-
-prefix_rule(pattern=["docker", "ps"], decision="allow")
-
-prefix_rule(pattern=["git", "push"], decision="prompt")
-prefix_rule(pattern=["git", "reset"], decision="prompt")
-prefix_rule(pattern=["git", "clean"], decision="prompt")
-prefix_rule(pattern=["git", "merge"], decision="prompt")
-prefix_rule(pattern=["git", "rebase"], decision="prompt")
-prefix_rule(pattern=["git", "checkout"], decision="prompt")
-
-prefix_rule(pattern=["rm"], decision="prompt")
-prefix_rule(pattern=["mv"], decision="prompt")
-prefix_rule(pattern=["chmod"], decision="prompt")
-prefix_rule(pattern=["chown"], decision="prompt")
-prefix_rule(pattern=["kill"], decision="prompt")
-prefix_rule(pattern=["pkill"], decision="prompt")
-
-prefix_rule(pattern=["npm", "install"], decision="prompt")
-prefix_rule(pattern=["npm", "uninstall"], decision="prompt")
-prefix_rule(pattern=["pnpm", "add"], decision="prompt")
-prefix_rule(pattern=["pnpm", "remove"], decision="prompt")
-prefix_rule(pattern=["yarn", "add"], decision="prompt")
-prefix_rule(pattern=["yarn", "remove"], decision="prompt")
-prefix_rule(pattern=["pip", "install"], decision="prompt")
-prefix_rule(pattern=["pip", "uninstall"], decision="prompt")
-prefix_rule(pattern=["pip3", "install"], decision="prompt")
-prefix_rule(pattern=["pip3", "uninstall"], decision="prompt")
-
-prefix_rule(pattern=["docker", "run"], decision="prompt")
-prefix_rule(pattern=["docker", "rm"], decision="prompt")
-prefix_rule(pattern=["docker", "stop"], decision="prompt")
-prefix_rule(pattern=["docker", "volume"], decision="prompt")
-prefix_rule(pattern=["docker", "system"], decision="prompt")
-prefix_rule(pattern=["docker", "compose", "up"], decision="prompt")
-prefix_rule(pattern=["docker", "compose", "down"], decision="prompt")
-prefix_rule(pattern=["docker", "compose", "rm"], decision="prompt")
-prefix_rule(pattern=["docker", "compose", "stop"], decision="prompt")
-prefix_rule(pattern=["docker-compose", "up"], decision="prompt")
-prefix_rule(pattern=["docker-compose", "down"], decision="prompt")
-prefix_rule(pattern=["docker-compose", "rm"], decision="prompt")
-prefix_rule(pattern=["docker-compose", "stop"], decision="prompt")
-
-# `tail -f`/`--follow` never returns and hangs the agent (bare `tail` stays allowed above).
-prefix_rule(pattern=["tail", "-f"], decision="prompt")
-prefix_rule(pattern=["tail", "--follow"], decision="prompt")
-# rg and `sed -n` are prompt, NOT allow: argv-prefix matching cannot gate their
-# code-exec forms (rg --pre=CMD or a reordered --pre; sed -n 'e CMD' / -ni) while a
-# shorter allow prefix would auto-approve the whole command.
-prefix_rule(pattern=["rg"], decision="prompt")
-prefix_rule(pattern=["sed", "-n"], decision="prompt")
-prefix_rule(pattern=["find"], decision="prompt")
-prefix_rule(pattern=["sed", "-i"], decision="prompt")
-prefix_rule(pattern=["sed", "--in-place"], decision="prompt")
-prefix_rule(pattern=["awk"], decision="prompt")
-prefix_rule(pattern=["xargs"], decision="prompt")
-prefix_rule(pattern=["tee"], decision="prompt")
-prefix_rule(pattern=["curl"], decision="prompt")
-prefix_rule(pattern=["env"], decision="prompt")
-
-prefix_rule(pattern=["sudo"], decision="forbidden")
-prefix_rule(pattern=["eval"], decision="forbidden")
-prefix_rule(pattern=["mkfs"], decision="forbidden")
-prefix_rule(pattern=["dd"], decision="forbidden")
-prefix_rule(pattern=["git", "push", "--force", "origin", "main"], decision="forbidden")
-prefix_rule(pattern=["git", "push", "--force", "origin", "master"], decision="forbidden")
-prefix_rule(pattern=["git", "push", "-f", "origin", "main"], decision="forbidden")
-prefix_rule(pattern=["git", "push", "-f", "origin", "master"], decision="forbidden")

package/SoT/models.json

@@ -1,31 +0,0 @@
-{
-  "$comment": "Kit-verified model catalog — single source for EngineNative validators, the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.",
-  "claude": {
-    "verified": "2026-07-08",
-    "models": [
-      { "id": "best", "kind": "alias", "note": "Fable 5 where the org has access, latest Opus otherwise (Claude Code >=2.1.170)" },
-      { "id": "opus", "kind": "alias", "note": "latest Opus (currently Opus 4.8) — the kit SoT default, paired with the fable advisor" },
-      { "id": "fable", "kind": "alias", "note": "Fable 5 — needs org access + Claude Code >=2.1.170" },
-      { "id": "sonnet", "kind": "alias", "note": "latest Sonnet (currently Sonnet 5)" },
-      { "id": "haiku", "kind": "alias", "note": "latest Haiku (currently Haiku 4.5)" },
-      { "id": "default", "kind": "alias", "note": "engine pseudo-value: deletes the deployed model key so the account default applies" },
-      { "id": "claude-fable-5", "kind": "id", "note": "Fable 5" },
-      { "id": "claude-opus-4-8", "kind": "id", "note": "Opus 4.8" },
-      { "id": "claude-sonnet-5", "kind": "id", "note": "Sonnet 5" },
-      { "id": "claude-haiku-4-5-20251001", "kind": "id", "note": "Haiku 4.5" }
-    ]
-  },
-  "codex": {
-    "verified": "2026-07-09",
-    "models": [
-      { "id": "gpt-5.6-sol", "kind": "id", "note": "GPT-5.6 Sol — frontier, recommended default; the kit SoT pin" },
-      { "id": "gpt-5.6-terra", "kind": "id", "note": "GPT-5.6 Terra — balanced tier" },
-      { "id": "gpt-5.6-luna", "kind": "id", "note": "GPT-5.6 Luna — fast/light tier" },
-      { "id": "gpt-5.5", "kind": "id", "note": "previous generation" },
-      { "id": "gpt-5.5-codex", "kind": "id", "note": "codex-tuned gpt-5.5" },
-      { "id": "gpt-5.1", "kind": "id", "note": "previous generation" },
-      { "id": "gpt-5", "kind": "id", "note": "previous generation" },
-      { "id": "gpt-5-codex", "kind": "id", "note": "codex-tuned gpt-5" }
-    ]
-  }
-}

package/SoT/toolchain.json

@@ -1,27 +0,0 @@
-{
-  "$comment": "Kit toolchain manifest — DATA only (versions, floors, policy); check/install logic lives in cli/src/engine-native/toolchain.ts with per-surface sync callbacks in cli/src/engine-native/. kind: required (preflight hard dep) | check (doctor visibility only) | managed (kit installs/upgrades it) | pin (no binary probe — a version pin for a tool the kit invokes via npx). policy (managed only): track (upgrade toward latest, gated by `verified`) | present (install when missing, never upgrade). `verified` = last kit-tested version — anything above it prompts before install (--yes auto-accepts; non-TTY declines and falls back to the pinned `verified` when pinnable). Supply-chain stance: every kit-driven install is pinned to `verified` or gated by it — never floating @latest (npm-worm/Shai-Hulud surface). Update `verified` after testing a new release.",
-  "tools": {
-    "jq":     { "kind": "required", "note": "deployed Claude hooks/statusline assets" },
-    "curl":   { "kind": "required", "note": "installers + usage fetch" },
-    "git":    { "kind": "check", "note": "plugin marketplaces (claude/codex clone them) + kit checkout updates" },
-    "node":   { "kind": "check", "note": "hosts npm globals (agent-browser, LSP servers)" },
-    "npm":    { "kind": "check", "note": "npm-global installer" },
-    "claude": { "kind": "check", "floor": "2.1.170", "note": "kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)" },
-    "codex":  { "kind": "check", "note": "upstream-owned; standalone installer prints when missing" },
-    "ffplay": { "kind": "check", "note": "Notification hook sound (previously unchecked)" },
-    "bwrap":  { "kind": "check", "os": "linux", "note": "Codex Linux sandbox runtime" },
-    "intelephense": { "kind": "check", "verified": "1.18.5", "note": "php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
-    "typescript-language-server": { "kind": "check", "verified": "5.3.0", "note": "typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
-    "tsc":    { "kind": "check", "verified": "6.0.3", "note": "typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install. Deliberately on the 6.x line: typescript-language-server embeds TypeScript's programmatic API, which TS7 (native) doesn't yet expose — the repo's own devDependency runs TS7 for tsc --noEmit" },
-    "rtk":    { "kind": "managed", "policy": "track", "floor": "0.43.0", "verified": "0.43.0", "pinnable": true,
-                "note": "PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin" },
-    "bun":    { "kind": "managed", "policy": "present", "verified": "1.3.14", "pinnable": true,
-                "note": "runtime for effect-solutions + the docks-kit CLI; bootstrap installs the verified release (installer takes bun-vX.Y.Z); self-updates via `bun upgrade` when wanted" },
-    "effect-solutions": { "kind": "managed", "policy": "track", "verified": "0.5.3", "pinnable": true,
-                "note": "Effect docs CLI (bun global) — track keeps it self-upgrading, gated by the verified pin" },
-    "agent-browser":    { "kind": "managed", "policy": "track", "verified": "0.31.1", "pinnable": true,
-                "note": "browser-automation CLI (npm global), gated by the verified pin; first install also downloads Chrome for Testing" },
-    "skills-cli": { "kind": "pin", "verified": "1.5.15",
-                "note": "the `skills` npm package the kit runs via `npx skills@<verified>` on every agents sync (universal-skill install/remove) — pinned, never @latest" }
-  }
-}