@geraldmaron/construct 1.0.15 → 1.0.16

package/lib/upgrade.mjs

@@ -10,6 +10,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
+import { writeVersionStamp } from './maintenance/cleanup.mjs';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..');
 const PACKAGE_NAME = '@geraldmaron/construct';
@@ -97,7 +99,7 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
   }
   
   stdout.write('Upgrading...\n\n');
-  
+
   const steps = [
     {
       label: 'Fetching latest from npm',
@@ -109,6 +111,15 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       command: 'construct',
       args: ['sync', '--no-docs'],
     },
+    // Sweep legacy cx-*.md/.toml/.prompt.md left behind by older releases at
+    // user scope. Without this the user gets a doctor warning every session
+    // until they manually run `construct doctor --fix-legacy-agents`.
+    {
+      label: 'Sweeping legacy agents at user scope',
+      command: 'construct',
+      args: ['doctor', '--fix-legacy-agents'],
+      optional: true,
+    },
     {
       label: 'Running health checks',
       command: 'construct',
@@ -123,18 +134,34 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       env,
       stdio: 'inherit',
     });
-    
+
     if (result.error) {
+      if (step.optional) {
+        stdout.write(`  (skipped: ${result.error.message})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed: ${result.error.message}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
-    
+
     if (result.status !== 0) {
+      if (step.optional) {
+        stdout.write(`  (skipped: exit ${result.status})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed with exit code ${result.status}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
   }
-  
+
+  // Advance the cleanup stamp so the next CLI invocation doesn't re-run a
+  // full cleanup pass under the assumption that the user just upgraded.
+  // Without this, every command pays the cleanup cost until something
+  // else writes the stamp.
+  try {
+    writeVersionStamp({ version: latestVersion, summary: { freedBytes: 0, durationMs: 0 } });
+  } catch { /* stamp write is best-effort */ }
+
   stdout.write('\n');
   stdout.write(`✓ Upgraded to ${latestVersion}\n`);
   return { success: true, upgraded: true, from: currentVersion, to: latestVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {

package/personas/construct.md

@@ -34,6 +34,8 @@ Execution model:
 
 Devil's advocate is mandatory for new architectural directions, AI/agent workflow changes, security or data-integrity changes, and promoting a temporary capability to persistent.
 
+Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
+
 ## Gates and contracts (org-in-a-box)
 
 `routeRequest` returns three artifacts; honor all three:

package/platforms/claude/CLAUDE.md

@@ -1,30 +1,58 @@
 # Construct: Claude Code Integration
 
-This project uses Construct. Personas and specialists are defined in `specialists/registry.json` and synced to Claude Code via `construct sync`.
+This file ships as a reference template alongside the Construct npm package. The canonical project-instructions file is `/CLAUDE.md` at your repo root — that's the file Claude Code actually reads at session start. The structure here mirrors that canonical file so users know what shape their own `/CLAUDE.md` should take after `construct init` scaffolds a project.
+
+Personas and specialists are defined in `specialists/registry.json` and rendered into Claude Code agents on every `construct sync`. The single user-facing persona is `construct`; the 28 specialists (cx-engineer, cx-security, cx-devil-advocate, …) are routed internally — you address Construct, Construct dispatches.
+
+## Critical rules (mirror in your project /CLAUDE.md)
+
+- **Never fabricate.** Every load-bearing claim cites a verifiable source. When a fact isn't in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.
+- **Confirm the working branch every session.** Session-start surfaces `## Working branch: <name>` at the top of the injected context.
+- **Never commit, push, or merge without asking first.** State the branch, state the action, wait for explicit yes.
+- **Never edit running hook files** without testing them in isolation. A broken hook blocks all tool use.
+- **Hooks fire unconditionally. No skip env vars on quality gates.** If a check fires wrong, repair the check — do not re-introduce `CONSTRUCT_SKIP_*` / `CONSTRUCT_ALLOW_*`.
+- **Never commit directly to main.** Branch, test, then merge.
+- **Run `construct doctor`** after structural changes.
 
 ## Workflow roles
 
-Construct is the only intended user-facing surface.
+| Role | What it covers |
+|---|---|
+| **Planning** | Requirements, strategy, architecture, framing challenges |
+| **Implementation** | Builds features and fixes bugs |
+| **Validation** | Quality gates, code review, security, accessibility |
+| **Research** | Docs, debugging, codebase exploration, external research |
+| **Operations** | Releases, dev servers, health checks, observability |
+
+Construct routes complex work through the full pipeline (plan → implement → validate → operate). For simple tasks, Construct acts directly without exposing the internal routing.
+
+## Beads issue tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` for the full workflow context.
 
-- **Planning**: requirements, strategy, architecture
-- **Implementation**: builds features and fixes bugs
-- **Validation**: quality gates, security, accessibility
-- **Research**: docs, debugging, codebase exploration
-- **Operations**: releases, dev servers, health checks
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
 
-## Usage
+Use `bd` for all task tracking. Do NOT use TodoWrite, TaskCreate, or markdown TODO lists.
 
-Talk to Construct normally. It routes complex work through the full pipeline internally:
-plan → implement → validate → operate
+## Session completion
 
-For simple tasks, Construct can act directly without exposing internal routing.
+When ending a work session, **work is not complete until `git push` succeeds.**
 
-All 26 internal specialists (cx-engineer, cx-security, cx-devil-advocate, etc.) are available as subagents.
+```bash
+git pull --rebase
+git push
+git status  # MUST show "up to date with origin"
+```
 
-## Tool Calls
+## Tool calls
 
 When using Bash, always provide both `command` and `description` string fields. Do not emit XML-style fallback tool calls.
 
-## Cross-Tool Memory
+## Cross-tool memory
 
-Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then use `memory_search` to find prior context.
+Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then `memory_search` to find prior context. Memory and beads are complementary: memory holds knowledge, beads hold tasks.

package/scripts/sync-specialists.mjs

@@ -950,7 +950,16 @@ function getVSCodeSettingsPaths() {
       path.join(appData, "Code - Insiders", "User", "settings.json"),
     );
   }
-  return candidates.filter(fs.existsSync);
+  // settings.json present → ready to merge. settings.json absent but the
+  // VS Code User dir exists → installed without ever opening Preferences,
+  // and global sync still needs to write the MCP block. The User dir is
+  // the installation signal; bootstrap a minimal settings.json there.
+
+  return candidates.filter((candidate) => {
+    if (fs.existsSync(candidate)) return true;
+    const userDir = path.dirname(candidate);
+    return fs.existsSync(userDir);
+  });
 }
 
 function syncVSCode(targetDir = null) {
@@ -991,7 +1000,16 @@ function syncVSCode(targetDir = null) {
   let synced = false;
   for (const settingsPath of settingsPaths) {
     try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      let settings;
+      if (fs.existsSync(settingsPath)) {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      } else {
+        // VS Code installed (User dir present) but never opened → seed an
+        // empty settings.json. Single object literal, no other keys, so
+        // a later launch of VS Code finds it valid and writes user prefs
+        // alongside.
+        settings = {};
+      }
       if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
       const mcpServers = settings["github.copilot.mcpServers"];
       for (const [id, mcpDef] of Object.entries(registryMcp)) {