@harness-forge/cli 1.1.1 → 1.2.1

package/manifests/catalog/package-surface.json

@@ -48,6 +48,7 @@
     ".agents/skills/powershell-engineering/SKILL.md",
     ".agents/skills/javascript-engineering/SKILL.md",
     ".agents/skills/cloud-architect/SKILL.md",
+    ".agents/skills/recursive-structured-analysis/SKILL.md",
     "docs/catalog/language-packs.md",
     "docs/catalog/framework-packs.md",
     "docs/templates/authoring.md",
@@ -74,6 +75,7 @@
     "skills/powershell-engineering/SKILL.md",
     "skills/javascript-engineering",
     "skills/cloud-architect",
+    "skills/recursive-structured-analysis/SKILL.md",
     "skills/repo-onboarding/SKILL.md",
     "skills/documentation-lookup/SKILL.md",
     "skills/security-scan/SKILL.md",
@@ -162,6 +164,10 @@
     "schemas/runtime/working-memory.schema.json",
     "schemas/runtime/recursive-session.schema.json",
     "schemas/runtime/recursive-budget.schema.json",
+    "schemas/runtime/recursive-execution-policy.schema.json",
+    "schemas/runtime/recursive-language-capabilities.schema.json",
+    "schemas/runtime/recursive-run-result.schema.json",
+    "schemas/runtime/recursive-run-meta.schema.json",
     "schemas/runtime/recursive-trace-event.schema.json",
     "schemas/runtime/recursive-session-summary.schema.json",
     "schemas/runtime/recursive-adr-candidate.schema.json",
@@ -376,6 +382,7 @@
         ".agents/skills/powershell-engineering/SKILL.md",
         ".agents/skills/javascript-engineering/SKILL.md",
         ".agents/skills/cloud-architect/SKILL.md",
+        ".agents/skills/recursive-structured-analysis/SKILL.md",
         "targets/codex/adapter.json",
         "targets/codex/runtime/.codex",
         "scripts/codex/apply-home-config.mjs",
@@ -401,6 +408,7 @@
         ".agents/skills/powershell-engineering/SKILL.md",
         ".agents/skills/javascript-engineering/SKILL.md",
         ".agents/skills/cloud-architect/SKILL.md",
+        ".agents/skills/recursive-structured-analysis/SKILL.md",
         "targets/claude-code/adapter.json",
         "targets/claude-code/runtime/.claude",
         "hooks"

package/manifests/targets/core.json

@@ -30,7 +30,8 @@
       "supportLevel": "full",
       "supportNotes": [
         "Codex is a first-class target for install guidance, repo intelligence, maintenance commands, and flow recovery.",
-        "Hook authoring ships, but native hook execution remains documentation-driven because Codex does not expose the same runtime hook model as Claude Code."
+        "Hook authoring ships, but native hook execution remains documentation-driven because Codex does not expose the same runtime hook model as Claude Code.",
+        "Codex installs also promote recursive structured-analysis discovery through AGENTS.md, the command catalog, and the shared runtime capability map."
       ]
     },
     {
@@ -63,7 +64,8 @@
       "supportLevel": "full",
       "supportNotes": [
         "Claude Code is a first-class target for packaged skills, hooks, repo intelligence, maintenance commands, and flow recovery.",
-        "Claude installs keep both CLAUDE.md and AGENTS.md available so Claude-native and cross-agent entrypoints stay discoverable."
+        "Claude installs keep both CLAUDE.md and AGENTS.md available so Claude-native and cross-agent entrypoints stay discoverable.",
+        "Claude installs also promote recursive structured-analysis discovery through shared runtime capability surfaces instead of hiding it behind target-only wording."
       ]
     },
     {
@@ -91,7 +93,8 @@
       "supportLevel": "partial",
       "supportNotes": [
         "Cursor can consume published docs, manifests, and recommendation output.",
-        "No first-class runtime mapping, hook execution, or flow-state recovery is shipped for Cursor yet."
+        "No first-class runtime mapping, hook execution, or flow-state recovery is shipped for Cursor yet.",
+        "Cursor still receives translated recursive structured-analysis promotion through the shared runtime capability map and recursive session artifacts."
       ]
     },
     {
@@ -119,7 +122,8 @@
       "supportLevel": "partial",
       "supportNotes": [
         "OpenCode can consume published docs, manifests, and recommendation output.",
-        "No first-class runtime mapping, hook execution, or flow-state recovery is shipped for OpenCode yet."
+        "No first-class runtime mapping, hook execution, or flow-state recovery is shipped for OpenCode yet.",
+        "OpenCode still receives translated recursive structured-analysis promotion through the shared runtime capability map and recursive session artifacts."
       ]
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-forge/cli",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Harness Forge: modular agentic AI workspace installer, catalog, and workflow runtime.",
   "type": "module",
   "bin": {

package/schemas/runtime/recursive-execution-policy.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness-forge.dev/schemas/runtime/recursive-execution-policy.schema.json",
+  "title": "Recursive structured execution policy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "policyId",
+    "sessionId",
+    "isolationLevel",
+    "allowStructuredRun",
+    "allowedInputs",
+    "restrictedBehaviors",
+    "budgetSummary",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "policyId": { "type": "string" },
+    "sessionId": { "type": "string" },
+    "isolationLevel": {
+      "type": "string",
+      "enum": ["metadata-only", "read-only-inspection", "read-only-repl", "isolated-execution"]
+    },
+    "allowStructuredRun": { "type": "boolean" },
+    "allowedInputs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "restrictedBehaviors": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "budgetSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maxDurationMs", "maxRuns", "notes"],
+      "properties": {
+        "maxDurationMs": { "type": "integer", "minimum": 1 },
+        "maxRuns": { "type": "integer", "minimum": 1 },
+        "notes": { "type": "string" }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/schemas/runtime/recursive-language-capabilities.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness-forge.dev/schemas/runtime/recursive-language-capabilities.schema.json",
+  "title": "Recursive language capabilities",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "workspaceRoot", "summary", "languages"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspaceRoot": { "type": "string" },
+    "summary": { "type": "string" },
+    "languages": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/languageCapability" }
+    }
+  },
+  "$defs": {
+    "languageCapability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["languageId", "displayName", "adapterStatus", "analysisDepth", "nativeExecutionStatus", "notes"],
+      "properties": {
+        "languageId": { "type": "string" },
+        "displayName": { "type": "string" },
+        "adapterStatus": {
+          "type": "string",
+          "enum": ["unavailable", "available", "degraded"]
+        },
+        "analysisDepth": {
+          "type": "string",
+          "enum": ["none", "syntax-aware", "build-aware", "semantic"]
+        },
+        "nativeExecutionStatus": {
+          "type": "string",
+          "enum": ["unsupported", "disabled", "available"]
+        },
+        "notes": { "type": "string" },
+        "evidenceRefs": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/runtime/recursive-run-meta.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness-forge.dev/schemas/runtime/recursive-run-meta.schema.json",
+  "title": "Recursive structured run metadata",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["runId", "sessionId", "submissionMode", "status", "startedAt", "policyRef", "summary"],
+  "properties": {
+    "runId": { "type": "string" },
+    "sessionId": { "type": "string" },
+    "submissionMode": {
+      "type": "string",
+      "enum": ["file", "stdin"]
+    },
+    "sourceRef": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "running", "success", "failure", "rejection", "interrupted", "degraded"]
+    },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "policyRef": { "type": "string" },
+    "resultRef": { "type": "string" },
+    "summary": { "type": "string" },
+    "warningCount": { "type": "integer", "minimum": 0 },
+    "failureReason": { "type": "string" }
+  }
+}

package/schemas/runtime/recursive-run-result.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harness-forge.dev/schemas/runtime/recursive-run-result.schema.json",
+  "title": "Recursive structured run result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["runId", "outcome", "findings", "warnings", "artifactsRead", "artifactsWritten", "diagnostics", "completedAt"],
+  "properties": {
+    "runId": { "type": "string" },
+    "outcome": {
+      "type": "string",
+      "enum": ["success", "failure", "rejection", "interrupted", "degraded"]
+    },
+    "findings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "artifactsRead": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "artifactsWritten": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "completedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/scripts/ci/release-smoke.mjs

@@ -71,9 +71,13 @@ const cliRuns = fs.existsSync(distCliPath)
       { name: "pack", result: run(nodeCommand, [distCliPath, "pack", "--help"]) },
       { name: "review", result: run(nodeCommand, [distCliPath, "review", "--help"]) },
       { name: "export", result: run(nodeCommand, [distCliPath, "export", "--help"]) },
+      { name: "update", result: run(nodeCommand, [distCliPath, "update", "--help"]) },
+      { name: "upgrade", result: run(nodeCommand, [distCliPath, "upgrade", "--help"]) },
       { name: "catalog", result: run(nodeCommand, [distCliPath, "catalog", "--json"]) },
       { name: "template-validate", result: run(nodeCommand, [distCliPath, "template", "validate", "--json"]) },
       { name: "flow-status", result: run(nodeCommand, [distCliPath, "flow", "status", "--json"]) },
+      { name: "recursive-capabilities", result: run(nodeCommand, [distCliPath, "recursive", "capabilities", "--help"]) },
+      { name: "recursive-run", result: run(nodeCommand, [distCliPath, "recursive", "run", "--help"]) },
       { name: "doctor", result: run(nodeCommand, [distCliPath, "doctor", "--json"]) },
       { name: "audit", result: run(nodeCommand, [distCliPath, "audit", "--json"]) }
     ]

package/scripts/ci/smoke-runner.mjs

@@ -57,6 +57,18 @@ const scenarios = [
     args: ["refresh", "--root", tempRoot],
     expectStatus: 1,
     expectStderr: "No installed targets were found"
+  },
+  {
+    name: "update-help",
+    args: ["update", "--help"],
+    expectStatus: 0,
+    expectStdout: "Usage: hforge update"
+  },
+  {
+    name: "recursive-capabilities-help",
+    args: ["recursive", "capabilities", "--help"],
+    expectStatus: 0,
+    expectStdout: "Usage: hforge recursive capabilities"
   }
 ];
 

package/scripts/ci/validate-doc-command-alignment.mjs

@@ -25,6 +25,8 @@ for (const command of [
   "shell setup",
   "shell status",
   "refresh",
+  "update",
+  "upgrade",
   "task list",
   "task inspect",
   "pack inspect",
@@ -42,6 +44,10 @@ for (const command of [
   "template validate",
   "template suggest",
   "flow status",
+  "recursive capabilities",
+  "recursive run",
+  "recursive runs",
+  "recursive inspect-run",
   "observability summarize",
   "observability report",
   "parallel plan",
@@ -59,7 +65,18 @@ for (const command of [
   }
 }
 
-for (const fragment of ["doctor", "audit", "cartograph", "target inspect", "shell setup", "validate:release", "validate:local", "release:dry-run"]) {
+for (const fragment of [
+  "doctor",
+  "audit",
+  "cartograph",
+  "target inspect",
+  "shell setup",
+  "recursive capabilities",
+  "update --root",
+  "validate:release",
+  "validate:local",
+  "release:dry-run"
+]) {
   if (!readme.includes(fragment)) {
     failures.push({ file: "README.md", issue: `Missing README reference ${fragment}` });
   }
@@ -72,7 +89,7 @@ if (!includesAny(readme, ["flow status", "flow recovery"])) {
   });
 }
 
-for (const fragment of ["doctor", "audit", "refresh", "diff-install", "sync", "upgrade-surface", "prune"]) {
+for (const fragment of ["doctor", "audit", "refresh", "update", "upgrade", "diff-install", "sync", "upgrade-surface", "prune"]) {
   if (!maintenanceDoc.includes(fragment)) {
     failures.push({ file: "docs/maintenance-lifecycle.md", issue: `Missing maintenance command ${fragment}` });
   }

package/scripts/ci/validate-manifest-runtime-consistency.mjs

@@ -75,7 +75,18 @@ for (const hook of hooksManifest.hooks ?? []) {
   }
 }
 
-for (const requiredArtifactId of ["spec", "plan", "tasks", "flow-state", "issue-export"]) {
+for (const requiredArtifactId of [
+  "spec",
+  "plan",
+  "tasks",
+  "flow-state",
+  "issue-export",
+  "recursive-runtime-language-capabilities",
+  "recursive-runtime-execution-policy",
+  "recursive-runtime-session-capabilities",
+  "recursive-runtime-run-meta",
+  "recursive-runtime-run-result"
+]) {
   if (!(flowArtifacts.artifacts ?? []).some((artifact) => artifact.id === requiredArtifactId)) {
     failures.push({ issue: "Flow artifact catalog is missing a required artifact.", artifactId: requiredArtifactId });
   }

package/scripts/ci/validate-packed-install-surface.mjs

@@ -16,6 +16,14 @@ const requiredPaths = new Set([
 
 const failures = [];
 const packageFiles = packageJson.files ?? [];
+const explicitlyRequiredRecursivePaths = [
+  ".agents/skills/recursive-structured-analysis/SKILL.md",
+  "skills/recursive-structured-analysis/SKILL.md",
+  "schemas/runtime/recursive-execution-policy.schema.json",
+  "schemas/runtime/recursive-language-capabilities.schema.json",
+  "schemas/runtime/recursive-run-meta.schema.json",
+  "schemas/runtime/recursive-run-result.schema.json"
+];
 
 function isCoveredByPackageFiles(requiredPath) {
   return packageFiles.some((entry) => requiredPath === entry || requiredPath.startsWith(`${entry}/`));
@@ -34,6 +42,12 @@ for (const requiredPath of requiredPaths) {
   }
 }
 
+for (const requiredPath of explicitlyRequiredRecursivePaths) {
+  if (!requiredPaths.has(requiredPath)) {
+    failures.push({ issue: "Recursive structured-analysis path is missing from package-surface manifest.", path: requiredPath });
+  }
+}
+
 const packed =
   process.platform === "win32"
     ? spawnSync("cmd.exe", ["/d", "/s", "/c", "npm pack --json --dry-run"], {

package/skills/recursive-structured-analysis/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: recursive-structured-analysis
+description: session-scoped recursive structured analysis for difficult repository investigation. use when recursive work needs a bounded capability map, explicit execution posture, and durable run records instead of free-form chat exploration.
+---
+
+# Recursive Structured Analysis
+
+## Trigger Signals
+
+- the task already needs a recursive session and now needs one bounded
+  analysis step inside that session
+- the repository is mixed-language or architecture-heavy and support truth
+  should be checked before deeper investigation
+- the operator needs a durable, inspectable analysis run rather than a prompt
+  transcript
+
+## Inspect First
+
+- `.hforge/runtime/recursive/language-capabilities.json`
+- `.hforge/runtime/recursive/sessions/<sessionId>/execution-policy.json`
+- `.hforge/runtime/recursive/sessions/<sessionId>/capabilities.json`
+- `.hforge/generated/agent-command-catalog.json`
+
+## Workflow
+
+1. inspect recursive capability truth before assuming a language or adapter is
+   available
+2. inspect the active recursive session and execution policy
+3. use one bounded structured run at a time
+4. inspect run history and run results instead of relying on chat-only memory
+5. keep support claims honest when a language is degraded, unavailable, or
+   host-executed only
+
+## Command Surface
+
+- `hforge recursive capabilities --root . --json`
+- `hforge recursive run <sessionId> --file <snippet> --root . --json`
+- `hforge recursive run <sessionId> --stdin --root . --json`
+- `hforge recursive runs <sessionId> --root . --json`
+- `hforge recursive inspect-run <sessionId> <runId> --root . --json`
+
+## Operating Rule
+
+Recursive structured analysis is the promoted execution surface for recursive
+repository investigation. Treat it as session-scoped, policy-bound, and
+artifact-backed. Do not describe it as a generic REPL or as native execution
+parity across all languages unless the capability map explicitly supports that
+claim.

package/targets/claude-code/adapter.json

@@ -34,10 +34,11 @@
     ],
     "runtimeSurfaces": [
       ".hforge/runtime/index.json",
-      ".hforge/runtime/README.md"
+      ".hforge/runtime/README.md",
+      ".hforge/runtime/recursive/language-capabilities.json"
     ],
     "supportMode": "native",
-    "notes": "Claude Code keeps repo-root and .claude bridges thin while canonical skills, rules, knowledge, and templates live under the hidden .hforge layer.",
+    "notes": "Claude Code keeps repo-root and .claude bridges thin while canonical skills, rules, knowledge, and templates live under the hidden .hforge layer, including promoted recursive structured-analysis discovery through the shared runtime.",
     "authoritativeSurfaces": [
       ".hforge/library/skills",
       ".hforge/library/rules",

package/targets/codex/adapter.json

@@ -33,10 +33,11 @@
     ],
     "runtimeSurfaces": [
       ".hforge/runtime/index.json",
-      ".hforge/runtime/README.md"
+      ".hforge/runtime/README.md",
+      ".hforge/runtime/recursive/language-capabilities.json"
     ],
     "supportMode": "native",
-    "notes": "Codex keeps repo-root bridges thin and routes canonical AI content through the hidden .hforge library, template, and runtime layer.",
+    "notes": "Codex keeps repo-root bridges thin and routes canonical AI content through the hidden .hforge library, template, and runtime layer, including promoted recursive structured-analysis discovery through the shared runtime.",
     "authoritativeSurfaces": [
       ".hforge/library/skills",
       ".hforge/library/rules",

package/targets/cursor/adapter.json

@@ -35,10 +35,11 @@
     ],
     "runtimeSurfaces": [
       ".hforge/runtime/index.json",
-      ".hforge/runtime/README.md"
+      ".hforge/runtime/README.md",
+      ".hforge/runtime/recursive/language-capabilities.json"
     ],
     "supportMode": "translated",
-    "notes": "Cursor relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content.",
+    "notes": "Cursor relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content, including translated recursive structured-analysis discovery through the shared runtime capability map and durable session artifacts.",
     "authoritativeSurfaces": [
       ".hforge/library/skills",
       ".hforge/library/rules",

package/targets/opencode/adapter.json

@@ -35,10 +35,11 @@
     ],
     "runtimeSurfaces": [
       ".hforge/runtime/index.json",
-      ".hforge/runtime/README.md"
+      ".hforge/runtime/README.md",
+      ".hforge/runtime/recursive/language-capabilities.json"
     ],
     "supportMode": "translated",
-    "notes": "OpenCode relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content.",
+    "notes": "OpenCode relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content, including translated recursive structured-analysis discovery through the shared runtime capability map and durable session artifacts.",
     "authoritativeSurfaces": [
       ".hforge/library/skills",
       ".hforge/library/rules",