tcw-cli 2.6.5__tar.gz → 2.8.0__tar.gz

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.5
+Version: 2.8.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -476,7 +476,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -685,9 +688,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -699,7 +702,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |
@@ -907,7 +910,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/README.md

@@ -260,7 +260,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -469,9 +472,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -483,7 +486,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |
@@ -691,7 +694,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.6.5"
+version = "2.8.0"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"

tcw_cli-2.8.0/tcw/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.8.0"

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/tcw/cli.py

@@ -10,6 +10,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from tcw.cli_suggest import SuggestingParser, attach_index
 from tcw import __version__
 from tcw.capabilities import cli as capabilities_cli
 from tcw.serve import DEFAULT_PORT, serve
@@ -210,12 +211,14 @@ def _declared_nodes_in_graph(
         # Every project the registry holds, not `ancestors + descendants`. That
         # triple omits a sibling and a sibling of an ancestor — the shapes a
         # workspace is actually made of — so a declaration living on one was
-        # never read, and the repository it named never obtained.
-        roots += [Path(project.locator) for project in
-                  FsProjectRegistry.open(root).projects()]
+        # never read, and the repository it named never obtained. Except an
+        # upstream: what it connects to is its own to obtain, not its readers'.
+        registry = FsProjectRegistry.open(root)
+        roots += [Path(project.locator) for project in registry.projects()
+                  if registry.read_only_reason(project.id) is None]
     except Exception:
         pass
-    found: list[tuple[Path, str, object]] = []
+    found: list[tuple[Path, str, object, str]] = []
     problems: list[str] = []
     for candidate in roots:
         candidate = candidate.resolve()
@@ -224,7 +227,7 @@ def _declared_nodes_in_graph(
         seen.add(candidate)
         declared, candidate_problems = declared_connected_projects(candidate)
         problems += [f"{candidate / SENTINEL}: {p}" for p in candidate_problems]
-        found += [(candidate, pid, d) for pid, d in declared]
+        found += [(candidate, pid, d, relation) for pid, d, relation in declared]
     return found, problems
 
 
@@ -250,7 +253,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
 
     failed = False
     seen: set[Path] = set()
-    queue: list[tuple[Path, str, object]] = []
+    queue: list[tuple[Path, str, object, str]] = []
     # "A project that is already here always wins" is the rule the whole feature
     # rests on, and the walk is the one place it was not applied: a declaration
     # is written by whichever node knows about that edge, so an ancestor
@@ -298,8 +301,14 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             return None
         return located if located != target.resolve() else None
 
-    def enqueue(root: Path) -> None:
+    def enqueue(root: Path, relation: str = "children") -> None:
         nonlocal failed
+        if relation == "upstream":
+            # Obtained so it can be read; its own connections are not followed,
+            # as the registry does not follow them. A reader must never fetch a
+            # project named only by something it reads — a public upstream can
+            # still name the private repository it is migrating away from.
+            return
         found, problems = _declared_nodes_in_graph(root, enqueued)
         for problem in problems:
             print(f"tcw provision: {problem}", file=sys.stderr)
@@ -314,7 +323,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
     enqueued: set[Path] = set()
     enqueue(node_root)
     while queue:
-        source, project_id, declaration = queue.pop(0)
+        source, project_id, declaration, relation = queue.pop(0)
         target = provisioned_store_root(source, declaration)
         if target in seen:
             continue
@@ -335,13 +344,13 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             # provisioning precisely when an earlier one was already in place.
             print(f"  {project_id}: already available")
             have.add(project_id)
-            enqueue(present)
+            enqueue(present, relation)
             continue
         provisioner = FsStoreProvisioner(source, NODE_TARGET, declaration)
         if provisioner.is_available() and not refresh:
             print(f"  {project_id}: already available at {target}")
             have.add(project_id)
-            enqueue(target)
+            enqueue(target, relation)
             continue
         print(f"→ {project_id}: {provisioner.describe().split(': ', 1)[1]}")
         try:
@@ -363,7 +372,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
         # routine when a parent and a grandparent both name it — report
         # "already available" in a run that fetched nothing.
         have.add(project_id)
-        enqueue(target)
+        enqueue(target, relation)
     return failed
 
 
@@ -437,6 +446,8 @@ def _cmd_validate(args: argparse.Namespace) -> int:
         print(f"{entry.declared_in}: connected project '{entry.id}' is declared "
               f"at {entry.locator}, which is not in this checkout; it was found "
               f"at {registry.get(entry.id).locator}", file=sys.stderr)
+    for warning in registry.warnings():
+        print(f"warning: {warning}", file=sys.stderr)
     from tcw.validate import validate
     recurse = args.path is None and not args.no_recurse
     projects = [registry.current, *registry.descendants()] if recurse else [registry.current]
@@ -469,7 +480,7 @@ def _cmd_serve(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
+    parser = SuggestingParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
     parser.add_argument("--version", action="version", version=f"tcw {__version__}")
     sub = parser.add_subparsers(dest="group", required=True)
 
@@ -518,6 +529,7 @@ def build_parser() -> argparse.ArgumentParser:
         p = sub.add_parser(name, help=f"{name} commands (not yet implemented)")
         p.set_defaults(func=_not_yet(name))
 
+    attach_index(parser)
     return parser
 
 
@@ -550,9 +562,9 @@ def main(argv: list[str] | None = None) -> int:
         return 1
     except subprocess.CalledProcessError as error:
         # Deliberately generic: the only policy here is "a git subprocess
-        # failed", which is true of every component. git's own diagnostic has
-        # already reached the terminal — no `check=True` call in the filesystem
-        # adapter captures output — so re-printing `error.stderr` would double it.
+        # failed", which is true of every component. The index-touching calls
+        # capture git's output (so a retried failure does not print once per
+        # try), and it is printed here; an uncaptured call has already shown it.
         # `cmd` is a sequence *or* a string (stdlib contract); joining a string
         # iterates its characters. No shipped raiser passes one, but a handler
         # whose whole justification is that it assumes nothing about its caller
@@ -561,6 +573,8 @@ def main(argv: list[str] | None = None) -> int:
             shlex.join(str(a) for a in error.cmd)
         print(f"tcw: git command failed (exit {error.returncode}): {cmd}",
               file=sys.stderr)
+        if isinstance(error.stderr, str) and error.stderr.strip():
+            print(error.stderr.rstrip("\n"), file=sys.stderr)
         return 1
 
 

tcw_cli-2.8.0/tcw/cli_suggest.py

@@ -0,0 +1,199 @@
+"""Answer a mistyped subcommand with the command that was probably meant.
+
+argparse reports a wrong subcommand by listing every valid choice at that level,
+which says nothing when the word exists one level down (`tcw tracker` for
+`tcw work tracker`) or is a synonym (`status` for `show`). `SuggestingParser`
+keeps argparse's message word for word and adds one line after it.
+
+Three rules, first match wins:
+
+1. The word is a subcommand somewhere else in the tree: name each full command,
+   and complete it with the word that followed when that is wrong there too —
+   `tcw tracker status` → `tcw work tracker show`.
+2. A small table of synonyms, offered only where their target is valid.
+3. Close spellings among the choices valid at that level.
+
+Only subcommands that `--help` lists are ever offered. That is what keeps the
+removed `tcw work stage <id>` spellings — registered without `help=` so that the
+old form can print its replacement — out of every suggestion, without naming
+them here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+
+# One clear target each. Words for removal are left out on purpose: `drop`,
+# `delete` and `rm` destroy things, and pointing at one is worse than no hint.
+SYNONYMS: dict[str, tuple[str, ...]] = {
+    "status": ("show", "list"),
+    "info": ("show",),
+    "view": ("show",),
+    "get": ("show",),
+    "cat": ("show",),
+    "ls": ("list",),
+}
+
+# Never offered by any rule, and never answered either: pointing somebody at a
+# command that destroys things, when they typed something else, is worse than
+# no hint — and so is guessing what a mistyped removal was meant to remove
+# (`tcw work tracker delete` is not `tcw work delete`, which deletes an item).
+REMOVAL = frozenset({"rm", "drop", "delete"})
+
+_MAX = 3
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def visible_choices(action: argparse._SubParsersAction) -> list[str]:
+    """The subcommands this action lists in its help, in its own order."""
+    listed = {choice.dest for choice in action._choices_actions}
+    return [name for name in action.choices if name in listed]
+
+
+def _offered(word: str, choices: list[str]) -> list[str]:
+    """Rules 2 and 3 for one level: synonyms valid here, else close spellings."""
+    safe = [c for c in choices if c not in REMOVAL]
+    synonyms = [s for s in SYNONYMS.get(word, ()) if s in safe]
+    if synonyms:
+        return synonyms
+    return difflib.get_close_matches(word, safe, n=_MAX, cutoff=0.6)
+
+
+def _command(path: tuple[str, ...]) -> str:
+    return "`" + " ".join(path) + "`"
+
+
+def _phrase(commands: list[str]) -> str:
+    if len(commands) == 1:
+        return f"did you mean {commands[0]}?"
+    if len(commands) == 2:
+        return f"did you mean {commands[0]} or {commands[1]}?"
+    return f"did you mean one of {', '.join(commands)}?"
+
+
+class SuggestingParser(argparse.ArgumentParser):
+    """An `ArgumentParser` whose wrong-subcommand error suggests what was meant.
+
+    Every subparser gets this class too, since `add_subparsers` defaults to the
+    parent's. `attach_index` gives the whole tree what the hint needs."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Python 3.14 has argparse's own close-spelling hint. Off, explicitly,
+        # so a later default cannot print a second, different suggestion.
+        self.suggest_on_error = False
+
+    def parse_known_args(self, args=None, namespace=None):
+        # The root keeps what it was asked to parse: a nested parser reports its
+        # own error and needs the word after the one it rejected.
+        if getattr(self, "_tcw_root", None) is self:
+            self._tcw_argv = list(args) if args is not None else None
+        return super().parse_known_args(args, namespace)
+
+    def _check_value(self, action, value):
+        if not isinstance(action, argparse._SubParsersAction) or value in action.choices:
+            return super()._check_value(action, value)
+        choices = visible_choices(action)
+        hint = self._hint(str(value), choices)
+        if len(choices) == len(action.choices):
+            # Nothing hidden: argparse's own message, exactly as this Python
+            # version words it (3.12 and 3.13 leave the choices unquoted).
+            try:
+                super()._check_value(action, value)
+            except argparse.ArgumentError as error:
+                if not hint:
+                    raise
+                raise argparse.ArgumentError(action, f"{error.message}\n{hint}") from None
+        message = (f"invalid choice: {value!r} (choose from "
+                   f"{', '.join(repr(c) for c in choices)})")
+        if hint:
+            message += f"\n{hint}"
+        raise argparse.ArgumentError(action, message)
+
+    def _hint(self, word: str, choices: list[str]) -> str:
+        root = getattr(self, "_tcw_root", None)
+        here = getattr(self, "_tcw_path", None)
+        if root is None or here is None or word in REMOVAL:
+            return ""
+        # Same component first — `tcw work tags show` means a `tcw work …` show,
+        # not `tcw taxonomy show` — then shallowest: `tcw show` means
+        # `tcw work show` before `tcw work inbox show`. `sorted` is stable, so
+        # ties keep tree order.
+        elsewhere = sorted(
+            (p for p in root._tcw_index.get(word, ()) if p[:-1] != here),
+            key=lambda p: (-_shared(p, here), len(p)))
+        if elsewhere:
+            following = _following(root, here, word)
+            commands = []
+            for path in elsewhere[:_MAX]:
+                commands += [_command(path + tail) for tail in _completion(root, path, following)]
+            return _phrase(commands[:_MAX])
+        offered = _offered(word, choices)
+        return _phrase([_command(here + (o,)) for o in offered]) if offered else ""
+
+
+def _shared(path: tuple[str, ...], here: tuple[str, ...]) -> int:
+    """How many leading words `path` shares with `here`."""
+    n = 0
+    for a, b in zip(path, here):
+        if a != b:
+            break
+        n += 1
+    return n
+
+
+def _following(root: SuggestingParser, here: tuple[str, ...], word: str) -> str:
+    """The word after `word` on the command line, if it is not an option."""
+    argv = getattr(root, "_tcw_argv", None) or []
+    start = len(here) - 1                           # `here` includes "tcw"
+    for index in range(start, len(argv)):
+        if argv[index] == word:
+            after = argv[index + 1] if index + 1 < len(argv) else ""
+            return "" if after.startswith("-") else after
+    return ""
+
+
+def _completion(root: SuggestingParser, path: tuple[str, ...],
+                following: str) -> list[tuple[str, ...]]:
+    """How to finish `path` with the word typed after it: kept when it is valid
+    there or there is nothing to finish, else what that word was likely meant as."""
+    parser = root._tcw_parsers.get(path)
+    action = _subparsers(parser) if parser is not None else None
+    if not following or action is None:
+        return [()]
+    choices = visible_choices(action)
+    if following in choices:
+        return [(following,)]
+    offered = _offered(following, choices)
+    return [(o,) for o in offered] or [()]
+
+
+def attach_index(root: SuggestingParser) -> None:
+    """Walk the finished tree once: every parser learns its own path and the
+    root, and the root learns every listed subcommand's full paths."""
+    index: dict[str, list[tuple[str, ...]]] = {}
+    parsers: dict[tuple[str, ...], argparse.ArgumentParser] = {}
+
+    def walk(parser: argparse.ArgumentParser, path: tuple[str, ...]) -> None:
+        parser._tcw_root = root
+        parser._tcw_path = path
+        parsers[path] = parser
+        action = _subparsers(parser)
+        if action is None:
+            return
+        listed = set(visible_choices(action))
+        for name, child in action.choices.items():
+            if name in listed:
+                index.setdefault(name, []).append(path + (name,))
+            walk(child, path + (name,))
+
+    walk(root, (root.prog,))
+    root._tcw_index = index
+    root._tcw_parsers = parsers

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/tcw/refs.py

@@ -135,6 +135,10 @@ def resolve_tcw_ref(node_root: Path | None, uri: str) -> ResolveResult:
             return ResolveResult(
                 False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
         store, bare = resolved
+        # A renamed item answers to its old slug too: a link is exactly the kind
+        # of reference a rename cannot rewrite.
+        if store.get(bare) is None and (renamed := store.renamed(bare)):
+            bare = renamed
         # Locating the store that would hold the item is not the item existing.
         # `resolve_qualified_work_ref` answers "which store addresses this ref",
         # which is what `tcw serve`'s routing wants; `ok` answers "does this

{tcw_cli-2.6.5 → tcw_cli-2.8.0}/tcw/serve/__init__.py

@@ -24,7 +24,8 @@ from tcw.store.base import (
 )
 from tcw.store.fs import (
     FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, descendant_nodes,
-    find_node_root, heading_slug, registered_project_id, resolve_qualified_work_ref,
+    find_node_root, heading_slug, registered_project_id, qualified_work_ref_read_only,
+    resolve_qualified_work_ref,
 )
 from tcw.refs import resolve_tcw_ref
 from tcw.validate import ValidationTarget, validate
@@ -507,6 +508,21 @@ class TcwHandler(BaseHTTPRequestHandler):
             return resolve_qualified_work_ref(self.server.node_root, slug)
         return FsWorkStore.open(self.server.node_root), slug
 
+    def _refused_read_only(self, slug: str) -> bool:
+        """Answer 403 and return True when `slug` names an item in a project this
+        node reads but may not write — an upstream project, or one reached only
+        through one. Every route that changes an item or runs its project's
+        scripts asks this first; reads do not, so the board can still show it."""
+        if not self.server.include_descendants:
+            return False
+        reason = qualified_work_ref_read_only(self.server.node_root, slug)
+        if reason is None:
+            return False
+        self._send_err(HTTPStatus.FORBIDDEN,
+                       f"{reason}; change it from that project itself",
+                       code="read-only-project")
+        return True
+
     def _hosted_projects(self) -> set[str]:
         """Project IDs whose items this server actually serves — the descendants it
         aggregates, or nothing when not aggregating.
@@ -951,6 +967,7 @@ class TcwHandler(BaseHTTPRequestHandler):
                 initiative = body.get("initiative", "")
                 type_val = body.get("type", "")
                 tags = body.get("tags") or None
+                work.refresh_for_creation()
                 detail = work.create_work(
                     title=title,
                     created=created,
@@ -971,6 +988,14 @@ class TcwHandler(BaseHTTPRequestHandler):
                     # stale — which the next sidecar write from the page would
                     # be rejected on.
                     detail = work.get_detail(detail.item.slug) or detail
+                # After the owed record, so it is in the same commit. A refusal
+                # is logged, not returned: the item exists, and an error here
+                # would invite the browser to create it a second time.
+                folder = work.path(detail.item.slug)
+                if folder is not None and (reason := work.commit_writes(
+                        f"tcw work: new {detail.item.slug}", folder)):
+                    print(f"tcw serve: created {detail.item.slug}, but {reason}",
+                          file=sys.stderr)
                 response = {
                     "item": _item_payload(work, detail.item.slug, detail.item),
                     "coreRevision": detail.core_revision,
@@ -993,6 +1018,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             slug = _decode_path_param(m.group(1))
             action = _decode_path_param(m.group(2))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1216,6 +1243,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1370,6 +1399,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             if name not in WORK_ARTIFACTS:
                 self._send(HTTPStatus.BAD_REQUEST, b"unknown artifact")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1408,6 +1439,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1443,6 +1476,8 @@ class TcwHandler(BaseHTTPRequestHandler):
                                f"{name} is written by `{owner}`, not edited; "
                                f"run that command instead.")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1498,6 +1533,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1515,6 +1552,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         m = re.match(r"^/api/work/([^/]+)$", path)
         if m:
             slug = _decode_path_param(m.group(1))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1584,6 +1623,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         slug_q, _, stage_q = middle.partition("/plan-stages/")
         slug = _decode_path_param(slug_q)
         stage_id = _decode_path_param(stage_q)
+        if self._refused_read_only(slug):
+            return
         resolved = self._resolve_work(slug)
         if resolved is None:
             self._send(HTTPStatus.NOT_FOUND, b"no such work item")