@starci/hfs 4.7.31 → 4.7.33

package/runtime/modules/kernel/command-policy.yaml

@@ -0,0 +1,249 @@
+# command-policy.yaml - the ONE rule table of what an agent may run on the host (rule R223 RIGHTS_ROLE_DENIED).
+# Two entry points read this table and nothing else: the PreToolUse command guard (scripts/guards/command-guard.mjs: Claude
+# and Devin) and the PATH shim wrappers an Orca worker terminal puts first on PATH (scripts/guards/command-policy.mjs
+# shimDecision: every agent kind, Codex and Cursor included). A rule is data here; the few matchers that need a real parse
+# (a push refspec, a tag read form, a whole-suite glob, a test file list) are named in `match` and live in rights.mjs.
+#
+# Side effects go through `starci <group> <verb>`: an agent is allowed the read-only commands below, the runtime's own verbs
+# and the file edits of its worktree (file rights, R224); every other raw tool is refused with the starci verb to use.
+# The owner (no role) and the release role are never refused. Unknown programs are refused (default deny).
+#
+# `use` names the allowed path (a verb of the CLI catalog, modules/cli/commands); the CLI lane edits the verbs, this file stays
+# the single place.
+roles:
+  bound: [op, lead, supervisor, coordinator, critic]
+  # roles that may run a targeted `node --test <explicit spec files>` (a package spec or the scaffold e2e); an op uses its gate
+  node-test: [lead, supervisor, coordinator]
+  # ops that may run a whole suite (the full unit / full e2e of an app)
+  suite-ops: [unit.verify, e2e.verify]
+  # the only refs a coordinator or the supervisor may push (backup namespace, explicit refspecs)
+  backup-roles: [coordinator, supervisor]
+  backup-ref: '^refs/backup/\S+$'
+# The Critic (rights role `critic`, a terminal bound to a critic job guard) reaches nothing but its own directory: scripts/guards/critic-reach.mjs.
+# `read` are the programs it may run on paths inside that directory; `write` the programs that may write the verdict file and nothing else.
+# The Orca self-lifecycle verbs (worker_done, escalation) below stay open to it; the rest of this table does not apply to it.
+critic:
+  read: [ls, dir, cat, type, head, tail, wc, file, stat, sha256sum, sha1sum, md5sum, cksum, od, xxd, hexdump, rg, grep, egrep, fgrep, jq, yq, nl, column, pwd, echo, printf, true, false,
+    get-content, gc, get-childitem, gci, get-item, gi, select-string, sls, test-path, resolve-path, get-location, write-output, write-host, measure-object, get-filehash]
+  write: [set-content, sc, out-file, add-content, ac]
+# The runtime's own verbs: the surface every other path is steered to.
+runtime: [starci]
+# Verbs that spend a provider model headlessly (a call tier of modules/models/tiers.yaml calls): a bound role runs one only as an op named
+# here, and a headless agent CLI by hand stays refused (AGENT_HEADLESS_LAUNCH).
+calls:
+  imagegen:
+    verb: [work, imagegen]
+    ops: [interface.draw, interface.asset, brand.decide]
+    use: starci work imagegen --prompt <file> --out <dir in the worktree> (interface.draw, interface.asset and brand.decide only)
+# Capability verbs the runtime performs for an op (a served app and a browser): a bound role runs one only as an op named here. The app is
+# served by the verb, on the host name the app's own proxy uses; a server an op starts by hand is refused (raw-tools.next, the node and npm rows).
+renders:
+  layoutRender:
+    verb: [work, layout-render]
+    ops: [brand.decide, interface.draw]
+    use: starci work layout-render --work .starciwork --node <layout node id> --breakpoint <bp> --theme <theme> --write (brand.decide and interface.draw only)
+# The Supervisor seat (a bound caller of role supervisor). The Supervisor judges and answers: it reads, it answers the items of its menu
+# with `starci supervisor decide`, it records a runtime defect for Debug and it runs the collectors it owns. It changes no runtime code
+# (RUNTIME_CHANGE_OWNED_BY_DEBUG) and runs no other mutating verb: a refusal names the status and decision verbs
+# (SUPERVISOR_USE_DECIDE). Every program but starci, the pure reads and the read forms of git and npm is refused (SUPERVISOR_STARCI_ONLY).
+supervisor:
+  # starci <group> <verb> words the Supervisor seat may run
+  verbs:
+    supervisor: [status, decide, poll, actions, channel, workers, gc, revision-ack]
+    machine: [decisions]
+    kernel: [status, logs, questions, messages, survey, hierarchy, artifacts, coverage, usage, observe, peers, foundations, extensions, decisions, inbox, log]
+    workflow: [status]
+    gate: [read]
+  # a verb of several actions allows only these
+  actions:
+    actions: [list, digest, record]
+    channel: [register, inbox, reply]
+    workers: [list, show, cap]
+  # read verbs that also have mutating flags: refused when one of these flags is present
+  read-flags:
+    decisions: [open, claim, resolve, escalate, ring]
+    inbox: [ack]
+  # `supervisor actions record` is the defect queue: allowed for these --item values only
+  record-items: '^runtime-defect:[^ ]+$'
+  # programs whose read forms the general policy judges (git status, npm view); every write form of them is refused there
+  defer: [orca, git, npm, pnpm, yarn, bun]
+  # pure reads that the Supervisor does not get
+  deny-programs: [sleep, node]
+  use: "answer an item of the menu: starci supervisor status prints it, starci supervisor decide --item <id> --choice <choice> --reason <why> [--text <input>] answers it; a defect of the runtime is recorded with starci supervisor actions record --item runtime-defect:<cause> --action recorded --reason <why>"
+# The Op (a bound guard of role op). Its starci calls are its work: the capability verbs (starci app stack and the runtime-slot verbs for servers,
+# starci work draw-render for renders, starci work imagegen for images, starci gate unit for tests, the checks) and its
+# report to its Kernel (starci kernel report). These groups are the control plane: the controllers, the Kernel and the Supervisor run them.
+op:
+  deny-groups: [supervisor, reconciler, workflow, route, debug]
+  use: "an Op runs the capability verbs of its work (starci app stack for servers, starci work draw-render for renders, starci work imagegen for images, starci gate unit for tests) and reports to its Kernel with starci kernel report"
+# Release path: refused to every bound role.
+release:
+  verbs: [cut, publish]
+  scripts: [release:cut, release:publish]
+  use: starci release cut is owner-approved and moves main plus its tag; starci release publish publishes packages from that release; starci release notes prints or writes a tag CHANGELOG section and is not owner-gated
+# Programs that cannot change state, with any arguments.
+read: [ls, dir, cat, type, head, tail, wc, uniq, cut, tr, diff, cmp, comm, rg, grep, egrep, fgrep, echo, printf, pwd, cd, pushd, popd, which, where, whoami, hostname,
+  stat, file, realpath, readlink, dirname, basename, date, true, false, test, '[', expr, sleep, seq, basename, md5sum, sha1sum, sha256sum, shasum, cksum, od, xxd, hexdump,
+  jq, yq, column, nl, rev, tac, fold, fmt, join, paste, split-none, env-none, get-content, gc, get-childitem, gci, get-item, gi, select-string, sls, test-path, resolve-path,
+  get-location, set-location, sl, write-output, write-host, measure-object, sort-object, where-object, select-object, format-table, ft, convert-to-json, convertfrom-json,
+  get-date, get-command, gcm, get-process-none, out-string, out-null, tee-object-none]
+# Read-only unless one of the options makes them write.
+guarded-read:
+  find: [-delete, -exec, -execdir, -ok, -okdir, -fprint, -fprint0, -fprintf, -fls]
+  sed: []   # sed -i is an in-place file edit inside the worktree: the file rights (R224) judge its target, like cp and mv
+  sort: [-o, --output]
+  awk: [-i, inplace]
+  gawk: [-i, inplace]
+  xargs: []
+  # static analysis: read-only when it does not write back or emit
+  eslint: [--fix, --fix-type]
+  prettier: [--write, -w]
+  stylelint: [--fix]
+  tsc: []
+  node: []
+# tsc and prettier are read-only only in their checking forms.
+require-flag:
+  tsc: ['--noEmit', '-noEmit']
+  prettier: ['--check', '-c', '--list-different', '-l']
+# File mutations inside the worktree: allowed here; the file rights (R224 protected zone, op never writes the runtime checkout)
+# judge the targets.
+scoped-write: [mkdir, cp, mv, rm, rmdir, touch, tee, install, truncate, copy, move, del, erase, ren, rename, new-item, ni, set-content, sc, add-content, ac, out-file, remove-item, ri,
+  copy-item, cpi, move-item, mi, clear-content, clc, rename-item, rni, mklink-none,
+  # process control: a kill by PID of a process the agent started passes here; the older guard rules (PROCESS_KILL_BY_NAME, process-query kills) refuse the rest
+  kill, taskkill, stop-process, spps, tasklist, ps, get-process, gps, printenv]
+git:
+  # read-only subcommands
+  read: [status, log, diff, show, rev-parse, ls-files, ls-tree, cat-file, blame, grep, describe, shortlog, rev-list, merge-base, for-each-ref, name-rev, ls-remote, show-ref,
+    check-ignore, diff-tree, diff-index, diff-files, count-objects, whatchanged, version, help, var, verify-commit, verify-tag, range-diff, cherry, show-branch, instaweb-none]
+  # subcommands whose read forms pass (match names the parse in rights.mjs)
+  list-forms: [branch, tag, stash, worktree, remote, config, reflog, notes]
+  # denied subcommands: code, and the starci verb to use
+  deny:
+    commit: {code: RIGHTS_GIT_COMMIT, use: starci git commit}
+    add: {code: RIGHTS_GIT_COMMIT, use: starci git commit}
+    rm: {code: RIGHTS_GIT_COMMIT, use: starci git commit}
+    mv: {code: RIGHTS_GIT_COMMIT, use: starci git commit}
+    push: {code: RIGHTS_GIT_PUSH, use: 'starci git backup (refs/backup/* only); main and its tag move only through starci release cut'}
+    tag: {code: RIGHTS_GIT_TAG, use: starci release cut (the only tag maker; housekeeping marks are refs/backup/* or refs/salvage/*, never tags)}
+    merge: {code: RIGHTS_GIT_SYNC, use: starci git sync (merge main into the lane) or starci git land (coordinator)}
+    rebase: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    pull: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    fetch: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    checkout: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    switch: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    reset: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    restore: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    clean: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    cherry-pick: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    revert: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    am: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    apply: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    stash: {code: RIGHTS_GIT_SYNC, use: starci git sync}
+    worktree: {code: RIGHTS_GIT_SYNC, use: starci worker start creates a dispatched worktree; starci machine worktrees-clean removes landed worktrees}
+    branch: {code: RIGHTS_GIT_SYNC, use: starci worker start creates the lane branch and its dispatched worktree}
+    update-ref: {code: RIGHTS_GIT_SYNC, use: starci git sync is the only lane ref integration; other ref edits are owner-only}
+    gc: {code: RIGHTS_GIT_SYNC, use: starci machine worktrees-clean performs the runtime-owned safe cleanup; repository GC is owner-only}
+    reflog: {code: RIGHTS_GIT_SYNC, use: starci git sync is the only lane ref integration; reflog mutation is owner-only}
+    config: {code: RIGHTS_GIT_SYNC, use: starci git sync carries the lane synchronization convention; configuration writes are owner-only}
+    remote: {code: RIGHTS_GIT_SYNC, use: starci git sync uses the configured repository; remote mutation is owner-only}
+    notes: {code: RIGHTS_GIT_SYNC, use: starci git sync is the lane integration path; notes mutation is owner-only}
+    submodule: {code: RIGHTS_GIT_SYNC, use: starci git sync is the lane integration path; submodule mutation is owner-only}
+    init: {code: RIGHTS_GIT_SYNC, use: starci worker start creates the runtime-owned checkout; repository creation is owner-only}
+    clone: {code: RIGHTS_GIT_SYNC, use: starci worker start creates the runtime-owned checkout; cloning is owner-only}
+npm:
+  programs: [npm, pnpm, yarn, bun]
+  read: [view, v, info, show, ls, list, la, ll, outdated, explain, why, root, prefix, bin, help, search, whoami, ping, '-v', '--version', 'config get', 'config list', pack-dry]
+  deny:
+    publish: {code: RIGHTS_NPM_PUBLISH, use: starci release cut authorizes the release; starci release publish publishes its packages once}
+    unpublish: {code: RIGHTS_NPM_PUBLISH, use: starci release publish is the only package-publication path; unpublishing is owner-only}
+    deprecate: {code: RIGHTS_NPM_PUBLISH, use: starci release publish is the only package-publication path; deprecation is owner-only}
+    dist-tag: {code: RIGHTS_NPM_PUBLISH, use: starci release publish is the only package-publication path; dist-tag mutation is owner-only}
+    pack: {code: RIGHTS_RAW_TOOL, use: starci release cut creates release artifacts; ad hoc package archives are owner-only}
+    ci: {code: RIGHTS_NPM_CI_UNLOCKED, use: starci npm ci installs dependencies under the host lock in the caller's own worktree}
+    install: {code: RIGHTS_RAW_TOOL, use: starci npm install adds exact-pinned dependencies and is limited to lead or owner}
+    i: {code: RIGHTS_RAW_TOOL, use: starci npm install adds exact-pinned dependencies and is limited to lead or owner}
+    add: {code: RIGHTS_RAW_TOOL, use: starci npm install adds exact-pinned dependencies and is limited to lead or owner}
+    update: {code: RIGHTS_RAW_TOOL, use: starci npm install is the owner-controlled dependency-change path using canon pins}
+    uninstall: {code: RIGHTS_RAW_TOOL, use: starci npm install is the owner-controlled dependency-change path using canon pins}
+    test: {code: RIGHTS_RAW_TOOL, use: starci runtime verify in the runtime (the check, package clean-test and scaffold e2e; the full proof is the release cut) or starci gate unit --root <app> in an app}
+    t: {code: RIGHTS_RAW_TOOL, use: starci runtime verify in the runtime (the check, package clean-test and scaffold e2e; the full proof is the release cut) or starci gate unit --root <app> in an app}
+    run: {code: RIGHTS_RAW_TOOL, use: 'starci runtime verify proves a runtime change; starci work layout-render serves the app for a layout capture; use starci release sync-runtime for package runtime copies and grammar preparation, or starci check run, starci lint run, starci typecheck run, starci app stack, or starci gate run for other scripts'}
+    run-script: {code: RIGHTS_RAW_TOOL, use: 'starci runtime verify proves a runtime change; use starci check run, starci lint run, starci typecheck run, starci app stack, or starci gate run for other scripts'}
+    start: {code: RIGHTS_RAW_TOOL, use: 'starci app stack'}
+    exec: {code: RIGHTS_RAW_TOOL, use: 'starci check run, starci lint run, starci typecheck run, or starci gate run for that tool'}
+    link: {code: RIGHTS_RAW_TOOL, use: starci npm install is the dependency path; an agent never makes a package link}
+    rebuild: {code: RIGHTS_RAW_TOOL, use: starci npm ci rebuilds the exact lockfile install under the host lock}
+    prune: {code: RIGHTS_RAW_TOOL, use: starci npm install is the owner-controlled dependency-change path; agents do not prune packages}
+    dedupe: {code: RIGHTS_RAW_TOOL, use: starci npm install is the owner-controlled dependency-change path; agents do not dedupe packages}
+# Side-effecting tools with no read form: refused whole, each with the starci verb to use.
+raw-tools:
+  docker: {use: 'starci docker up, starci docker down, starci docker build, or starci docker ps; a release image proof is starci release images'}
+  docker-compose: {use: 'starci docker up, starci docker down, starci docker build, or starci docker ps'}
+  podman: {use: 'starci docker up, starci docker down, starci docker build, or starci docker ps'}
+  kubectl: {use: 'starci app stack'}
+  k3d: {use: 'starci app stack'}
+  supabase: {use: "starci supabase start, starci supabase stop, or starci supabase status for the app's own stack"}
+  gh: {use: 'starci release cut (the GitHub release is created from the CHANGELOG section of the tag); anything else is the owner''s'}
+  schtasks: {use: 'starci task register, starci task show, or starci task list for runtime scheduled tasks'}
+  shutdown: {use: 'ask the owner: a worker never shuts the host down'}
+  reboot: {use: 'ask the owner: a worker never reboots the host'}
+  next: {use: 'starci work layout-render serves the product app on localhost and captures a layout (brand.decide and interface.draw); a dev server started by hand renders nothing the runtime can use'}
+  jest: {use: starci gate unit --root <app> in an app, or starci runtime verify in the runtime}
+  vitest: {use: starci gate unit --root <app> in an app, or starci runtime verify in the runtime}
+  mocha: {use: starci gate unit --root <app> in an app, or starci runtime verify in the runtime}
+  playwright: {use: starci gate run --root <app> for the app's e2e proof, or starci runtime verify in the runtime}
+  cypress: {use: starci gate run --root <app> for the app's e2e proof, or starci runtime verify in the runtime}
+  pytest: {use: starci gate unit --root <app> in an app, or starci runtime verify in the runtime}
+  turbo: {use: 'starci gate run --root <app>'}
+  nest: {use: 'starci gate run --root <app>'}
+  curl: {use: 'ask the owner or use the service catalog command; a worker does not call the network by hand'}
+  wget: {use: 'ask the owner or use the service catalog command'}
+  ssh: {use: 'ask the owner'}
+  scp: {use: 'ask the owner'}
+# Orca: reads pass; only the caller's own worker protocol bypasses the runtime mutation verbs.
+orca:
+  read: [check, worker-show, worker-list, worker-read, inbox, run-show, run-list, task-show, task-list, status, list, read, show, tail, get, wait-none]
+  groups-read: [terminal, worktree, repo, orchestration]
+  # Kernel guards resolve to lead. Supervisor workers resolve to supervisor; app workers resolve to op.
+  # The Kernel mailbox refusal (install-verdict.mjs KERNEL_ORCA_CHECK) still precedes admission.
+  self-lifecycle:
+    group: orchestration
+    roles: [op, lead, supervisor, coordinator, critic]
+    verbs:
+      send:
+        identity: --from
+        types: [heartbeat, worker_done, escalation]
+        typesByRole: {critic: [worker_done, escalation]}
+        values: [--from, --type, --subject, --body, --to, --run, --priority, --thread-id, --payload, --task-id, --dispatch-id,
+          --outcome, --files-modified, --report-path, --phase, --dispatch-capability, --retry-request]
+        flags: [--json, --help]
+        # an Op reports to its own Kernel's Run and addresses no one else (modules/kernel/roles.yaml chain.opMayNotAddress)
+        refuse-for: {op: [--to, --run]}
+      ask:
+        roles: [op, lead, supervisor, coordinator]
+        identity: --from
+        values: [--from, --question, --resume, --to, --run, --options, --timeout-ms, --dispatch-capability, --retry-request]
+        flags: [--json, --help]
+        refuse-for: {op: [--to, --run]}
+      check:
+        identity: --terminal
+        values: [--terminal, --run, --ack, --types, --timeout-ms, --retry-request]
+        flags: [--json, --help, --unread, --peek, --all, --format, --wait]
+  use: starci worker start, starci worker show, starci worker read, starci worker list, starci worker stop, starci worker release, or starci worker close
+# The Kernel seat (a bound guard of role kernel). A Kernel judges and answers: it reads, it answers the items of its menu with
+# `starci kernel decide`, and it attests the runtime revision. Every other `starci kernel <verb>` is the runtime's own (the
+# controllers run it) or the lead's and owner's; a refusal names the status and decision verbs (KERNEL_USE_DECIDE). Every program
+# but the pure reads below is refused (KERNEL_STARCI_ONLY): the Kernel's shell is starci.
+kernel:
+  # starci <group> <verb> words the Kernel seat may run
+  verbs:
+    kernel: [status, logs, questions, messages, survey, hierarchy, artifacts, coverage, usage, observe, peers, foundations, extensions, decisions, inbox, log, decide, kernel-ack-rev, revision-ack]
+    workflow: [status]
+    gate: [read]
+  # read verbs that also have mutating flags: refused when one of these flags is present
+  read-flags:
+    decisions: [open, claim, resolve, escalate]
+    inbox: [ack]
+  # pure reads of `read` that the Kernel does not get
+  deny-programs: [sleep]
+  use: "answer an item of the menu: starci kernel status prints it, starci kernel decide --workflow <workflow> --item <id> --choice <choice> --reason <why> answers it"