workspai 0.43.1 → 0.45.0

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

@@ -0,0 +1,723 @@
+{
+  "schemaVersion": "workspai-workspace-intelligence-architecture-v1",
+  "name": "Workspace Intelligence Architecture",
+  "canonicalPositioning": {
+    "tagline": "Open-Source Workspace Intelligence for Software Systems",
+    "category": "Workspace Intelligence",
+    "primaryPromise": "Workspai turns repositories, projects, dependencies, rules, changes, and evidence into shared understanding for developers, CI, IDEs, and AI agents.",
+    "mentalModel": [
+      "Repositories · Projects · Dependencies · Changes",
+      "Workspace Intelligence",
+      "Evidence-backed outputs",
+      "Developers · CI · IDEs · AI agents"
+    ]
+  },
+  "workspaceLifecycle": {
+    "ingestionRoutes": [
+      {
+        "id": "create",
+        "label": "Create",
+        "commands": [
+          "create workspace",
+          "create project"
+        ],
+        "result": "Create a workspace or supported project and write canonical Workspai metadata."
+      },
+      {
+        "id": "adopt",
+        "label": "Adopt",
+        "commands": [
+          "adopt"
+        ],
+        "result": "Register an existing project in place without requiring source relocation."
+      },
+      {
+        "id": "import",
+        "label": "Import",
+        "commands": [
+          "import",
+          "workspace import"
+        ],
+        "result": "Attach an existing project or repository path to the workspace inventory."
+      }
+    ],
+    "durableState": [
+      {
+        "id": "workspace-identity",
+        "paths": [
+          ".workspai-workspace",
+          ".workspai/workspace.json"
+        ],
+        "purpose": "Identify the workspace boundary, profile, and canonical root."
+      },
+      {
+        "id": "project-inventory",
+        "paths": [
+          ".workspai/project.json",
+          ".workspai/context.json",
+          ".workspai/adopt.json",
+          "~/.workspai/workspaces.json",
+          "~/.rapidkit/workspaces.json (legacy compatibility mirror)"
+        ],
+        "purpose": "Record native, adopted, imported, and globally registered project locations while preserving a non-authoritative mirror for legacy extension discovery."
+      },
+      {
+        "id": "governance",
+        "paths": [
+          ".workspai/policies.yml",
+          ".workspai/workspace.contract.json"
+        ],
+        "purpose": "Define workspace policy and explicit structural relationships."
+      },
+      {
+        "id": "graph-overrides",
+        "paths": [
+          ".workspai/workspace-graph.overrides.json"
+        ],
+        "purpose": "Provide explicit dependency edges that override inferred relationships."
+      }
+    ],
+    "rule": "Create, adopt, and import are ingestion routes, not intelligence facts. Their durable state becomes observable input to Model."
+  },
+  "observedInputs": [
+    {
+      "id": "projects-repositories",
+      "label": "Projects and repositories",
+      "sources": [
+        "projects",
+        "repositories",
+        "services",
+        "modules",
+        "imported paths"
+      ],
+      "entersAt": "model"
+    },
+    {
+      "id": "runtime-dependencies",
+      "label": "Runtime and dependencies",
+      "sources": [
+        "runtime manifests",
+        "lockfiles",
+        "scripts",
+        "framework markers",
+        "package dependencies",
+        "supported source imports (currently bounded JavaScript and TypeScript scanning)"
+      ],
+      "entersAt": "model"
+    },
+    {
+      "id": "workspace-rules",
+      "label": "Workspace rules",
+      "sources": [
+        "workspace markers",
+        "registry",
+        "project metadata",
+        "contracts",
+        "policies",
+        "ownership",
+        "graph overrides"
+      ],
+      "entersAt": "model"
+    },
+    {
+      "id": "changes",
+      "label": "Changes",
+      "sources": [
+        "repository state",
+        "git state",
+        "model baseline",
+        "workspace diff"
+      ],
+      "entersAt": "diff"
+    },
+    {
+      "id": "model-baseline",
+      "label": "Explicit model baseline",
+      "sources": [
+        ".workspai/reports/workspace-model-snapshot.json"
+      ],
+      "entersAt": "diff"
+    },
+    {
+      "id": "existing-evidence",
+      "label": "Existing evidence",
+      "sources": [
+        "doctor reports",
+        "analysis reports",
+        "contract verification",
+        "release readiness",
+        "pipeline results",
+        "tests and runtime evidence",
+        "previous intelligence artifacts"
+      ],
+      "entersAt": "doctor-evidence"
+    }
+  ],
+  "outputFamilies": [
+    {
+      "id": "understanding",
+      "label": "System understanding",
+      "artifacts": [
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-model-diff-last-run.json",
+        ".workspai/reports/workspace-impact-last-run.json"
+      ],
+      "producedBy": [
+        "model",
+        "diff",
+        "impact"
+      ],
+      "inventory": "complete-for-chain"
+    },
+    {
+      "id": "governance-evidence",
+      "label": "Governance evidence",
+      "artifacts": [
+        ".workspai/reports/doctor-last-run.json",
+        ".workspai/reports/workspace-contract-verify-last-run.json",
+        ".workspai/reports/analyze-last-run.json",
+        ".workspai/reports/release-readiness-last-run.json",
+        ".workspai/reports/workspace-verify-last-run.json",
+        ".workspai/reports/workspace-intelligence-history.json"
+      ],
+      "producedBy": [
+        "doctor-evidence",
+        "contract-evidence",
+        "analyze-evidence",
+        "readiness-evidence",
+        "verify"
+      ],
+      "inventory": "complete-for-chain"
+    },
+    {
+      "id": "agent-grounding",
+      "label": "Agent grounding",
+      "artifacts": [
+        ".workspai/reports/workspace-context-agent.json",
+        ".workspai/reports/INDEX.json",
+        ".workspai/reports/agent-customization-pack.json",
+        ".workspai/reports/workspace-skills-index.json",
+        "AGENTS.md"
+      ],
+      "producedBy": [
+        "context",
+        "agent-sync"
+      ],
+      "inventory": "canonical-minimum",
+      "inventoryContract": "contracts/agent-customization-pack.v1.json"
+    },
+    {
+      "id": "explanations",
+      "label": "Explainable decisions",
+      "artifacts": [
+        ".workspai/reports/workspace-explain-last-run.json"
+      ],
+      "producedBy": [
+        "explain"
+      ],
+      "inventory": "complete-for-chain"
+    }
+  ],
+  "deliveryChannels": [
+    {
+      "id": "artifacts",
+      "carries": [
+        "reports",
+        "models",
+        "context",
+        "grounding",
+        "skills"
+      ],
+      "authority": "canonical"
+    },
+    {
+      "id": "json-stdout",
+      "carries": [
+        "structured command results"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "human-cli",
+      "carries": [
+        "summaries",
+        "diagnostics",
+        "next actions"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "exit-codes",
+      "carries": [
+        "gate and command status"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "watch-events",
+      "carries": [
+        "incremental workspace change events"
+      ],
+      "authority": "projection"
+    },
+    {
+      "id": "mcp",
+      "carries": [
+        "read-mostly access to current workspace artifacts"
+      ],
+      "authority": "projection"
+    }
+  ],
+  "feedback": {
+    "from": [
+      "developers",
+      "ci",
+      "ides",
+      "ai-agents"
+    ],
+    "signals": [
+      "source commits",
+      "dependency updates",
+      "policy and contract edits",
+      "repairs",
+      "test and runtime results",
+      "agent action outcomes"
+    ],
+    "reentersThrough": [
+      "projects-repositories",
+      "runtime-dependencies",
+      "workspace-rules",
+      "changes",
+      "existing-evidence"
+    ],
+    "rule": "Consumer actions are not silently treated as truth. They re-enter as observable changes or evidence and must be modeled and verified again."
+  },
+  "auxiliaryCapabilities": [
+    {
+      "id": "graph",
+      "commands": [
+        "workspace graph emit",
+        "workspace graph explain",
+        "workspace graph dot",
+        "workspace graph mermaid"
+      ],
+      "reads": [
+        ".workspai/reports/workspace-model.json#graph"
+      ],
+      "role": "Inspect or render the graph already embedded in the workspace model.",
+      "chainStep": false
+    },
+    {
+      "id": "watch",
+      "commands": [
+        "workspace watch"
+      ],
+      "reads": [
+        "workspace inputs",
+        ".workspai/reports/workspace-model.json"
+      ],
+      "role": "Refresh the model incrementally and emit deterministic change events.",
+      "chainStep": false
+    },
+    {
+      "id": "mcp",
+      "commands": [
+        "workspace mcp serve"
+      ],
+      "reads": [
+        "workspace evidence artifacts"
+      ],
+      "role": "Expose read-mostly workspace evidence to compatible clients.",
+      "chainStep": false
+    }
+  ],
+  "architectureCore": {
+    "executionChainContract": {
+      "schemaVersion": "workspai-workspace-intelligence-chain-v1",
+      "path": "contracts/workspace-intelligence-chain.v1.json"
+    },
+    "loop": [
+      {
+        "id": "model",
+        "status": "available",
+        "purpose": "Build the canonical current model of the software system.",
+        "commands": [
+          "workspace model --json --write"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-model.json"
+        ]
+      },
+      {
+        "id": "diff",
+        "status": "available",
+        "purpose": "Describe structural change against the selected baseline.",
+        "commands": [
+          "workspace diff --from .workspai/reports/workspace-model-snapshot.json --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-model-diff-last-run.json"
+        ]
+      },
+      {
+        "id": "impact",
+        "status": "available",
+        "purpose": "Calculate transitive blast radius over the workspace graph.",
+        "commands": [
+          "workspace impact --from .workspai/reports/workspace-model-diff-last-run.json --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-impact-last-run.json"
+        ]
+      },
+      {
+        "id": "doctor-evidence",
+        "status": "available",
+        "purpose": "Refresh health evidence after the impact artifact exists.",
+        "commands": [
+          "doctor workspace --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/doctor-last-run.json"
+        ]
+      },
+      {
+        "id": "contract-evidence",
+        "status": "available",
+        "purpose": "Refresh structural contract evidence without hiding failed verdicts.",
+        "commands": [
+          "workspace contract verify --strict --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-contract-verify-last-run.json"
+        ]
+      },
+      {
+        "id": "analyze-evidence",
+        "status": "available",
+        "purpose": "Refresh analysis evidence required by the release-readiness gate.",
+        "commands": [
+          "analyze --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/analyze-last-run.json"
+        ]
+      },
+      {
+        "id": "readiness-evidence",
+        "status": "available",
+        "purpose": "Refresh release-readiness evidence before the definitive gate.",
+        "commands": [
+          "readiness --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/release-readiness-last-run.json"
+        ]
+      },
+      {
+        "id": "verify",
+        "status": "available",
+        "purpose": "Emit the definitive evidence-backed workspace gate.",
+        "commands": [
+          "workspace verify --from-impact .workspai/reports/workspace-impact-last-run.json --json"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-verify-last-run.json",
+          ".workspai/reports/workspace-intelligence-history.json"
+        ]
+      },
+      {
+        "id": "context",
+        "status": "available",
+        "purpose": "Build compact agent context from the same verified evidence.",
+        "commands": [
+          "workspace context --for-agent --json --write --no-agent-sync"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-context-agent.json"
+        ]
+      },
+      {
+        "id": "agent-sync",
+        "status": "available",
+        "purpose": "Distribute one context into portable agent and IDE surfaces.",
+        "commands": [
+          "workspace agent-sync --write --json --preset enterprise"
+        ],
+        "artifacts": [
+          ".workspai/reports/INDEX.json",
+          ".workspai/reports/agent-customization-pack.json",
+          ".workspai/reports/workspace-skills-index.json",
+          "AGENTS.md"
+        ]
+      },
+      {
+        "id": "explain",
+        "status": "available",
+        "purpose": "Translate evidence and blockers into a human and agent-readable narrative.",
+        "commands": [
+          "workspace explain release-blocked --json --write"
+        ],
+        "artifacts": [
+          ".workspai/reports/workspace-explain-last-run.json"
+        ]
+      }
+    ],
+    "evidencePrinciples": [
+      "Evidence is the source of understanding; documentation is an output, not the authority.",
+      "Facts should be marked or treated as verified, observed, inferred, or unknown based on available evidence.",
+      "Marketing and integration surfaces must not claim native, doctor depth, module support, or agent grounding beyond the generated contracts."
+    ]
+  },
+  "consumers": [
+    {
+      "id": "developers",
+      "status": "available",
+      "consumes": [
+        "workspace model",
+        "doctor evidence",
+        "explain/trace narratives",
+        "workspace run results"
+      ],
+      "allowedClaims": [
+        "Developers can inspect structure, context, impact, verification, and remediation evidence from one workspace model."
+      ]
+    },
+    {
+      "id": "ci",
+      "status": "available",
+      "consumes": [
+        "pipeline",
+        "readiness",
+        "workspace verify",
+        "doctor workspace/project evidence"
+      ],
+      "allowedClaims": [
+        "CI can gate release readiness and workspace verification through structured JSON reports and exit codes."
+      ]
+    },
+    {
+      "id": "ides-and-extensions",
+      "status": "available",
+      "consumes": [
+        "runtime-command-surface.v1.json",
+        "workspace registry",
+        "agent customization pack"
+      ],
+      "allowedClaims": [
+        "IDEs can discover supported command surfaces and consume shared contracts instead of parsing help text."
+      ]
+    },
+    {
+      "id": "ai-agents",
+      "status": "available",
+      "consumes": [
+        "workspace context",
+        "AGENTS.md",
+        "skills index",
+        "MCP evidence tools"
+      ],
+      "allowedClaims": [
+        "AI agents can use generated grounding artifacts and MCP access to work from evidence-backed workspace context."
+      ]
+    },
+    {
+      "id": "docs-and-marketing",
+      "status": "available",
+      "consumes": [
+        "this architecture contract",
+        "project-entry-capability.v1.json",
+        "runtime-command-surface.v1.json",
+        "create-planner-capabilities.v1.json"
+      ],
+      "allowedClaims": [
+        "Public messaging can describe the architecture as inputs -> Workspace Intelligence -> consumers."
+      ]
+    }
+  ],
+  "claimBoundaries": {
+    "allowed": [
+      "Open-Source Workspace Intelligence for Software Systems.",
+      "One shared model of structure, context, impact, and verification.",
+      "Workspai can create projects only for native kits and available official generator paths listed in the create planner contract.",
+      "Any readable project can enter Workspace Intelligence through adopt/import when it can be registered.",
+      "Existing projects can enter Workspace Intelligence through adopt/import when they are readable and can be registered, even when native scaffold is unavailable.",
+      "Existing runtime signals in the create planner are examples for detection, not a closed allowlist of adopt/import support.",
+      "Agent grounding is available through workspace context, agent-sync, generated agent files, skills index, and MCP evidence access.",
+      "Verification and governance claims must reference doctor, analyze, readiness, pipeline, workspace verify, or generated evidence artifacts."
+    ],
+    "forbiddenUnlessImplemented": [
+      "Do not claim native scaffolding for every language or framework.",
+      "Do not claim module commands are supported for runtimes where moduleSupport/moduleCommands are false.",
+      "Do not claim a chat UI or repository chat exists in the CLI unless a shipped command or product surface implements it.",
+      "Do not present inferred or unknown facts as verified evidence.",
+      "Do not describe documentation as the source of truth; documentation must be described as generated from evidence."
+    ]
+  },
+  "createPlannerReality": {
+    "nativeCreateKits": [
+      "fastapi.standard",
+      "fastapi.ddd",
+      "nestjs.standard",
+      "springboot.standard",
+      "gofiber.standard",
+      "gogin.standard",
+      "dotnet.webapi.clean"
+    ],
+    "officialCreate": [
+      "frontend.nextjs",
+      "frontend.remix",
+      "frontend.vite-react",
+      "frontend.vite-vue",
+      "frontend.vite-svelte",
+      "frontend.vite-solid",
+      "frontend.vite-vanilla",
+      "frontend.nuxt",
+      "frontend.angular",
+      "frontend.astro",
+      "frontend.sveltekit",
+      "wordpress-site",
+      "wordpress-block",
+      "laravel",
+      "symfony",
+      "rails"
+    ],
+    "existingRuntimeSignals": [
+      "php",
+      "ruby",
+      "rust",
+      "elixir",
+      "clojure",
+      "scala",
+      "kotlin"
+    ]
+  },
+  "projectEntryCapability": {
+    "schemaVersion": "workspai-project-entry-capability-v1",
+    "name": "Project Entry Capability",
+    "plainLanguageRule": "Any readable project can enter Workspace Intelligence through adopt/import. Runtime-specific detection improves understanding depth; it is not the permission gate.",
+    "entryRoutes": [
+      {
+        "id": "create",
+        "status": "available",
+        "purpose": "Start a new project only through native kits or available official generator paths listed in the create planner contract.",
+        "commands": [
+          "create workspace",
+          "create project"
+        ]
+      },
+      {
+        "id": "adopt",
+        "status": "available",
+        "purpose": "Register an existing local project in place without moving or rewriting its source.",
+        "commands": [
+          "adopt"
+        ]
+      },
+      {
+        "id": "import",
+        "status": "available",
+        "purpose": "Attach an existing project, repository folder, or imported path to a workspace inventory.",
+        "commands": [
+          "import",
+          "workspace import"
+        ]
+      }
+    ],
+    "universalExistingProjectEntry": {
+      "status": "available",
+      "appliesTo": [
+        "any readable repository",
+        "any readable local project folder",
+        "monorepos and multi-project workspaces",
+        "known runtimes, unknown runtimes, and mixed stacks"
+      ],
+      "minimumConditions": [
+        "The path is readable by the CLI.",
+        "The workspace can write Workspai metadata or record an external adopted path.",
+        "The project can be represented with at least a name, path, and entry record."
+      ],
+      "doesNotRequire": [
+        "native scaffold support",
+        "official generator support",
+        "module command support",
+        "a known runtime detector",
+        "moving source files into the workspace"
+      ],
+      "result": [
+        "project registry membership",
+        "workspace model participation",
+        "workspace context participation",
+        "governance and evidence participation according to available facts"
+      ]
+    },
+    "supportDepths": [
+      {
+        "id": "registered",
+        "label": "Registered",
+        "meaning": "The project is known to the workspace and can participate in inventory, context, and governance.",
+        "examples": [
+          "unknown runtime",
+          "custom stack",
+          "legacy service"
+        ]
+      },
+      {
+        "id": "detected",
+        "label": "Detected",
+        "meaning": "The CLI recognizes runtime or framework signals and can label the project with higher confidence.",
+        "examples": [
+          "node package.json",
+          "python pyproject.toml",
+          "php composer.json"
+        ]
+      },
+      {
+        "id": "operational",
+        "label": "Operational",
+        "meaning": "The CLI can infer or use lifecycle commands, health checks, or workspace run stages.",
+        "examples": [
+          "test script",
+          "build script",
+          "doctor evidence"
+        ]
+      },
+      {
+        "id": "deep",
+        "label": "Deep",
+        "meaning": "The project has stack-specific module, doctor, or scaffold support beyond generic Workspace Intelligence.",
+        "examples": [
+          "FastAPI module support",
+          "NestJS module support",
+          "native Workspai kit"
+        ]
+      }
+    ],
+    "runtimeSignals": {
+      "purpose": "Help the planner and model recognize common existing-project requests and improve labels.",
+      "examples": [
+        "php",
+        "ruby",
+        "rust",
+        "elixir",
+        "clojure",
+        "scala",
+        "kotlin"
+      ],
+      "rule": "Runtime signals are examples for detection and messaging, not a closed allowlist for adopt/import."
+    },
+    "boundaries": {
+      "allowedClaims": [
+        "Any readable project can enter Workspace Intelligence through adopt/import when it can be registered.",
+        "Known runtime and framework detectors improve confidence and depth, but unknown projects can still be registered.",
+        "Create support is limited to native kits and available official generator paths in the create planner contract."
+      ],
+      "forbiddenClaims": [
+        "Do not say adopt/import supports only the listed runtime signals.",
+        "Do not say every imported project receives deep runtime-specific module support.",
+        "Do not say Workspai can natively scaffold every language or framework."
+      ]
+    }
+  },
+  "futureExtensions": []
+}