forge-workflow 0.1.0-beta.2 → 0.1.0-beta.4

package/lib/core/runtime-graph.js

@@ -161,6 +161,55 @@ const PLAN_SUBSKILL_DEFINITIONS = [
 
 const PLAN_SUBSKILL_IDS = new Set(PLAN_SUBSKILL_DEFINITIONS.map(definition => definition.id));
 
+// The `smith` orchestrator composes the stage skills end-to-end. Its sub-skills
+// are the stage skill NAMES (each a real `skills/<name>/` dir), unlike plan's
+// fine-grained internal planning phases. Both resolve through the ONE generic
+// registry below (keyed by owning skill), so composition is no longer hardcoded
+// to plan. See docs/work kernel-native-skills composition epic (a0776e61) +
+// smith-orchestrator (7da81cbd).
+const SMITH_SUBSKILL_DEFINITIONS = ['plan', 'dev', 'validate', 'ship', 'review', 'verify']
+  .map(stage => ({ id: stage, label: `${stage} stage`, owner: 'smith' }));
+
+// Skills that `plan` COMPOSES at the whole-skill level (its SKILL.md `subskills:`
+// frontmatter), distinct from the fine-grained plan.* planning micro-phases in
+// PLAN_SUBSKILL_DEFINITIONS. A composed whole-skill is an advertised sub-skill
+// that must both VALIDATE and RESOLVE, but it is NOT a partialInvocation
+// micro-phase (it maps to no runtime-graph action), so it lives OUTSIDE
+// PLAN_SUBSKILL_IDS (which governs planning.template.only/skip).
+const PLAN_COMPOSED_SUBSKILLS = ['research'];
+const PLAN_COMPOSED_SUBSKILL_DEFINITIONS = PLAN_COMPOSED_SUBSKILLS.map(id => ({
+  id,
+  label: `${id.charAt(0).toUpperCase()}${id.slice(1)} (composed skill)`,
+  kind: 'composed-skill',
+  owner: 'plan',
+}));
+
+// Generic per-skill sub-skill registry, keyed by owning skill id. Generalizes
+// plan's previously hardcoded PLAN_SUBSKILL_DEFINITIONS / validatePlanSubSkillList
+// so any composing skill (plan, smith, ...) declares its sub-skill set through a
+// single mechanism. This registry is the SINGLE source for BOTH validation (ids)
+// and resolution (definitions), so getSubSkillDefinitions and validateSubSkillList
+// can never disagree. plan's set = its planning micro-phases + composed whole-skills.
+const SUBSKILL_REGISTRY = {
+  plan: [...PLAN_SUBSKILL_DEFINITIONS, ...PLAN_COMPOSED_SUBSKILL_DEFINITIONS],
+  smith: SMITH_SUBSKILL_DEFINITIONS,
+};
+
+// Validation id sets DERIVED from the registry definitions — guarantees
+// validate-vs-resolve parity for every owner (a subskill that validates also
+// resolves, and vice versa).
+const SUBSKILL_IDS_BY_OWNER = Object.fromEntries(
+  Object.entries(SUBSKILL_REGISTRY).map(([owner, defs]) => [owner, new Set(defs.map(d => d.id))])
+);
+
+function getSubSkillDefinitions(owner) {
+  return SUBSKILL_REGISTRY[owner] ? [...SUBSKILL_REGISTRY[owner]] : [];
+}
+
+function getSubSkillIds(owner) {
+  return new Set(SUBSKILL_IDS_BY_OWNER[owner] || []);
+}
+
 function planningSubSkillFromDefinition(definition) {
   return PlanningSubSkill({
     id: definition.id,
@@ -412,6 +461,27 @@ const RESOLVED_RUNTIME_GRAPH = {
       label: 'Issue write verification (check-after-write)',
       requires: [],
     }),
+    // Grounding gates (epic 6ef96e92, design docs/work/2026-07-16-grounding-
+    // enforcement/design.md) — the first gates that DENY (fd4c03b3's first real
+    // payment). gate.read_first: acting on an issue requires having read it —
+    // consulted fail-closed at the `forge claim` boundary against a
+    // `context.loaded` kernel event (lib/grounding/context-events.js), remedy
+    // `forge recap <id>`. gate.cite: shipped artifacts must cite their sources —
+    // registered here (togglable) but its scanner lands in P3; it denies nothing
+    // yet. Both phase-less, default-ON, UNLOCKED, same toggle surface as
+    // gate.issue_verify (`forge gate disable gate.read_first`). Master switch is
+    // the unlocked rail.grounding below. `requires: []` — the context.loaded
+    // event (not evidence) is the exit condition.
+    Gate({
+      id: 'gate.read_first',
+      label: 'Read the issue before acting on it',
+      requires: [],
+    }),
+    Gate({
+      id: 'gate.cite',
+      label: 'Cite sources in shipped artifacts',
+      requires: [],
+    }),
   ],
   evidence: [
     Evidence({
@@ -446,12 +516,18 @@ const RESOLVED_RUNTIME_GRAPH = {
   // may opt out via `forge gate disable rail.kernel_tracking`, consumed by the
   // resolver's rail-aware gate loop over workflow.gates.<id>.enabled).
   rails: [
-    { key: 'tdd_intent', label: 'TDD intent evidence', description: 'Source changes require test intent and TDD evidence.' },
+    { key: 'tdd_intent', label: 'TDD intent evidence', description: 'Source changes require test intent and TDD evidence. Strong default (ON), but not a hard floor — disable with `forge gate disable rail.tdd_intent`.', locked: false },
     { key: 'secret_scan', label: 'Secret scan', description: 'Validation must not knowingly ship secrets.' },
     { key: 'branch_protection', label: 'Branch protection', description: 'Ship through reviewed branches instead of direct protected-branch edits.' },
     { key: 'signed_commits', label: 'Signed commits', description: 'Preserve commit provenance requirements where configured.' },
     { key: 'schema_integrity', label: 'Schema integrity', description: 'Keep runtime graph and config schemas internally consistent.' },
     { key: 'kernel_tracking', label: 'Kernel issue tracking', description: 'Every issue, idea, bug, and decision discussed is filed to the Forge Kernel.', locked: false },
+    { key: 'auto_shepherd', label: 'Auto-start PR shepherd watch', description: 'On `forge ship` success, auto-start the detached, self-stopping `forge shepherd watch <pr>` monitor so a shipped PR is tended without a manual trigger. Default-ON, UNLOCKED — opt out with `forge gate disable rail.auto_shepherd`.', locked: false },
+    // grounding — the one-switch master toggle over gate.read_first + gate.cite.
+    // UNLOCKED, default-ON (like kernel_tracking): a maintainer may opt out via
+    // `forge gate disable rail.grounding`, which the read_first consult treats as
+    // "allow, logged". Ingrains "read the documented source before acting; cite it".
+    { key: 'grounding', label: 'Documented-grounding enforcement', description: 'Read the issue before acting on it; cite sources in shipped artifacts.', locked: false },
   ].map(def => Rail({ id: `rail.${def.key}`, ...def })),
   adapters: [
     Adapter({
@@ -605,14 +681,18 @@ function applyRailConfig(graph, config, errors) {
     if (!enabled.valid) {
       continue;
     }
-    if (enabled.value === false) {
+    if (enabled.value === false && rail.locked === true) {
+      // Locked L1 rails remain a non-negotiable floor; only unlocked rails
+      // (e.g. tdd_intent, kernel_tracking) may be disabled via config.
       errors.push({
         code: 'LOCKED_L1_RAIL_DISABLED',
         message: `Cannot disable locked L1 rail '${key}'.`,
       });
       continue;
     }
-    if (options && Object.keys(options).length > 0) {
+    if (enabled.present) {
+      markConfigured(rail, { enabled: enabled.value });
+    } else if (options && Object.keys(options).length > 0) {
       rail.configSource = CONFIG_SOURCE;
     }
   }
@@ -746,31 +826,51 @@ function assertStringList(value, errors, code, message) {
   return valid;
 }
 
-function validatePlanSubSkillList(value, errors, path) {
-  if (!assertStringList(
-    value,
-    errors,
-    'INVALID_PLAN_SUBSKILL_LIST',
-    `${path} must be a list of planning sub-skill IDs.`
-  )) {
+function subSkillCodesForOwner(owner) {
+  return owner === 'plan'
+    ? { listCode: 'INVALID_PLAN_SUBSKILL_LIST', unknownCode: 'UNKNOWN_PLAN_SUBSKILL', noun: 'planning sub-skill' }
+    : { listCode: 'INVALID_SUBSKILL_LIST', unknownCode: 'UNKNOWN_SUBSKILL', noun: `${owner} sub-skill` };
+}
+
+// Core list validator against an explicit known-id Set. The two callers below
+// deliberately pass DIFFERENT id sets so the two contracts never leak into each
+// other (see validatePlanSubSkillList).
+function validateAgainstKnownIds(knownIds, codes, value, errors, path) {
+  const { listCode, unknownCode, noun } = codes;
+  if (!assertStringList(value, errors, listCode, `${path} must be a list of ${noun} IDs.`)) {
     return undefined;
   }
 
   const normalized = value.map(item => item.trim());
   let hasUnknown = false;
   for (const id of normalized) {
-    if (!PLAN_SUBSKILL_IDS.has(id)) {
+    if (!knownIds.has(id)) {
       hasUnknown = true;
       errors.push({
-        code: 'UNKNOWN_PLAN_SUBSKILL',
-        message: `Unknown planning sub-skill '${id}' in ${CONFIG_SOURCE}.`,
+        code: unknownCode,
+        message: `Unknown ${noun} '${id}' in ${CONFIG_SOURCE}.`,
       });
     }
   }
-  if (hasUnknown) {
-    return undefined;
-  }
-  return normalized;
+  return hasUnknown ? undefined : normalized;
+}
+
+// Generic COMPOSITION validator, keyed by owning skill — validates a skill's
+// ADVERTISED (SKILL.md frontmatter) subskills. For `plan` the known-id set is the
+// composition union (plan.* micro-phases + composed whole-skills like research).
+function validateSubSkillList(owner, value, errors, path) {
+  const knownIds = SUBSKILL_IDS_BY_OWNER[owner] || new Set();
+  return validateAgainstKnownIds(knownIds, subSkillCodesForOwner(owner), value, errors, path);
+}
+
+// partialInvocation validator (.forge/config.yaml planning.template.only/skip).
+// SEPARATE contract from composition: it MUST accept ONLY the fine-grained plan.*
+// MICRO-PHASE ids (PLAN_SUBSKILL_IDS), never composed whole-skill ids like
+// `research` — a composed skill maps to no runtime-graph action, so `only:
+// [research]` would be silent dead config. Validates against PLAN_SUBSKILL_IDS,
+// NOT the composition union, so it fails closed on composed ids.
+function validatePlanSubSkillList(value, errors, path) {
+  return validateAgainstKnownIds(PLAN_SUBSKILL_IDS, subSkillCodesForOwner('plan'), value, errors, path);
 }
 
 function applyPlanningMode(template, nextTemplate, errors) {
@@ -937,6 +1037,11 @@ module.exports = {
   PlanningSubSkill,
   Role,
   ROLE_IDS,
+  SUBSKILL_REGISTRY,
+  getSubSkillDefinitions,
+  getSubSkillIds,
+  validateSubSkillList,
+  validatePlanSubSkillList,
   loadRuntimeGraphConfig,
   lintRuntimeGraphConfig,
   resolveRuntimeGraph,