docs: v1.1.8 — parallel-sessions guide, README, CHANGELOG

Releases v1.1.8 (the framework version is the CHANGELOG's top
`## [X.Y.Z]` header, which generate-plugin.sh extracts).

- CHANGELOG: new [1.1.8] entry — git branch discipline (branch per
  initiative, user-gated merge, per-initiative decision logs),
  opt-in worktree isolation (isolation: config, sage worktree
  launcher, collision guard, workflow bounce), the multi-agent
  /build-x quality+efficiency work, and the sage-memory 0.11
  codebase-scan docs sync.
- README: sage worktree in the CLI table; isolation: in the config
  block + toggle table; a new 'Parallel Sessions (optional)'
  section; sage-version example bumped to 1.1.8.
- docs/parallel-sessions.md (new): comprehensive guide — why
  branches aren't enough for parallel work, the can't-relocate-a-
  session constraint, quickstart, isolation: worktree, the full
  sage worktree reference, the collision guard, the tracked-vs-
  gitignored .sage/ worlds (incl. WSL/symlink notes), per-initiative
  state, a typical parallel day, merge/cleanup, troubleshooting.

Independently accuracy-reviewed against the shipped code (the one
BLOCKER it found — the multi-agent runtime copy — was fixed in the
preceding commit so every claim holds).

Author: xoai

CHANGELOG.md

@@ -2,6 +2,96 @@
 
 All notable changes to Sage will be documented in this file.
 
+## [1.1.8] — Git discipline + parallel-session worktrees
+
+Every delivery workflow now works on its own branch, merges only when
+you say so, and can run in an isolated `git worktree` so multiple
+Claude Code sessions develop in parallel without clobbering each
+other. All of it is opt-in or degrades silently in non-git projects —
+nothing changes for a single sequential session in a repo that doesn't
+opt in.
+
+### Branch discipline (all delivery workflows)
+- `/build`, `/fix`, `/architect`, and the multi-agent `/build-x` now
+  create a branch per initiative before implementation commits —
+  `feat/<slug>`, `fix/<slug>`, `arch/<slug>` respectively (extending
+  the conventional-commit convention to branch names). Propose-confirm:
+  the branch is never created silently; dirty-tree, already-on-a-branch,
+  and detached-HEAD states are each handled.
+- **Merge is always user-gated.** Completion checkpoints add an
+  `[M] Merge to <default>` option; `[A]` no longer merges. Before a
+  merge: the test suite is gated on its own exit code, the tree must be
+  clean (`git status --porcelain`) and the branch must have commits
+  (`git rev-list`), and the merge is `--no-ff`. No workflow path ever
+  merges, pushes, or opens a PR on its own.
+- **Per-initiative decision logs.** Checkpoint decisions now go to
+  `.sage/work/<slug>/decisions.md` (the global `.sage/decisions.md` is
+  reserved for cross-initiative decisions) — two parallel branches no
+  longer collide on one append-only file. Readers check the initiative
+  log first and fall back to the global one; older projects keep
+  working.
+- The new single-source-of-truth capability
+  `core/capabilities/execution/git-discipline/SKILL.md` defines naming,
+  creation, the user-gated merge protocol, worktrees, and cleanup;
+  workflows cite it, never restate it.
+
+### Parallel sessions — opt-in worktree isolation
+- New `isolation: branch | worktree` key in `.sage/config.yaml`
+  (default `branch`). Branches isolate *history* (enough for one
+  session at a time); worktrees isolate the *working tree* (required
+  for simultaneous sessions, because two `claude` processes in one
+  checkout share one working tree and one HEAD).
+- New **`sage worktree <slug>`** launcher — the front door for a
+  parallel task. Creates the branch + a sibling worktree directory,
+  copies the gitignored runtime into it (real `cp -R`, never symlinks),
+  and prints the `cd … && claude` line to open an isolated session.
+  Flags `--from`, `--prefix feat|fix|arch`, `--launch`; plus
+  `sage worktree list` and `sage worktree prune`.
+- **Collision guard.** A second `claude` opened in the *same* checkout
+  is warned (never blocked) by the session-init hook —
+  "Another Sage session appears active in this checkout … run
+  `sage worktree <name>`" — instead of silently clobbering. Liveness
+  is grounded on the hook's parent process id (`$PPID` + `kill -0`),
+  with a 6-hour staleness backstop; non-git projects skip it entirely.
+- **Workflow bounce.** Under `isolation: worktree`, a delivery workflow
+  started in the main checkout offers a guided menu (set up a worktree
+  / proceed here / sequential this once) — never a hard refusal.
+- See **[docs/parallel-sessions.md](docs/parallel-sessions.md)** for
+  the full guide.
+
+### Multi-agent `/build-x` — quality + efficiency
+- **Deterministic stop-rule.** Review-loop verdicts (Phase 3/5/7) are
+  computed by `review-stop.sh`, not counted in-head — the script reads
+  the review files, applies the seven rules, and returns the action.
+- **Per-task-class cost tier.** `[roles.<role>.tiers]` in `agents.toml`
+  lets a `mechanical` cycle review with a cheaper model than an
+  `architecture-shaped` one; the planner proposes the class and the
+  user confirms.
+- **Iron-law TDD + active scope-guard** in the implementer charter;
+  a **per-step validator** (`validate-step.sh`) and a
+  **hallucination-check precondition** (`hallucination-check.sh`,
+  per-file polyglot manifest resolution) catch defects before the
+  full code-review pass pays for them.
+- **Structured `handoff:` frontmatter** on every artifact, injected
+  into downstream CLI-role prompts as the cross-model bridge.
+- **Stuck-handling** (technique-switch, not attempt-count) and a
+  **plan-keyed memory-context refresh** between plan and implementation.
+
+### sage-memory 0.11+ codebase-scan docs
+- The `sage-memory`, `sage-ontology`, and `sage-self-learning` skills
+  document the `scan-codebase` CLI / `sage_memory_scan_codebase` MCP
+  tool (tree-sitter source indexing) — cross-referencing scanned code,
+  linking learnings to code symbols, 10–50× token savings on cross-file
+  queries. Mirrored in the plugin tree.
+
+### Notes
+- All git behavior is conditional on `git rev-parse --git-dir` — a
+  non-git project sees no branching, no worktree prompts, no collision
+  warnings.
+- Claude Code is the verified platform for the collision warning (a
+  session-init hook); the config switch and launcher are
+  platform-agnostic.
+
 ## [1.1.7] — sage-memory integration (unified naming, auto-upgrade, auto-sync)
 
 ### Renamed (BREAKING for custom prompts referencing old names)

README.md

@@ -229,6 +229,7 @@ Run in your terminal:
 | `sage remove <skill>` | Remove a skill from project |
 | `sage skills` | List installed skills |
 | `sage update [target]` | Update community skills to latest |
+| `sage worktree <slug>` | Create an isolated worktree + branch for a parallel session ([guide](docs/parallel-sessions.md)) |
 
 ## How Sage Works
 
@@ -508,23 +509,25 @@ relationships) for smarter integration.
 Sage configuration lives in `.sage/config.yaml`:
 
 ```yaml
-sage-version: "1.1.1"
+sage-version: "1.1.8"
 project-name: "my-app"
 detected-stack: [react, typescript]
 auto_review: true          # sub-agent review after spec/plan approval
 auto_qa: true              # sub-agent QA after quality gates
 independent_gate3: true    # sub-agent code quality review (Gate 3)
 command_prefix: false      # prefix commands as sage:build, sage:fix, etc.
+isolation: branch          # branch | worktree — how parallel work is isolated
 ```
 
-All toggles default to `true` (except `command_prefix`). Set to `false` to disable:
+All toggles default to `true` (except `command_prefix` and `isolation`). Set to `false` to disable:
 
 | Setting | What It Controls |
 |---------|-----------------|
 | `auto_review` | Sub-agent review of spec, plan, and ADR after approval |
 | `auto_qa` | Sub-agent code verification after quality gates pass |
 | `independent_gate3` | Sub-agent code quality review at Gate 3 (falls back to self-review) |
 | `command_prefix` | Namespace all commands as `sage:build`, `sage:fix`, etc. (set via `--prefix` flag) |
+| `isolation` | `branch` (default, sequential) or `worktree` (parallel sessions). See [Parallel Sessions](#parallel-sessions-optional). |
 
 ## Multi-Agent (optional)
 
@@ -575,6 +578,37 @@ Claude Code only in v1.
 - `.sage/docs/multi-agent.md` (post-install) — protocol contract,
   schema, integration points
 
+## Parallel Sessions (optional)
+
+Every delivery workflow works on its own branch (`feat/<slug>`,
+`fix/<slug>`, `arch/<slug>`) and merges only when you choose `[M]` at
+the completion checkpoint — never on its own. That gives you clean,
+reviewable, one-PR-per-initiative history out of the box, with no new
+steps for a single sequential session.
+
+To run **two tasks at once** — one session fixing a bug, another
+building a feature — branches alone aren't enough: two `claude`
+sessions in the same directory share one working tree and clobber each
+other's files. The isolation that simultaneous sessions need is a
+`git worktree` — a directory per session. One command sets it up:
+
+```bash
+sage worktree payment-retry          # creates ../<repo>-payment-retry on
+                                     # branch feat/payment-retry, copies the
+                                     # runtime, prints: cd … && claude
+cd ../<repo>-payment-retry && claude  # an isolated session; /build works as normal
+```
+
+Opt in with `isolation: worktree` in `.sage/config.yaml` to make the
+workflows offer this automatically. If you forget and open a second
+session in the same checkout, Sage warns you (it can't silently move a
+running session into a worktree — that's a launch-time action).
+
+**Learn more:** **[docs/parallel-sessions.md](docs/parallel-sessions.md)**
+— when to use a branch vs a worktree, the full `sage worktree`
+reference, the collision guard, and the tracked-vs-gitignored `.sage/`
+details.
+
 ## Project State
 
 When Sage runs in your project, it manages state in `.sage/`: