@ktpartners/dgs-platform 3.3.1 → 3.4.1

package/deliver-great-systems/workflows/complete-milestone.md

@@ -81,6 +81,19 @@ Milestone completion requires manual oversight for conflict resolution.
 ```
 **STOP.** Do not proceed. Exit the workflow.
 
+**ADH-14 — ad-hoc container preamble.** Read the read-only ad-hoc marker:
+
+```bash
+# ADH-14: surface ad-hoc container status in the completion preamble (read-only)
+ADHOC=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state read-adhoc --raw 2>/dev/null)
+```
+
+If `$ADHOC` is `true`, show this note before proceeding (omit it entirely for non-ad-hoc milestones):
+
+```
+ℹ Ad-hoc container milestone — quicks & fasts routed into this milestone. Completion will relax the readiness gate and clean up ad-hoc bookkeeping.
+```
+
 </step>
 
 <step name="verify_readiness">
@@ -96,6 +109,32 @@ This returns all phases with plan/summary counts and disk status. Use this to ve
 - All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
 - `progress_percent` should be 100%.
 
+**── Ad-hoc relaxed gate (ADH-10/11/13) ──────────────────────────────────**
+
+Read the ad-hoc marker + minimum-bar readiness BEFORE the strict checks below:
+
+```bash
+READINESS=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state adhoc-readiness --raw)
+ADHOC=$(echo "$READINESS" | jq -r '.adhoc')
+ADHOC_READY=$(echo "$READINESS" | jq -r '.ready')
+```
+
+**If `ADHOC` is `true`:** This is an ad-hoc container milestone. Apply the relaxed gate:
+
+- **If `ADHOC_READY` is not `true`:** Refuse completion. Output exactly this line:
+
+  ```
+  Nothing to ship — run a quick/fast or execute a phase first, or `/dgs:abandon-milestone`
+  ```
+
+  Then **STOP** — do not proceed to gather_stats and do not run any of the strict checks below. (ADH-13)
+
+- **Otherwise (`ADHOC_READY` is `true`):** Take the RELAXED path — **SKIP** the strict 100%-phase-completion check, **SKIP** the REQUIREMENTS-traceability parse and the "Unchecked Requirements" presentation, and DO **NOT** recommend `/dgs:audit-milestone`. Proceed directly to gather_stats. (ADH-10)
+
+**If `ADHOC` is not `true`:** Proceed with the strict gate exactly as specified below — no behavioral change. (ADH-11)
+
+**── Strict gate (non-ad-hoc only; runs only when `ADHOC` is not `true`) ──**
+
 **Requirements completion check (REQUIRED before presenting):**
 
 Parse REQUIREMENTS.md traceability table:
@@ -140,6 +179,8 @@ MUST present 3 options:
 
 If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
 
+**── End strict gate. The checks below run for BOTH ad-hoc and non-ad-hoc milestones. ──**
+
 **REVIEW.md existence check:**
 
 ```bash
@@ -292,7 +333,13 @@ MERGE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" work
 ```
 ✓ ${REPO_NAME}: Rebased and merged to ${BASE_BRANCH}
 ```
-Continue to next repo.
+On the success path, `rebaseAndMerge` also deletes the owned remote
+`milestone/${MILESTONE_SLUG}` branch per-repo (`git push origin --delete
+milestone/<slug>`) to reclaim the milestone name and prevent future branch-name
+collisions. This remote delete is **non-fatal**: if it fails (offline, no remote
+branch, etc.) the result still reports `success: true` with
+`remoteBranchDeleted: false` and a warning on stderr — completion is never
+blocked by a failed remote delete. Continue to next repo.
 
 **If `conflicted: true`:**
 Display the `manualInstructions` from the result:
@@ -337,8 +384,15 @@ This removes:
 - Milestone branches
 - active_context cleared to null
 
+```bash
+# ADH-21: remove residual ad-hoc bookkeeping (base ref + any stale entry).
+# No-op for non-ad-hoc milestones (no base ref to delete).
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone cleanup-adhoc "${MILESTONE_SLUG}" 2>/dev/null || true
+```
+
 ```
 ✓ Worktree cleanup complete for milestone '${MILESTONE_SLUG}'
+✓ Ad-hoc bookkeeping cleaned (base ref removed if present)
 ✓ Active context cleared
 ```
 
@@ -679,11 +733,11 @@ After `milestone complete` has archived, reorganize ROADMAP.md with milestone gr
 </details>
 ```
 
-**Then delete originals:**
+**Then delete originals** (REQUIREMENTS.md deletion is existence-guarded so a quicks-only ad-hoc milestone with no REQUIREMENTS.md does not error — ADH-10):
 
 ```bash
-rm ${roadmap_path}
-rm ${project_root}/REQUIREMENTS.md
+[ -f "${roadmap_path}" ] && rm "${roadmap_path}"
+[ -f "${project_root}/REQUIREMENTS.md" ] && rm "${project_root}/REQUIREMENTS.md"
 ```
 
 </step>

package/deliver-great-systems/workflows/create-milestone-job.md

@@ -102,6 +102,21 @@ N. audit-milestone v6.0
 Create this job? (yes/no)
 ```
 
+**Non-blocking collision advisory.** Before waiting for approval, surface a
+warning (NOT a halt — writing a job file is harmless) if the milestone branch
+name is already squatted on origin:
+
+```bash
+MILESTONE_SLUG=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init milestone-op | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{console.log(JSON.parse(d).milestone_slug||"")}catch{console.log("")}})')
+COLLISION=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees check-collision "${MILESTONE_SLUG}")
+```
+
+If the parsed `collision` is `true`, display the `message` (which names the
+colliding `branch` and repo(s)) as an advisory so the user can clean up the
+squatting remote branch before running the job. The job-start guard in
+`run-job` will REFUSE if the collision is still present at run time, so this is
+an early heads-up, not a blocker.
+
 Wait for user response.
 </step>
 

package/deliver-great-systems/workflows/help.md

@@ -313,6 +313,13 @@ Start a new milestone (or the first milestone after `/dgs:new-project`). *(Tier
 Handles both first milestones (creates STATE.md, defaults to v1.0) and subsequent milestones (continues from MILESTONES.md).
 
 Usage: `/dgs:new-milestone "v2.0 Features"`
+Usage: `/dgs:new-milestone --adhoc "Quick experiments"` (ad-hoc container — quicks & fasts route in)
+
+**`/dgs:abandon-milestone`**
+
+Cleanly discard an ad-hoc container milestone — removes milestone worktrees/branches and
+restores the project-scoped planning docs to their pre-milestone state. Ad-hoc-only;
+refuses on spec/phase-driven milestones. Destructive — requires confirmation.
 
 **`/dgs:complete-milestone <version>`**
 Archive completed milestone and prepare for next version. *(Tier 4: verification)*

package/deliver-great-systems/workflows/new-milestone.md

@@ -68,6 +68,75 @@ All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE
 - Read `${state_path}` (pending todos, blockers) — if file does not exist, will be created in Step 5
 - Check for `${project_root}/MILESTONE-CONTEXT.md` (from /dgs:discuss-milestone)
 
+## 1a. Ad-hoc Container (--adhoc)
+
+**Triggered when:** `--adhoc` is present in `$ARGUMENTS`.
+
+This branch establishes a worktree-isolated milestone container DIRECTLY and
+**skips questioning, research, requirements, and roadmap** (steps 2, 8, 9, 10).
+On completion it jumps straight to `## 11. Done`. `detectQuickMode` is never
+modified — once the container exists, quicks/fasts auto-route into it.
+
+**Step 0 — derive slug + version.**
+Derive `{slug}` from the milestone name argument (same slug derivation used
+elsewhere in this workflow). Determine the version using the major/minor prompt
+from `## 3. Determine Milestone Version`, but for `--adhoc` **always present
+minor as the recommended option** (default minor). The chosen `vX.Y` is
+provisional — nothing product-global is written at creation.
+
+**Atomic, canonically-ordered creation with full rollback.** The 6 ordered
+steps below are performed atomically by a single CLI verb. The verb captures the
+planning base ref, creates the code worktrees, mirrors the marker, commits
+STATE.md, and sets `active_context` LAST — rolling everything back (in reverse)
+on any failure so there is no leak window and no residue:
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone create-adhoc "{name}" --version {vX.Y}
+```
+
+The verb implements, in this exact canonical order:
+
+1. **Assert preconditions (ADH-19).** Refuse with a non-zero exit and ZERO
+   mutation if any planning-repo or registered-code-repo working tree is dirty
+   (`git -C <repo> status --porcelain` non-empty, ignoring machine-local
+   `config.local.json`), or if `execution.active_context` is already set
+   (`config-get execution.active_context` non-empty). The error tells the user
+   to "commit or stash changes first" / "complete or abandon the active context
+   first", making a repeated invocation deterministic.
+2. **Capture planning base ref (ADH-06).**
+   `git -C <planning_root> update-ref refs/dgs/adhoc/{slug}/base HEAD` — tracked
+   for rollback.
+3. **Create code worktrees (ADH-02).**
+   `worktrees create {slug} --type milestone --adhoc --base-ref refs/dgs/adhoc/{slug}/base`
+   loops every registered code repo and stamps the entry with `adhoc:true` +
+   `adhoc_base_ref`. Any repo failure → ROLLBACK.
+4. **Confirm marker on the worktree entry (ADH-04 mirror).** Verify the entry
+   now carries `adhoc:true` and `adhoc_base_ref`. If absent → ROLLBACK.
+5. **Commit STATE.md with `adhoc:true` (ADH-04 primary).** Write the milestone
+   fields (name, `vX.Y`, status) PLUS `adhoc: true` to STATE.md frontmatter (the
+   `state set-adhoc` helper) and commit it. Commit failure → ROLLBACK.
+6. **Set `execution.active_context` LAST (ADH-03).**
+   `config-local-set execution.active_context {slug}` — set ONLY after steps 2–5
+   succeed, so `detectQuickMode` never observes a half-created milestone (no leak
+   window).
+
+**ROLLBACK (ADH-18) — undo in reverse, only this invocation's artifacts:**
+1. `active_context` is set last, so a pre-step-6 failure never set it.
+2. Reset the just-made STATE.md commit if step 5 committed.
+3. Remove created worktrees: `worktrees remove {slug} --force` (also nulls
+   `active_context`).
+4. Delete the base ref: `git -C <planning_root> update-ref -d refs/dgs/adhoc/{slug}/base`.
+5. Print an actionable error naming what was rolled back; exit non-zero.
+Leave NO residue — no ref, no worktree entry, no marker, `active_context` unset.
+
+**On success — ADH-22 advisory.** The verb prints:
+"Advisory: while this ad-hoc milestone is active, any product-level (`--main`)
+quick that commits to `base_branch` will have its STATE.md row reverted if you
+later run `/dgs:abandon-milestone`."
+
+Then **jump directly to `## 11. Done`** (skipping steps 2/8/9/10). Do NOT run
+questioning, research, requirements, or roadmap for an ad-hoc container.
+
 ## 1b. Spec-Driven Milestone (auto mode only)
 
 **Triggered when:** `--auto` argument references a spec file.

package/deliver-great-systems/workflows/progress.md

@@ -94,15 +94,19 @@ Use this instead of manually reading/parsing ROADMAP.md.
 ```bash
 # Get formatted progress bar
 PROGRESS_BAR=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" progress bar --raw)
+
+# ADH-14: detect ad-hoc container milestone (read-only marker)
+ADHOC=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state read-adhoc --raw 2>/dev/null)
 ```
 
-Present:
+Present (if `ADHOC` is `true`, include the `**Ad-hoc container:**` line below; otherwise omit it):
 
 ```
 # [Project Name]
 
 **Progress:** {PROGRESS_BAR}
 **Profile:** [quality/balanced/budget]
+**Ad-hoc container:** active — quicks & fasts route into this milestone
 
 ## Recent Work
 - [Phase X, Plan Y]: [what was accomplished - 1 line from summary-extract]

package/deliver-great-systems/workflows/run-job.md

@@ -20,7 +20,11 @@ Load planning context:
 INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
 ```
 
-Extract: `project_root`, `jobs_root`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull` as needed by the workflow.
+Extract: `project_root`, `jobs_root`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`, and `milestone_slug` as needed by the workflow. `milestone_slug` (the stamped/legacy-resolved structural slug) feeds the pre-flight collision guard in `sync_before`:
+
+```bash
+MILESTONE_SLUG=$(echo "$INIT" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{console.log(JSON.parse(d).milestone_slug||"")}catch{console.log("")}})')
+```
 
 Set `WORKFLOW_NAME = "run-job"`.
 Initialize `SYNC_WARNINGS = []` (accumulates mid-workflow push warnings).
@@ -221,6 +225,24 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull
   If `action` is `"aborted"`: halt job before any steps run with diagnosis.
 
 - **If `suppressed` is true:** Pull silently (recent Yes answer).
+
+**Pre-flight collision guard (REFUSE — safe default).** After the pull, and
+BEFORE any job step runs, check that the milestone branch name is not already
+squatted on origin by an unrelated lingering branch. **Refuse (not warn) is the
+deliberate safe default for job start**: starting a job whose `milestone/<slug>`
+collides with unmerged remote commits would silently entangle two milestones'
+histories, so we halt loudly at the one moment a clean abort costs nothing.
+
+```bash
+COLLISION=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees check-collision "${MILESTONE_SLUG}")
+```
+
+Parse the JSON. **If `collision` is `true`:** HALT the job before any steps run.
+Surface the `branch` and the colliding repo(s) from `message`, and instruct the
+user to merge or delete the squatting remote branch
+(`git push origin --delete milestone/<slug>`) and then re-run. Do NOT proceed.
+
+**If `collision` is `false`:** continue normally.
 </step>
 
 <step name="execute_steps">

package/hooks/dist/dgs-enforce-discipline.js

@@ -28,6 +28,17 @@ const ALLOWED_PATH_PATTERNS = [
   /\.claude\/projects\/.*\/memory\//,   // Auto-memory system
   /\.claude\/.*\/memory\//,             // Memory in any .claude subfolder
   /\/tmp\//,                            // Temp files
+  // DGS planning-artifact paths (safety net): workflow doc writes are allowed
+  // purely by path even with no active marker. Anchored to a path-segment
+  // boundary so arbitrary CODE files in registered repos are NOT exempted.
+  /(^|\/)projects\/[^/]+\/phases\/.*\.md$/,                       // phase docs
+  /(^|\/)projects\/[^/]+\/(PROJECT|ROADMAP|STATE|REQUIREMENTS)\.md$/, // project-level docs
+  /(^|\/)(STATE|PROJECTS|MILESTONES|RETROSPECTIVE)\.md$/,         // top-level docs
+  /(^|\/)ideas\/.*\.md$/,                                         // ideas
+  /(^|\/)specs\/.*\.md$/,                                         // specs
+  /(^|\/)todos\/.*\.md$/,                                         // todos
+  /(^|\/)jobs\/.*\.md$/,                                          // jobs
+  /(^|\/)quick\/.*$/,                                             // quick tasks
 ];
 
 // DGS-managed paths that should be committed (relative to planning root)
@@ -101,7 +112,6 @@ process.stdin.on('end', () => {
         if (skillName.startsWith('dgs:')) {
           // Delete the active marker
           const markerPath = getMarkerPath(sessionId);
-          try { fs.unlinkSync(markerPath); } catch { /* already gone */ }
 
           // Safety net: check for uncommitted DGS-managed files
           if (isDgsProject(cwd)) {
@@ -156,6 +166,29 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // ── PreToolUse: Bash → opportunistic marker-on-init (never blocks) ──
+    // Every /dgs:* workflow's first step is `dgs-tools.cjs init <workflow>`.
+    // Inline slash-command expansion emits no Skill event, so the marker is
+    // otherwise never written. Seeing any dgs-tools Bash invocation is a
+    // reliable signal that a workflow is active — write the marker so
+    // subsequent Edit/Write calls in this session are allowed. This branch
+    // NEVER denies: all Bash is allowed regardless of whether it matched.
+    if (hookEvent === 'PreToolUse' && toolName === 'Bash') {
+      const cmd = toolInput.command || '';
+      if (/\bdgs-tools(\.cjs)?\b/.test(cmd)) {
+        try {
+          const markerPath = getMarkerPath(sessionId);
+          const marker = {
+            command: 'bash:dgs-tools',
+            started: new Date().toISOString(),
+            session_id: sessionId,
+          };
+          fs.writeFileSync(markerPath, JSON.stringify(marker));
+        } catch { /* marker write failure must never block Bash */ }
+      }
+      process.exit(0);
+    }
+
     // ── PreToolUse: Edit/Write → check marker ──
     if (hookEvent === 'PreToolUse' && (toolName === 'Edit' || toolName === 'Write')) {
       // Not a DGS project? Allow everything.

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"