rapidkit 0.40.0 → 0.41.0

package/README.md

@@ -23,7 +23,9 @@ contracts, and release gates.
 npm install -g rapidkit
 ```
 
-or run without installing:
+### CLI help
+
+Browse all commands without a global install (first run fetches from npm):
 
 ```bash
 npx rapidkit --help
@@ -32,11 +34,8 @@ npx rapidkit --help
 ### Create a governed workspace
 
 ```bash
-mkdir -p ~/rapidkit/workspaces
-cd ~/rapidkit/workspaces
-
-npx rapidkit create workspace platform --yes --profile polyglot --output .
-cd platform
+npx rapidkit my-workspace --yes --profile polyglot
+cd ~/rapidkit/workspaces/my-workspace
 
 npx rapidkit bootstrap --profile polyglot
 npx rapidkit create project
@@ -50,13 +49,9 @@ npx rapidkit pipeline --json --strict
 ### Adopt an existing project
 
 ```bash
-mkdir -p ~/rapidkit/workspaces
-cd ~/rapidkit/workspaces
+npx rapidkit adopt /path/to/project
+cd ~/rapidkit/workspaces/workspai
 
-npx rapidkit create workspace platform --yes --profile polyglot --output .
-npx rapidkit adopt /path/to/project --workspace ~/rapidkit/workspaces/platform
-
-cd ~/rapidkit/workspaces/platform
 npx rapidkit workspace model --json
 npx rapidkit workspace context --for-agent --json --write
 npx rapidkit pipeline --json --strict
@@ -167,8 +162,11 @@ For the visual experience, install the [Workspai VS Code extension](https://mark
 | What projects exist in this workspace?        | `workspace model --json`                       |
 | What context should AI agents receive?        | `workspace context --for-agent --json --write` |
 | What breaks if I change this?                 | `workspace impact --from <snapshot>`           |
+| Why is release blocked?                       | `workspace explain release-blocked --json --write` |
+| Trace a diff through blast radius and gates?  | `workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write` |
 | Can I safely release?                         | `pipeline --json --strict`                     |
 | How do I align AI tools and CI?               | `workspace agent-sync --write`                 |
+| Expose workspace evidence to MCP clients?     | `workspace mcp serve`                          |
 | How do I onboard an existing project?         | `adopt`                                        |
 | How do I bring repositories into a workspace? | `import`                                       |
 
@@ -247,11 +245,39 @@ Workspace Intelligence provides a shared understanding of projects, dependencies
 | `workspace snapshot --json`                       | Persist model snapshot                                                               |
 | `workspace diff --from <file\|git[:ref]> --json`  | Diff against snapshot or git                                                         |
 | `workspace impact --from <file> --json`           | Graph-aware transitive blast-radius evidence                                         |
-| `workspace verify [--strict] --json`              | Definitive verification gate (subgraph + freshness + policy)                         |
+| `workspace verify [--strict] --json`              | Definitive verification gate (subgraph + freshness + policy + fleet evidence)        |
+| `workspace explain <target> [--write] --json`     | Human narrative for release blockers, projects, or trace slices                      |
+| `workspace why <target>`                          | Alias of `workspace explain`                                                         |
+| `workspace trace --from <diff> [--write] --json`  | Diff → impact → gates narrative for agents and IDE handoff                           |
+| `workspace feedback record --json`                | Append structured agent action outcomes to intelligence history                      |
+| `workspace mcp serve`                             | Read-mostly stdio MCP bridge over workspace evidence                                 |
 | `workspace graph <emit\|explain\|dot\|mermaid>`   | Inspect and visualize the dependency graph                                           |
 | `workspace watch [--json] [--once]`               | Daemon mode: keep model + graph in memory, stream change events                      |
+| `workspace run <stage> [--scope project:X] [--reuse-passed]` | Fleet init/test/build/start or custom stages from `.rapidkit/context.json` |
+
+JSON schemas: `contracts/workspace-intelligence/`. Command coexistence and naming:
+[docs/contracts/NAMING_AND_COEXISTENCE.md](docs/contracts/NAMING_AND_COEXISTENCE.md).
+Details: [commands-reference.md](docs/commands-reference.md).
+
+### Operational intelligence (Phase 4)
+
+After model → diff → impact → verify, use **explain** and **trace** for
+human/agent narratives, **feedback** to record outcomes, and **MCP serve** for
+read-only tool access:
+
+```bash
+npx rapidkit workspace explain release-blocked --json --write
+npx rapidkit workspace trace --from .rapidkit/reports/workspace-model-diff-last-run.json --json --write
+npx rapidkit workspace feedback record --json
+npx rapidkit workspace mcp serve
+```
+
+Fleet runs support scoped execution and result reuse:
 
-JSON schemas: `contracts/workspace-intelligence/`. Details: [commands-reference.md](docs/commands-reference.md).
+```bash
+npx rapidkit workspace run test --scope project:api --reuse-passed --json
+npx rapidkit workspace run lint --scope project:api   # custom stage from context.json
+```
 
 ### Graph-aware intelligence engine
 
@@ -308,6 +334,9 @@ npm run check:agent-customization-drift -- --workspace <workspace-root>
 | Artifact / file                                                         | Purpose                                                  |
 | ----------------------------------------------------------------------- | -------------------------------------------------------- |
 | `.rapidkit/reports/agent-customization-pack.json`                       | Versioned output inventory, target matrix, drift state   |
+| `.rapidkit/reports/workspace-explain-last-run.json`                     | Unified explain / trace narrative for blockers and projects |
+| `.rapidkit/reports/workspace-skills-index.json`                        | Index of operational playbooks (`.rapidkit/skills/*.md`)      |
+| `.rapidkit/skills/rapidkit-*.md`                                       | Operational playbooks (generated by agent-sync)               |
 | `.rapidkit/reports/rapidkit-mcp-design.json`                            | Read-mostly MCP-ready tool design manifest               |
 | `.rapidkit/reports/INDEX.json`                                          | Read order, blockers, report timestamps                  |
 | `.rapidkit/reports/workspace-context-agent.json`                        | Canonical agent context pack                             |
@@ -361,8 +390,6 @@ CI template: [docs/examples/ci-agent-grounding.yml](docs/examples/ci-agent-groun
 
 ```bash
 npm install -g rapidkit
-# or
-npx rapidkit --help
 ```
 
 ## Project workflows
@@ -370,8 +397,10 @@ npx rapidkit --help
 ### I already have a project
 
 ```bash
-npx rapidkit adopt /path/to/project --workspace /path/to/workspace
-npx rapidkit import ../orders-api --workspace ./platform
+npx rapidkit adopt /path/to/project
+npx rapidkit import ../orders-api
+cd ~/rapidkit/workspaces/workspai
+
 npx rapidkit workspace model --json
 npx rapidkit doctor workspace --json
 ```
@@ -379,11 +408,8 @@ npx rapidkit doctor workspace --json
 ### I want a new project
 
 ```bash
-mkdir -p ~/rapidkit/workspaces
-cd ~/rapidkit/workspaces
-
-npx rapidkit create workspace platform --yes --profile polyglot --output .
-cd platform
+npx rapidkit my-workspace --yes --profile polyglot
+cd ~/rapidkit/workspaces/my-workspace
 
 npx rapidkit bootstrap --profile polyglot
 npx rapidkit create project          # interactive kit picker

package/contracts/agent-customization-pack.v1.json

@@ -19,7 +19,8 @@
         ".github/prompts/rapidkit-diagnose.prompt.md",
         ".github/skills/rapidkit-workspace-intelligence/SKILL.md",
         ".github/agents/workspai-advisor.agent.md",
-        ".rapidkit/reports/rapidkit-mcp-design.json"
+        ".rapidkit/reports/rapidkit-mcp-design.json",
+        ".rapidkit/reports/workspace-skills-index.json"
       ]
     }
   },
@@ -99,6 +100,11 @@
       "label": "Agent context pack",
       "required": true
     },
+    {
+      "path": ".rapidkit/reports/workspace-skills-index.json",
+      "label": "Operational skills index",
+      "required": true
+    },
     {
       "path": ".rapidkit/reports/workspace-model.json",
       "label": "Workspace model graph",
@@ -133,6 +139,31 @@
       "path": ".rapidkit/reports/workspace-verify-last-run.json",
       "label": "Workspace verify",
       "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-model-snapshot.json",
+      "label": "Workspace model snapshot",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-model-diff-last-run.json",
+      "label": "Workspace model diff",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-explain-last-run.json",
+      "label": "Workspace explain",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-contract-verify-last-run.json",
+      "label": "Workspace contract verify",
+      "required": false
+    },
+    {
+      "path": ".rapidkit/reports/workspace-intelligence-history.json",
+      "label": "Workspace intelligence history",
+      "required": false
     }
   ],
   "strictRules": [
@@ -151,9 +182,28 @@
     "prompt",
     "skill",
     "skill-resource",
+    "operational-skill",
+    "skills-index",
+    "explain-report",
     "agent",
     "rule",
     "hook",
     "mcp-design"
-  ]
+  ],
+  "pathLayers": {
+    "l1CanonicalRoots": [
+      ".rapidkit/reports/",
+      ".rapidkit/skills/"
+    ],
+    "l2PrefixedMirrorRoots": [
+      ".github/",
+      ".cursor/",
+      ".claude/"
+    ],
+    "l3SharedIndustryFiles": [
+      "AGENTS.md",
+      ".github/copilot-instructions.md",
+      "CLAUDE.md"
+    ]
+  }
 }

package/contracts/extension-cli-compatibility.v1.json

@@ -1,10 +1,22 @@
 {
   "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
   "cli": "rapidkit-npm",
-  "minimumVerifiedCliVersion": "0.40.0",
+  "minimumVerifiedCliVersion": "0.41.0",
   "publishedContractSchemas": {
     "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
     "cliLogEvent": "cli-log-event-v1",
-    "freshnessMetadata": "rapidkit-freshness-metadata-v1"
+    "freshnessMetadata": "rapidkit-freshness-metadata-v1",
+    "blockerResolution": "rapidkit-blocker-resolution-v1",
+    "workspaceModel": "workspace-model.v1",
+    "workspaceImpact": "workspace-impact.v1",
+    "workspaceVerify": "workspace-verify.v1",
+    "workspaceContext": "workspace-context.v1",
+    "workspaceDependencyGraph": "workspace-dependency-graph.v1",
+    "workspaceIntelligenceHistory": "workspace-intelligence-history.v1",
+    "agentCustomizationPack": "rapidkit-agent-customization-pack.v1",
+    "workspaceOperationalSkill": "workspace-operational-skill.v1",
+    "workspaceSkillsIndex": "workspace-skills-index.v1",
+    "workspaceExplain": "workspace-explain.v1",
+    "agentActionOutcome": "agent-action-outcome.v1"
   }
 }

package/contracts/runtime-command-surface.v1.json

@@ -53,6 +53,11 @@
     "watch",
     "context",
     "agent-sync",
+    "explain",
+    "why",
+    "trace",
+    "feedback",
+    "mcp",
     "policy",
     "contract",
     "share",
@@ -70,7 +75,8 @@
     "impact",
     "verify",
     "context",
-    "agent-sync"
+    "agent-sync",
+    "explain"
   ],
   "moduleSuggestionFrameworks": [
     "fastapi",

package/contracts/workspace-intelligence/agent-action-outcome.v1.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/agent-action-outcome.v1.json",
+  "title": "RapidKit Agent Action Outcome",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "actionId", "scope", "summary", "outcome"],
+  "properties": {
+    "schemaVersion": { "const": "agent-action-outcome.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "actionId": { "type": "string", "minLength": 1 },
+    "scope": { "type": "string" },
+    "summary": { "type": "string" },
+    "outcome": { "enum": ["ok", "failed"] },
+    "affectedFiles": { "type": "array", "items": { "type": "string" } },
+    "commandsRun": { "type": "array", "items": { "type": "string" } },
+    "verifyBefore": { "type": "string" },
+    "verifyAfter": { "type": "string" },
+    "evidenceSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "evidencePath": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/blocker-resolution.v1.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/blocker-resolution.v1.json",
+  "title": "RapidKit Blocker Resolution Hint",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "blockerId",
+    "resolutionClass",
+    "blockerSignature",
+    "fixHints"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-blocker-resolution-v1"
+    },
+    "blockerId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sourceCommand": {
+      "type": "string"
+    },
+    "sourceArtifact": {
+      "type": "string"
+    },
+    "resolutionClass": {
+      "enum": [
+        "artifact-missing",
+        "command-failed-repeat",
+        "config-fixable",
+        "semantic-attention",
+        "unresolvable-without-human"
+      ]
+    },
+    "blockerSignature": {
+      "type": "string",
+      "minLength": 8
+    },
+    "commandRetryHint": {
+      "type": "string"
+    },
+    "fixHints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["actionKind", "detail"],
+        "properties": {
+          "actionKind": {
+            "enum": ["edit-file", "run-once", "commit-files", "refresh-baseline"]
+          },
+          "targetPath": { "type": "string" },
+          "detail": { "type": "string" },
+          "studioActionId": {
+            "enum": ["fix-lens", "verify-gates", "run-analyze", "doctor-fix"]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "verifyCommand": { "type": "string" },
+    "verifyArtifact": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/doctor-fix-result.v1.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "rapidkit-doctor-fix-result-v1",
+  "title": "Doctor fix execution result",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion", "appliedFixes", "remainingBlockers", "verifyRecommended"],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-doctor-fix-result-v1"
+    },
+    "appliedFixes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "action", "outcome"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "type": "string" },
+          "outcome": {
+            "enum": ["applied", "failed", "skipped", "guidance"]
+          }
+        }
+      }
+    },
+    "remainingBlockers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "verifyRecommended": {
+      "type": "string"
+    }
+  }
+}

package/contracts/workspace-intelligence/studio-blocker-handoff.v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/studio-blocker-handoff.v1.json",
+  "title": "Workspai Studio Blocker Handoff",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "cardId",
+    "cardStatus",
+    "blockers",
+    "artifactPath",
+    "sourceCommand",
+    "scope"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "rapidkit-studio-blocker-handoff-v1"
+    },
+    "cardId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cardLabel": {
+      "type": "string"
+    },
+    "cardStatus": {
+      "enum": ["pass", "warn", "fail", "missing"]
+    },
+    "blockers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "artifactPath": {
+      "type": "string"
+    },
+    "sourceCommand": {
+      "type": "string"
+    },
+    "scope": {
+      "enum": ["workspace", "project"]
+    },
+    "stderrTail": {
+      "type": "string"
+    },
+    "exitCode": {
+      "type": ["integer", "null"]
+    },
+    "blockerSignature": {
+      "type": "string",
+      "minLength": 8
+    },
+    "commandRunCount": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "resolutionClass": {
+      "enum": [
+        "artifact-missing",
+        "command-failed-repeat",
+        "config-fixable",
+        "semantic-attention",
+        "unresolvable-without-human"
+      ]
+    },
+    "studioMode": {
+      "enum": ["FIX", "RUN_ONCE", "VERIFY_ONLY", "EXPLAIN"]
+    },
+    "resolutionHints": {
+      "type": "array",
+      "items": {
+        "$ref": "blocker-resolution.v1.json"
+      }
+    },
+    "verifyCommand": {
+      "type": "string"
+    },
+    "verifyArtifact": {
+      "type": "string"
+    },
+    "handoffSource": {
+      "enum": ["repair", "artifacts", "advisor", "tree", "dashboard"]
+    },
+    "workspacePath": {
+      "type": "string"
+    },
+    "projectPath": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-contract-verify.v1.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "workspace-contract-verify.v1",
+  "title": "Workspace contract verify evidence",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "status",
+    "contractPath",
+    "projectCount",
+    "checks",
+    "violations"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "workspace-contract-verify.v1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "status": {
+      "enum": ["passed", "failed"]
+    },
+    "contractPath": {
+      "type": "string"
+    },
+    "projectCount": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "status": { "enum": ["passed", "failed"] },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "violations": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/contracts/workspace-intelligence/workspace-explain.v1.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-explain.v1.json",
+  "title": "RapidKit Workspace Explain Report",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "workspacePath", "target", "summary", "sections"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-explain.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspacePath": { "type": "string" },
+    "target": { "type": "object", "additionalProperties": true },
+    "summary": { "type": "string" },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "body"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "body": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "releaseRisk": { "type": "string" },
+    "blockingReasons": { "type": "array", "items": { "type": "string" } },
+    "resolutionHints": { "type": "array", "items": { "type": "object" } }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-intelligence-history.v1.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-intelligence-history.v1.json",
+  "title": "RapidKit Workspace Intelligence History",
+  "type": "object",
+  "required": ["schemaVersion", "retention", "entries"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-intelligence-history.v1" },
+    "retention": { "type": "integer", "minimum": 1 },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["generatedAt"],
+        "properties": {
+          "generatedAt": { "type": "string", "format": "date-time" },
+          "kind": { "enum": ["verify", "agent-action"] },
+          "verdict": { "enum": ["ready", "needs-attention", "blocked"] },
+          "risk": { "type": "string" },
+          "affectedProjects": { "type": "integer", "minimum": 0 },
+          "freshness": { "enum": ["fresh", "stale", "unknown"] },
+          "gatePassed": { "type": "boolean" },
+          "blockingReasons": { "type": "integer", "minimum": 0 },
+          "policyViolations": { "type": "integer", "minimum": 0 },
+          "actionId": { "type": "string" },
+          "scope": { "type": "string" },
+          "summary": { "type": "string" },
+          "outcome": { "enum": ["ok", "failed"] },
+          "evidenceSha256": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-operational-skill.v1.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-operational-skill.v1.json",
+  "title": "RapidKit Workspace Operational Skill",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "skillId",
+    "canonicalPath",
+    "title",
+    "triggers",
+    "requiredReports",
+    "scopedProjects",
+    "verificationCommands",
+    "answerContractSections",
+    "markdown"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-operational-skill.v1" },
+    "skillId": { "type": "string", "minLength": 1 },
+    "canonicalPath": { "type": "string", "pattern": "^\\.rapidkit/skills/[^/]+\\.md$" },
+    "title": { "type": "string" },
+    "triggers": { "type": "array", "items": { "type": "string" } },
+    "requiredReports": { "type": "array", "items": { "type": "string" } },
+    "scopedProjects": { "type": "array", "items": { "type": "string" } },
+    "verificationCommands": { "type": "array", "items": { "type": "string" } },
+    "answerContractSections": {
+      "type": "array",
+      "items": {
+        "enum": ["Scope", "Evidence", "Diagnosis", "Fix Plan", "Run", "Verify", "Assumptions"]
+      }
+    },
+    "promptStem": { "type": "string" },
+    "markdown": { "type": "string" }
+  },
+  "additionalProperties": false
+}