@geraldmaron/construct 1.0.6 → 1.0.7

package/rules/common/review-before-change.md

@@ -0,0 +1,58 @@
+<!--
+rules/common/review-before-change.md: audit the current state before authoring anything new.
+
+Applies to every specialist on every platform. Pairs with framing.md (frame the
+problem) and development-workflow.md step 0 (research and reuse before code).
+This rule extends the same discipline to artifacts: docs, strategy, PRDs, ADRs,
+RFCs, rules, templates, and any other durable file. Read before scaffolding.
+-->
+# Review Before Change
+
+Before creating or rewriting a durable artifact, check what already exists.
+
+This rule exists because the most common waste in Construct is duplicated effort: a new strategy doc landing next to a PRD that already covers it, a new rule re-stating a section of `framing.md`, a new diagram drawn while an equivalent one sits two folders away. The fix is not more process. It is a fifteen-second audit before the first write.
+
+## When this applies
+
+Any time the work would produce or significantly rewrite one of:
+
+- A doc under `docs/`, including concepts, cookbook, providers, runbooks, ADRs, RFCs, PRDs, memos, runbooks, decisions.
+- A rule under `rules/` or a skill under `skills/`.
+- A template under `templates/`.
+- A top-level repo doc (README, CHANGELOG, STRATEGY, AGENTS, CONTRIBUTING).
+- A profile under `profiles/` or a registered agent.
+
+It does not apply to local-only working files (`plan.md`, `.cx/` state, draft scratch).
+
+## The audit
+
+Before writing, answer all three:
+
+1. **Does an artifact for this already exist?** Search by topic, not filename. `grep -rli "<topic>" docs/ rules/ skills/` is the floor. If something close exists, the default is to extend or supersede, not to create a sibling.
+2. **Is there a template or canonical shape for this artifact type?** Check `templates/docs/` and the matching `skills/docs/*-workflow.md`. If a shape exists, use it; do not invent a new structure.
+3. **What is the canonical home for this kind of content?** A strategy doc belongs in one place. A new ADR does not live in `docs/notes/`. If you have to think about where to put it, the location is wrong.
+
+If any answer surfaces an existing artifact, you have two valid moves:
+
+- **Extend it.** Add the missing section to the existing file.
+- **Supersede it.** Replace the old artifact and mark it superseded. Do not leave two competing sources of truth.
+
+Creating a new sibling artifact "because the old one didn't quite fit" is the failure mode this rule prevents. If the old one doesn't fit, fix it.
+
+## Documenting the audit
+
+For artifacts that go through a review cycle (strategy, PRD, ADR, RFC), the framing or problem-statement section should briefly note what existing artifacts were reviewed and why a new one is warranted. One sentence is enough. The point is to leave evidence that the audit happened.
+
+## Anti-patterns
+
+- Creating `docs/notes/strategy.md` because you didn't notice `STRATEGY.md` at the root.
+- Writing a new rule that paraphrases an existing one.
+- Adding a new template alongside `templates/docs/strategy.md` because the existing one "needed a couple of tweaks."
+- Drafting an ADR for a decision already captured in an existing ADR.
+- Producing a recipe in `docs/cookbook/` for a workflow already documented in `docs/concepts/`.
+
+## Related
+
+- `rules/common/framing.md`: frame the underlying problem before reaching for inputs.
+- `rules/common/development-workflow.md`: step 0 covers the same discipline for code.
+- `rules/common/doc-ownership.md`: which specialist owns which artifact type.

package/scripts/sync-agents.mjs

@@ -121,6 +121,18 @@ if (validationErrors.length > 0) {
   process.exit(1);
 }
 
+// Sync-time contract validation: contracts.json shape, schema refs, and
+// producer/consumer name resolution against the registry above.
+{
+  const { validateContractsFile } = await import("../lib/contracts/validate.mjs");
+  const contractsResult = validateContractsFile();
+  if (!contractsResult.ok) {
+    console.error("Contract validation failed:");
+    for (const err of contractsResult.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+}
+
 // --- Dry-run + lockfile + two-phase write infrastructure ---
 
 const DRY_RUN = process.argv.includes("--dry-run");
@@ -671,9 +683,13 @@ ${agentList || "(all specialists are internal — routed through Construct)"}`;
       if (!settings.mcpServers) settings.mcpServers = {};
       const registryMcp = registry.mcpServers ?? {};
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(settings.mcpServers[id] ?? "");
+        const existingEntry = settings.mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (settings.mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
@@ -711,8 +727,8 @@ function hasCodexMcpTable(text, id) {
   return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, "m").test(text);
 }
 
-function isCodexMcpSupported(id) {
-  return id !== "memory";
+function isCodexMcpSupported() {
+  return true;
 }
 
 function syncCodex(entries) {
@@ -834,9 +850,13 @@ function syncVSCode() {
       if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
       const mcpServers = settings["github.copilot.mcpServers"];
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(mcpServers[id] ?? "");
+        const existingEntry = mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       settings["github.copilot.mcpServers"] = mcpServers;
@@ -862,9 +882,13 @@ function syncCursor() {
     const config = JSON.parse(fs.readFileSync(cursorMcpPath, "utf8"));
     if (!config.mcpServers) config.mcpServers = {};
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
-      const existing = JSON.stringify(config.mcpServers[id] ?? "");
+      const existingEntry = config.mcpServers[id];
+      const existing = JSON.stringify(existingEntry ?? "");
       const hasPlaceholder = existing.includes("__");
-      if (config.mcpServers[id] && !hasPlaceholder) continue;
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+      if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
       config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
     }
     if (!DRY_RUN) fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
@@ -963,14 +987,21 @@ function syncOpencode(entries) {
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
       const openCodeId = getOpenCodeMcpId(id);
       if (openCodeId !== id) delete config.mcp[id];
-      if (id === 'memory' && config.mcp.cass && !config.mcp[openCodeId]) {
-        config.mcp[openCodeId] = config.mcp.cass;
-      }
       if (id === 'memory') delete config.mcp.cass;
-      const existing = JSON.stringify(config.mcp[openCodeId] ?? "");
-      const hasPlaceholder = existing.includes("__") && existing.includes("__");
+
+      // Migrate the legacy cass-memory HTTP entry to the stdio bridge. cm v0.2.x
+      // rejects the MCP handshake (OpenCode surfaces 405 on the SSE GET), so
+      // any remote/http memory entry must be rewritten when the registry
+      // defines a command-based bridge.
+      const existingEntry = config.mcp[openCodeId];
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'remote' || existingEntry.type === 'http');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+
+      const existing = JSON.stringify(existingEntry ?? "");
+      const hasPlaceholder = existing.includes("__");
       const argsHaveTemplates = (mcpDef.args ?? []).some((a) => typeof a === 'string' && a.includes('__'));
-      if (!config.mcp[openCodeId] || hasPlaceholder || argsHaveTemplates) {
+      if (!existingEntry || hasPlaceholder || argsHaveTemplates || transportMismatch) {
         config.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcpDef, process.env).entry;
       }
     }

package/templates/docs/construct_guide.md

@@ -2,7 +2,7 @@
 
 This file was generated by `construct init` to help you get oriented. It's safe to edit: Construct only writes it once, then leaves it alone.
 
-**Full docs:** [https://geraldmaron.github.io/construct/v2/](https://geraldmaron.github.io/construct/v2/)
+**Full docs:** [https://geraldmaron.github.io/construct/](https://geraldmaron.github.io/construct/)
 
 ## What Construct is doing in your project
 
@@ -117,7 +117,7 @@ All ports bind to `127.0.0.1` only; nothing is reachable from other machines on
 | `construct search "..."` | Hybrid file + SQL + semantic search over project state |
 | `construct uninstall` | Interactive teardown: never touches Docker or your code |
 
-Full reference: <https://geraldmaron.github.io/construct/v2/docs/reference/cli>
+Full reference: <https://geraldmaron.github.io/construct/docs/reference/cli>
 
 ## Updating Construct
 
@@ -134,13 +134,13 @@ construct doctor              # most issues surface here with a fix hint
 construct down && construct up  # restart local services
 ```
 
-Troubleshooting guide: <https://geraldmaron.github.io/construct/v2/docs/operations/troubleshooting>
+Troubleshooting guide: <https://geraldmaron.github.io/construct/docs/operations/troubleshooting>
 
 ## Next steps
 
-- [Connect your editor](https://geraldmaron.github.io/construct/v2/docs/start/connect-your-editor) if you haven't already.
-- [Run your first task](https://geraldmaron.github.io/construct/v2/docs/start/first-task) to feel the flow.
-- Skim [the architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) when you have 10 minutes: it'll save you hours later.
+- [Connect your editor](https://geraldmaron.github.io/construct/docs/start/connect-your-editor) if you haven't already.
+- [Run your first task](https://geraldmaron.github.io/construct/docs/start/first-task) to feel the flow.
+- Skim [the architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture) when you have 10 minutes: it'll save you hours later.
 
 If you'd rather have a teammate walk you through it, the persona itself can:
 

package/templates/docs/skill-artifact.md

@@ -1,6 +1,6 @@
 ---
 name: <verb-led-id>
-scope: <one paragraph: what it covers, what it does not>
+scope: "<one paragraph: what it covers, what it does not>"
 observable_outcome: <how someone outside the role tells this skill happened>
 provenance:
   - <citation: post-mortem, public framework, competency model>