@yunhozz/arc 0.0.0-stage → 0.1.0

package/lib/policy/render.mjs

@@ -0,0 +1,74 @@
+import {renderSourceClaudeHook} from './claude-hook.mjs';
+import {validateGitPolicy} from '../../claude/skill/hooks/role-git-guard.mjs';
+import source from './role-policy.json' with {type: 'json'};
+const ROLES = ['orchestrator','scouter','planner','coder','qa','reviewer'];
+const CONTROLS = ['prompt','capability','hook'];
+const fail = message => { throw new Error(`Role policy: ${message}`); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = value => Array.isArray(value) && value.length > 0 && value.every(x => typeof x === 'string' && x.length > 0) && new Set(value).size === value.length;
+const same = (a,b) => JSON.stringify(a) === JSON.stringify(b);
+export function validateRolePolicy(input) {
+  if (!object(input) || input.schemaVersion !== 1 || !Array.isArray(input.roles) || !same(input.roles.map(x=>x?.id),ROLES) || input.roles.some(x=>typeof x.description !== 'string' || !x.description)) fail('expected six known roles in canonical order');
+  if (!Array.isArray(input.rules) || !input.rules.length) fail('rules are required');
+  const ids = new Set();
+  for (const rule of input.rules) {
+    if (!object(rule) || typeof rule.id !== 'string' || !/^[a-z][a-z0-9.-]+$/.test(rule.id) || ids.has(rule.id)) fail('invalid or duplicate rule ID');
+    ids.add(rule.id);
+    if (!strings(rule.roles) || rule.roles.some(x=>!ROLES.includes(x)) || !['allow','deny','require'].includes(rule.effect) || !strings(rule.operations) || !strings(rule.evidence) || !['user','orchestrator'].includes(rule.authority) || typeof rule.text !== 'string' || !rule.text || /[\r\n]/.test(rule.text)) fail(`invalid rule ${rule.id}`);
+    if (!object(rule.controls) || !same(Object.keys(rule.controls).sort(),['claude','codex']) || Object.values(rule.controls).some(x=>!CONTROLS.includes(x))) fail(`invalid control level for ${rule.id}`);
+  }
+  for (const id of ['scope.non-escalation','git.specialists-deny','git.orchestrator-accept-commit','external.explicit-user-authority',...ROLES.map(x=>({orchestrator:'role.orchestrator-boundary',scouter:'role.scouter-read-only',planner:'role.planner-draft-only',coder:'role.coder-implementation',qa:'role.qa-verification',reviewer:'role.reviewer-independent'})[x]),'review.significant-no-plan','review.significant-plan','review.final-plan-recheck']) if(!ids.has(id)) fail(`missing required rule ${id}`);
+  for (const platform of ['codex','claude']) if (!object(input.platforms?.[platform]) || !CONTROLS.includes(input.platforms[platform].level) || typeof input.platforms[platform].notice !== 'string' || !input.platforms[platform].notice) fail(`invalid ${platform} controls`);
+  // These are workflow invariants, not customizable scheduling options.
+  const routes = {noPlan:['coder','qa','reviewer','orchestrator-accept'],planTask:['coder','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['coder','reviewer']};
+  if (!object(input.review) || Object.keys(input.review).length !== 4 || Object.entries(routes).some(([key,value])=>!same(input.review[key],value))) fail('invalid review routing');
+  try {validateGitPolicy(input.git);} catch {fail('invalid Git policy');}
+  return input;
+}
+export const defaultRolePolicy = source;
+export const POLICY_TARGETS = ['codex','claude'].flatMap(platform => [
+  {path:`${platform}/skill/SKILL.md`,platform,audience:'orchestrator'},
+  ...ROLES.slice(1).map(audience=>({path:`${platform}/agents/arc-${audience}.${platform==='codex'?'toml':'md'}`,platform,audience})),
+  ...['planning','handoff','handoff-prep','commit','verification'].map(name=>({path:`${platform}/skill/references/${name}.md`,platform,audience:'orchestrator'})),
+]);
+POLICY_TARGETS.splice(POLICY_TARGETS.length-1,0,{path:'claude/skill/hooks/git-policy.json',platform:'claude',audience:'specialists',asset:'git'});
+export function renderPolicySection(policy, {platform, audience, section = 'contract', skillPath} = {}) {
+  validateRolePolicy(policy);
+  if (!['codex','claude'].includes(platform) || !ROLES.includes(audience) || !['contract','global'].includes(section)) fail('unknown render target');
+  const rules = policy.rules.filter(rule=>section === 'global' || audience === 'orchestrator' || rule.roles.includes(audience));
+  const lines = ['Generated from lib/policy/role-policy.json; do not edit this managed section manually.', ...rules.map(rule=>`- [${rule.id}] ${rule.text}`), ...(section === 'global' ? [] : [`- [platform.${platform}] ${policy.platforms[platform].notice}`])];
+  if (skillPath !== undefined) { if(typeof skillPath !== 'string' || !skillPath || /[\r\n]/.test(skillPath)) fail('invalid skill path'); lines.push(`- Policy details: \`${skillPath}\`.`); }
+  return lines.join('\n');
+}
+export function replaceManagedPolicyBlocks(text, blocks) {
+  if(typeof text !== 'string' || !object(blocks) || !Object.keys(blocks).length) fail('invalid managed block input');
+  const tokens = [...text.matchAll(/\[ARC role policy: ([a-z-]+) (begin|end)\]/g)];
+  if (tokens.length !== Object.keys(blocks).length * 2 || tokens.some(x=>!Object.hasOwn(blocks,x[1]))) fail('missing or unexpected managed marker');
+  const ranges=[];
+  for(const [name,body] of Object.entries(blocks)) {
+    if(!/^[a-z-]+$/.test(name) || typeof body !== 'string' || body.includes('[ARC role policy:')) fail('invalid managed section');
+    const matches=tokens.filter(x=>x[1]===name);
+    if(matches.length!==2 || matches[0][2]!=='begin' || matches[1][2]!=='end') fail(`duplicate, missing or reversed ${name} markers`);
+    const start=matches[0].index+matches[0][0].length,end=matches[1].index;
+    const eol=/\r?\n/.exec(text)?.[0]??'\n';
+    if(tokens.some(x=>x.index>=start && x.index<end)) fail('nested managed markers');
+    ranges.push({start,end,body:eol+body.replace(/\r?\n/g,eol)+eol});
+  }
+  let result=text;
+  for(const {start,end,body} of ranges.sort((a,b)=>b.start-a.start)) result=result.slice(0,start)+body+result.slice(end);
+  return result;
+}
+export function buildPolicyOutputs(inputs, policy = source) {
+  validateRolePolicy(policy);
+  if (!(inputs instanceof Map) || inputs.size !== POLICY_TARGETS.length) fail('expected complete target map');
+  const outputs=new Map();
+  for(const target of POLICY_TARGETS) {
+    const bytes=inputs.get(target.path); if(!Buffer.isBuffer(bytes)) fail(`missing target ${target.path}`);
+    let text; try{text=new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes);}catch{fail(`invalid UTF-8 target ${target.path}`);}
+    if(target.asset==='git') {try{JSON.parse(text);}catch{fail('invalid Git policy asset');}outputs.set(target.path,Buffer.from(JSON.stringify(policy.git,null,2)+'\n'));continue;}
+    let rendered=replaceManagedPolicyBlocks(text,{contract:renderPolicySection(policy,{...target,section:'contract'})});
+    if(target.platform==='claude' && target.path.startsWith('claude/agents/')) {try{rendered=renderSourceClaudeHook(rendered);}catch{fail('invalid Claude hook wiring');}}
+    outputs.set(target.path,Buffer.from(rendered));
+  }
+  return outputs;
+}

package/lib/policy/role-policy.json

@@ -0,0 +1,577 @@
+{
+  "schemaVersion": 1,
+  "roles": [
+    {
+      "id": "orchestrator",
+      "description": "Coordinate, prepare, verify evidence, accept and serialize Git changes."
+    },
+    {
+      "id": "scouter",
+      "description": "Read assigned static material and report sources and limits."
+    },
+    {
+      "id": "planner",
+      "description": "Return design, spec and plan drafts to Orchestrator."
+    },
+    {
+      "id": "coder",
+      "description": "Implement assigned approved changes and focused checks."
+    },
+    {
+      "id": "qa",
+      "description": "Run approved checks and report evidence."
+    },
+    {
+      "id": "reviewer",
+      "description": "Independently inspect final changes and report findings."
+    }
+  ],
+  "rules": [
+    {
+      "id": "scope.non-escalation",
+      "roles": [
+        "orchestrator",
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "deny",
+      "operations": [
+        "scope-expansion",
+        "indirect-bypass"
+      ],
+      "evidence": [
+        "approved-scope",
+        "assigned-role"
+      ],
+      "authority": "orchestrator",
+      "text": "Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "git.specialists-deny",
+      "roles": [
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "deny",
+      "operations": [
+        "stage",
+        "commit",
+        "push",
+        "merge",
+        "rebase",
+        "reset",
+        "branch-create",
+        "branch-switch",
+        "worktree-create",
+        "worktree-remove"
+      ],
+      "evidence": [
+        "role-contract"
+      ],
+      "authority": "orchestrator",
+      "text": "Specialist roles MUST NOT change Git state: no stage, commit, push, merge, rebase, reset, branch creation/switching or worktree creation/removal, during normal implementation or recovery. Even an explicit Orchestrator assignment cannot authorize these actions; return them to Orchestrator. Read-only Git inspection remains allowed within the assigned scope.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "hook"
+      }
+    },
+    {
+      "id": "git.orchestrator-accept-commit",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "allow",
+      "operations": [
+        "accept",
+        "stage",
+        "commit"
+      ],
+      "evidence": [
+        "acceptance-criteria",
+        "required-checks",
+        "findings-disposition"
+      ],
+      "authority": "orchestrator",
+      "text": "Only Orchestrator accepts work and executes Git mutations. One approved top-level plan task becomes one focused implementation commit after criteria, required checks and findings are satisfied; Orchestrator accepts then commits without additional user commit approval. Reports, passing checks and Reviewer opinions do not replace acceptance. Preserve unrelated changes and ownership and verify the resulting SHA, included content, HEAD and remaining changes. Existing small-task direct and plan-omission paths are unchanged.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "external.explicit-user-authority",
+      "roles": [
+        "orchestrator",
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "require",
+      "operations": [
+        "push",
+        "merge",
+        "deploy",
+        "publish",
+        "external-message"
+      ],
+      "evidence": [
+        "explicit-user-authorization-for-action"
+      ],
+      "authority": "user",
+      "text": "Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.orchestrator-boundary",
+      "roles": [
+        "orchestrator"
+      ],
+      "effect": "require",
+      "operations": [
+        "coordinate",
+        "accept"
+      ],
+      "evidence": [
+        "role-ownership"
+      ],
+      "authority": "orchestrator",
+      "text": "Assign design/spec/plan/brainstorming drafts ONLY to Planner and implementation/configuration/test edits to Coder. Orchestrator saves complete drafts and owns approval requests, preparation, scheduling, evidence, acceptance and completion. Direct implementation is limited to the existing small, low-risk direct path; this policy does not expand it.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.scouter-read-only",
+      "roles": [
+        "scouter"
+      ],
+      "effect": "allow",
+      "operations": [
+        "static-research"
+      ],
+      "evidence": [
+        "sources",
+        "limits"
+      ],
+      "authority": "orchestrator",
+      "text": "Research assigned static sources and report findings, evidence and limits. Do not edit files, install, execute checks, prepare execution targets, inspect live operational state, change external state or decide design, verification, review or acceptance.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.planner-draft-only",
+      "roles": [
+        "planner"
+      ],
+      "effect": "allow",
+      "operations": [
+        "draft-response"
+      ],
+      "evidence": [
+        "prepared-target-evidence",
+        "approved-spec-before-dependent-plan"
+      ],
+      "authority": "orchestrator",
+      "text": "Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.coder-implementation",
+      "roles": [
+        "coder"
+      ],
+      "effect": "allow",
+      "operations": [
+        "assigned-edit",
+        "focused-check"
+      ],
+      "evidence": [
+        "approved-brief",
+        "tdd-or-recorded-exception"
+      ],
+      "authority": "orchestrator",
+      "text": "Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.qa-verification",
+      "roles": [
+        "qa"
+      ],
+      "effect": "allow",
+      "operations": [
+        "approved-check",
+        "scoped-temporary-artifact"
+      ],
+      "evidence": [
+        "commands",
+        "observations",
+        "criterion-evidence"
+      ],
+      "authority": "orchestrator",
+      "text": "Run approved checks and report commands, observations, reproduction, evidence and limits. Create only essential temporary data/logs/reports in the brief-authorized location and lifetime. Do not edit product source, tests, fixtures or configuration to pass checks, deploy or accept work. Persistent product-state checks require explicit scope and cleanup ownership. Return failures for Coder correction and required QA recheck.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "role.reviewer-independent",
+      "roles": [
+        "reviewer"
+      ],
+      "effect": "allow",
+      "operations": [
+        "static-review"
+      ],
+      "evidence": [
+        "assigned-final-diff",
+        "relevant-qa-evidence"
+      ],
+      "authority": "orchestrator",
+      "text": "Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "review.significant-no-plan",
+      "roles": [
+        "orchestrator",
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "require",
+      "operations": [
+        "no-plan-final-review"
+      ],
+      "evidence": [
+        "required-qa",
+        "qa-rechecks"
+      ],
+      "authority": "orchestrator",
+      "text": "For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "review.significant-plan",
+      "roles": [
+        "orchestrator",
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "require",
+      "operations": [
+        "plan-final-review"
+      ],
+      "evidence": [
+        "all-tasks-accepted",
+        "required-qa"
+      ],
+      "authority": "orchestrator",
+      "text": "For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    },
+    {
+      "id": "review.final-plan-recheck",
+      "roles": [
+        "orchestrator",
+        "scouter",
+        "planner",
+        "coder",
+        "qa",
+        "reviewer"
+      ],
+      "effect": "require",
+      "operations": [
+        "plan-finding-recheck"
+      ],
+      "evidence": [
+        "reviewer-findings"
+      ],
+      "authority": "orchestrator",
+      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "controls": {
+        "codex": "prompt",
+        "claude": "prompt"
+      }
+    }
+  ],
+  "platforms": {
+    "codex": {
+      "level": "prompt",
+      "notice": "Role restrictions are prompt-level contracts, not a filesystem sandbox. No documented role-specific Git hook or generic per-agent tool allowlist is assumed. Existing shell capabilities are retained because static read access after shell reduction has not been verified; Coder and QA need shell for approved checks."
+    },
+    "claude": {
+      "level": "capability",
+      "notice": "Existing per-role tool allowlists reduce available tools; Bash and role contracts are not a filesystem sandbox. A role-scoped Git guard is a separate integration and is not supplied by these policy sections alone."
+    }
+  },
+  "review": {
+    "noPlan": [
+      "coder",
+      "qa",
+      "reviewer",
+      "orchestrator-accept"
+    ],
+    "planTask": [
+      "coder",
+      "fresh-qa",
+      "orchestrator-accept",
+      "orchestrator-commit"
+    ],
+    "planFinal": [
+      "required-qa",
+      "reviewer"
+    ],
+    "planFinding": [
+      "coder",
+      "reviewer"
+    ]
+  },
+  "git": {
+    "schemaVersion": 1,
+    "globalValueOptions": [
+      "-C",
+      "--git-dir",
+      "--work-tree"
+    ],
+    "globalFlags": [
+      "--no-pager",
+      "-P",
+      "--literal-pathspecs"
+    ],
+    "commands": {
+      "status": {
+        "flags": [
+          "--short",
+          "-s",
+          "--branch",
+          "-b",
+          "--porcelain",
+          "--porcelain=v1",
+          "--porcelain=v2",
+          "--untracked-files=no",
+          "--untracked-files=all"
+        ],
+        "values": [],
+        "positionals": "any"
+      },
+      "diff": {
+        "flags": [
+          "--stat",
+          "--numstat",
+          "--shortstat",
+          "--name-only",
+          "--name-status",
+          "--oneline",
+          "--no-color",
+          "--color=never",
+          "--no-ext-diff",
+          "--no-textconv",
+          "--raw",
+          "--patch",
+          "-p",
+          "--summary",
+          "--exit-code",
+          "--quiet",
+          "--check",
+          "--cached",
+          "--staged",
+          "--relative",
+          "--no-index"
+        ],
+        "values": [],
+        "positionals": "any"
+      },
+      "log": {
+        "flags": [
+          "--stat",
+          "--numstat",
+          "--shortstat",
+          "--name-only",
+          "--name-status",
+          "--oneline",
+          "--no-color",
+          "--color=never",
+          "--no-ext-diff",
+          "--no-textconv",
+          "--raw",
+          "--patch",
+          "-p",
+          "--summary",
+          "--exit-code",
+          "--quiet",
+          "-<count>",
+          "--all",
+          "--decorate",
+          "--no-decorate",
+          "--graph"
+        ],
+        "values": [
+          "-n",
+          "--max-count",
+          "--format",
+          "--pretty"
+        ],
+        "positionals": "any"
+      },
+      "show": {
+        "flags": [
+          "--stat",
+          "--numstat",
+          "--shortstat",
+          "--name-only",
+          "--name-status",
+          "--oneline",
+          "--no-color",
+          "--color=never",
+          "--no-ext-diff",
+          "--no-textconv",
+          "--raw",
+          "--patch",
+          "-p",
+          "--summary",
+          "--exit-code",
+          "--quiet",
+          "--no-patch",
+          "-s"
+        ],
+        "values": [
+          "--format",
+          "--pretty"
+        ],
+        "positionals": "any"
+      },
+      "rev-parse": {
+        "flags": [
+          "--show-toplevel",
+          "--git-common-dir",
+          "--absolute-git-dir",
+          "--git-dir",
+          "--verify",
+          "--short",
+          "--is-inside-work-tree",
+          "--abbrev-ref",
+          "--path-format=absolute"
+        ],
+        "values": [],
+        "positionals": "any"
+      },
+      "ls-files": {
+        "flags": [
+          "--stage",
+          "-s",
+          "--cached",
+          "--others",
+          "--exclude-standard",
+          "--deleted",
+          "--modified"
+        ],
+        "values": [],
+        "positionals": "any"
+      },
+      "ls-tree": {
+        "flags": [
+          "-r",
+          "--name-only",
+          "-l"
+        ],
+        "values": [],
+        "positionals": "any"
+      },
+      "branch": {
+        "flags": [
+          "--list",
+          "--all",
+          "-a",
+          "--remotes",
+          "-r",
+          "--show-current",
+          "-v",
+          "-vv"
+        ],
+        "values": [],
+        "positionals": "list"
+      },
+      "config": {
+        "flags": [
+          "--get",
+          "--get-all",
+          "--get-regexp",
+          "--list",
+          "-l",
+          "--show-origin",
+          "--show-scope",
+          "--local",
+          "--global",
+          "--system"
+        ],
+        "values": [],
+        "positionals": "query"
+      },
+      "worktree list": {
+        "flags": [
+          "--porcelain",
+          "-z",
+          "-v"
+        ],
+        "values": [],
+        "positionals": "none"
+      },
+      "remote": {
+        "flags": [
+          "-v",
+          "--verbose"
+        ],
+        "values": [],
+        "positionals": "none"
+      },
+      "remote get-url": {
+        "flags": [
+          "--all",
+          "--push"
+        ],
+        "values": [],
+        "positionals": "any"
+      }
+    }
+  }
+}