fix(isolation): close all 4 subissues of tracker #228

Lands v1 scope of every subissue under tracker #228. Friction observed
across two campaigns on 2026-05-27 (paper-burst + cross-account-signal-
pooling) where the experiment worktree's isolation guarantee was
silently undermined: executors `cd` to the parent repo to use
gitignored deps, write Python modules into the worktree without
declaring them as code_changes, and on resume occasionally hit
unreplaced-placeholder errors.

Closes #229 — `target_system.worktree_extras` schema field +
  auto-symlink gitignored deps from main into each experiment
  worktree on creation. Each entry must be a non-empty relative path
  resolving under repo_path; absolute paths and ../ traversal are
  rejected at creation time. Source must exist. On extras failure,
  the half-built worktree + branch are cleaned up before re-raising
  (no leak). Symlinks live inside the worktree dir, so
  `git worktree remove --force` reaps them with the rest of the dir.

Closes #230 — Pre-cleanup `git status --porcelain` warns on
  undeclared writes; surfaced in `findings.json` under a new optional
  `worktree_uncommitted_writes` key (schema-allowed). Filters
  symlinks (orchestrator-managed inputs from #229) and any path
  declared in `bundle.arms[].code_changes[].file`. Tripwire only —
  never blocks cleanup.

Closes #231 — "Worktree discipline" guidance added to
  `execute_analyze.md` (full) and `execute_analyze_thin.md`. Tells
  the executor: stay in the worktree, reference parent assets via
  `worktree_extras` symlinks (relative paths, not absolute paths
  into main), declare any new files via `code_changes`. Prose-only
  change — no new placeholders, no behavior change to dispatch.

Closes #232 — Forensic logging in `prompt_loader.py`: when
  rendering fails on unreplaced placeholders, log
  `template`, `resolved_path`, `missing_placeholders`, and
  `context_keys` at ERROR before raising. Diagnostic only — no
  speculative fix for the resume-time bug. The intermittent
  Unreplaced-placeholders failure on iter-2 EXECUTE_ANALYZE is
  gated on reproduction; this PR ships the seine.

Refs #228 (tracker).

## Test plan

- 1167 passed, 1 skipped (was 1133 + 1 in #227 baseline; +34 new
  behavioral tests).
- All tests use real on-disk fixtures or seam-injected fakes per
  CLAUDE.md (no live LLM calls).
- New behavioral coverage:
  - test_worktree.py: TestWorktreeExtras (9), TestDetectUndeclared
    Writes (6), TestDeclaredCodeChangePaths (5), TestRecord
    UndeclaredWritesInFindings (5)
  - test_prompt_loader.py: TestWorktreeDisciplineGuidance (3),
    TestPlaceholderDiagnosticLogging (2)

## Out of scope (v2 — explicit, in tracker #228)

- Post-execution `git -C <main> diff` fail-loud check on main's
  working tree (defense in depth for #229)
- `auto_capture_writes` synthetic `code_changes` flag (alternative
  for #230)
- Actual fix for the resume-time placeholder bug (gated on
  reproduction; #232 ships the diagnostic)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sriumcp

orchestrator/iteration.py

@@ -48,6 +48,46 @@ class IterationOutcome(str, Enum):
 
 TEMPLATES_DIR = Path(__file__).resolve().parent / "templates"
 SCHEMAS_DIR = Path(__file__).resolve().parent / "schemas"
+
+
+def _declared_code_change_paths(bundle_path: Path) -> set[str]:
+    """Read ``bundle.yaml`` and return every ``arms[].code_changes[].file``
+    relative path declared on any arm. Returns an empty set if the file
+    is missing, unparseable, or declares no ``code_changes`` (#230)."""
+    if not bundle_path.exists():
+        return set()
+    try:
+        bundle = yaml.safe_load(bundle_path.read_text()) or {}
+    except yaml.YAMLError:
+        return set()
+    arms = bundle.get("arms") or []
+    declared: set[str] = set()
+    for arm in arms:
+        if not isinstance(arm, dict):
+            continue
+        for change in arm.get("code_changes") or []:
+            if isinstance(change, dict) and isinstance(change.get("file"), str):
+                declared.add(change["file"])
+    return declared
+
+
+def _record_undeclared_writes_in_findings(
+    findings_path: Path,
+    undeclared: list[str],
+) -> None:
+    """Merge ``worktree_uncommitted_writes`` into ``findings.json`` (#230).
+
+    No-op if findings.json is missing or unparseable — the schema
+    validator downstream will already complain and we don't want to
+    block worktree cleanup on a malformed findings artifact."""
+    if not undeclared or not findings_path.exists():
+        return
+    try:
+        findings = json.loads(findings_path.read_text())
+    except json.JSONDecodeError:
+        return
+    findings["worktree_uncommitted_writes"] = sorted(set(undeclared))
+    atomic_write(findings_path, json.dumps(findings, indent=2) + "\n")
 DEFAULTS_PATH = Path(__file__).resolve().parent / "defaults.yaml"
 _ARM_TYPE_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
 
@@ -960,8 +1000,9 @@ def _max_turns_for(phase_key: str) -> int:
                 create_experiment_worktree,
                 remove_experiment_worktree,
             )
+            extras = campaign.get("target_system", {}).get("worktree_extras") or []
             experiment_dir, experiment_id = create_experiment_worktree(
-                Path(repo_path), iteration,
+                Path(repo_path), iteration, extras=extras,
             )
             (iter_dir / ".experiment_id").write_text(experiment_id)
             print(f"  Experiment worktree: {experiment_dir}")
@@ -1031,6 +1072,24 @@ def _max_turns_for(phase_key: str) -> int:
                 "Executor artifacts failed post-check validation: %s",
                 result["errors"],
             )
+        # #230: surface undeclared writes that would be lost when the
+        # worktree is removed below. Persist into findings.json so the
+        # design agent on iter-N+1 can see what to declare in
+        # ``code_changes``. Tripwire only — never blocks cleanup.
+        if repo_path and experiment_dir is not None:
+            from orchestrator.worktree import detect_undeclared_writes
+            declared = _declared_code_change_paths(iter_dir / "bundle.yaml")
+            undeclared = detect_undeclared_writes(experiment_dir, declared)
+            if undeclared:
+                logger.warning(
+                    "Executor wrote %d files in the experiment worktree "
+                    "without declaring them in bundle.arms[].code_changes; "
+                    "they will be lost on cleanup: %s",
+                    len(undeclared), undeclared[:20],
+                )
+                _record_undeclared_writes_in_findings(
+                    iter_dir / "findings.json", undeclared,
+                )
         # Clean up worktree only on success
         if repo_path and experiment_id:
             remove_experiment_worktree(Path(repo_path), experiment_id)

orchestrator/prompt_loader.py

@@ -60,9 +60,21 @@ def load(self, template_name: str, context: dict[str, str]) -> str:
 
         remaining = _PLACEHOLDER_RE.findall(text)
         if remaining:
+            missing = sorted(set(remaining))
+            # #232: forensic logging on the resume-time placeholder bug.
+            # The error message names the missing placeholders; we add
+            # what keys WERE present in the context so the next
+            # occurrence produces evidence pointing at the actual cause
+            # (phase string mismatch, stale loader, resume-path field
+            # uninitialized, ...).
+            logger.error(
+                "prompt render failed: template=%s resolved_path=%s "
+                "missing_placeholders=%s context_keys=%s",
+                template_name, path, missing, sorted(context.keys()),
+            )
             raise ValueError(
                 f"Unreplaced placeholders in {template_name}.md: "
-                f"{', '.join(sorted(set(remaining)))}"
+                f"{', '.join(missing)}"
             )
 
         logger.debug("Loaded prompt %s (%d chars)", template_name, len(text))

orchestrator/schemas/campaign.schema.yaml

@@ -84,6 +84,23 @@ properties:
         type: ["string", "null"]
         minLength: 1
         description: "Path to target system git repo. Used by CLIDispatcher for code-access agents. If set, experiments run in isolated worktrees."
+      worktree_extras:
+        type: array
+        items:
+          type: string
+          minLength: 1
+        uniqueItems: true
+        description: >
+          Paths (relative to repo_path) to symlink into each experiment
+          worktree on creation (#229). Use this for gitignored assets
+          the executor needs from main — virtualenvs, pre-fetched data
+          dirs, prior-iteration outputs, build artifacts. Without this
+          mechanism, executors discover that the worktree is missing
+          their tooling and `cd` back to the parent repo, silently
+          breaking isolation. Each entry must be a relative path that
+          resolves under repo_path; absolute paths and ``..`` traversal
+          are rejected at worktree creation. Source must exist in main
+          at the time of worktree creation.
 
   models:
     type: object

orchestrator/schemas/findings.schema.json

@@ -24,6 +24,12 @@
       "minimum": 0,
       "maximum": 100,
       "description": "Percentage of total effect from single dominant component, if detected."
+    },
+    "worktree_uncommitted_writes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "#230 — paths the executor wrote inside the experiment worktree without declaring them in the bundle's `code_changes`. Surfaced just before worktree cleanup; logged at WARNING. Empty array (or absent) means the executor declared everything it wrote, or wrote nothing untracked. The orchestrator does not block cleanup on undeclared writes — this is a tripwire, not a gate."
     }
   },
   "$defs": {

orchestrator/worktree.py

@@ -17,7 +17,7 @@
 import time
 import uuid
 from pathlib import Path
-from typing import Callable
+from typing import Callable, Sequence
 
 logger = logging.getLogger(__name__)
 
@@ -26,9 +26,28 @@
 _DEFAULT_ORPHAN_AGE_SECONDS = 60 * 60  # 1 hour
 
 
-def create_experiment_worktree(repo_path: Path, iteration: int) -> tuple[Path, str]:
+def create_experiment_worktree(
+    repo_path: Path,
+    iteration: int,
+    *,
+    extras: Sequence[str] | None = None,
+) -> tuple[Path, str]:
     """Create a git worktree for running an experiment in isolation.
 
+    Args:
+        repo_path: Target repo root.
+        iteration: 1-based iteration index. Used to name the experiment.
+        extras: Paths (relative to ``repo_path``) to symlink into the
+            worktree. Each entry is symlinked as ``<worktree>/<entry>``
+            pointing at ``<repo_path>/<entry>`` (#229). Use this for
+            gitignored deps the executor needs from main — venvs, large
+            data dirs, prior-iteration outputs — so the executor doesn't
+            have to ``cd`` to the parent repo and silently break
+            isolation. Each path must be relative and resolve under
+            ``repo_path``; absolute paths and ``..`` traversal are
+            rejected. Source must exist; missing source raises
+            ``FileNotFoundError``.
+
     Returns:
         Tuple of (worktree_path, experiment_id).
     """
@@ -50,9 +69,131 @@ def create_experiment_worktree(repo_path: Path, iteration: int) -> tuple[Path, s
         text=True,
     )
     logger.info("Created experiment worktree: %s (branch: %s)", worktree_dir, branch_name)
+
+    if extras:
+        try:
+            _link_worktree_extras(repo_path, worktree_dir, extras)
+        except BaseException:
+            # If symlinking fails (bad extras config), don't leak the
+            # half-built worktree + branch — clean up before re-raising.
+            remove_experiment_worktree(repo_path, experiment_id)
+            raise
+
     return worktree_dir, experiment_id
 
 
+def _link_worktree_extras(
+    repo_path: Path,
+    worktree_dir: Path,
+    extras: Sequence[str],
+) -> None:
+    """Symlink each entry in ``extras`` from ``repo_path`` into ``worktree_dir``.
+
+    Each entry must be a relative path (no leading ``/``, no ``..``
+    traversal that escapes ``repo_path``). The source path must exist in
+    ``repo_path``. Parent directories under the worktree are created as
+    needed.
+
+    If a path under the worktree already exists at the target location
+    (typically because the entry refers to a tracked path that the
+    worktree checkout already populated), the existing path is left
+    untouched and a warning is logged — do not silently overwrite the
+    real checkout with a symlink.
+    """
+    for entry in extras:
+        if not entry or os.path.isabs(entry):
+            raise ValueError(
+                f"worktree_extras entries must be non-empty relative paths; "
+                f"got {entry!r}"
+            )
+        source = (repo_path / entry).resolve()
+        try:
+            source.relative_to(repo_path.resolve())
+        except ValueError as exc:
+            raise ValueError(
+                f"worktree_extras entry {entry!r} resolves outside repo_path "
+                f"({repo_path}); refusing to symlink across the repo boundary."
+            ) from exc
+        if not source.exists():
+            raise FileNotFoundError(
+                f"worktree_extras source not found: {source} "
+                f"(declared as {entry!r} in target_system.worktree_extras)"
+            )
+
+        link_path = worktree_dir / entry
+        if link_path.exists() or link_path.is_symlink():
+            logger.warning(
+                "worktree_extras: %s already present in worktree; leaving "
+                "the existing path untouched (entry was %r)",
+                link_path, entry,
+            )
+            continue
+        link_path.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(source, link_path)
+        logger.info("worktree_extras: linked %s -> %s", link_path, source)
+
+
+def detect_undeclared_writes(
+    worktree_path: Path,
+    declared_paths: set[str] | None = None,
+) -> list[str]:
+    """Return paths in ``worktree_path`` that the executor wrote without
+    declaring them via the bundle's ``code_changes`` (#230).
+
+    Parses ``git -C <worktree_path> status --porcelain`` and reports
+    every untracked file (``??``) and modified-tracked file (``M``) that
+    is not already covered by ``declared_paths``. Each returned path is
+    relative to ``worktree_path``.
+
+    Symlinks (typically created by ``worktree_extras``, #229) are
+    excluded — they're orchestrator-managed inputs, not undeclared
+    executor writes.
+
+    The intent is to surface silent loss of work: an executor that
+    writes a Python module via the ``Write`` tool but forgets to add a
+    ``code_changes`` entry will lose the file when the worktree is
+    cleaned up. Reporting it loudly turns the silent loss into an
+    auditable trail.
+    """
+    declared_paths = declared_paths or set()
+    worktree_path = Path(worktree_path)
+
+    if not worktree_path.exists():
+        return []
+
+    result = subprocess.run(
+        ["git", "-C", str(worktree_path), "status", "--porcelain"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        # Worktree may have been removed already, or git is unhappy —
+        # don't make cleanup fail because diagnostics failed.
+        logger.debug(
+            "git status --porcelain on %s exited %s: %s",
+            worktree_path, result.returncode, result.stderr.strip(),
+        )
+        return []
+
+    undeclared: list[str] = []
+    for line in result.stdout.splitlines():
+        if len(line) < 4:
+            continue
+        # Porcelain v1 prefix: 2 status chars + space + path.
+        status = line[:2]
+        path = line[3:].strip()
+        if not (status.startswith("??") or "M" in status):
+            continue
+        if path in declared_paths:
+            continue
+        full = worktree_path / path
+        if full.is_symlink():
+            continue
+        undeclared.append(path)
+    return undeclared
+
+
 def remove_experiment_worktree(repo_path: Path, experiment_id: str) -> None:
     """Remove a previously created experiment worktree and its branch.
 

prompts/methodology/execute_analyze.md

@@ -2,6 +2,14 @@ You are a scientific executor for the Nous hypothesis-driven experimentation fra
 
 You have **shell access**. You are running inside an isolated git worktree of the target system. You own this worktree — reset it yourself with `git checkout -- .` between conditions.
 
+## Worktree discipline (#228)
+
+Your `cwd` is an experiment worktree forked from the target repo's main branch. It contains the tracked source tree plus any symlinks the orchestrator created from `target_system.worktree_extras` (#229) — typically virtualenvs, prefetched data dirs, prior-iteration outputs, build artifacts.
+
+- **Stay in your worktree.** Do not `cd` to the parent repo to "use the real venv" or "read prior-iter results from main." Reference parent assets via the `worktree_extras` symlinks. They appear as ordinary paths inside the worktree and resolve to main automatically.
+- **Reference parent assets through symlinks, not absolute paths into main.** If `worktree_extras` includes `.nous/<campaign>`, read prior-iter files at `.nous/<campaign>/runs/iter-{N-1}/...` (relative — resolves through the symlink), NOT `/Users/<user>/.../<repo>/.nous/<campaign>/...`. Absolute paths into main work today by accident; they break under harness-managed isolation (#123).
+- **Code you write must be declared.** Any new file you create in the worktree must appear in your bundle arm's `code_changes[]` to survive cleanup. Files you don't declare get listed in `findings.worktree_uncommitted_writes` (#230) and lost when the worktree is removed. If you write code outside the worktree (e.g., into a `worktree_extras`-symlinked parent dir), that code persists by virtue of living in main — but think twice before doing it; you're outside the experiment's isolation.
+
 Your job has FIVE phases — all in one session with full context:
 1. **Prepare** — build, create patches, validate ALL commands
 2. **Execute** — run all conditions across seeds, capture results

prompts/methodology/execute_analyze_thin.md

@@ -11,6 +11,15 @@ This iteration's mode is: **{{iteration_mode}}**
 
 {{mode_guidance}}
 
+## Worktree discipline (#228)
+
+Your `cwd` is an experiment worktree, not the target repo. Stay in it.
+Parent-repo assets (venvs, data dirs, prior-iter outputs) appear as
+symlinks declared in `target_system.worktree_extras` (#229) — reference
+them via relative paths, never `cd` to the parent repo. Any file you
+write that isn't in a bundle arm's `code_changes[]` gets listed in
+`findings.worktree_uncommitted_writes` and lost on cleanup (#230).
+
 ## Active principles
 {{active_principles}}