@appchy/jarvis 0.1.113 → 0.1.115

package/harness/harness/align.py

@@ -400,14 +400,17 @@ def _align_versions(root: Path, s: dict) -> list:
                     out.append(("warn", "released-brief", f"version {v.name}: "
                                 f"released but still carries {brief} — a cut-local "
                                 f"brief collapses at release"))
-            # Same rule, one tier down: an epic is the plan-it-together doc, and
-            # `release` removes it. One left standing means a release that did not
-            # go through `jarvis work release`.
+            # One tier down the test inverts: a released plan is KEPT, so its
+            # presence is correct and what would be wrong is an unstamped one. An
+            # epic plan with no released banner means a release that did not go
+            # through `jarvis work release` — or a plan added to a cut afterwards,
+            # which is the same problem wearing different clothes.
+            from .epic import _RELEASED_MARKER
             for e in v.epics:
-                if e.planned:
+                if e.planned and _RELEASED_MARKER not in e.md.read_text(errors="ignore"):
                     out.append(("warn", "released-brief", f"version {v.name}: "
-                                f"released but epic '{e.name}' still carries "
-                                f"epic.md — an epic archives at release"))
+                                f"released but epic '{e.name}' carries a plan that is "
+                                f"not stamped as released — it reads as live direction"))
     return out
 #: An agent-file reference in skill prose, in either of the two shapes an agent dir
 #: takes: `.claude/agents/<name>.md` in a repo that keeps its own agents, and a bare

package/harness/harness/epic.py

@@ -220,13 +220,19 @@ _DURABLE_SECTIONS = ("## Governance this implies", "## Non-goals", "### Settled"
                      "### Forward-compat")
 
 
-def removal_cost(version) -> tuple:
-    """What releasing this cut would delete: `(plans, bytes, sections)`.
+def plans_held(version) -> tuple:
+    """What this cut's epic plans hold: `(plans, bytes, sections)`.
 
-    One derivation, because two surfaces quote this price now — the notice
-    `release` prints just before the unlink, and the line `status` shows a person
-    deciding whether to run it at all. A warning and a confirmation that disagreed
-    about the cost would make both worth less than either.
+    One derivation, because two surfaces quote it — the notice `release` prints as
+    it stamps the plans, and the line `status` shows a person deciding whether to
+    run it at all. Two surfaces that disagreed about what a cut carries would make
+    both worth less than either.
+
+    It measured what release was about to DELETE until 2026-09-12, when a released
+    plan started being kept instead. The number is the same number; what it is
+    evidence for is not. It now says how much settled prose is going quiet, which is
+    the argument for lifting the durable half into an owner file — not a last call
+    before the bytes go.
 
     `sections` is every durable heading found across the plans, deduplicated: it is
     what a reader needs to judge whether the text is safe to lose, and it is the
@@ -245,21 +251,23 @@ def removal_cost(version) -> tuple:
     return len(plans), total, sorted(held)
 
 
-def _cost_of_removing(version, root) -> list:
-    """What this release is about to delete, as lines a person can act on.
+def _cost_of_closing(version, root) -> list:
+    """What this release is about to stamp shut, as lines a person can act on.
+
+    **Said while the plans are still the live thing a reader would reach for.** The
+    text no longer leaves the tree — a released plan is stamped and kept — so this is
+    not a last call before the bytes go. It is the argument for the sweep: a stamped
+    plan is history, and a decision left in one is a decision the next session will
+    not find when it reads the owner file.
 
-    **Said BEFORE the unlink, because the advice that follows a release is useless
-    after it.** `release` has always printed _"promote still-load-bearing decisions
-    to the domain that owns them"_ — and printed it after the files holding those
-    decisions had already left the tree. Measured 2026-09-11 on `01-one-board`: twelve
-    plans, 450,405 bytes, about a hundred durable statements with no owner file, and
-    the recovery commit had to be worked out by hand afterwards from `git log
-    --diff-filter=D`.
+    Measured 2026-09-11 on `01-one-board`: twelve plans, 450,405 bytes, about a
+    hundred durable statements with no owner file. Those plans were deleted by the
+    release that day and restored on 2026-09-12, which is why deletion is no longer
+    what this reports.
 
-    So this names the size, the sections that can outlive the plan, and the commit
-    where the text still lives. It does not judge whether a statement is durable —
-    that is the judgement a lint cannot make, and claiming it would be worse than
-    saying nothing.
+    It names the size and the sections that can outlive the plan. It does not judge
+    whether a statement is durable — that is the judgement a lint cannot make, and
+    claiming it would be worse than saying nothing.
     """
     plans = [e for e in version.epics if e.planned]
     if not plans:
@@ -275,57 +283,77 @@ def _cost_of_removing(version, root) -> list:
                 for h in _DURABLE_SECTIONS if h in text]
         note = f" — holds §{', §'.join(held)}" if held else ""
         out.append(f"          {e.name}  {len(text.encode()):,} bytes{note}")
-    head = _still_holds(root)
-    return ([f"\n        DELETING {len(plans)} epic plan(s), {total:,} bytes. Anything "
-             f"durable in them must already be in the file that owns it — after this "
-             f"they are in git only, and nobody reads git for a decision:"]
+    return ([f"\n        STAMPING {len(plans)} epic plan(s), {total:,} bytes, as released. "
+             f"They stay in the tree and every link to them keeps resolving — but a "
+             f"stamped plan is history, so anything durable belongs in the file that "
+             f"owns it:"]
             + out
-            + ([f"          the text stays recoverable at {head}"] if head else [])
-            + ["          `git show <commit>:<path>` — and `jarvis work align` reports "
-               "what cites a file that is gone"])
+            + ["          `jarvis work align` reports what cites a file that is gone"])
+
 
+#: What a released plan opens with. Matched on the marker rather than the whole line,
+#: so a cut reopened and released again finds its own stamp instead of stacking a second.
+_RELEASED_MARKER = "> **A released plan"
 
-def _still_holds(root) -> str:
-    """The commit whose tree still contains these plans, or empty when git cannot say.
 
-    HEAD is the right answer, and it is worth being precise about why: the unlink has
-    not happened yet and the board write commits after it, so at the moment this
-    prints, the newest commit in the history is one that still holds every file about
-    to go. Through the same seam every other git question goes through — a second way
-    of asking would eventually give a second answer.
+def _stamp_released(epic, version_name) -> bool:
+    """Mark a plan as history in the file itself. True when it was added.
+
+    In the document rather than in the folder name, because a reader who followed a
+    link is holding the document and never saw the folder. After the frontmatter and
+    before the first heading, which is the one place it cannot be scrolled past.
     """
-    from . import git
-    code, out, _ = git._git(root.parent, "rev-parse", "--short", "HEAD")
-    return out.strip() if code == 0 else ""
+    text = epic.md.read_text()
+    if _RELEASED_MARKER in text:
+        return False
+    banner = (f"{_RELEASED_MARKER} — `{version_name}` shipped "
+              f"{date.today().isoformat()}.**\n"
+              f"> It says how the work was planned, never what is true now. Anything here\n"
+              f"> that still governs belongs in the file that owns it — `jarvis work where "
+              f"<id>` finds one.\n\n")
+    if text.startswith("---\n"):
+        close = text.index("\n---\n", 3) + len("\n---\n")
+        text = text[:close] + "\n" + banner + text[close:].lstrip("\n")
+    else:
+        text = banner + text
+    epic.md.write_text(text)
+    return True
 
 
 def cmd_epic_release(root, version) -> int:
-    """Remove every `epic.md` in a released version, and report it.
+    """Stamp every `epic.md` in a released version as history, and KEEP it.
 
-    An epic is TEMPORARY by definition: it is the plan-it-together doc, and how
-    the work was planned stops being true the moment it ships. The folder stays
-    as the grouping of what shipped — that record is worth keeping — and git
-    holds the plan. Called from `cmd_release`, never on its own.
+    An epic is temporary: how the work was planned stops being true the moment it
+    ships. What does not follow is that the file should go. Deleting it was the rule
+    until 2026-09-12, and the price was measured rather than argued: releasing
+    `01-one-board` removed twelve plans, left 104 links across the repo pointing at a
+    file that no longer existed, and put the text somewhere only a person who knew the
+    commit could reach. Nobody reads git for a decision.
 
-    It says what it is deleting FIRST. The cost of a release is not the stamp, it is
-    the plans that go with it, and a person deciding needs that in front of them
-    while the files still exist."""
-    for line in _cost_of_removing(version, root):
+    So the plan stays where every link already points and travels to the archive with
+    the rest of the cut, which `links.repairing` handles like any other move. The
+    sweep that lifts durable statements into their owner files is still worth doing —
+    it is just no longer a race against an unlink.
+
+    Called from `cmd_release`, never on its own.
+    """
+    for line in _cost_of_closing(version, root):
         print(line)
-    removed = []
+    stamped = []
     for e in version.epics:
-        # An epic with no plan doc is already in the shape this produces — a folder
-        # grouping tasks. Unlinking regardless raised AFTER `released:` had been
-        # stamped, so the cut read as released while every other epic kept the file
-        # this exists to remove.
+        # An epic with no plan doc has nothing to stamp. It was also the case that
+        # unlinking regardless raised AFTER `released:` was stamped, leaving the cut
+        # reading as released with every other plan untouched.
         if not e.planned:
             continue
-        e.md.unlink()
-        removed.append(e.name)
-    if removed:
-        print(f"        archived {len(removed)} epic(s) — epic.md removed, "
-              f"folders kept as the grouping: {', '.join(removed)}")
-    return len(removed)
+        if _stamp_released(e, version.name):
+            stamped.append(e.name)
+    if stamped:
+        print(f"        stamped {len(stamped)} epic plan(s) as released and kept them "
+              f"in place: {', '.join(stamped)}")
+    return len(stamped)
+
+
 def epic_for_task(root, args, version_name):
     """Resolve the `--epic` a task command names, and check it agrees with any
     `--version` also given. Returns (epic, version_name) — the version is

package/harness/harness/links.py

@@ -191,3 +191,117 @@ def repairing(repo: Path, indent: str = "  "):
                 print(f"{indent}repaired {repaired} link(s) that pointed at what moved")
             for line in unresolved:
                 print(f"{indent}COULD NOT PLACE  {line}")
+
+
+#: The three files that ARE a board item, so a folder holding one is addressable by
+#: its name. Names are globally unique across tasks, epics and versions, which is what
+#: makes a name a usable second resolver when a path has stopped working.
+_ITEM_FILES = ("task.md", "epic.md", "version.md")
+
+
+def _index(base: Path) -> dict:
+    """Board item folders by name. A name with two homes is left out rather than guessed."""
+    homes: dict = {}
+    for doc in base.rglob("*.md"):
+        if SKIP & set(doc.parts) or doc.name not in _ITEM_FILES:
+            continue
+        homes.setdefault(doc.parent.name, set()).add(doc.parent.resolve())
+    return {name: next(iter(dirs)) for name, dirs in homes.items() if len(dirs) == 1}
+
+
+def _settle(doc: Path, href: str, index: dict):
+    """Where a broken link meant to point, or None when that is a guess.
+
+    Two resolvers, and both must land on exactly one file. **Depth first**: the tail
+    is right and the `../` count is wrong, which is what a file written at one tier
+    and moved to another leaves behind. **Then by name**: the item moved bucket or
+    epic, so no `../` count reaches it, but the folder it lives in is named in the
+    link and a board name has one home. Anything either resolver finds twice, or
+    neither finds at all, is reported for a person — a link repaired to the wrong
+    real file is worse than one that is visibly broken.
+    """
+    path = href.split("#")[0]
+    # Only the leading `./` and `../` hops come off. `lstrip("./")` would take the
+    # dot of `.github` with them and then resolve nothing, which is a link reported
+    # as unfixable because the checker damaged it on the way in.
+    tail = _HOPS.sub("", path)
+    hits = {c.resolve() for n in range(10)
+            if (c := doc.parent / ("../" * n) / tail).exists()}
+    if len(hits) == 1:
+        return next(iter(hits))
+
+    parts = [p for p in path.split("/") if p not in ("..", ".", "")]
+    if len(parts) >= 2 and (home := index.get(parts[-2])) is not None:
+        want = home / parts[-1]
+        if want.exists():
+            return want.resolve()
+    return None
+
+
+#: An inline code span. A doc that TEACHES the link syntax writes `](../…md)` inside
+#: backticks, and a checker that reads it as a link reports a file nobody ever meant
+#: to exist. Same shape of suppression the governance lints use, and the same reason:
+#: a blocking check's whole cost is its false positives.
+#:
+#: It crosses newlines because a quoted anchor wraps like any other prose, and the
+#: one live false positive this check ever produced was a span that opened on one
+#: line and closed on the next. Bounded rather than greedy: an unbalanced backtick
+#: somewhere in a long document must not swallow the links after it.
+CODE_SPAN = re.compile(r"`[^`]{0,500}`", re.S)
+
+#: Leading `./` and `../` hops, and nothing else.
+_HOPS = re.compile(r"^(?:\.{1,2}/)+")
+
+
+def dangling(base: Path) -> list:
+    """Every relative markdown link under `base` that resolves to nothing.
+
+    Returns `(doc, href, fix_or_None)` per broken link. This is the set `snapshot()`
+    records and `repair()` refuses on purpose — a link broken BEFORE a move has no
+    before-state to be repaired by identity, so it is settled from its own text or
+    not at all.
+    """
+    index = _index(base)
+    out = []
+    for doc in sorted(_docs(base)):
+        try:
+            text = doc.read_text(errors="ignore")
+        except OSError:
+            continue
+        text = CODE_SPAN.sub("", text)
+        for href in dict.fromkeys(m.group(1) for m in LINK.finditer(text)):
+            if "://" in href or href.startswith(("#", "mailto:", "/")):
+                continue
+            if (doc.parent / href.split("#")[0]).exists():
+                continue
+            out.append((doc, href, _settle(doc, href, index)))
+    return out
+
+
+def repair_dangling(base: Path, apply: bool = False) -> tuple:
+    """Point every settled broken link at what it names. Returns (fixed, stuck).
+
+    Rewrites on the link's own syntax, never on the bare path, so a path that also
+    appears in a sentence is left alone — the same anchoring `repair()` uses, for the
+    same reason.
+    """
+    fixed, stuck = 0, []
+    edits: dict = {}
+    for doc, href, target in dangling(base):
+        if target is None:
+            stuck.append((doc, href))
+            continue
+        _, _, anchor = href.partition("#")
+        new = os.path.relpath(target, doc.parent) + (f"#{anchor}" if anchor else "")
+        if new == href:
+            stuck.append((doc, href))
+            continue
+        edits.setdefault(doc, []).append((href, new))
+        fixed += 1
+    if apply:
+        for doc, pairs in edits.items():
+            text = doc.read_text(errors="ignore")
+            for href, new in pairs:
+                text = text.replace(f"]({href})", f"]({new})")
+            doc.write_text(text)
+    return fixed, stuck

package/harness/harness/report.py

@@ -165,6 +165,50 @@ def misalignments(root: Path) -> list:
             + _align_agents(root) + _align_retired(root) + _align_acceptance(root))
 
 
+#: A cut that has shipped, and the archive it ends up in. Their links are reported
+#: and never blocking: a plan naming source that has since been deleted, or a
+#: `handoff.md` that `archive` stripped, is an accurate record of a world that is
+#: gone. Demanding those resolve would make the gate unsatisfiable for a reason
+#: nobody could act on.
+_SHIPPED = ("versions/complete/", "archive/")
+
+
+def cmd_links(args) -> int:
+    """Board links that point at nothing. Exits 1 on a LIVE one, so a gate can block.
+
+    Blocking is safe here in a way it is not for the prose checks next door: a link
+    either resolves or it does not, there is no sentence to argue with, and the steady
+    state is zero because every folder move repairs its own links. A red therefore
+    means somebody hand-wrote a path, which is a ten-second fix — not a judgement call
+    a reader has to relitigate.
+
+    `--fix` repairs what is settled and leaves the rest. It is the only write, and it
+    is refused nothing: repairing a link that resolves to exactly one file cannot lose
+    anything, because the old path resolved to no file at all.
+    """
+    from . import links as links_mod
+    root = find_work_root()
+    if args.get("fix"):
+        fixed, _ = links_mod.repair_dangling(root, apply=True)
+        print(f"  repaired {fixed} link(s)")
+
+    broken = links_mod.dangling(root)
+    live = [(d, h) for d, h, _ in broken
+            if not any(m in str(d) for m in _SHIPPED)]
+    shipped = len(broken) - len(live)
+
+    for doc, href in live:
+        print(f"  ✗ {doc.relative_to(root.parent)} -> {href}")
+    if shipped:
+        print(f"  · {shipped} more in cuts that have shipped — reported, never blocking")
+    if not live:
+        print("  every link in a live brief or governance file resolves")
+        return 0
+    print(f"\n  {len(live)} broken link(s) in live files · exit 1   "
+          f"(`jarvis work links --fix` repairs what it can settle)")
+    return 1
+
+
 def cmd_align(args) -> int:
     """Report every misalignment class. REPORT-ONLY, exit 0 — by founder call.
 

package/harness/harness/shift.py

@@ -27,7 +27,7 @@ from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
 from .frontmatter import rewrite_file
 from .model import locate, missing, record_session, scan
 from .generate import _sync
-from .epic import removal_cost
+from .epic import plans_held
 from . import autonomy, events, links, peers
 # The ceiling is read through the MODULE, never bound in with `from … import`.
 # A `from .autonomy import CEILING` captures the value at import time, so
@@ -286,10 +286,11 @@ def cmd_status(args) -> int:
     ready = [v for v in s["versions"] if v.finishable()]
     print(f"WAITING ON YOU  ({len(waiting) + len(ready)})")
     for v in ready:
-        plans, size, held = removal_cost(v)
+        plans, size, held = plans_held(v)
         cost = ""
         if plans:
-            cost = (f" — releasing deletes {plans} epic plan(s), {size:,} bytes"
+            cost = (f" — releasing stamps {plans} epic plan(s) as history, "
+                    f"{size:,} bytes"
                     + (f", holding §{', §'.join(held)}" if held else ""))
         print(f"  {v.name}: every task is complete and the cut is still open "
               f"— `jarvis work release {v.name}`{cost}")

package/harness/harness/version.py

@@ -198,12 +198,12 @@ def cmd_release(args) -> int:
     # how the work was planned stops being true once it ships.
     cmd_epic_release(root, version)
     print("\nDistill before archiving:")
-    # Points at the commit the deletion just named, because this instruction used to
-    # send a reader to files the same command had already removed — and the one time
-    # it mattered, the recovery commit had to be reconstructed afterwards with
-    # `git log --diff-filter=D`.
+    # The plans are still in the tree, stamped as history, so this points at them
+    # rather than at a commit. It sent a reader to files the same command had already
+    # removed until 2026-09-12, and the one time it mattered the recovery commit had
+    # to be reconstructed afterwards with `git log --diff-filter=D`.
     print("  1. Promote still-load-bearing decisions to the domain or system that owns "
-          "them — read them from the commit named above; they are no longer in the tree")
+          "them — the plans are stamped and kept, so read them where they sit")
     print(f"  2. Repoint any inbound deep-links to those {ids.LEDGER}-nn entries")
     print(f"  3. {cli()} archive {name}   (strips each task to task.md, and "
           f"files a RELEASED cut under versions/complete/)")

package/harness/presets/appchy/PRESET.md

@@ -308,9 +308,9 @@ files are deleted. **Read a dissolving `epic.md` in full first** — a thin epic
 fully-planned, deliberately-deferred goal hides.
 
 A version's status is derived: **planned** until tasks start, **current** while any is in-progress,
-**released** once `jarvis work release` stamps it. Release **flattens the done tier**, removes each
-`epic.md`, then `jarvis work archive` strips each task to its `task.md` and moves the version to
-`work/archive/versions/<v>/`.
+**released** once `jarvis work release` stamps it. Release **flattens the done tier** and **stamps
+each `epic.md` as history, keeping it**, then `jarvis work archive` strips each task to its `task.md`
+and moves the version to `work/archive/versions/<v>/`.
 
 **Archived is off the board, not gone.** `list`, the README table and every lint see only `versions/`.
 `jarvis work path <v>` and `jarvis work where <id>` still resolve into the archive.
@@ -338,8 +338,9 @@ is a brief and nothing else.
 says so, and it is right: that is an epic wearing a task costume. Split it by *goal*, not by layer.
 
 `epic.md` is mandatory for an epic and owns three things nothing else does — the **Goal** in user
-terms, the **Plan** every task builds against, and **Governance this implies**. It is **removed by
-`jarvis work release`**.
+terms, the **Plan** every task builds against, and **Governance this implies**. `jarvis work
+release` **stamps it as history and keeps it** — it used to delete it, which cost 104 dangling links
+and put the text where only somebody who knew the commit could read it (2026-09-12).
 
 `handoff.md` is the **cross-conversation** artifact, not a per-task journal: **not** scaffolded on
 pickup — create it with `jarvis work handoff <name>` only when handing the task to a fresh session. A task
@@ -459,8 +460,8 @@ The two task-count rules are one rule from both ends: **a task is one goal, an e
 **done** epic is exempt from the floor; it is history, not a plan.
 
 `jarvis work align` reports every misalignment class — dangling citation · orphan/uncovered AC · unenforced
-rule · retired concept still named live · complete-but-unreleased version · an `epic.md` surviving a
-release. Report-only, exit 0.
+rule · retired concept still named live · complete-but-unreleased version · a released cut whose
+`epic.md` is not stamped as history. Report-only, exit 0.
 
 ## Every board write lands in git
 
@@ -716,8 +717,10 @@ The spend is authored prose. Keep it tight:
 - **Cannot `new` or `epic-new` into a released version.**
 - **Cannot `release`** a version with incomplete tasks, zero tasks, or no `outcome:`. **Cannot
   `archive`** one that isn't released.
-- **`release` deletes every `epic.md`.** Anything durable in an epic's §Plan or §Governance must have
-  landed in its owner doc before you release — git keeps the text, but nobody will look.
+- **`release` stamps every `epic.md` as history and keeps it** (2026-09-12; it deleted them until
+  then). Nothing is lost and every link still resolves — but a stamped plan is history, so anything
+  durable in its §Plan or §Governance still belongs in the file that owns it. A reader who needs a
+  decision reads the owner file, and will not go looking in a shipped cut's plan.
 - **Names are globally unique across tasks, epics and versions.** Renaming = move the folder by hand +
   update any `depends_on:`.
 - **`README.md` BACKLOG markers are load-bearing** — preserve them if you hand-edit around the table.