deepmodel-dmx 0.3.3__tar.gz → 0.3.4__tar.gz

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/CHANGELOG.md

@@ -7,6 +7,17 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [Unreleased]
+
+## [0.3.4] — 2026-09-08
+
+### Fixed
+
+- Loop run state (`.dmx/jobs/{job_id}/*.json`) and the session-note breadcrumb `_finish_loop` writes to `activeContext.md` are now committed once a loop run genuinely finishes (not `paused`/`iterating`), instead of being left as an uncommitted, local-only change — matching the README's documented "committed with the PR" contract for `jobs/`. This mattered most for the bundled `release` loop, which has no `on_complete` chain target: nothing downstream ran to commit its final state, and `close-ticket` explicitly makes no `.dmx/` changes before force-deleting the branch, so the loop's own "complete" outcome was silently and permanently lost every time. Silent no-op outside a git repo or when there's nothing to commit; if a commit is attempted but fails (e.g. rejected by a pre-commit hook), the loop's own response now surfaces a warning instead of only logging it server-side, and every git call is timeout-bounded so a hung `git commit` (e.g. waiting on a GPG passphrase) can't hang the whole MCP tool call. (GH-23)
+- `close-ticket` no longer transitions the ticket to Done/Complete (or adds the "PR merged" comment) unless Step 4 actually found a merged PR for the branch — previously the transition step ran unconditionally, so running `/dmx/close-ticket` while a PR was still open could mark the ticket Done before the code had actually merged. Also hardened the transition itself to treat an already-terminal ticket/issue as a no-op success rather than an error (idempotent for `github-issues`' auto-close-via-`Closes #N`, and for Jira setups where a GitHub↔Jira integration already auto-transitioned the ticket). (GH-21)
+- `draft-release-note` now commits and pushes `.dmx/releases/{version}.md` after writing it, instead of leaving it as an uncommitted local file. `release-merge` opens its PR straight from `{branch_base}`'s pushed state, so the release notes file was previously silently absent from that PR's diff whenever it hadn't been committed by hand first. Re-running it against unchanged content (nothing new merged) is a no-op rather than failing on "nothing to commit". (GH-22)
+- Starting the `spec` loop, or running `/dmx/create-ticket` manually, on a repository with zero commits now surfaces a clear, actionable error instead of a confusing one. Previously, `current_branch()` (which shells out to `git rev-parse --abbrev-ref HEAD`) silently returned `None` on a freshly `git init`'d repo's unborn `HEAD`, causing the `spec` loop's branch guard to fail with a generic "could not determine the current git branch" message — even though the branch name itself was perfectly resolvable. `_branch_guard_error` now distinguishes this specific case and tells the user to commit and push before retrying. `dmx-create-ticket.md` gained the same check as its new Step 2, so manual/foreground usage fails fast before creating a ticket or attempting to branch, rather than failing later when GitHub's `create_branch` API rejects branching from a ref-less remote. (GH-19)
+
 ## [0.3.3] — 2026-09-02
 
 ### Fixed

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepmodel-dmx
-Version: 0.3.3
+Version: 0.3.4
 Summary: AI SDLC MCP server — skills and rules for any AI IDE.
 License: AGPL-3.0
 License-File: LICENSE
@@ -90,7 +90,7 @@ Bundled loops for the SDLC pipeline:
 | `plan` | plan | `dev` |
 | `dev` | implement-next-phase, commit | `validate` |
 | `validate` | validate | `release` |
-| `release` | create-pr, update-memory | — |
+| `release` | create-pr | — |
 
 Each loop config defines a goal state, optional `repeat_until` condition, validators, human gate policy, and `on_complete` chaining. Run state is written to `.dmx/jobs/{job_id}/{loop_name}-{task_id}.json` — there's no separate active-run pointer; the active run is derived by scanning a job's state files for the one non-terminal (`pending`/`running`/`paused`/`iterating`) entry, keyed off the current branch/ticket. This keeps loop state isolated per branch: pausing work on one branch and running a loop on another can't corrupt or lose either one's state.
 
@@ -121,12 +121,111 @@ Loop-level memory hooks: before the first skill runs, the runtime surfaces `acti
 }
 ```
 
-Add to your IDE config ([Claude Code, Copilot, Antigravity ↓](#step-1--add-the-mcp-server)). Run `/dmx/init` once per project. Then:
+Add to your IDE config ([Claude Code, Copilot, Antigravity ↓](#step-1--add-the-mcp-server)). Then follow [Your first project](#your-first-project) to initialize and run the full loop on a new repo.
+
+## Your first project
+
+A brand-new repo, from `/dmx/init` through the first merged PR. You review at every gate; `/dmx/loop-continue` is how you move forward.
+
+### Before you start
+
+- A GitHub repo cloned locally with an `origin` remote. The spec loop creates the feature branch on GitHub from `origin/{branch_base}` (usually `main` or `master`), even if you track work in Jira or use no ticketing system.
+- The dmx MCP server added to your IDE ([install guide](#step-1--add-the-mcp-server)).
+- The GitHub MCP server (`user-github`) authenticated. `/dmx/init` probes it before writing any files.
+- The Atlassian MCP server only if you will choose Jira at init.
+
+### 1. Initialize
+
+On the integration branch (`main` or `master`):
 
 ```
-/dmx/create-ticket
+/dmx/init
 ```
 
+Choose a workflow — **sdlc** (this walkthrough) or **freestyle** (no process enforced) — and a ticketing system: `none`, `github-issues`, or `jira`. Re-run `/dmx/init` at any time to switch workflow or ticketing; existing memory bank files with content are left intact.
+
+Init writes `.dmx/config.md` and the memory bank (`projectbrief.md`, `productContext.md`, `systemPatterns.md`, `techContext.md`, `activeContext.md`). Open a **new chat** so the IDE rules take effect.
+
+If you already have a `docs/` folder, init reads it when populating the memory bank. Writing the requirement first is slightly better; either order works.
+
+### 2. Write the product requirement
+
+Create `docs/requirements.md` at the repo root and put the product or feature description there. You can paste the requirement into chat later instead, but a file is easier to review and reuse.
+
+`docs/requirements.md` is a convention, not a dmx artifact. The spec loop uses whatever you point it at.
+
+### 3. Commit and push
+
+The spec loop must start from the configured integration branch, and it creates the remote feature branch from whatever is already on origin. Commit `.dmx/`, `docs/`, and any files init wrote, then push:
+
+```
+git add .
+git commit -m "chore: initialize dmx and capture product requirements"
+git push -u origin HEAD
+```
+
+Stay on `main` or `master`.
+
+### 4. Start the spec loop
+
+In the same message as the command, point at the requirement file or paste it:
+
+```
+/dmx/run-loop spec
+
+See docs/requirements.md
+```
+
+This creates a GitHub issue or Jira ticket (if you configured one), cuts a feature branch from `origin/{branch_base}`, checks it out, and writes `.dmx/spec.md`. Then it pauses.
+
+### 5. Answer the spec
+
+Open `.dmx/spec.md`. Fill in Technical Approach if it is incomplete, and answer every question. Empty answers or placeholders (`TBD`, `TODO`) fail the spec validator.
+
+```
+/dmx/loop-continue
+```
+
+On success the runtime auto-chains to the `plan` loop.
+
+### 6. Review the plan
+
+`plan` writes `.dmx/tasks.md` with phases and tasks, then pauses. Edit freely — this is the implementation contract.
+
+```
+/dmx/loop-continue
+```
+
+That starts the `dev` loop.
+
+### 7. Build phase by phase
+
+Each `dev` cycle:
+
+1. Implements the next unchecked phase in `tasks.md`, then pauses.
+2. Review the diff.
+3. `/dmx/loop-continue` runs **commit only**. It does not push.
+4. Review the commit.
+5. `/dmx/loop-continue` again — validators run, then either the next phase starts or the loop chains to `validate`.
+
+Repeat until every phase is checked off.
+
+### 8. Validate and open the PR
+
+After the last phase, `validate` runs the quality gate and pauses. Review the report, then `/dmx/loop-continue`. On success the `release` loop runs `create-pr`: it pushes the feature branch and opens the pull request.
+
+### 9. Merge and close
+
+Review the PR and merge it. Then:
+
+```
+/dmx/close-ticket
+```
+
+That closes the ticket, comments the PR link, and deletes the feature branch locally and on origin. `/dmx/loop-continue` after merge is not a close path — the release loop ends when the PR exists.
+
+You can run the same steps by hand (`/dmx/create-ticket`, `/dmx/plan`, `/dmx/implement-next-phase`, …) instead of loops. See the skill catalog below.
+
 ## Learn more
 
 - [When Is a Loop Ready to Run Without You?](https://himakara.hashnode.dev/when-is-a-loop-ready-to-run-without-you) — the thinking behind dmx
@@ -208,6 +307,10 @@ Safe to re-run. Updates config without overwriting memory bank files that alread
 
 ### Step 3 — Start your first ticket
 
+On a new repo, follow [Your first project](#your-first-project) (`/dmx/run-loop spec` through `/dmx/close-ticket`).
+
+To start a ticket by hand instead:
+
 ```
 /dmx/create-ticket
 ```

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/README.md

@@ -55,7 +55,7 @@ Bundled loops for the SDLC pipeline:
 | `plan` | plan | `dev` |
 | `dev` | implement-next-phase, commit | `validate` |
 | `validate` | validate | `release` |
-| `release` | create-pr, update-memory | — |
+| `release` | create-pr | — |
 
 Each loop config defines a goal state, optional `repeat_until` condition, validators, human gate policy, and `on_complete` chaining. Run state is written to `.dmx/jobs/{job_id}/{loop_name}-{task_id}.json` — there's no separate active-run pointer; the active run is derived by scanning a job's state files for the one non-terminal (`pending`/`running`/`paused`/`iterating`) entry, keyed off the current branch/ticket. This keeps loop state isolated per branch: pausing work on one branch and running a loop on another can't corrupt or lose either one's state.
 
@@ -86,12 +86,111 @@ Loop-level memory hooks: before the first skill runs, the runtime surfaces `acti
 }
 ```
 
-Add to your IDE config ([Claude Code, Copilot, Antigravity ↓](#step-1--add-the-mcp-server)). Run `/dmx/init` once per project. Then:
+Add to your IDE config ([Claude Code, Copilot, Antigravity ↓](#step-1--add-the-mcp-server)). Then follow [Your first project](#your-first-project) to initialize and run the full loop on a new repo.
+
+## Your first project
+
+A brand-new repo, from `/dmx/init` through the first merged PR. You review at every gate; `/dmx/loop-continue` is how you move forward.
+
+### Before you start
+
+- A GitHub repo cloned locally with an `origin` remote. The spec loop creates the feature branch on GitHub from `origin/{branch_base}` (usually `main` or `master`), even if you track work in Jira or use no ticketing system.
+- The dmx MCP server added to your IDE ([install guide](#step-1--add-the-mcp-server)).
+- The GitHub MCP server (`user-github`) authenticated. `/dmx/init` probes it before writing any files.
+- The Atlassian MCP server only if you will choose Jira at init.
+
+### 1. Initialize
+
+On the integration branch (`main` or `master`):
 
 ```
-/dmx/create-ticket
+/dmx/init
 ```
 
+Choose a workflow — **sdlc** (this walkthrough) or **freestyle** (no process enforced) — and a ticketing system: `none`, `github-issues`, or `jira`. Re-run `/dmx/init` at any time to switch workflow or ticketing; existing memory bank files with content are left intact.
+
+Init writes `.dmx/config.md` and the memory bank (`projectbrief.md`, `productContext.md`, `systemPatterns.md`, `techContext.md`, `activeContext.md`). Open a **new chat** so the IDE rules take effect.
+
+If you already have a `docs/` folder, init reads it when populating the memory bank. Writing the requirement first is slightly better; either order works.
+
+### 2. Write the product requirement
+
+Create `docs/requirements.md` at the repo root and put the product or feature description there. You can paste the requirement into chat later instead, but a file is easier to review and reuse.
+
+`docs/requirements.md` is a convention, not a dmx artifact. The spec loop uses whatever you point it at.
+
+### 3. Commit and push
+
+The spec loop must start from the configured integration branch, and it creates the remote feature branch from whatever is already on origin. Commit `.dmx/`, `docs/`, and any files init wrote, then push:
+
+```
+git add .
+git commit -m "chore: initialize dmx and capture product requirements"
+git push -u origin HEAD
+```
+
+Stay on `main` or `master`.
+
+### 4. Start the spec loop
+
+In the same message as the command, point at the requirement file or paste it:
+
+```
+/dmx/run-loop spec
+
+See docs/requirements.md
+```
+
+This creates a GitHub issue or Jira ticket (if you configured one), cuts a feature branch from `origin/{branch_base}`, checks it out, and writes `.dmx/spec.md`. Then it pauses.
+
+### 5. Answer the spec
+
+Open `.dmx/spec.md`. Fill in Technical Approach if it is incomplete, and answer every question. Empty answers or placeholders (`TBD`, `TODO`) fail the spec validator.
+
+```
+/dmx/loop-continue
+```
+
+On success the runtime auto-chains to the `plan` loop.
+
+### 6. Review the plan
+
+`plan` writes `.dmx/tasks.md` with phases and tasks, then pauses. Edit freely — this is the implementation contract.
+
+```
+/dmx/loop-continue
+```
+
+That starts the `dev` loop.
+
+### 7. Build phase by phase
+
+Each `dev` cycle:
+
+1. Implements the next unchecked phase in `tasks.md`, then pauses.
+2. Review the diff.
+3. `/dmx/loop-continue` runs **commit only**. It does not push.
+4. Review the commit.
+5. `/dmx/loop-continue` again — validators run, then either the next phase starts or the loop chains to `validate`.
+
+Repeat until every phase is checked off.
+
+### 8. Validate and open the PR
+
+After the last phase, `validate` runs the quality gate and pauses. Review the report, then `/dmx/loop-continue`. On success the `release` loop runs `create-pr`: it pushes the feature branch and opens the pull request.
+
+### 9. Merge and close
+
+Review the PR and merge it. Then:
+
+```
+/dmx/close-ticket
+```
+
+That closes the ticket, comments the PR link, and deletes the feature branch locally and on origin. `/dmx/loop-continue` after merge is not a close path — the release loop ends when the PR exists.
+
+You can run the same steps by hand (`/dmx/create-ticket`, `/dmx/plan`, `/dmx/implement-next-phase`, …) instead of loops. See the skill catalog below.
+
 ## Learn more
 
 - [When Is a Loop Ready to Run Without You?](https://himakara.hashnode.dev/when-is-a-loop-ready-to-run-without-you) — the thinking behind dmx
@@ -173,6 +272,10 @@ Safe to re-run. Updates config without overwriting memory bank files that alread
 
 ### Step 3 — Start your first ticket
 
+On a new repo, follow [Your first project](#your-first-project) (`/dmx/run-loop spec` through `/dmx/close-ticket`).
+
+To start a ticket by hand instead:
+
 ```
 /dmx/create-ticket
 ```

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deepmodel-dmx"
-version = "0.3.3"
+version = "0.3.4"
 description = "AI SDLC MCP server — skills and rules for any AI IDE."
 readme = "README.md"
 requires-python = ">=3.11"

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/src/dmx/loop_tools.py

@@ -40,6 +40,7 @@ from __future__ import annotations
 import importlib.resources as pkg
 import logging
 import re
+import subprocess
 from pathlib import Path
 
 from fastmcp import (
@@ -150,6 +151,41 @@ def _read_branch_base(workspace_root: Path) -> str | None:
     return value if value and value != "{REQUIRED}" else None
 
 
+def _repo_has_no_commits(root: Path) -> bool:
+    """True if *root* is a git repo with an unborn HEAD (zero commits).
+
+    ``git rev-parse --abbrev-ref HEAD`` — what :func:`current_branch` uses —
+    fails on a freshly ``git init``'d repo before its first commit, even
+    though the branch name (e.g. ``main``/``master``) is perfectly
+    resolvable via ``git symbolic-ref``. This distinguishes that specific,
+    fixable case (make a commit) from other reasons ``current_branch``
+    might return ``None`` (not a git repo at all, detached HEAD, etc.),
+    which don't have an actionable one-line fix.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            cwd=root,
+        )
+    except Exception:  # noqa: BLE001
+        return False
+    if result.returncode != 0 or result.stdout.strip() != "true":
+        return False  # not a git repo at all — a different problem
+
+    try:
+        verify = subprocess.run(
+            ["git", "rev-parse", "--verify", "--quiet", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=root,
+        )
+    except Exception:  # noqa: BLE001
+        return False
+    return verify.returncode != 0
+
+
 def _branch_guard_error(root: Path, config: LoopConfig) -> str | None:
     """Return an error message if *config* declares ``require_branch`` and
     the current branch doesn't satisfy it, else None."""
@@ -166,6 +202,13 @@ def _branch_guard_error(root: Path, config: LoopConfig) -> str | None:
 
     branch = current_branch(root)
     if branch is None:
+        if _repo_has_no_commits(root):
+            return (
+                f"Cannot start the `{config.name}` loop: this repository has no commits yet. "
+                f"`{config.name}` creates a new branch from `{branch_base}` on GitHub, which "
+                "requires at least one commit to exist first. Commit something (e.g. the "
+                "`.dmx/` files `/dmx/init` just wrote) and push to origin, then try again."
+            )
         return (
             f"Cannot start the `{config.name}` loop: could not determine the current git "
             f"branch. Make sure you're in a git repository checked out to `{branch_base}`."
@@ -451,6 +494,79 @@ def _start_loop(root: Path, name: str, description: str | None = None) -> str:
 # ---------------------------------------------------------------------------
 
 
+_COMMIT_DMX_STATE_TIMEOUT_SECONDS = 15
+
+
+def _commit_dmx_state(root: Path, message: str) -> str | None:
+    """Best-effort commit of any uncommitted ``.dmx/`` changes.
+
+    Called once a loop run has genuinely finished (a terminal outcome —
+    not ``paused``/``iterating``, which will write state again on the next
+    call) so its final state — the job's state JSON and the session-note
+    breadcrumb ``_finish_loop`` just wrote to ``activeContext.md`` — isn't
+    left as an uncommitted, local-only change. This matters most for a
+    loop with no ``on_complete`` chain target (e.g. the bundled ``release``
+    loop): nothing downstream runs to commit on its behalf, and
+    ``close-ticket`` explicitly makes no ``.dmx/`` changes before
+    force-deleting the branch, so an uncommitted final state here would be
+    silently and permanently lost — see GH-23.
+
+    Silently does nothing if *root* isn't a git repo or there's nothing to
+    commit — this is a best-effort durability improvement (matching the
+    README's "committed with the PR" claim for ``.dmx/jobs/``), not
+    something that should ever break a loop response.
+
+    Every subprocess call is timeout-bounded so a hung ``git`` invocation
+    (e.g. a pre-commit hook prompting for input, or GPG signing waiting on
+    a passphrase) can't hang the whole MCP tool call indefinitely.
+
+    Returns:
+        ``None`` if there was nothing to commit or the commit succeeded.
+        A short, user-facing warning string if a commit was *attempted*
+        but failed (e.g. a pre-commit hook rejected it) — silently
+        swallowing that would defeat the entire point of this call, so
+        callers should surface it in the loop's response rather than only
+        logging it server-side.
+    """
+    try:
+        status = subprocess.run(
+            ["git", "status", "--short", "--", ".dmx/"],
+            capture_output=True,
+            text=True,
+            cwd=root,
+            timeout=_COMMIT_DMX_STATE_TIMEOUT_SECONDS,
+        )
+    except Exception:  # noqa: BLE001
+        return None
+    if status.returncode != 0 or not status.stdout.strip():
+        return None  # not a git repo, or nothing under .dmx/ to commit
+
+    try:
+        subprocess.run(
+            ["git", "add", ".dmx/"],
+            capture_output=True,
+            text=True,
+            cwd=root,
+            check=True,
+            timeout=_COMMIT_DMX_STATE_TIMEOUT_SECONDS,
+        )
+        subprocess.run(
+            ["git", "commit", "-m", message],
+            capture_output=True,
+            text=True,
+            cwd=root,
+            check=True,
+            timeout=_COMMIT_DMX_STATE_TIMEOUT_SECONDS,
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("could not auto-commit .dmx/ state (%s): %s", message, exc)
+        return (
+            "⚠️ Could not auto-commit the loop's final `.dmx/` state (see server logs for "
+            "details) — run `git status .dmx/` and commit manually if needed."
+        )
+    return None
+
+
 def _finish_loop(
     root: Path,
     job_id: str,
@@ -571,25 +687,42 @@ def _finish_loop(
                 f"{loop_name} loop completed (outcome: {outcome}) — chaining to "
                 f"{next_loop} was configured but blocked: {chain_guard_error}",
             )
-            return (
+            commit_warning = _commit_dmx_state(
+                root, f"chore: sync loop state for {loop_name} (job {job_id})"
+            )
+            message = (
                 f"{_complete_message(loop_name, job_id, outcome)}\n\n"
                 f"Configured to chain to **{next_loop}**, but it couldn't start: "
                 f"{chain_guard_error}"
             )
+            if commit_warning:
+                message += f"\n\n{commit_warning}"
+            return message
 
         append_session_note(
             root,
             f"{loop_name} loop completed (outcome: {outcome}) — "
             f"chained to {next_loop} (job `{job_id}`).",
         )
+        commit_warning = _commit_dmx_state(
+            root, f"chore: sync loop state for {loop_name} (job {job_id})"
+        )
         chain_header = (
             f"**{loop_name} loop — complete** (outcome: `{outcome}`)\n\n"
             f"Chaining automatically to **{next_loop}** loop.\n\n"
         )
+        if commit_warning:
+            chain_header += f"{commit_warning}\n\n"
         return chain_header + _start_loop(root, next_loop)
 
     append_session_note(root, f"{loop_name} loop completed (outcome: {outcome}) (job `{job_id}`).")
-    return _complete_message(loop_name, job_id, outcome)
+    commit_warning = _commit_dmx_state(
+        root, f"chore: sync loop state for {loop_name} (job {job_id})"
+    )
+    message = _complete_message(loop_name, job_id, outcome)
+    if commit_warning:
+        message += f"\n\n{commit_warning}"
+    return message
 
 
 # ---------------------------------------------------------------------------

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/src/dmx/skills/workflow/1-triage/dmx-create-ticket.md

@@ -28,7 +28,29 @@ The project configuration is injected into your context as a rule. Extract:
 
 If configuration is not available in context, fall back to reading `.dmx/config.md`. If neither is found, stop: "Project configuration not found. Run /dmx/init to set up this project."
 
-## Step 2 — Read project context
+## Step 2 — Verify the repo has at least one commit
+
+Run:
+```
+git rev-parse --verify --quiet HEAD
+```
+
+If this fails (non-zero exit, no output — an unborn `HEAD`, meaning zero commits exist yet), stop before creating anything:
+```
+This repository has no commits yet. Creating a ticket branches from `{config.branch_base}`
+on GitHub, which requires at least one commit to exist first.
+
+Commit something first, e.g. the files /dmx/init just wrote:
+  git add .
+  git commit -m "chore: initialize project"
+  git push -u origin HEAD
+
+Then run /dmx/create-ticket again.
+```
+
+Do not proceed to Step 3 in this case, even if `{{task}}` was provided.
+
+## Step 3 — Read project context
 
 Read the following memory bank files:
 - `.dmx/projectbrief.md` — project goals and scope
@@ -39,7 +61,7 @@ If `.dmx/` does not exist, stop: "Memory bank not found. Run /dmx/init to set up
 
 Store this context. It will inform the ticket content, technical approach, and spec questions.
 
-## Step 3 — Infer type
+## Step 4 — Infer type
 
 If `{{type}}` was provided, use it. Accepted values: `feature`, `bug`, `chore`.
 
@@ -53,9 +75,9 @@ Store as `branch_type` (`feature` | `bug` | `chore`).
 For Jira `issueTypeName` mapping: `feature` → `Story`, `bug` → `Bug`, `chore` → `Task`.
 For GitHub Issues label: use `branch_type` as-is.
 
-## Step 4 — Draft ticket content
+## Step 5 — Draft ticket content
 
-Using `{{task}}` and the project context from Step 2, generate a `summary` and `description`.
+Using `{{task}}` and the project context from Step 3, generate a `summary` and `description`.
 
 ### Summary
 Single sentence, max 80 characters, imperative present tense, capital first letter, no trailing period. Specific enough that scope is clear without reading the description.
@@ -86,7 +108,7 @@ Examples:
 
 Rules: write for the implementer. For bugs, lead with observed vs expected behaviour. Acceptance criteria must be independently verifiable.
 
-## Step 5 — Create the ticket
+## Step 6 — Create the ticket
 
 **If `ticketing` is `jira`:**
 
@@ -96,7 +118,7 @@ Call `createJiraIssue` on `user-atlassian`:
 ```
 cloudId:              {config.cloud_id}
 projectKey:           {config.project_key}
-issueTypeName:        {Jira type from Step 3}
+issueTypeName:        {Jira type from Step 4}
 summary:              {summary}
 description:          {description}
 assignee_account_id:  {account_id}
@@ -129,7 +151,7 @@ Store `ticket_url` = `{html_url}`.
 
 No ticket is created. `ticket_ref` = `none`. `ticket_url` = none.
 
-## Step 6 — Construct the branch name
+## Step 7 — Construct the branch name
 
 Slugify the summary:
 - Lowercase, hyphens for spaces, remove special characters, collapse consecutive hyphens, truncate to 60 chars
@@ -140,7 +162,7 @@ Slugify the summary:
 | `github-issues` | `{branch_type}-gh-{number}-{slug}` | `feature-gh-123-add-rate-limiting` |
 | `none` | `{branch_type}-{slug}` | `feature-add-rate-limiting` |
 
-## Step 7 — Create the remote branch and check out locally
+## Step 8 — Create the remote branch and check out locally
 
 Call `create_branch` on `user-github`:
 ```
@@ -158,7 +180,7 @@ git fetch origin
 git checkout {branch_name}
 ```
 
-## Step 8 — Scaffold spec.md
+## Step 9 — Scaffold spec.md
 
 Write `.dmx/spec.md`:
 
@@ -179,7 +201,7 @@ ticketing: {ticketing}
 ---
 
 ## Context
-{From ticket description Step 4 — why this work is needed in this project}
+{From ticket description Step 5 — why this work is needed in this project}
 
 ## Scope
 {Bullet list of what is included. Use project patterns to name specific layers, services, or files.}
@@ -221,7 +243,7 @@ ticketing: {ticketing}
 
 When `ticketing` is `none`, omit `ticket` from frontmatter.
 
-## Step 9 — Transition to In Progress
+## Step 10 — Transition to In Progress
 
 **If `ticketing` is `jira`:**
 Call `getTransitionsForJiraIssue` on `user-atlassian`. Find `In Progress`. Call `transitionJiraIssue`.
@@ -237,7 +259,7 @@ labels:       ["in-progress"]
 
 **If `ticketing` is `none`:** Skip.
 
-## Step 10 — Return the result
+## Step 11 — Return the result
 
 ```
 {if ticketing ≠ none} Ticket: {ticket_ref} — {summary}

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/src/dmx/skills/workflow/5-ship/dmx-close-ticket.md

@@ -67,13 +67,15 @@ head:   {config.owner}:{close_branch}
 
 Filter to PRs where `merged_at` is not null. Store `html_url` and `base.ref`.
 
-If no merged PR is found, warn: "No merged PR found for `{close_branch}`. Proceeding with branch deletion only — ticket will not be updated."
+If no merged PR is found, warn: "No merged PR found for `{close_branch}`. Proceeding with branch deletion only — ticket will not be updated." Then **skip Steps 5 and 6 entirely** — do not transition or comment on a ticket whose work hasn't actually merged yet.
 
 ## Step 5 — Transition ticket to Done
 
+Only run this step if Step 4 found a merged PR. Otherwise skip to Step 7.
+
 **If `ticketing` is `jira`:**
 1. Call `getTransitionsForJiraIssue` on `user-atlassian` with `{config.cloud_id}` and ticket ID.
-2. Find transition named `Done`. Call `transitionJiraIssue`.
+2. If no transition named `Done` is available (e.g. the ticket is already in a terminal state — possibly auto-transitioned by a GitHub↔Jira integration when the PR merged), treat this as already-done and continue; do not fail. Otherwise call `transitionJiraIssue`.
 
 **If `ticketing` is `github-issues`:**
 Call `update_issue` on `user-github`:
@@ -83,6 +85,7 @@ repo:         {config.repo}
 issue_number: {ticket number}
 state:        closed
 ```
+This is idempotent — if the issue was already auto-closed by a `Closes #N` reference in the PR body, this call succeeds as a no-op. Do not treat an already-closed issue as an error.
 
 **If `ticketing` is `none`:** Skip.
 
@@ -167,4 +170,5 @@ Next:
 
 - Never close a protected branch.
 - If the PR is not confirmed merged, warn before deleting the branch. Do not assume the work is done.
+- Never transition or comment on a ticket unless Step 4 found a merged PR — a ticket must not jump to Done while its PR is still open.
 - Make no changes to any `.dmx/` files — this skill is external-cleanup only. Memory learnings were already synced by `/dmx/create-pr`.

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/src/dmx/skills/workflow/6-release/dmx-draft-release-note.md

@@ -205,13 +205,44 @@ Create `.dmx/releases/` if it does not exist.
 
 Write the assembled release notes to `.dmx/releases/{{version}}.md`.
 
-## Step 11 — Return the result
+## Step 11 — Commit and push the release notes
+
+`/dmx/release-merge` opens a real GitHub pull request from `{config.branch_base}` — which only
+reflects what's actually pushed to origin. Leaving this file uncommitted means it silently
+never makes it into that PR's diff.
+
+Run:
+```
+git status --short .dmx/releases/{{version}}.md
+```
+
+If this reports a change:
+```
+git add .dmx/releases/{{version}}.md
+git commit -m "docs: draft release notes for {{version}}"
+git push
+```
+
+If it reports nothing (e.g. re-running against identical content — a bare `git commit` here
+would fail with "nothing to commit"), skip straight to Step 12; the file is already committed
+and pushed from a previous run.
+
+This skill must never leave `.dmx/releases/{{version}}.md` uncommitted when it was actually
+changed — do not skip the commit above just because you expect a later command to commit it.
+
+## Step 12 — Return the result
 
 Output:
 ```
 Release notes drafted: .dmx/releases/{{version}}.md
 {N} changes across {categories list}.
+{if committed in Step 11} Committed and pushed to {config.branch_base}.
+{else} Already committed from a previous run — nothing new to push.
 
 Review and edit the file, then:
   - Run /dmx/release-merge version:{{version}} to open the {config.branch_base} → {config.production_branch} PR.
 ```
+
+## Guards
+
+- Never leave `.dmx/releases/{{version}}.md` uncommitted — Step 11 is mandatory whenever the file was created or changed.

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/src/dmx/validators/check_spec_complete.py

@@ -65,7 +65,7 @@ def _qa_answered(content: str) -> tuple[bool, str]:
     Structural rather than label-based, to tolerate wording drift between
     this validator and whatever skill scaffolds spec.md: a question is
     recognized as either a numbered list item (``N. {question}`` — the
-    format ``dmx-create-ticket.md`` Step 8 actually writes) or a classic
+    format ``dmx-create-ticket.md`` Step 9 actually writes) or a classic
     ``Q:`` line. Everything following it, up to the next question or
     heading, is its answer — whether labeled ``Answer:``/``A:`` or not. A
     blank body or an explicit TBD/N/A placeholder counts as unanswered.

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/tests/test_loop_tools.py

@@ -6,6 +6,7 @@ can be exercised directly without mocking the MCP server plumbing.
 
 from __future__ import annotations
 
+import subprocess
 from typing import TYPE_CHECKING
 
 from dmx.loop_schema import LoopConfig
@@ -16,7 +17,13 @@ from dmx.loop_state import (
     read_state,
     write_initial_state,
 )
-from dmx.loop_tools import _find_active, _finish_loop, _maybe_promote_pending_job, _start_loop
+from dmx.loop_tools import (
+    _commit_dmx_state,
+    _find_active,
+    _finish_loop,
+    _maybe_promote_pending_job,
+    _start_loop,
+)
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -455,6 +462,52 @@ class TestBranchGuard:
         message = _start_loop(tmp_path, "spec")
 
         assert "cannot start" in message.lower()
+        assert "no commits yet" not in message.lower()
+
+    def test_blocks_start_with_specific_message_on_a_zero_commit_repo(self, tmp_path: Path) -> None:
+        """A freshly `git init`'d repo (no commits yet) makes
+        `git rev-parse --abbrev-ref HEAD` fail (unborn HEAD), even though the
+        branch name is perfectly real and resolvable via `git symbolic-ref`.
+        This must surface a specific, actionable message rather than the
+        generic "could not determine branch" one."""
+        (tmp_path / ".dmx").mkdir(exist_ok=True)
+        (tmp_path / ".dmx" / "config.md").write_text("branch_base: main\n", encoding="utf-8")
+        subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+
+        message = _start_loop(tmp_path, "spec")
+
+        assert "cannot start" in message.lower()
+        assert "no commits yet" in message.lower()
+        assert "commit something" in message.lower()
+        assert "get_skill_definition" not in message
+
+    def test_zero_commit_guard_does_not_fire_outside_a_git_repo(self, tmp_path: Path) -> None:
+        """A plain non-git directory must still get the generic message, not
+        be misreported as a zero-commit git repo."""
+        (tmp_path / ".dmx").mkdir(exist_ok=True)
+        (tmp_path / ".dmx" / "config.md").write_text("branch_base: main\n", encoding="utf-8")
+
+        message = _start_loop(tmp_path, "spec")
+
+        assert "cannot start" in message.lower()
+        assert "no commits yet" not in message.lower()
+
+    def test_zero_commit_guard_does_not_fire_once_a_commit_exists(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+        subprocess.run(
+            ["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True
+        )
+        subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+        (tmp_path / "README.md").write_text("hi\n", encoding="utf-8")
+        subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+        subprocess.run(["git", "commit", "-q", "-m", "initial"], cwd=tmp_path, check=True)
+        _allow_spec_loop_start(tmp_path, monkeypatch, branch="main")
+
+        message = _start_loop(tmp_path, "spec")
+
+        assert "get_skill_definition" in message
 
     def test_allows_start_from_configured_base_branch(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -574,3 +627,157 @@ class TestFindActiveAndPendingPromotion:
     def test_promote_is_noop_for_non_pending_job_id(self, tmp_path: Path) -> None:
         (tmp_path / ".dmx").mkdir(exist_ok=True)
         assert _maybe_promote_pending_job(tmp_path, "GH-9") == "GH-9"
+
+
+def _init_real_git_repo(root: Path) -> None:
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=root, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=root, check=True)
+    (root / "README.md").write_text("hi\n", encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-q", "-m", "initial"], cwd=root, check=True)
+
+
+def _dmx_dirty(root: Path) -> str:
+    result = subprocess.run(
+        ["git", "status", "--short", "--", ".dmx/"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout
+
+
+def _install_rejecting_pre_commit_hook(root: Path) -> None:
+    """Install a pre-commit hook that always rejects the commit, so
+    `git commit` fails deterministically regardless of the host's git
+    identity configuration."""
+    hooks_dir = root / ".git" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / "pre-commit"
+    hook_path.write_text("#!/bin/sh\nexit 1\n", encoding="utf-8")
+    hook_path.chmod(0o755)
+
+
+def _commit_count(root: Path) -> int:
+    result = subprocess.run(
+        ["git", "rev-list", "--count", "HEAD"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return int(result.stdout.strip())
+
+
+class TestCommitDmxState:
+    """GH-23: .dmx/jobs/*.json (and other .dmx/ writes made by _finish_loop,
+    e.g. the activeContext.md session note) must not be left as an
+    uncommitted, local-only change once a loop run has genuinely finished —
+    otherwise a terminal loop like `release`, with nothing downstream to
+    commit on its behalf, permanently loses that final state the moment
+    close-ticket force-deletes the branch."""
+
+    def test_commits_dirty_dmx_changes(self, tmp_path: Path) -> None:
+        _init_real_git_repo(tmp_path)
+        (tmp_path / ".dmx").mkdir(exist_ok=True)
+        (tmp_path / ".dmx" / "activeContext.md").write_text("note\n", encoding="utf-8")
+        before = _commit_count(tmp_path)
+
+        result = _commit_dmx_state(tmp_path, "chore: sync loop state")
+
+        assert result is None
+        assert _dmx_dirty(tmp_path) == ""
+        assert _commit_count(tmp_path) == before + 1
+
+    def test_noop_when_nothing_dirty(self, tmp_path: Path) -> None:
+        _init_real_git_repo(tmp_path)
+        before = _commit_count(tmp_path)
+
+        result = _commit_dmx_state(tmp_path, "chore: sync loop state")
+
+        assert result is None
+        assert _commit_count(tmp_path) == before
+
+    def test_noop_outside_a_git_repo(self, tmp_path: Path) -> None:
+        (tmp_path / ".dmx").mkdir(exist_ok=True)
+        (tmp_path / ".dmx" / "activeContext.md").write_text("note\n", encoding="utf-8")
+
+        result = _commit_dmx_state(tmp_path, "chore: sync loop state")  # must not raise
+
+        assert result is None
+        assert not (tmp_path / ".git").exists()
+
+    def test_returns_a_warning_string_when_commit_is_attempted_but_fails(
+        self, tmp_path: Path
+    ) -> None:
+        """A commit can be attempted and still fail (rejected by a
+        pre-commit hook, GPG signing failure, disk full, etc.) — that must
+        never be swallowed silently, since silent failure here defeats the
+        entire point of this function (durability of the loop's final
+        state). Forced here via an always-failing pre-commit hook, which
+        reliably fails `git commit` regardless of the host's git identity
+        configuration (unlike unsetting user.name/email, which a global
+        config can silently paper over)."""
+        _init_real_git_repo(tmp_path)
+        _install_rejecting_pre_commit_hook(tmp_path)
+        (tmp_path / ".dmx").mkdir(exist_ok=True)
+        (tmp_path / ".dmx" / "activeContext.md").write_text("note\n", encoding="utf-8")
+
+        result = _commit_dmx_state(tmp_path, "chore: sync loop state")
+
+        assert result is not None
+        assert "could not auto-commit" in result.lower()
+        # The failed commit must leave the change sitting uncommitted, not
+        # silently discarded — an operator following the warning's advice
+        # to inspect/commit manually still has something to find.
+        assert "activeContext.md" in _dmx_dirty(tmp_path)
+
+    def test_release_style_loop_with_no_chain_target_commits_final_state(
+        self, tmp_path: Path
+    ) -> None:
+        """End-to-end: a terminal loop (on_complete -> null, matching the
+        bundled `release` loop) leaves .dmx/ clean after _finish_loop
+        returns, instead of stranding the job state JSON + session note as
+        an uncommitted change nothing downstream will ever pick up."""
+        _init_real_git_repo(tmp_path)
+        config = LoopConfig.model_validate(
+            {
+                "name": "release",
+                "skills": ["create-pr"],
+                "validators": [{"tool": "v", "checks": [{"name": "check_a", "required": True}]}],
+            }
+        )
+        _write_validator(tmp_path, "v", PASSING_VALIDATOR)
+        _setup(tmp_path, config, job_id="GH-1", task_id="T")
+        before = _commit_count(tmp_path)
+
+        message = _finish_loop(tmp_path, "GH-1", "release", "T", config, {})
+
+        assert "complete" in message.lower()
+        assert _dmx_dirty(tmp_path) == ""
+        assert _commit_count(tmp_path) == before + 1
+
+    def test_release_style_loop_surfaces_a_warning_when_the_commit_attempt_fails(
+        self, tmp_path: Path
+    ) -> None:
+        """A failed auto-commit must be visible in the loop's own response,
+        not just a server-side log line an operator has no reason to go
+        looking for."""
+        _init_real_git_repo(tmp_path)
+        _install_rejecting_pre_commit_hook(tmp_path)
+        config = LoopConfig.model_validate(
+            {
+                "name": "release",
+                "skills": ["create-pr"],
+                "validators": [{"tool": "v", "checks": [{"name": "check_a", "required": True}]}],
+            }
+        )
+        _write_validator(tmp_path, "v", PASSING_VALIDATOR)
+        _setup(tmp_path, config, job_id="GH-1", task_id="T")
+
+        message = _finish_loop(tmp_path, "GH-1", "release", "T", config, {})
+
+        assert "complete" in message.lower()
+        assert "could not auto-commit" in message.lower()

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/tests/test_validators.py

@@ -63,7 +63,7 @@ class TestCheckSpecComplete:
         assert qa_check["pass"] is False
 
     def test_dmx_create_ticket_numbered_answer_template_passes(self, tmp_path: Path) -> None:
-        """The actual template dmx-create-ticket.md Step 8 writes — numbered
+        """The actual template dmx-create-ticket.md Step 9 writes — numbered
         questions with an indented 'Answer:' line, not 'Q:'/'A:'."""
         self._write_spec(
             tmp_path,

{deepmodel_dmx-0.3.3 → deepmodel_dmx-0.3.4}/uv.lock

@@ -443,7 +443,7 @@ wheels = [
 
 [[package]]
 name = "deepmodel-dmx"
-version = "0.3.3"
+version = "0.3.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },