@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/core/registry/contracts.json

@@ -1,5 +1,11 @@
 {
   "version": 1,
+  "agentSkillsSpec": {
+    "skillFields": ["name", "description", "license", "compatibility", "metadata", "allowed-tools"],
+    "source": "https://agentskills.io/specification",
+    "verifiedOn": "2026-10-27",
+    "note": "The Agent Skills standard's SKILL.md keys; metadata is a map of string keys to string values. A projected SKILL.md keeps these and its harness's skillFields at the top level and carries every other key under metadata (src/adapters/copy-tree.js, skill-frontmatter-<harness>; G22). unknownSkillFields records what the vendor page says the harness does with a key it does not define."
+  },
   "contracts": [
     {
       "harness": "claude",
@@ -22,8 +28,14 @@
         "background",
         "hooks",
         "paths",
-        "shell"
+        "shell",
+        "metadata",
+        "license",
+        "compatibility"
       ],
+      "skillFieldsSource": "https://code.claude.com/docs/en/skills",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "ignored",
       "agentFields": [
         "name",
         "description",
@@ -40,7 +52,10 @@
         "effort",
         "isolation",
         "color",
-        "initialPrompt"
+        "initialPrompt",
+        "autoCompactWindow",
+        "omitClaudeMd",
+        "experimental"
       ],
       "hookEvents": [
         "SessionStart",
@@ -73,7 +88,9 @@
         "Notification",
         "MessageDisplay",
         "Elicitation",
-        "ElicitationResult"
+        "ElicitationResult",
+        "PreModelSwitch",
+        "PostModelSwitch"
       ],
       "evidence": [
         "https://code.claude.com/docs/en/skills",
@@ -85,7 +102,11 @@
     {
       "harness": "codex",
       "completeness": "lower-bound",
-      "note": "Frontmatter field lists are deliberately absent: shared skills and agent specs are byte-identical across harnesses, so a per-harness list could only restate a subset of claude's and would change no guard outcome \u2014 an inert declaration of exactly the kind these guards exist to remove. hookEvents IS per-harness and lists the events DoFlow actually wires; widen it only with an added evidence URL.",
+      "note": "skillFields lists the SKILL.md keys Codex documents; the projected SKILL.md keeps only those and the Agent Skills spec keys at the top level (row 131). agentFields is deliberately absent: shared agent specs are byte-identical across harnesses, so a per-harness list could only restate a subset of claude's and would change no guard outcome \u2014 an inert declaration of exactly the kind these guards exist to remove. hookEvents IS per-harness and lists the events DoFlow actually wires; widen it only with an added evidence URL.",
+      "skillFields": ["name", "description"],
+      "skillFieldsSource": "https://learn.chatgpt.com/docs/build-skills",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "not-documented",
       "hookEvents": [
         "SessionStart",
         "SessionEnd",
@@ -103,27 +124,14 @@
         "https://learn.chatgpt.com/docs/agent-configuration/subagents"
       ]
     },
-    {
-      "harness": "gemini",
-      "completeness": "lower-bound",
-      "note": "Frontmatter field lists are deliberately absent: shared skills and agent specs are byte-identical across harnesses, so a per-harness list could only restate a subset of claude's and would change no guard outcome \u2014 an inert declaration of exactly the kind these guards exist to remove. hookEvents IS per-harness and lists the events DoFlow actually wires; widen it only with an added evidence URL.",
-      "hookEvents": [
-        "SessionStart",
-        "SessionEnd",
-        "BeforeTool",
-        "AfterTool",
-        "PreCompress"
-      ],
-      "evidence": [
-        "https://geminicli.com/docs/cli/skills/",
-        "https://geminicli.com/docs/hooks/",
-        "https://geminicli.com/docs/cli/settings/"
-      ]
-    },
     {
       "harness": "opencode",
       "completeness": "lower-bound",
       "note": "hookEvents is empty by design, not by omission: OpenCode implements lifecycle handlers as JavaScript/TypeScript plugin modules exporting named hooks such as tool.execute.before, while DoFlow ships shell scripts invoked by a command string. The events exist natively and are recorded under capabilities.hooks.events with status \"different\"; wiring them would mean shipping executable code into the user's agent, which is a distribution decision rather than a projection. Widen this list only alongside that decision and an added evidence URL. See https://opencode.ai/docs/plugins.",
+      "skillFields": ["name", "description", "license", "compatibility", "metadata"],
+      "skillFieldsSource": "https://opencode.ai/docs/skills",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "ignored",
       "hookEvents": [],
       "evidence": [
         "https://opencode.ai/docs/plugins",
@@ -135,6 +143,10 @@
       "harness": "pi",
       "completeness": "lower-bound",
       "note": "DoFlow installs a user- or project-scope extension that registers tool_call through pi.on() and invokes the shared lifecycle bridge. Project scope requires project trust. The handler can block before tools execute; tool_execution_start remains observation-only. See https://pi.dev/docs/latest/extensions.",
+      "skillFields": ["name", "description", "license", "compatibility", "metadata", "allowed-tools", "disable-model-invocation"],
+      "skillFieldsSource": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/docs/skills.md",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "warned",
       "hookEvents": ["tool_call"],
       "evidence": [
         "https://pi.dev/docs/latest/extensions",
@@ -145,8 +157,18 @@
     {
       "harness": "copilot",
       "completeness": "lower-bound",
-      "note": "Copilot CLI now documents a full hook surface (use-hooks / hooks-reference, 2026): .github/hooks/*.json and ~/.copilot/hooks/, shape {version:1,hooks:{camelCaseEvent:[entries]}}. DoFlow wires none of it: the shipped scripts are Claude-payload-coupled (tool names, .session_id/.transcript_path stdin fields, CLAUDE_* envs) and Copilot's payload schemas are unverified here. hookEvents stays empty until that verification lands; widen only alongside it and an added evidence URL.",
-      "hookEvents": [],
+      "note": "hookEvents lists the events DoFlow wires through .github/hooks/doflow.json, under the PascalCase names the lifecycle registry uses: SessionStart (native sessionStart), PreToolUse (preToolUse), Stop (agentStop), SubagentStart (subagentStart) and SubagentStop (subagentStop). Event surface, payloads and the deny shape were read from https://docs.github.com/en/copilot/reference/hooks-reference and checked against a live Copilot CLI 1.0.103 capture on 2026-10-27 (verified_on 2026-10-27); where they disagree the capture wins (toolArgs is a JSON object, or a raw string for apply_patch, not the documented JSON string). Widen only alongside an added evidence URL.",
+      "skillFields": ["name", "description", "license", "allowed-tools"],
+      "skillFieldsSource": "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "not-documented",
+      "hookEvents": [
+        "SessionStart",
+        "PreToolUse",
+        "Stop",
+        "SubagentStart",
+        "SubagentStop"
+      ],
       "evidence": [
         "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills",
         "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli",
@@ -157,32 +179,37 @@
     {
       "harness": "kiro",
       "completeness": "lower-bound",
-      "note": "hookEvents lists only the events DoFlow actually installs a doflow.json entry for (session-context on SessionStart, pre-implementation-gate, pre-bash-guard and mcp-tool-guard all on PreToolUse \u2014 hence PreToolUse appearing once, not twice \u2014 and stop-check on Stop), not the full set of trigger names Kiro's docs confirm (SessionStart, Stop, PreToolUse, PostToolUse, UserPromptSubmit, PreTaskExec, PostTaskExec, PostFileSave, PostFileCreate, PostFileDelete \u2014 see kiro.dev/docs/hooks/actions/). Widen this list only when DoFlow wires a hook to one of the unused confirmed events, alongside an added evidence URL.",
+      "note": "hookEvents lists only the events DoFlow actually installs a doflow.json entry for (session-context on SessionStart, pre-implementation-gate and mcp-tool-guard both on PreToolUse \u2014 hence PreToolUse appearing once, not twice \u2014 and stop-check on Stop), not the full set of trigger names Kiro's docs confirm (SessionStart, Stop, PreToolUse, PostToolUse, UserPromptSubmit, PreTaskExec, PostTaskExec, PostFileSave, PostFileCreate, PostFileDelete, plus SessionEnd on CLI V3 only \u2014 see kiro.dev/docs/hooks/types/). Widen this list only when DoFlow wires a hook to one of the unused confirmed events, alongside an added evidence URL.",
+      "skillFields": ["name", "description", "license", "compatibility", "metadata"],
+      "skillFieldsSource": "https://kiro.dev/docs/skills/",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "not-documented",
       "hookEvents": [
         "SessionStart",
         "PreToolUse",
         "Stop"
       ],
       "evidence": [
-        "https://kiro.dev/docs/steering/",
-        "https://kiro.dev/docs/mcp/configuration/",
         "https://kiro.dev/docs/hooks/",
-        "https://kiro.dev/docs/hooks/actions/"
+        "https://kiro.dev/docs/hooks/actions/",
+        "https://kiro.dev/docs/hooks/types/"
       ]
     },
     {
       "harness": "antigravity",
       "completeness": "lower-bound",
-      "note": "hookEvents lists what DoFlow wires; widen only with added evidence. Antigravity documents five hook events; DoFlow wires PreToolUse (pre-implementation gate) and Stop (stop check) today.",
+      "note": "hookEvents lists what DoFlow wires; widen only with added evidence. Antigravity documents six hook events (SessionStart added); DoFlow wires PreToolUse (pre-implementation gate) and Stop (stop check) today.",
+      "skillFields": ["name", "description"],
+      "skillFieldsSource": "https://www.antigravity.google/docs/skills",
+      "skillFieldsVerifiedOn": "2026-10-27",
+      "unknownSkillFields": "not-documented",
       "hookEvents": [
         "PreToolUse",
         "Stop"
       ],
       "evidence": [
-        "https://antigravity.google/docs/cli/gcli-migration",
         "https://antigravity.google/docs/hooks",
-        "https://antigravity.google/docs/cli/mcp",
-        "https://antigravity.google/docs/hooks/"
+        "https://antigravity.google/docs/mcp?tab=cli"
       ]
     }
   ]

package/core/registry/contribution-points.json

@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "trustPolicyVersion": 1,
+  "forbiddenFields": [
+    "enabled", "defaultEnabled", "trust", "trusted", "settings", "guards", "hooks", "floors", "invariants", "order",
+    "position", "replaces", "override", "familyProven", "crossFamily", "firstParty", "scripts", "install", "postinstall"
+  ],
+  "limits": { "files": 512, "bytes": 4194304, "fileBytes": 262144, "pathLength": 200 },
+  "points": [
+    { "id": "review-preset", "versions": [1], "tier": "inert", "status": "open", "entry": "file",
+      "validator": "review-preset-v1", "combine": "add-only", "consumer": "src/runtime/review/protocols.js",
+      "referencedBy": ["review.preset"], "slice": "A", "template": "package-templates/review-preset" },
+    { "id": "debate-preset", "versions": [1], "tier": "inert", "status": "open", "entry": "file",
+      "validator": "debate-preset-v1", "combine": "add-only", "consumer": "src/runtime/review/protocols.js",
+      "referencedBy": ["debate.preset"], "slice": "A", "template": "package-templates/debate-preset" },
+    { "id": "skill", "versions": [1], "tier": "instruction", "status": "open", "entry": "dir",
+      "validator": "skill-v1", "combine": "add-only", "consumer": "src/lifecycle/index.js",
+      "referencedBy": [], "slice": "C", "template": "package-templates/skill" },
+    { "id": "agent", "versions": [1], "tier": "instruction", "status": "open", "entry": "file",
+      "validator": "agent-v1", "combine": "add-only", "consumer": "src/lifecycle/index.js",
+      "referencedBy": [], "slice": "C", "template": "package-templates/agent" },
+    { "id": "worker", "versions": [1], "tier": "executable", "status": "open", "entry": "file",
+      "validator": "worker-v1", "combine": "add-only", "consumer": "src/runtime/worker/catalogue.js",
+      "referencedBy": ["workers.billing"], "slice": "D", "template": "package-templates/worker" },
+    { "id": "capability-provider", "versions": [1], "tier": "executable", "status": "open", "entry": "file",
+      "validator": "capability-provider-v1", "combine": "add-only", "consumer": "src/runtime/capability-router.js",
+      "referencedBy": [], "slice": "D", "template": "package-templates/capability-provider" },
+    { "id": "intake-category", "versions": [1], "tier": "inert", "status": "open", "entry": "file",
+      "validator": "intake-category-v1", "combine": "add-only", "consumer": "src/runtime/intake/taxonomy.js",
+      "referencedBy": [], "slice": "136", "template": "package-templates/intake-category" }
+  ],
+  "bundled": [
+    { "id": "doflow", "dir": "core/registry/packages/doflow", "contentDigest": "4684bab1385564aef5e65100c789605895f3597c7fc23f340afa55333d11377b" }
+  ]
+}

package/core/registry/gates.json

@@ -0,0 +1,32 @@
+{
+  "schema": 1,
+  "classes": {
+    "feature": {
+      "gate-0": { "autopilot": "approve", "predicates": ["markers-zero:requirement"] },
+      "gate-a": { "autopilot": "approve", "predicates": ["protected-paths", "plan-verification-absent", "plan-parses", "markers-zero:design", "markers-zero:plan", "needs-merged", "requires-reachable", "plan-within-write-set"] },
+      "gate-b": { "autopilot": "approve", "minSeats": 2, "predicates": ["protected-paths", "plan-verification-absent", "verify-pass-on-head", "findings-valid", "no-dropped-findings", "dispositions-backed", "blockers-zero"] }
+    },
+    "bug": { "gate-b": { "autopilot": "approve", "minSeats": 2, "predicates": ["protected-paths", "plan-verification-absent", "verify-pass-on-head", "findings-valid", "no-dropped-findings", "dispositions-backed", "blockers-zero"] } },
+    "refactor": { "gate-b": { "autopilot": "approve", "minSeats": 2, "predicates": ["protected-paths", "plan-verification-absent", "verify-pass-on-head", "findings-valid", "no-dropped-findings", "dispositions-backed", "blockers-zero"] } },
+    "review": {},
+    "research": {},
+    "documentation": { "gate-b": { "autopilot": "approve", "minSeats": 2, "predicates": ["protected-paths", "plan-verification-absent", "verify-pass-on-head", "findings-valid", "no-dropped-findings", "dispositions-backed", "blockers-zero"] } },
+    "dependency-change": {},
+    "operations": {},
+    "trivial-edit": { "gate-b": { "autopilot": "approve", "minSeats": 2, "predicates": ["protected-paths", "plan-verification-absent", "verify-pass-on-head", "findings-valid", "no-dropped-findings", "dispositions-backed", "blockers-zero"] } }
+  },
+  "protected": {
+    "paths": ["core/registry/gates.json", "src/runtime/roadmap/", "core/registry/verification.json", "src/runtime/workflow-orchestrator.js", "src/runtime/decision-register.js", "core/registry/settings.json", "core/harnesses/shared/hooks/policies/", ".github/workflows/"],
+    "guardDir": "test/guards/",
+    "packageJsonKeys": ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]
+  },
+  "loop": { "maxSteps": 200, "wip": 2 },
+  "merge": { "staleLockSeconds": 120, "extraTrailers": [] },
+  "denyReasons": [
+    "no-policy", "policy-invalid", "policy-override-widens", "policy-override-invalid", "policy-never", "class-unsupported", "row-unknown", "row-proposed", "seed-typed-status",
+    "unresolved-clarifications", "markers-open", "protected-path", "plan-unparsable", "need-unmerged", "prerequisite-no-source", "capability-unreachable", "write-set-exceeded",
+    "verify-missing", "verify-not-pass", "verify-flaky", "findings-missing", "findings-invalid", "review-stale-head", "seats-too-few", "finding-dropped", "refuted-without-evidence", "accepted-without-user-decision", "user-accepted-needs-person", "fixed-not-ancestor", "blockers-open",
+    "lease-held", "lease-lost", "stage-not-performed", "plan-exit-refused", "report-changed", "pause-not-machine", "facts-unreadable", "autopilot-disabled",
+    "git-too-old", "merge-conflict", "develop-wrong-branch", "develop-dirty", "ff-running", "develop-moved", "head-moved", "no-develop-worktree", "plan-changed", "needs-person-tty", "needs-person-confirm"
+  ]
+}

package/core/registry/guidance-caps.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "description": "Vendor-documented size caps on always-loaded guidance, per harness. scope per-file-after-includes caps each projected always-on file after its includes are expanded; combined-chain caps everything a harness loads at startup together. cap_bytes is null when the vendor documents no byte cap; source_url is then the page checked. Never estimate a number. Read by test/guards/guidance-caps.test.ts (G74). agent_description_caps (row 131) is the same record for the combined name and description text of the shared agent specs, in tokens estimated at 4 characters each; agent_description_ratchet is a growth ceiling, not a vendor cap, that applies where no vendor documents one. Read by test/guards/skill-structure.test.ts (G75).",
+  "caps": [
+    {"harness": "claude", "cap_bytes": 4194304, "scope": "per-file-after-includes", "source_url": "https://code.claude.com/docs/en/memory", "verified_on": "2026-10-27",
+     "note": "4 MiB per CLAUDE.md file loaded at launch; a larger file is skipped entirely. The page's 200-line target is advice, not a cap."},
+    {"harness": "codex", "cap_bytes": 32768, "scope": "combined-chain", "source_url": "https://learn.chatgpt.com/docs/agent-configuration/agents-md", "verified_on": "2026-10-27",
+     "note": "project_doc_max_bytes, 32 KiB by default: Codex stops adding AGENTS.md files once the combined size reaches it."},
+    {"harness": "opencode", "cap_bytes": null, "scope": "combined-chain", "source_url": "https://opencode.ai/docs/rules", "verified_on": "2026-10-27",
+     "note": "No size cap documented."},
+    {"harness": "pi", "cap_bytes": null, "scope": "combined-chain", "source_url": "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/configuration.md", "verified_on": "2026-10-27",
+     "note": "No cap documented; the context-file loader reads each file whole."},
+    {"harness": "copilot", "cap_bytes": null, "scope": "per-file-after-includes", "source_url": "https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions", "verified_on": "2026-10-27",
+     "note": "No cap documented for the CLI. A 4,000-character limit for code review only is cited secondhand and is not in the current docs."},
+    {"harness": "kiro", "cap_bytes": null, "scope": "per-file-after-includes", "source_url": "https://kiro.dev/docs/steering/", "verified_on": "2026-10-27",
+     "note": "No size cap documented for steering files."},
+    {"harness": "antigravity", "cap_bytes": 24000, "scope": "per-file-after-includes", "source_url": "https://antigravity.google/docs/rules", "verified_on": "2026-10-27",
+     "note": "Antigravity truncates any single rule file over 24,000 bytes after expanding @[label](path) includes."},
+    {"harness": "antigravity", "cap_bytes": null, "scope": "combined-chain", "source_url": "https://antigravity.google/docs/rules", "verified_on": "2026-10-27",
+     "note": "All active global and always_on rules share a 20,000-token budget; over it the largest are demoted to pointers. Tokens, not bytes, so no byte cap is recorded."}
+  ],
+  "agent_description_caps": [
+    {"harness": "claude", "cap_tokens": 15000, "source_url": "https://code.claude.com/docs/en/sub-agents", "verified_on": "2026-10-27",
+     "note": "When the combined descriptions of the subagents, built-in ones excepted, pass 15,000 tokens, Claude Code warns at startup and still loads every subagent. Each agent counts its name plus its description."},
+    {"harness": "codex", "cap_tokens": null, "source_url": "https://learn.chatgpt.com/docs/agent-configuration/subagents", "verified_on": "2026-10-27",
+     "note": "No description cap documented; the only cap is agents.max_concurrent_threads_per_session, a thread count."},
+    {"harness": "opencode", "cap_tokens": null, "source_url": "https://opencode.ai/docs/agents", "verified_on": "2026-10-27",
+     "note": "No cap documented; the page asks for a brief description."},
+    {"harness": "pi", "cap_tokens": null, "source_url": "https://github.com/earendil-works/pi", "verified_on": "2026-10-27",
+     "note": "Pi has no subagent surface (its README says it skips sub-agents), so nothing lists agent descriptions."},
+    {"harness": "copilot", "cap_tokens": null, "source_url": "https://docs.github.com/en/copilot/reference/custom-agents-configuration", "verified_on": "2026-10-27",
+     "note": "No description cap documented; the agent prompt body is capped at 30,000 characters."},
+    {"harness": "kiro", "cap_tokens": null, "source_url": "https://kiro.dev/docs/custom-agents/configuration-reference/", "verified_on": "2026-10-27",
+     "note": "No description cap documented."},
+    {"harness": "antigravity", "cap_tokens": null, "source_url": "https://antigravity.google/docs/subagents", "verified_on": "2026-10-27",
+     "note": "No description cap documented."}
+  ],
+  "agent_description_ratchet": {"chars": 1040, "measured_on": "2026-10-27",
+    "note": "RATCHET, NOT A VENDOR CAP. The combined name and description characters of core/shared/agent-specs/*.md, measured at row 131. It holds the harnesses whose vendor documents no cap to the current size: raise it in its own commit with the new measurement when an added or longer description is deliberate."}
+}