magic-spec 1.4.162 → 1.5.71

package/CHANGELOG.md

@@ -5,6 +5,98 @@ 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.5.70] - 2026-03-30
+
+### Changed
+
+- **Documentation**: Updated `README.md` and `docs/README.md` to include a mandatory recommendation to run `/magic.analyze` after updating the Magic Spec engine. This ensures that specifications and engine metadata remain synchronized after a core logic update.
+
+### Meta
+
+- **Automated Update**: Engine version bumped to `1.5.70`, history updated, and checksums regenerated (C14).
+
+## [1.5.71] - 2026-03-26
+
+### Added
+
+- **Gitignore Safety (Invariant 8)** in `analyze.md`: The agent now MUST scan and apply `.gitignore` patterns before any project scan or architecture inference. This prevents `node_modules`, `dist`, `.venv`, and other build artifacts from leaking into the analysis reports or coverage checks.
+
+### Changed
+
+- **Stack & Structure**: Refined the initial scan step to build the high-level project map only *after* applying gitignore filters.
+
+### Meta
+
+- **Automated Update**: Engine version bumped to `1.5.71`, history updated, and checksums regenerated (C14).
+
+## [1.5.50] - 2026-03-26
+
+### Added
+
+- **Anti-Stall Mechanism (Invariant 12)**: Solved the "AI holds specs in mind" issue (reported by user). The agent is now forced to write a `Draft` spec if it asks more than one clarifying question without file creation. Added `<!-- TBD -->` inline markers for ambiguous sections.
+- **Mode Transition Protocol**: Defined explicit triggers to exit `Explore Mode` and enter `Dispatch Mode` automatically (3+ topics, confirmation words, or 2nd idea exchange in Trust Mode).
+- **Non-Blocking Dispatch Notice**: Reframed "Notice of Intent" as a statement of action rather than a question to prevent infinite loops.
+
+### Changed
+
+- **Analysis Mode Scope**: Strictly limited the "do not modify specs/registry" prohibition to `Project Analysis Delegation` mode, allowing normal `Dispatch` to proceed without friction.
+- **Workflow Wrapper**: Updated `.agents/workflows/magic.spec.md` to align with the new non-blocking exploration logic.
+
+### Meta
+
+- **Automated Update**: Engine version bumped to `1.5.50`, history updated, and checksums regenerated (C14).
+
+## [1.5.49] - 2026-03-25
+
+### Added
+
+- **Config Drift Guard**: `check-prerequisites` now detects uncommitted manual changes to `RULES.md` via `git diff` and emits a non-blocking `CONFIG_DRIFT` advisory warning. Supports workspace-specific `RULES.md` per C22. Gracefully skips when git is unavailable.
+- **Init Workflow**: Added Config Drift Advisory sub-step to pre-flight check (show diff / proceed / restore options).
+- **Test Suite**: Added cognitive tests T168-T170 for config drift detection (drift present, no git, workspace C22). Suite version bumped to 1.9.51.
+- **Engine Spec**: New `config-drift-guard.md` specification (Stable, L1) in engine workspace.
+
+## [1.5.48] - 2026-03-24
+
+### Added
+
+- **Publish Workflow**: Restored `.agents/workflows/publish.md` for engine maintenance and registry publishing.
+- **History Tracking**: Initialized history for `magic.analyze` and `magic.dev.simulate` wrappers to ensure full auditability.
+
+### Changed
+
+- **Version Synchronization**: Unified project version to `1.5.71` across all manifests (`package.json`, `pyproject.toml`, `__init__.py`) and the `.magic/.version` engine core.
+- **Instruction Density**: Refined `.magic/simulate.md` (Context Bleed Warning) to remove vague qualifiers ("high-confidence" -> "strictly unbiased"), reaching a density score of 10/10.
+- **Engine Integrity**: Optimized `generate-checksums.js` to exclude the `.checksums` file from its own mapping, preventing confusion and unstable hash values.
+
+### Fixed
+
+- **Testing Logic**: Corrected `run_tests.py` to properly set `PYTHONPATH` for Python installer subprocesses and fixed an `os.environ` access bug.
+- **Sandbox Cleanup**: Removed dev-only `simulate.md` from installer test sandbox.
+- **RULES Template**: Added missing conventions C18-C23 to `init.js` RULES.md generator.
+- **Python Installer**: Fixed `_resolve_package_version()` to read actual package version.
+- **Engine Scripts**: Deduplicated `workspace.json` reads in `executor.js`.
+- **History Cleanup**: Removed legacy `audit.md` and `docs.md` files from `.magic/history/`.
+
+## [1.5.30] - 2026-03-24
+
+### Fixed
+
+- **Version Synchronization**: Unified project version across `package.json` (was 1.5.0), `pyproject.toml` (was 1.4.162), and `__init__.py` (was 1.4.162) to a single `1.5.30`. Previously 5 different versions existed across 5 sources.
+- **CONTEXT.md**: Regenerated stale context file (was 9 days old).
+
+## [1.5.29] - 2026-03-16
+
+### Added
+
+- **Argument Routing (A–D)** for `task.md` and `run.md`: Both workflows now accept optional arguments — workspace name, directive text, or both. Consistent with `analyze.md` pattern. Includes Workspace Fallback, Disambiguation, and Handoff Propagation rules.
+- **T4 Inline Guards** in `spec.md`: When spec workflow captures a standing rule via T4 trigger ("remember that..."), it now applies Tier Routing (global vs workspace RULES.md), Duplication Check (across both tiers), and Constitutional Guard (§1–6 protection) — matching `rule.md` safety guarantees without breaking T4's "Apply Immediately" semantics.
+- **Regression Tests (T153–T161)**: 9 new scenarios covering argument routing (scoped planning, workspace fallback, disambiguation, targeted task/phase execution, cross-workflow handoff propagation) and T4 inline guards (tier routing, duplication detection, constitutional block).
+
+### Changed
+
+- **AGENTS.md**: Clarified C14 Enforcement scope — explicitly covers all `.magic/` content (workflows, scripts, templates, tests, config), not just workflow files. Added description of what `update-engine-meta` does (bumps `.version`, regenerates `.checksums`).
+- **`run.md` Argument Routing**: Detection column harmonized with `analyze.md` — accepts both quoted text and non-workspace tokens (e.g., unquoted `T-1A01` or `phase-2`).
+
 ## [1.4.162] - 2026-03-12
 
 ### Added
@@ -16,7 +108,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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.
+- **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agents/` directories with idempotent updates.
 - **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
 
 ### Fixed
@@ -113,7 +205,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.3.1] - 2026-02-27### Added
 
-- **Workflow Test Suite** (`.magic/tests/suite.md`): 16 predefined regression test scenarios covering all 8 engine workflows. Run via `/magic.simulate test`.
+- **Workflow Test Suite** (`.magic/tests/suite.md`): 16 predefined regression test scenarios covering all 8 engine workflows. Run via `/magic.dev.simulate test`.
 - **Test Suite mode** in `simulate.md`: reads `suite.md` and reports PASS/FAIL for each scenario.
 - **Template directory** (`.magic/templates/`): extracted inline templates from core workflow files:
   - `specification.md` — Specification Template (from `spec.md`)
@@ -164,8 +256,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **System Automation Hooks:** Added `generate-context` script hooks into `task.md` and `run.md` post-write triggers.
 - **Context Automation Script:** Created `generate-context.sh` and `generate-context.ps1` to assemble `CONTEXT.md` from PLAN, workspace trees, and changelogs.
 - **Spec Engine Protections:** Added strict Explore Mode Safety rules and Delta Editing constraints for spec updates over 200 lines to `.magic/spec.md`.
-- **Explore Hints:** Updated `.agent/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
+- **Explore Hints:** Updated `.agents/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
 - **CLI Doctor Command (Node/Python):** Implemented `--doctor` and `--check` parsing in installers, executing the prerequisite script and outputting a formatted terminal validation report.
 - **Interactive Onboarding Script:** Created `.magic/onboard.md` to guide new developers through building a toy "console logger" specification.
-- **Onboarding Wrapper:** Added `.agent/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
+- **Onboarding Wrapper:** Added `.agents/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
 - **Prerequisite Validation:** Created `check-prerequisites.sh` and `check-prerequisites.ps1` parsing `INDEX.md` and returning valid JSON results.

package/README.md

@@ -36,15 +36,14 @@ After running the installer, your project directory will be augmented with the f
 
 ```plaintext
 root-project/
-├── .agent/workflows/         # Slash commands wrapper (e.g., magic.spec, magic.task)
+├── .agents/workflows/         # Slash commands wrapper (e.g., magic.spec, magic.task)
 ├── .magic/                   # The SDD Engine (workflow logic and scripts - read-only)
 └── .design/                  # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
 ```
 
 1. **`.magic/`**: Deploys the core SDD engine.
-2. **`.agent/`**: Sets up workflows for your AI.
+2. **`.agents/`**: Sets up workflows for your AI.
 3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
-4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
 
 > [!TIP]
 > **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
@@ -172,7 +171,7 @@ Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or a
 **Stable Release:**
 
 ```bash
-# Basic installation (defaults to .agent/ folder)
+# Basic installation (defaults to .agents/ folder)
 npx magic-spec@latest
 
 # Targeted installation for Cursor
@@ -222,7 +221,7 @@ npx magic-spec@latest --cursor --copilot --windsurf
 If automated installers do not fit your environment:
 
 1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
-2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
+2. **Workflows**: Download command wrappers from [`workflows/`](https://github.com/teratron/magic-spec/tree/main/workflows).
 3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
 
 ## 🔄 Updating
@@ -238,14 +237,14 @@ 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).
+> The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agents/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort). **After updating Magic Spec, it is highly recommended to run the `/magic.analyze` command to ensure your project's specifications and engine metadata are fully synchronized.**
 
 ### 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.
+The installer automatically adds `.magic/` and the adapter directory (e.g., `.agents/`, `.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`.
+> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agents/` entries from your `.gitignore`.
 
 ## 💬 Usage
 
@@ -289,14 +288,13 @@ You can install support for a specific adapter using the shortcut flag (e.g., `-
 
 - [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
 - [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
-- [**Contributing**](./docs/contributing.md) — How to develop, test, and extend the engine.
+- [**Contributing**](./CONTRIBUTING.md) — How to develop, test, and extend the engine.
 
 ## 🛟 Support
 
 If you encounter issues or have questions:
 
 - Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
-- Run `magic.onboard` in your agent to restart the interactive tutorial.
 
 ## 🗺️ Roadmap
 
@@ -309,7 +307,7 @@ If you encounter issues or have questions:
 ## 🏗️ Contributing
 
 We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
-Please see [**Contributing Guide**](./docs/contributing.md) for details.
+Please see [**Contributing Guide**](./CONTRIBUTING.md) for details.
 
 ## 👥 Authors and Acknowledgments
 

package/installers/config.json

@@ -1,31 +1,27 @@
 {
     "githubRepo": "teratron/magic-spec",
     "packageName": "magic-spec",
-    "removePrefix": "magic.",
     "engineDir": ".magic",
-    "agentDir": ".agent",
+    "agentDir": ".agents",
     "workflowsDir": "workflows",
+    "defaultExt": ".md",
     "designDir": ".design",
     "versionFile": ".version",
     "checksumsFile": ".checksums",
     "historyDir": "history",
-    "defaultExt": ".md",
     "workflows": [
         "magic.analyze",
-        "magic.onboard",
         "magic.rule",
         "magic.run",
-        "magic.simulate",
         "magic.spec",
         "magic.task"
     ],
     "magicFiles": [
         "analyze.md",
-        "onboard.md",
+        "init.md",
         "retrospective.md",
         "rule.md",
         "run.md",
-        "simulate.md",
         "spec.md",
         "task.md",
         ".version",
@@ -41,39 +37,32 @@
         "templates/tasks.md"
     ],
     "download": {
-        "timeoutMs": 60000,
-        "tempPrefix": "magic-spec-"
+        "timeoutMs": 10000,
+        "tempPrefix": "magic-spec-tmp-"
     },
     "userAgent": {
-        "node": "magic-spec-node",
-        "python": "magic-spec-cli"
+        "python": "magic-spec-python-installer/1.0",
+        "node": "magic-spec-node-installer/1.0"
     },
     "eject": {
         "targets": [
             ".magic",
-            ".agent",
-            ".magic.bak",
-            ".agent.bak"
+            ".agents",
+            "installers"
         ]
     },
     "publish": {
         "versionFiles": [
-            "pyproject.toml",
-            "installers/python/magic_spec/__init__.py",
             "package.json",
-            ".magic/.version"
+            "pyproject.toml",
+            "installers/python/magic_spec/__init__.py"
         ],
         "docsTargets": [
-            "README.md",
             "CHANGELOG.md"
-        ],
-        "docsDir": "docs"
-    },
-    "git": {
-        "defaultBranch": "master"
+        ]
     },
     "tests": {
-        "sandboxDir": "installers/tests/sandbox",
+        "sandboxDir": "tmp/sandbox",
         "adaptersJson": "installers/adapters.json",
         "pythonInstaller": "installers/python/magic_spec/__main__.py",
         "nodeInstaller": "installers/node/index.js",

package/installers/node/index.js

@@ -297,7 +297,7 @@ function installAdapter(sourceRoot, env, adapters, conflictsToSkip = []) {
         installedChecksums[relTarget] = crypto.createHash('sha256').update(finalContent).digest('hex');
     }
 
-    // Copy other files in .agent if any
+    // Copy other files in .agents if any
     const srcEng = path.join(sourceRoot, AGENT_DIR);
     if (fs.existsSync(srcEng)) {
         const items = fs.readdirSync(srcEng, { withFileTypes: true });
@@ -893,7 +893,7 @@ async function main() {
                 }
             }
 
-            // Copy other files in .agent if any (not workflows subfolder which we handled selectively)
+            // Copy other files in .agents if any (not workflows subfolder which we handled selectively)
             if (fs.existsSync(srcEng)) {
                 const items = fs.readdirSync(srcEng, { withFileTypes: true });
                 for (const item of items) {

package/package.json

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