magic-spec 1.4.77 → 1.4.162

package/CHANGELOG.md

@@ -5,7 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.4.77] - 2026-03-03
+## [1.4.162] - 2026-03-12
+
+### Added
+
+- **Session Isolation Rule (C17)**: Formalized the requirement for "New Chat" sessions between major workflow transitions (Spec → Task → Run) to prevent context bleed-over and hallucinations.
+- **Multi-Workspace Support (C22)**: Enhanced `check-prerequisites.js` and `init.js` to support nested workspaces with inherited root rules.
+- **Model-Aware History**: Updated engine history schema to include AI Model information, improving auditability of generated code.
+
+### Changed
+
+- **Task Checklist Logic**: Consolidated implementation checklists into `TASKS.md` for better execution tracking and status reporting.
+- **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agent/` directories with idempotent updates.
+- **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
+
+### Fixed
+
+- **Error Reporting**: Enhanced `check-prerequisites.js` with structured, actionable JSON error suggestions.
+- **Path Handling**: Fixed Windows-specific path issues in installer scripts.
+
+## [1.4.162] - 2026-03-03
 
 ### Added
 
@@ -20,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
 
-## [1.4.77] - 2026-03-02
+## [1.4.162] - 2026-03-02
 
 ### Changed
 

package/README.md

@@ -55,16 +55,23 @@ root-project/
 
 Magic Spec is built around a single conviction: **AI agents write better code when they are forced to think before they act.** Left unconstrained, they jump straight to implementation — producing code that is fragile, misaligned, and expensive to refactor. Magic Spec installs a structured pipeline that makes this impossible.
 
-### Human-Minimal Engineering
+### Human-Minimal Engineering (Autonomous Partner)
 
-The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters.
+The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters. Magic Spec moves from manual "Status Gates" to an **Autonomous Partner** model.
+
+#### Trust Mode: Encapsulated Logic
 
 Once you describe what you want, the engine takes over:
 
-- Specifications are drafted, reviewed, and promoted through their lifecycle automatically.
-- Tasks are decomposed, prioritized, and assigned default values without prompting.
-- Phases execute end-to-end: retrospective snapshots fire, changelogs are compiled, and context files are regenerated — all silently.
-- The only moments requiring human input are deliberate gates: approving a spec before implementation begins, and signing off on an external release changelog.
+- **Type A — "AI Trust"**: You provide intent, the agent handles the rest (`Draft -> RFC -> Stable -> Plan -> Run`). The internal SDD ceremony is **encapsulated** — you only see the result and a final "Go" gate.
+- **Type B — "Expert Audit"**: You maintain full control. Inspect `.design/` at any time to review specifications and plans. The rigor is there for when you need it.
+
+#### Silent Orchestration
+
+- **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
+- **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
+- **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
+- **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
 
 Everything else is automated. The agent does the engineering. You approve the direction.
 
@@ -87,6 +94,7 @@ This separation prevents a common failure mode in AI-assisted development: mixin
 The engine actively protects specification integrity throughout the project lifecycle:
 
 - **Quarantine Cascade**: If a Layer 1 spec is destabilized (demoted from `Stable`), all dependent Layer 2 specs are automatically flagged and their tasks are blocked. The plan cannot proceed on a broken foundation.
+- **Session Isolation (Phase Gates)**: To prevent AI "hallucinations" and context bleed-over, major workflow transitions enforce a **Hard Stop** (e.g., from Specification to Planning). You are required to physically open a "New Chat" in your IDE to proceed. Simply telling the AI to "forget" does not clear its context window reliably.
 - **Registry Parity**: Every spec that exists on disk must be registered in `INDEX.md`. Every registered spec must appear in the implementation plan or the backlog. Orphaned specs are treated as critical blockers.
 - **Rules Parity**: If project conventions change (`RULES.md`), any existing task plan is flagged as stale. The agent will not execute tasks generated under outdated rules without an explicit sync.
 - **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
@@ -232,11 +240,19 @@ npx magic-spec@latest --update
 > [!TIP]
 > The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agent/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
 
+### Post-Install: `.gitignore`
+
+The installer automatically adds `.magic/` and the adapter directory (e.g., `.agent/`, `.cursor/rules/`) to your project's `.gitignore`. These directories are **installed dependencies** — similar to `node_modules/` — and should be reinstalled via `npx magic-spec@latest` rather than committed to version control.
+
+> [!TIP]
+> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agent/` entries from your `.gitignore`.
+
 ## 💬 Usage
 
 Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
 
 - *"Dispatch this thought into specs..."* → Triggers **Specification** workflow.
+- *"Run a project audit"*, *"magic.analyze"* → Triggers **Analyze** (Ventilation) workflow.
 - *"Create an implementation plan"* → Triggers **Task & Plan** workflow.
 - *"Execute the next task"* → Triggers **Run** workflow.
 - *"Add a rule: always use Inter font"* → Triggers **Rule** workflow.

package/installers/config.json

@@ -5,8 +5,13 @@
     "engineDir": ".magic",
     "agentDir": ".agent",
     "workflowsDir": "workflows",
+    "designDir": ".design",
+    "versionFile": ".version",
+    "checksumsFile": ".checksums",
+    "historyDir": "history",
     "defaultExt": ".md",
     "workflows": [
+        "magic.analyze",
         "magic.onboard",
         "magic.rule",
         "magic.run",
@@ -32,7 +37,7 @@
         "scripts/init.js",
         "templates/plan.md",
         "templates/retrospective.md",
-        "templates/specification.md",
+        "templates/spec.md",
         "templates/tasks.md"
     ],
     "download": {
@@ -64,6 +69,9 @@
         ],
         "docsDir": "docs"
     },
+    "git": {
+        "defaultBranch": "master"
+    },
     "tests": {
         "sandboxDir": "installers/tests/sandbox",
         "adaptersJson": "installers/adapters.json",

package/installers/node/index.js

@@ -77,6 +77,11 @@ function loadInstallerConfig() {
         failConfig("field 'magicFiles' must be an array of strings");
     }
 
+    const designDir = requireNonEmptyString(parsed.designDir, 'designDir');
+    const versionFile = requireNonEmptyString(parsed.versionFile, 'versionFile');
+    const checksumsFile = requireNonEmptyString(parsed.checksumsFile, 'checksumsFile');
+    const historyDir = requireNonEmptyString(parsed.historyDir, 'historyDir');
+
     return {
         githubRepo,
         packageName,
@@ -84,6 +89,10 @@ function loadInstallerConfig() {
         engineDir,
         agentDir,
         workflowsDir,
+        designDir,
+        versionFile,
+        checksumsFile,
+        historyDir,
         defaultExt,
         workflows,
         magicFiles,
@@ -102,6 +111,10 @@ const WORKFLOWS_DIR = INSTALLER_CONFIG.workflowsDir;
 const DEFAULT_EXT = INSTALLER_CONFIG.defaultExt;
 const WORKFLOWS = INSTALLER_CONFIG.workflows;
 const MAGIC_FILES = INSTALLER_CONFIG.magicFiles;
+const DESIGN_DIR = INSTALLER_CONFIG.designDir;
+const VERSION_FILE = INSTALLER_CONFIG.versionFile;
+const CHECKSUMS_FILE = INSTALLER_CONFIG.checksumsFile;
+const HISTORY_DIR = INSTALLER_CONFIG.historyDir;
 const DEFAULT_REMOVE_PREFIX = INSTALLER_CONFIG.removePrefix;
 const DOWNLOAD_TIMEOUT_MS = INSTALLER_CONFIG.download.timeoutMs;
 const NODE_USER_AGENT = INSTALLER_CONFIG.userAgent.node;
@@ -178,6 +191,45 @@ function copyDir(src, dest) {
     fs.cpSync(src, dest, { recursive: true, force: true });
 }
 
+function appendToGitignore(entries) {
+    const gitignoreFile = path.join(cwd, '.gitignore');
+    let content = '';
+    if (fs.existsSync(gitignoreFile)) {
+        content = fs.readFileSync(gitignoreFile, 'utf8');
+    }
+
+    const added = [];
+    for (const entry of entries) {
+        // Normalize: ensure trailing slash for directories
+        const normalized = entry.endsWith('/') ? entry : entry + '/';
+        // Check if already present (with or without trailing slash)
+        const base = normalized.replace(/\/$/, '');
+        const alreadyPresent = content.split(/\r?\n/).some(line => {
+            const trimmed = line.trim();
+            return trimmed === base || trimmed === normalized;
+        });
+        if (!alreadyPresent) {
+            added.push(normalized);
+        }
+    }
+
+    if (added.length === 0) return;
+
+    // Append under a Magic Spec section header
+    const section = '\n# Magic Spec (engine & workflows — installed via npx/uvx)';
+    const hasSection = content.includes('# Magic Spec');
+    let appendBlock = '';
+    if (!hasSection) {
+        appendBlock = section + '\n';
+    }
+    appendBlock += added.join('\n');
+
+    content = content.trimEnd() + '\n' + appendBlock + '\n';
+    fs.writeFileSync(gitignoreFile, content, 'utf8');
+    console.log(`📝 Updated .gitignore: added ${added.join(', ')}`);
+    console.log(`   💡 To vendor engine files in your repo, remove these entries.`);
+}
+
 function convertToToml(content, description) {
     // Escape quotes and backslashes for TOML triple-quoted strings
     const escapedContent = content
@@ -327,7 +379,7 @@ function runDoctor() {
                 console.log(`✅ ${item.path || name} is present`);
             } else {
                 const hint = requiredHint ? ` (Hint: ${requiredHint})` : '';
-                console.log(`❌ .design/${name} is missing${hint}`);
+                console.log(`❌ ${DESIGN_DIR}/${name} is missing${hint}`);
             }
         };
 
@@ -363,12 +415,12 @@ function runInfo() {
     console.log('magic-spec installation status');
     console.log('────────────────────────────────');
 
-    const versionFile = path.join(cwd, '.magic', '.version');
+    const versionFilePath = path.join(cwd, ENGINE_DIR, VERSION_FILE);
     let installedVersion = 'none';
-    if (fs.existsSync(versionFile)) {
-        installedVersion = fs.readFileSync(versionFile, 'utf8').trim();
+    if (fs.existsSync(versionFilePath)) {
+        installedVersion = fs.readFileSync(versionFilePath, 'utf8').trim();
     }
-    console.log(`Installed version : ${installedVersion}  (.magic/.version)`);
+    console.log(`Installed version : ${installedVersion}  (${ENGINE_DIR}/${VERSION_FILE})`);
 
     const ADAPTERS_PATH = path.join(__dirname, '..', 'adapters.json');
     let activeEnvs = [];
@@ -387,8 +439,8 @@ function runInfo() {
     const enginePresent = fs.existsSync(path.join(cwd, ENGINE_DIR));
     console.log(`Engine            : ${ENGINE_DIR}/     ${enginePresent ? '✅ present' : '❌ missing'}`);
 
-    const designPresent = fs.existsSync(path.join(cwd, '.design'));
-    console.log(`Workspace         : .design/    ${designPresent ? '✅ present' : '❌ missing'}`);
+    const designPresent = fs.existsSync(path.join(cwd, DESIGN_DIR));
+    console.log(`Workspace         : ${DESIGN_DIR}/    ${designPresent ? '✅ present' : '❌ missing'}`);
 
     console.log('────────────────────────────────');
     console.log(`Run \`npx ${PACKAGE_NAME}@latest --update\` to refresh engine files.`);
@@ -396,9 +448,9 @@ function runInfo() {
 }
 
 function runCheck() {
-    const versionFile = path.join(cwd, ENGINE_DIR, '.version');
+    const versionFile = path.join(cwd, ENGINE_DIR, VERSION_FILE);
     if (!fs.existsSync(versionFile)) {
-        console.log(`⚠️  Not installed via magic-spec (no ${ENGINE_DIR}/.version file)`);
+        console.log(`⚠️  Not installed via magic-spec (no ${ENGINE_DIR}/${VERSION_FILE} file)`);
         process.exit(0);
     }
 
@@ -451,7 +503,7 @@ async function runEject() {
     console.log(`   -  ${ENGINE_DIR}/`);
     console.log(`   -  ${AGENT_DIR}/  (or active env adapter dir)`);
     console.log(`   -  ${ENGINE_DIR}.bak/  (if exists)`);
-    console.log('\n   Your .design/ workspace will NOT be affected.');
+    console.log(`\n   Your ${DESIGN_DIR}/ workspace will NOT be affected.`);
 
     let shouldRun = autoAccept;
     if (!shouldRun) {
@@ -500,10 +552,10 @@ function getDirectoryChecksums(dir, baseDir = dir) {
     for (const item of items) {
         const fullPath = path.join(dir, item.name);
         if (item.isDirectory()) {
-            if (item.name === '.checksums' || item.name === 'history') continue;
+            if (item.name === CHECKSUMS_FILE || item.name === HISTORY_DIR) continue;
             Object.assign(results, getDirectoryChecksums(fullPath, baseDir));
         } else {
-            if (item.name === '.checksums') continue;
+            if (item.name === CHECKSUMS_FILE) continue;
             const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
             results[relPath] = getFileChecksum(fullPath);
         }
@@ -512,22 +564,22 @@ function getDirectoryChecksums(dir, baseDir = dir) {
 }
 
 async function handleConflicts(cwd) {
-    const checksumsFile = path.join(cwd, '.magic', '.checksums');
-    if (!fs.existsSync(checksumsFile)) return;
+    const checksumsFilePath = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
+    if (!fs.existsSync(checksumsFilePath)) return;
 
     let storedChecksums = {};
     try {
-        storedChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
+        storedChecksums = JSON.parse(fs.readFileSync(checksumsFilePath, 'utf8'));
     } catch (e) {
         return;
     }
 
     const conflicts = [];
     for (const [relPath, storedHash] of Object.entries(storedChecksums)) {
-        if (relPath === '.checksums' || relPath === '.version') continue;
+        if (relPath === CHECKSUMS_FILE || relPath === VERSION_FILE) continue;
 
-        // Backward compatibility: try .magic first, then project root
-        let localPath = path.join(cwd, '.magic', relPath);
+        // Backward compatibility: try engine dir first, then project root
+        let localPath = path.join(cwd, ENGINE_DIR, relPath);
         if (!fs.existsSync(localPath)) {
             localPath = path.join(cwd, relPath);
         }
@@ -733,6 +785,7 @@ async function main() {
     }
 
     try {
+        let selectedEnvResolved = null;
         if (!isLocal) {
             sourceRoot = await downloadPayload(versionToFetch);
         }
@@ -863,8 +916,8 @@ async function main() {
         if (!isUpdate) {
             const isWindows = process.platform === 'win32';
             const initScript = isWindows
-                ? path.join(cwd, '.magic', 'scripts', 'init.ps1')
-                : path.join(cwd, '.magic', 'scripts', 'init.sh');
+                ? path.join(cwd, ENGINE_DIR, 'scripts', 'init.ps1')
+                : path.join(cwd, ENGINE_DIR, 'scripts', 'init.sh');
 
             if (fs.existsSync(initScript)) {
                 let shouldRun = true;
@@ -901,21 +954,36 @@ async function main() {
             console.log(`✅ ${PACKAGE_NAME} updated successfully!`);
         }
 
-        // 4. Write version file (.magic/.version) - [T-2B01]
+        // 4. Write version file - [T-2B01]
         try {
-            const versionFile = path.join(cwd, '.magic', '.version');
-            fs.writeFileSync(versionFile, version, 'utf8');
+            const versionFileDest = path.join(cwd, ENGINE_DIR, VERSION_FILE);
+            fs.writeFileSync(versionFileDest, version, 'utf8');
         } catch (vErr) {
-            console.warn(`⚠️  Failed to write .magic/.version: ${vErr.message}`);
+            console.warn(`⚠️  Failed to write ${ENGINE_DIR}/${VERSION_FILE}: ${vErr.message}`);
         }
 
+        // 5. Auto-update .gitignore
+        const gitignoreEntries = [ENGINE_DIR];
+        if (envValues.length > 0) {
+            for (const env of envValues) {
+                const adapter = ADAPTERS[env];
+                if (adapter && adapter.dest) {
+                    gitignoreEntries.push(adapter.dest);
+                }
+            }
+        } else if (selectedEnvResolved && ADAPTERS[selectedEnvResolved]) {
+            gitignoreEntries.push(ADAPTERS[selectedEnvResolved].dest);
+        } else {
+            gitignoreEntries.push(AGENT_DIR);
+        }
+        appendToGitignore(gitignoreEntries);
 
         // 6. Save checksums - [T-2C03]
         try {
-            const currentChecksums = getDirectoryChecksums(path.join(cwd, '.magic'));
+            const currentChecksums = getDirectoryChecksums(path.join(cwd, ENGINE_DIR));
 
             if (isUpdate) {
-                const checksumsFile = path.join(cwd, '.magic', '.checksums');
+                const checksumsFile = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
                 if (fs.existsSync(checksumsFile)) {
                     try {
                         const oldChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
@@ -930,7 +998,7 @@ async function main() {
 
             Object.assign(currentChecksums, adapterChecksums);
 
-            fs.writeFileSync(path.join(cwd, '.magic', '.checksums'), JSON.stringify(currentChecksums, null, 2), 'utf8');
+            fs.writeFileSync(path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE), JSON.stringify(currentChecksums, null, 2), 'utf8');
         } catch (cErr) {
             console.warn(`⚠️  Failed to save checksums: ${cErr.message}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-spec",
-  "version": "1.4.77",
+  "version": "1.4.162",
   "description": "Magic Specification-Driven Development (SDD) Workflow",
   "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
   "license": "MIT",