devrites 6.0.2 → 6.0.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [6.0.3](https://github.com/ViktorsBaikers/DevRites/compare/v6.0.2...v6.0.3) (2026-10-14)
+
+### Changed
+
+* **devrites:** cut rite-build time without weakening gates ([#104](https://github.com/ViktorsBaikers/DevRites/issues/104)) ([64133ca](https://github.com/ViktorsBaikers/DevRites/commit/64133ca070947c3e9b170f1ee978302d63937c03))
+
+### Fixed
+
+* **no-release:** accept --help after dispatch subcommand ([#103](https://github.com/ViktorsBaikers/DevRites/issues/103)) ([532ce43](https://github.com/ViktorsBaikers/DevRites/commit/532ce4324ae155f891345f825cbd2e04dd37ae85))
+
 ## [6.0.2](https://github.com/ViktorsBaikers/DevRites/compare/v6.0.1...v6.0.2) (2026-10-14)
 
 ### Fixed

package/README.md

@@ -31,7 +31,7 @@ history can't lose it. After you clear the conversation, switch hosts, or hand
 the feature to another engineer, the next session reads the same plan,
 decisions, and evidence before it continues.
 
-**Status:** [`v6.0.2`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v6.0.2): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v6.0.3`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v6.0.3): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 

package/docs/adr/0034-workflow-artifact-byte-corrections-get-code-review.md

@@ -0,0 +1,60 @@
+# ADR-0034: Workflow Artifact byte corrections get code review, not a plan loop
+
+- **Status:** Accepted
+- **Date:** 2026-10-15
+
+## Context
+
+A Workflow Artifact is a root-authored executable file under `.devrites/` that
+proves a slice (for example a native UI test launcher). Vet admits its design:
+paths, modes, behavior/interface/fixture rows, and the proof command. The root
+authors the bytes in a disposable preflight after Vet `READY`. The source handle
+derives from the readiness binding (ADR-0027), so promoting corrected bytes
+needs a new binding, and only Vet may record one.
+
+In practice every bug fix in such a script ran `/rite-plan repair` (plan-drafter)
+plus an affected `/rite-vet` (plan-reviewer). The plan reviewer then reviewed
+Python cleanup and rollback code. One measured feature spent 36% of agent time
+after Build started in Plan and Vet. All 144 of its Plan/Vet waves served one
+slice's proof harness, for example four consecutive archive-policy repair/Vet
+pairs for close and rollback bugs.
+
+## Decision
+
+- A correction that leaves every admission row and `WA-*` reference row
+  unchanged is a technical fix. It follows `OFFLINE_RECOVERY` and never
+  `/rite-plan repair`.
+- The root records the corrected bytes' identity digest as one exact
+  `test-plan.md` line below the admission block:
+  `Workflow Artifact reviewed identity: <64 lowercase hex>`.
+- `devrites-engine check drift` keeps a second digest of `test-plan.md` with
+  only that exact line shape removed. When it is the only change across all
+  readiness inputs, the drift is reported as `reviewed-identity-only`.
+- In that case narrow `/rite-vet` dispatches one fresh `devrites-code-reviewer`
+  on the prior-source→re-preflight diff against the unchanged admission rows,
+  instead of a plan drafter and plan reviewer. Fold and recheck follow the
+  canonical retry contract. Green review lets Vet record the new binding as
+  usual (ADR-0027 still applies; the engine never refreshes it).
+- Any other drift, including a malformed identity line, keeps the existing
+  narrow recheck by the plan reviewer.
+
+This narrows ADR-0027's "semantic review" for this one case to an independent
+code review of the exact bytes. The Workflow Artifact module, source-handle
+derivation, routes, and golden values are unchanged.
+
+## Consequences
+
+- The reviewed bytes are now bound into a readiness input. Before this, Vet
+  approved the design but never the exact corrected bytes.
+- A contract change to a Workflow Artifact still goes through Plan and Vet.
+- Slice-bound Vet rechecks also count toward the per-slice round cap
+  (`dispatch open --slice`), so a harness that keeps failing forces a recorded
+  reslice or simpler-proof review.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Derive the source handle from the identity digest | Changes the protocol's crypto, golden values, and the reference model test, for the same saving. |
+| Let the engine refresh the binding after review | ADR-0027 keeps binding renewal a Vet act; the engine stays thin. |
+| Keep plan-reviewer for byte fixes | Measured cost above; a plan reviewer is the wrong specialist for code defects. |

package/docs/adr/README.md

@@ -72,10 +72,11 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | [0024](0024-native-policy-offline-installer-boundary.md) | Native policy and offline installer boundary | Accepted in part; offline engine-update clause superseded by 0028 | `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/host-artifacts-test.sh` |
 | [0025](0025-evidence-gated-workspace-upgrades.md) | Evidence-gated semantic workspace upgrades | Accepted; no-migrator scope superseded by 0029 | `tests/phase-gate-routing-test.sh`, `tests/host-artifacts-test.sh` |
 | [0026](0026-content-bound-proof-and-bounded-inputs.md) | Content-bound proof and bounded inputs | Accepted | `engine/internal/lib/candidate_test.go`, `engine/internal/lib/evidencefresh_test.go`, `engine/internal/gate/gate_test.go`, `engine/root_routing_test.go`, `engine/tests/parity_githelpers_test.go`, `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/update-smoke.sh`, `tests/npx-pack-smoke.sh`, `tests/release-tarball-test.sh` |
-| [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted; AC ID map amended 2026-09-04 | `engine/tests/adr_0027_readiness_binding_test.go`, `engine/internal/state/acceptance_test.go` |
+| [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted; AC ID map amended 2026-09-04; semantic review narrowed by 0034 for Workflow Artifact byte fixes | `engine/tests/adr_0027_readiness_binding_test.go`, `engine/internal/state/acceptance_test.go` |
 | [0028](0028-self-contained-engine-update.md) | Self-contained engine update | Accepted | `engine/internal/install/install_test.go`, `engine/internal/release/release_test.go`, `engine/tests/meta_test.go` |
 | [0029](0029-v5-workspace-schema-and-native-migration.md) | v5 workspace schema and native migration | Accepted | `engine/internal/state/workspaceschema_test.go`, `engine/tests/parity_resolve_test.go`, `engine/tests/parity_closeout_test.go` |
 | 0030 | Reserved number; no ADR is published under it | Unpublished | none |
 | [0031](0031-overhaul-agents-keep-every-tool.md) | `/overhaul` ships its own agents that keep every tool | Accepted; scopes the one-writer clauses of 0010/0015/0017/0018/0019 to `devrites-*` specialists | `scripts/validate-agent-composition.py`, `tests/codex-agent-generation-test.sh` |
 | [0032](0032-single-lint-gate-and-cached-pr-tests.md) | One engine lint gate, and PR tests that reuse main's results | Accepted | `tests/validation-governance-test.sh` |
 | [0033](0033-rite-fast-own-agents.md) | `/rite-fast` ships its own agents and its own writer | Accepted; adds `fast-builder` as a writer outside the `devrites-*` one-writer rule | `scripts/validate-agent-composition.py`, `tests/rite-fast-contract-test.sh` |
+| [0034](0034-workflow-artifact-byte-corrections-get-code-review.md) | Workflow Artifact byte corrections get code review, not a plan loop | Accepted; narrows 0027's semantic review for contract-preserving Workflow Artifact byte fixes | `engine/internal/lib/drift_test.go` |

package/docs/engine/commands.md

@@ -18,12 +18,12 @@ workflow strategy.
 | `check path-disjoint [--root <dir>] [<json-file> | -]` | Verify slice path sets are pairwise disjoint. |
 | `parallel select --cap <1-10> [--root <dir>] [<json-file> | -]` | Choose the greedy path-disjoint subset ≤ cap from supplied ready slices. |
 | `parallel <create\|integrate\|cleanup\|status\|abort\|lease-read\|lease-write\|lease-clear\|record-green>` | Deterministic parallel worktree leases, integration, and cleanup for parallel writer batches. |
-| `check task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles, unknown deps, malformed tokens, duplicate IDs, missing `Dependencies`, and `depends_on` mismatch. |
+| `check task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles, unknown deps, malformed tokens, duplicate IDs, missing `Dependencies`, and `depends_on` mismatch. Prints a non-blocking `ADVISORY size:` line (and records a `size-advisory` metric) for each slice with 12+ Writer allowlist files and no `Size rationale:`. |
 | `check regression <slug> [--update]` | Compare the workspace's structural progress facts (phase ordinal, checked ACs, met/abandoned gates, done slices, resolved questions, present artifacts) against the recorded `regression-baseline.json` high-water mark; `--update` ratchets the baseline forward under the feature lock and prints each blessed regression. |
-| `check drift <slug> [--record]` | Attribute readiness-input changes to the exact artifact. `--record` writes the per-input `readiness-inputs.json` digest baseline under the feature lock; without it the workspace diffs current inputs against that baseline (or falls back to the aggregate binding recorded in `eng-review.md`). Advisory: exit `0` on drift; a corrupt baseline exits `3`. |
-| `check windows <slug> [--worktree\|--staged\|--base <ref>]` | Fail on deferral markers (TODO/FIXME/XXX/HACK, skipped-test and stub idioms) the change's added lines introduce without a waiver row in the workspace's `windows.md`. |
+| `check drift <slug> [--record]` | Attribute readiness-input changes to the exact artifact. `--record` writes the per-input `readiness-inputs.json` digest baseline under the feature lock; without it the workspace diffs current inputs against that baseline (or falls back to the aggregate binding recorded in `eng-review.md`). Advisory: exit `0` on drift; a corrupt baseline exits `3`. A `test-plan.md` change limited to exact `Workflow Artifact reviewed identity: <64hex>` lines is reported as `reviewed-identity-only` (ADR-0034). |
+| `check windows <slug> [--worktree\|--staged\|--base <ref>]` | Fail on deferral and bar-lowering markers the change introduces without a waiver row in the workspace's `windows.md`: added TODO/FIXME/XXX/HACK, skipped/focused-test and stub idioms, checker suppressions, one-line empty catch; removed `deleted-test` files and net `removed-assertion` lines in remaining test files. |
 | `check dup [slug] [--all\|--worktree\|--staged\|--base <ref>] [--min-lines n] [--threshold f] [--ignore-file <path>] [--limit n] [--exclude <csv>]` | Report near-duplicate code clusters that survive comment stripping, literal collapsing, and identifier renaming — token-shingle matches chained into segments, clustered transitively, ranked with bounded path/line-distance boosts. Diff modes mark units overlapping changed hunks with `*`; stable content-derived cluster hashes let `.devrites/dup-ignore` dismissals survive line moves but resurface on structural edits. Staged mode reads index blobs and excludes untracked files. Bounded heuristic: successful scans/leads exit `0`; usage, unavailable input, and partial scans exit `2`. |
-| `check slice <slug> <SLICE-ID>` | Pre-dispatch lint of one slice's wright contract: contract present, exact Writer allowlist paths, resolvable `Satisfies` AC ids, bounded scope. |
+| `check slice <slug> <SLICE-ID>` | Pre-dispatch lint of one slice's wright contract: contract present, exact Writer allowlist paths, resolvable `Satisfies` AC ids, bounded scope. Same non-blocking size advisory as `check task-graph`. |
 | `check diff-scope <slug> --allow <csv>\|--allow-file <path> [--worktree\|--staged\|--base <ref>]` | Verify the changed-path set stays inside the declared allowlist; the mechanical gate run before reviewer dispatch. |
 | `check skill-trust <path>` | Scan one skill/agent Markdown file for structural trust violations. |
 | `check indexes [--root <dir>]` | Report install manifest and code-index presence as JSON. |
@@ -32,8 +32,8 @@ workflow strategy.
 | `observe slice <slug> <SLICE-ID>` | Print one `SLICE-###` section of `tasks.md` so Build reads a slice, not the file. |
 | `next [slug]` | Print the minimal remaining lifecycle path plus advisory skips. |
 | `handoff [slug]` | Emit the deterministic resume record: cursor fields, `awaiting_human`, open `questions.md` gate kinds, the `gates.md` reduction with unmet/stale/abandoned ids, `decisions.md` dead ends, missing required files, and the canonical read-next order. Read-only; the `/rite-handoff` spine and the compaction-fallback entry point. |
-| `context [slug] (--phase <p>\|--skill <name>) [--role <r>] [--trigger a,b]` | Emit one deduplicated read-set bundle per phase/role/skill from each skill's `loads:` manifest; `--skill` works without a workspace when `--out` is given. |
-| `dispatch <slug> <open\|start\|seal\|return\|status\|abandon>` | Launch-wave barrier for parallel dispatch: seal needs a handle per role, return needs seal; start/return auto-record metrics. |
+| `context [slug] (--phase <p>\|--skill <name>) [--role <r>] [--slice <SLICE-ID>] [--trigger a,b]` | Emit one deduplicated read-set bundle per phase/role/skill from each skill's `loads:` manifest; `--skill` works without a workspace when `--out` is given. A `--role` bundle leads with the role's agent contract and names the manifest's `rootOnly` paths instead of inlining them. `--slice` inlines that slice's `tasks.md` block and turns each over-budget artifact into a by-reference index (path, SHA-256, headings, line hits for every ID the block cites); repeat `--slice` for several slices; an unknown slice exits `3`. |
+| `dispatch <slug> <open\|start\|seal\|return\|status\|abandon>` | Launch-wave barrier for parallel dispatch: seal needs a handle per role, return needs seal; start/return auto-record metrics. A build wave with a wright role needs `--slice <SLICE-ID>` per slice, and a slice-bound vet wave takes it too; every 5 rounds of either kind on one slice, `open` exits `3` until `--reslice-review <DRIFT-ID>` names an unused `drift.md` `## <DRIFT-ID>` heading for that slice. |
 | `metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]` | Append an event to the workspace's `metrics.jsonl` ledger. |
 | `metrics summary [slug]` | Reduce `metrics.jsonl` into a per-phase roll-up. |
 | `claim <add\|release\|list\|check>` | Advisory session-scoped file claims in `.devrites/claims.jsonl` (append-only). `add` records intent to write a path set with a TTL (1–240 min, default 30); a live claim by another session exits `3` and names the holder. `release` appends a release event owned by the claiming session. `list` shows live claims (`--all` includes expired/released). `check` is the read-only preflight for a path set. Coordination aid only — never a substitute for one-writer-per-worktree. |

package/engine/help.go

@@ -125,16 +125,20 @@ func takesSubcommand(command string) bool {
 	}
 }
 
-// claimValueFlags are the claim flags that consume the next argument as a value.
-var claimValueFlags = map[string]bool{"--session": true, "--reason": true, "--ttl": true, "--id": true}
+// valueFlags lists, per command, the flags that consume the next argument as a
+// value. A command listed here has known flags, so its help flag is honoured
+// anywhere except as the value of one of these flags.
+var valueFlags = map[string]map[string]bool{
+	"claim":    {"--session": true, "--reason": true, "--ttl": true, "--id": true},
+	"dispatch": {"--phase": true, "--wave": true, "--role": true, "--handle": true, "--reason": true},
+}
 
 // hasHelpFlag reports whether args (the arguments after the command word) are a
 // help request. The command path is consumed by dispatch, so a help flag is
 // honoured among the leading flags that follow it. The scan stops at the first
 // argument that does not start with a dash, because from there the engine
-// cannot tell a flag from a value or operand. Only claim, whose value flags are
-// known, honours a help flag later, and never one that is the value of such a
-// flag.
+// cannot tell a flag from a value or operand. Commands in valueFlags honour a
+// help flag later, and never one that is the value of such a flag.
 func hasHelpFlag(command string, args []string) bool {
 	if len(args) > 0 && !strings.HasPrefix(args[0], "-") && takesSubcommand(command) {
 		args = args[1:]
@@ -143,9 +147,10 @@ func hasHelpFlag(command string, args []string) bool {
 		if isHelpFlag(args[i]) {
 			return true
 		}
-		if command == "claim" && claimValueFlags[args[i]] {
+		known, ok := valueFlags[command]
+		if ok && known[args[i]] {
 			i++
-		} else if command != "claim" && !strings.HasPrefix(args[i], "-") {
+		} else if !ok && !strings.HasPrefix(args[i], "-") {
 			return false
 		}
 	}

package/engine/help_test.go

@@ -48,6 +48,7 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"handoff", "--help"}, want: "handoff [slug]"},
 		{args: []string{"next", "help"}, want: "devrites-engine next [slug]"},
 		{args: []string{"dispatch", "help"}, want: "devrites-engine dispatch <slug>"},
+		{args: []string{"dispatch", "x", "open", "--help"}, want: "devrites-engine dispatch <slug>"},
 		{args: []string{"secret-scan", "help"}, want: "secret-scan [--staged] [--stdin]"},
 		{args: []string{"open-visual", "help"}, want: "open-visual <path-or-name>"},
 		{args: []string{"claim", "--help"}, want: "claim <add|release|list|check>"},

package/engine/internal/gate/readiness_binding.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"hash"
+	"regexp"
 	"strings"
 
 	"github.com/devrites/devrites/internal/markdowntext"
@@ -147,6 +148,20 @@ type ReadinessInputDigest struct {
 	Path    string `json:"path"`
 	Present bool   `json:"present"`
 	SHA256  string `json:"sha256,omitempty"`
+	// Normalized is test-plan.md's digest without its reviewed-identity lines,
+	// so drift can prove a Workflow Artifact byte correction changed nothing
+	// else Vet approved.
+	Normalized string `json:"normalized,omitempty"`
+}
+
+// reviewedIdentityRE is the exact test-plan.md line binding the Workflow
+// Artifact bytes an independent code review approved. Only this exact shape
+// is ignored, so the exclusion cannot hide any other edit.
+var reviewedIdentityRE = regexp.MustCompile(`(?m)^Workflow Artifact reviewed identity: [0-9a-f]{64}\r?\n?`)
+
+// withoutReviewedIdentity drops every exact reviewed-identity line.
+func withoutReviewedIdentity(content []byte) []byte {
+	return reviewedIdentityRE.ReplaceAll(content, nil)
 }
 
 // ReadinessInputDigests returns each readiness input's content digest plus the
@@ -172,6 +187,10 @@ func ReadinessInputDigests(root, slug string) ([]ReadinessInputDigest, string, e
 		if present {
 			sum := sha256.Sum256(content)
 			entry.SHA256 = hex.EncodeToString(sum[:])
+			if input.logical == "test-plan.md" {
+				normalized := sha256.Sum256(withoutReviewedIdentity(content))
+				entry.Normalized = hex.EncodeToString(normalized[:])
+			}
 		}
 		digests = append(digests, entry)
 	}

package/engine/internal/lib/cli_observe.go

@@ -5,6 +5,7 @@ import (
 	"io"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
 )
 
 // RunTaskGraphCheck validates tasks.md for one slug.
@@ -21,6 +22,21 @@ func RunTaskGraphCheck(root, slug string, stdout, stderr io.Writer) int {
 		return 3
 	}
 	fmt.Fprintf(stdout, "task-graph: ok (%d slices)\n", len(graph.Slices))
+	// Size advisory: never changes the exit code; the metric shows how often
+	// it would have fired before anyone makes it blocking.
+	if raw, err := readWorkspaceArtifact(root, slug, "tasks.md"); err == nil {
+		over := 0
+		for _, s := range graph.Slices {
+			block, _ := state.ExtractTaskSlice(raw, s.ID)
+			if n, ok := sliceSizeAdvisory(block); ok {
+				fmt.Fprintf(stdout, "task-graph: ADVISORY size: %s has %d Writer allowlist files (>= %d); split it (acceptance-preserving) or record `Size rationale:`\n", s.ID, n, sliceFileAdvisory)
+				over++
+			}
+		}
+		if over > 0 {
+			recordMetric(root, slug, "define", "size-advisory", "", int64(over))
+		}
+	}
 	return 0
 }
 

package/engine/internal/lib/context.go

@@ -14,6 +14,8 @@ import (
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/markdowntext"
+	"github.com/devrites/devrites/internal/state"
 )
 
 // loadsManifest is the machine-readable read-set a skill declares in an HTML
@@ -24,29 +26,35 @@ import (
 // role key is present its list replaces "workspace" entirely (an empty list
 // means the role needs no workspace artifacts). "agents" maps a --role name to
 // an agents-root-relative path when it deviates from the devrites-<role>
-// convention.
+// convention. "rootOnly" lists always/trigger paths that only the controlling
+// root executes; a --role bundle names them instead of inlining them.
 type loadsManifest struct {
 	Always          []string            `json:"always"`
 	Triggers        map[string][]string `json:"triggers"`
 	Workspace       []string            `json:"workspace"`
 	WorkspaceByRole map[string][]string `json:"workspaceByRole"`
 	Agents          map[string]string   `json:"agents"`
+	RootOnly        []string            `json:"rootOnly"`
 }
 
 const loadsMarker = "<!-- loads:"
 
-const contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
+const contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--slice <SLICE-###>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
 
 Emits one deduplicated context bundle for a phase or standalone skill
 (+ optional dispatch role) into .devrites/work/<slug>/ctx/ so an agent
 reads a single file. With --skill, slug may be omitted; then --out is
-required and no workspace section is included.
+required and no workspace section is included. --slice scopes the
+workspace section to one slice: tasks.md contributes that slice's block,
+and an artifact over its line/byte budget becomes a by-reference index
+(path, SHA-256, headings, and line hits for every ID the block cites).
+Repeat --slice for a recheck that spans several slices.
 `
 
 // RunContext emits one deduplicated context bundle for a phase (+ optional
 // dispatch role) so an agent reads a single file instead of selecting files.
 //
-//	context <slug> --phase <p> [--role <r>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
+//	context <slug> --phase <p> [--role <r>] [--slice <SLICE-###>] [--trigger a,b] [--skills-root <dir>] [--out <path>]
 func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 	opts, code := parseContextArgs(args, stderr)
 	if code != 0 {
@@ -82,6 +90,27 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 		return 2
 	}
 
+	var sliceBlock string
+	var sliceIDs []citedID
+	if opts.slice != "" {
+		raw, err := os.ReadFile(filepath.Join(featureDir, "tasks.md")) // #nosec G304 -- featureDir is the validated feature workspace
+		if err != nil {
+			fmt.Fprintf(stderr, "context: %v\n", err)
+			return 2
+		}
+		var blocks []string
+		for _, id := range opts.slices {
+			block, ok := state.ExtractTaskSlice(raw, id)
+			if !ok {
+				fmt.Fprintf(stdout, "context: BLOCKED: %s not found in tasks.md\n", id)
+				return 3
+			}
+			blocks = append(blocks, block)
+		}
+		sliceBlock = strings.Join(blocks, "\n")
+		sliceIDs = citedIDs(sliceBlock)
+	}
+
 	var files []string
 	var missingRequired []string
 	var autoTriggers []string
@@ -124,12 +153,31 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 
 	seen := map[string]bool{}
 	loaded := 0
+	// The role contract leads the bundle so the agent reads its rules before
+	// reference text.
+	if opts.role != "" {
+		rel := roleAgentPath(manifest, opts.role)
+		if writeContextEntry(&bundle, filepath.Join(skillsRoot, "..", "agents", filepath.FromSlash(rel)),
+			"agents/"+rel, seen, true) {
+			loaded++
+		} else {
+			// The agent contract is a pack file, not a workspace artifact: a
+			// miss means a typo'd role or a pack bug, and a dispatch without
+			// its contract must fail loudly.
+			missingRequired = append(missingRequired, "agents/"+rel)
+		}
+	}
+	var rootOnly []string
 	for _, rel := range files {
 		abs := filepath.Join(skillsRoot, filepath.FromSlash(rel))
 		if seen[abs] {
 			continue
 		}
 		seen[abs] = true
+		if opts.role != "" && slices.Contains(manifest.RootOnly, rel) {
+			rootOnly = append(rootOnly, rel)
+			continue
+		}
 		data, err := os.ReadFile(abs) // #nosec G304 -- abs is resolved from the validated skills root
 		fmt.Fprintf(&bundle, "===== %s =====\n", rel)
 		if err != nil {
@@ -144,34 +192,37 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 		bundle.WriteByte('\n')
 		loaded++
 	}
+	if len(rootOnly) > 0 {
+		fmt.Fprintf(&bundle, "===== root-only (not inlined for role %s) =====\n%s\n\n", opts.role, strings.Join(rootOnly, "\n"))
+	}
 
+	whole, byReference := 0, 0
 	workspaceList, workspaceScoped := workspaceReadSet(manifest, opts.role)
 	if hasManifest && featureDir != "" {
 		if workspaceScoped && len(workspaceList) == 0 {
 			bundle.WriteString("===== workspace =====\nskipped: role-scoped read-set declares no workspace artifacts\n\n")
 		}
 		for _, rel := range workspaceList {
-			if writeContextEntry(&bundle, filepath.Join(featureDir, filepath.FromSlash(rel)),
-				"workspace/"+rel, seen, false) {
+			abs := filepath.Join(featureDir, filepath.FromSlash(rel))
+			if opts.slice == "" {
+				if writeContextEntry(&bundle, abs, "workspace/"+rel, seen, false) {
+					loaded++
+				}
+				continue
+			}
+			ok, byRef := writeSliceEntry(&bundle, filepath.Dir(root), abs, "workspace/"+rel, opts.slice, sliceBlock, sliceIDs, seen)
+			if ok {
 				loaded++
 			}
+			if byRef {
+				byReference++
+			} else if ok {
+				whole++
+			}
 		}
 	} else if hasManifest && len(workspaceList) > 0 {
 		bundle.WriteString("===== workspace =====\nskipped: no feature workspace (slug omitted)\n\n")
 	}
-	if opts.role != "" {
-		rel := roleAgentPath(manifest, opts.role)
-		if writeContextEntry(&bundle, filepath.Join(skillsRoot, "..", "agents", filepath.FromSlash(rel)),
-			"agents/"+rel, seen, true) {
-			loaded++
-		} else {
-			// The agent contract is a pack file, not a workspace artifact: a
-			// miss means a typo'd role or a pack bug, and a dispatch without
-			// its contract must fail loudly.
-			missingRequired = append(missingRequired, "agents/"+rel)
-		}
-	}
-
 	out := opts.out
 	if out == "" {
 		out = filepath.Join(featureDir, "ctx", bundleName(opts))
@@ -216,6 +267,9 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, ", MISSING: %s", strings.Join(missingRequired, ","))
 	}
 	fmt.Fprintln(stdout, ")")
+	if opts.slice != "" {
+		fmt.Fprintf(stdout, "scope: slice %s (%d whole, %d by-reference)\n", opts.slice, whole, byReference)
+	}
 	if workspaceScoped {
 		fmt.Fprintf(stdout, "workspace: role-scoped for %s (%d of %d declared artifacts)\n",
 			opts.role, len(workspaceList), len(manifest.Workspace))
@@ -280,6 +334,110 @@ func expandIncludes(abs string, data []byte) []byte {
 	})
 }
 
+// writeSliceEntry writes one workspace artifact of a --slice bundle: tasks.md
+// as the slice block plus a by-reference index, any other canonical artifact
+// over its line/byte budget as a by-reference index, everything else whole.
+func writeSliceEntry(bundle *strings.Builder, project, abs, label, slice, block string, ids []citedID, seen map[string]bool) (loaded, byRef bool) {
+	if seen[abs] {
+		return false, false
+	}
+	data, err := os.ReadFile(abs) // #nosec G304 -- abs is resolved from the validated feature workspace
+	name := filepath.Base(abs)
+	if err == nil && name == "tasks.md" {
+		seen[abs] = true
+		fmt.Fprintf(bundle, "===== %s (%s block) =====\n%s\n", label, slice, block)
+	} else if status, ok := state.ArtifactBudget(name, data); err != nil || !ok || !status.Over {
+		return writeContextEntry(bundle, abs, label, seen, false), false
+	} else {
+		seen[abs] = true
+	}
+	writeAnchorIndex(bundle, project, abs, label, data, ids)
+	return true, true
+}
+
+var (
+	citedIDRE       = regexp.MustCompile(`\b[A-Z]{1,6}-\d{2,}(?:-[A-Z][A-Z0-9]*)*\b`)
+	anchorHeadingRE = regexp.MustCompile(`^#{1,3}\s`)
+)
+
+// maxIDHits bounds the line anchors listed per ID; the live file holds the rest.
+const maxIDHits = 20
+
+// citedID is one ID the slice block cites with its word-bounded matcher.
+type citedID struct {
+	id string
+	re *regexp.Regexp
+}
+
+// citedIDs returns each distinct ID the slice block cites (AC-###, DEC-###,
+// T-###, PF-##, SLICE-###, ...).
+func citedIDs(block string) []citedID {
+	var out []citedID
+	seen := map[string]bool{}
+	for _, id := range citedIDRE.FindAllString(block, -1) {
+		if !seen[id] {
+			seen[id] = true
+			out = append(out, citedID{id, regexp.MustCompile(`\b` + regexp.QuoteMeta(id) + `\b`)})
+		}
+	}
+	return out
+}
+
+// writeAnchorIndex emits a by-reference entry: identity, heading anchors, and
+// line hits for each cited ID, so the agent reads owning sections from the
+// live file instead of the whole artifact.
+func writeAnchorIndex(bundle *strings.Builder, project, abs, label string, data []byte, ids []citedID) {
+	rel, err := filepath.Rel(project, abs)
+	if err != nil {
+		rel = abs
+	}
+	lines := strings.Split(strings.ReplaceAll(string(data), "\r\n", "\n"), "\n")
+	structural := lines
+	if masked, err := markdowntext.Structural(data); err == nil {
+		structural = strings.Split(strings.ReplaceAll(string(masked), "\r\n", "\n"), "\n")
+	}
+	fmt.Fprintf(bundle, "===== %s (by reference) =====\n", label)
+	fmt.Fprintf(bundle, "path: %s sha256: %x bytes: %d lines: %d\n", filepath.ToSlash(rel), sha256.Sum256(data), len(data), len(lines))
+	bundle.WriteString("Not inlined. Read owning sections from the live file by line anchor; nothing is omitted there.\n")
+	bundle.WriteString("headings:\n")
+	for i, line := range structural {
+		if anchorHeadingRE.MatchString(line) {
+			fmt.Fprintf(bundle, "- L%d %s\n", i+1, clipRunes(lines[i], 120))
+		}
+	}
+	if len(ids) > 0 {
+		bundle.WriteString("id hits (IDs cited by the slice block):\n")
+	}
+	for _, cited := range ids {
+		var at []string
+		total := 0
+		for i, line := range lines {
+			if cited.re.MatchString(line) {
+				total++
+				if len(at) < maxIDHits {
+					at = append(at, fmt.Sprintf("L%d", i+1))
+				}
+			}
+		}
+		hits := "none"
+		if total > 0 {
+			hits = strings.Join(at, " ")
+			if total > len(at) {
+				hits += fmt.Sprintf(" (+%d more)", total-len(at))
+			}
+		}
+		fmt.Fprintf(bundle, "- %s: %s\n", cited.id, hits)
+	}
+	bundle.WriteByte('\n')
+}
+
+func clipRunes(s string, n int) string {
+	if r := []rune(s); len(r) > n {
+		return string(r[:n]) + "…"
+	}
+	return s
+}
+
 func writeContextEntry(bundle *strings.Builder, abs, label string, seen map[string]bool, expand bool) bool {
 	if seen[abs] {
 		return false
@@ -308,6 +466,8 @@ type contextOpts struct {
 	phase      string
 	skill      string
 	role       string
+	slice      string // display label: slices joined with "+"
+	slices     []string
 	triggers   []string
 	skillsRoot string
 	out        string
@@ -325,6 +485,8 @@ func parseContextArgs(args []string, stderr io.Writer) (contextOpts, int) {
 			opts.skill = value
 		case "--role":
 			opts.role = value
+		case "--slice":
+			opts.slices = append(opts.slices, value)
 		case "--trigger", "--triggers":
 			for _, name := range strings.Split(value, ",") {
 				if name = strings.TrimSpace(name); name != "" {
@@ -353,6 +515,13 @@ func parseContextArgs(args []string, stderr io.Writer) (contextOpts, int) {
 		fmt.Fprintf(stderr, "context: --skill must be a directory name, not a path\n")
 		return opts, 2
 	}
+	for _, id := range opts.slices {
+		if !state.ValidSliceID(id) || len(positional) == 0 {
+			fmt.Fprintf(stderr, "context: --slice needs a slug and a SLICE-### id, got %q\n", id)
+			return opts, 2
+		}
+	}
+	opts.slice = strings.Join(opts.slices, "+")
 	if len(positional) == 1 {
 		opts.slug = positional[0]
 	} else if opts.out == "" {
@@ -429,6 +598,9 @@ func bundleName(opts contextOpts) string {
 	if opts.role != "" {
 		name += "-" + opts.role
 	}
+	if opts.slice != "" {
+		name += "." + opts.slice
+	}
 	return name + ".bundle.md"
 }