@appchy/jarvis 0.1.113 → 0.1.115

package/harness/test_work.py

@@ -506,21 +506,43 @@ def test_a_grandfathered_flat_version_still_reads():
         assert [t.epic for t in ver.all_tasks()] == [None]
 
 
-def test_release_removes_epic_md_without_orphaning_its_tasks():
-    # The bug this guards: `release` deletes the plan doc, so "an epic is a dir
-    # with epic.md" would stop matching and the shipped tasks would disappear.
+def test_release_stamps_the_plan_as_history_and_keeps_it():
+    # Release deleted the plan until 2026-09-12. It cost 104 dangling links across
+    # the repo and put the text where only somebody who knew the commit could read
+    # it, so the plan is now stamped and kept. What this guards is that the stamp
+    # actually lands in the file a reader opens — a folder-level marker would be
+    # invisible to anyone who arrived by following a link.
     with tempfile.TemporaryDirectory() as tmp:
         v = _tree(tmp)
         e = _epic(v, "publish-under-your-name")
         _task(e / "complete", "author-a-lesson")
         version.cmd_epic_release(Path(tmp), model.Version(v))
-        assert not (e / "epic.md").exists()
+        assert (e / "epic.md").is_file()
+        body = (e / "epic.md").read_text()
+        assert epic._RELEASED_MARKER in body
+        # Before the first heading, so it cannot be scrolled past.
+        assert body.index(epic._RELEASED_MARKER) < body.index("# ")
         after = model.Version(v)
         assert [x.name for x in after.epics] == ["publish-under-your-name"]
-        assert after.epics[0].planned is False
+        assert after.epics[0].planned is True
         assert [t.name for t in after.all_tasks()] == ["author-a-lesson"]
 
 
+def test_releasing_twice_does_not_stack_a_second_stamp():
+    # A cut can be reopened and released again, and `align` reads the marker to tell
+    # a stamped plan from a live one. Two banners would still read as stamped, so
+    # this is about the document staying readable rather than about the check.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        e = _epic(v, "publish-under-your-name")
+        _task(e / "complete", "author-a-lesson")
+        version.cmd_epic_release(Path(tmp), model.Version(v))
+        first = (e / "epic.md").read_text()
+        version.cmd_epic_release(Path(tmp), model.Version(v))
+        assert (e / "epic.md").read_text() == first
+        assert first.count(epic._RELEASED_MARKER) == 1
+
+
 def test_a_finished_epic_drops_into_the_done_tier_and_comes_back_out():
     # The tier is DERIVED, so the only thing that may move an epic is what its
     # tasks say — and it has to work in BOTH directions, or reopening a task would
@@ -951,13 +973,13 @@ def test_a_flat_version_is_grandfathered_but_a_mixed_one_is_not():
         assert any("straggler: loose in version" in w for w in _warns(Path(tmp)))
 
 
-def test_release_removes_epic_md_for_an_epic_parked_in_the_done_tier():
+def test_release_stamps_the_plan_of_an_epic_parked_in_the_done_tier():
     # THE bug on release's only normal path. A version is releasable only when every
     # task is complete — which is exactly the condition that parks each epic in
     # `<v>/complete/`. `release` flattens that tier first, then removed `epic.md`
     # from the PRE-MOVE model: FileNotFoundError, raised *after* `released:` was
-    # already stamped. A traceback, a half-applied release, and `epic.md` — the one
-    # file release exists to remove — left behind for `align` to report.
+    # already stamped. A traceback, a half-applied release, and an unstamped plan
+    # left behind for `align` to report.
     import os
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
@@ -970,10 +992,13 @@ def test_release_removes_epic_md_for_an_epic_parked_in_the_done_tier():
         finally:
             os.environ.pop("WORK_DIR")
 
-        # Flattened out of the done tier, epic.md gone, folder kept as the grouping.
+        # Flattened out of the done tier, the plan kept and stamped, folder kept as
+        # the grouping.
         assert (v / "a-shipped-goal").is_dir()
         assert not (v / tree.DONE_TIER).exists()
-        assert not list(v.rglob("epic.md")), "release must remove every epic.md"
+        plans = list(v.rglob("epic.md"))
+        assert len(plans) == 1, "release must keep the plan, not remove it"
+        assert epic._RELEASED_MARKER in plans[0].read_text()
         assert (v / "a-shipped-goal" / "complete" / "shipped-thing" / "task.md").is_file()
         assert model.Version(v).released
 
@@ -2051,6 +2076,103 @@ def test_a_finished_cut_leaves_the_board_without_pretending_it_shipped():
             os.environ.pop("WORK_DIR", None)
 
 
+def test_a_standing_broken_link_is_settled_by_depth_or_by_board_name():
+    # The set `repair()` refuses on purpose: broken BEFORE any move, so there is no
+    # before-state and identity cannot answer. Two resolvers instead — the tail is
+    # right and the `../` count is wrong, or the item moved bucket and the folder it
+    # lives in is named in the link.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        (base / "product").mkdir(parents=True)
+        (base / "product" / "board.md").write_text("# board\n")
+        moved = base / "versions" / "a-cut" / "an-epic" / "complete" / "shipped-thing"
+        moved.mkdir(parents=True)
+        (moved / "task.md").write_text("# shipped thing\n")
+
+        doc = base / "versions" / "a-cut" / "an-epic" / "queue" / "live-one" / "task.md"
+        doc.parent.mkdir(parents=True)
+        doc.write_text(
+            # two hops short of product/
+            "governed by [board](../../../product/board.md), "
+            # names a bucket the item has left
+            "after [shipped](../shipped-thing/task.md).\n")
+
+        fixed, stuck = links.repair_dangling(base, apply=True)
+        assert (fixed, stuck) == (2, []), (fixed, stuck)
+        body = doc.read_text()
+        assert "](../../../../../product/board.md)" in body, body
+        assert "](../../complete/shipped-thing/task.md)" in body, body
+        assert links.dangling(base) == []
+
+
+def test_a_broken_link_two_resolvers_disagree_about_is_left_for_a_person():
+    # A link repaired to the wrong real file is worse than one that is visibly
+    # broken: nothing afterwards can tell it was ever wrong.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        # The SAME tail exists at two heights on one walk up, so counting `../`
+        # cannot choose between them.
+        (base / "notes").mkdir(parents=True)
+        (base / "notes" / "shared.md").write_text("# the outer one\n")
+        (base / "one" / "notes").mkdir(parents=True)
+        (base / "one" / "notes" / "shared.md").write_text("# the inner one\n")
+        doc = base / "one" / "notes" / "deep" / "doc.md"
+        doc.parent.mkdir(parents=True)
+        doc.write_text("see [it](../../../../notes/shared.md)\n")
+
+        fixed, stuck = links.repair_dangling(base, apply=True)
+        assert fixed == 0, "a link two candidates answer must not be rewritten"
+        assert [h for _, h in stuck] == ["../../../../notes/shared.md"]
+        assert "](../../../../notes/shared.md)" in doc.read_text(), "it was rewritten"
+
+
+def test_a_link_inside_a_code_span_is_prose_and_never_a_finding():
+    # A doc teaching the syntax writes `](../…md)` in backticks. The live false
+    # positive this check ever produced was a quoted anchor whose span opened on one
+    # line and closed on the next, so the span has to cross newlines.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        base.mkdir(parents=True)
+        (base / "doc.md").write_text(
+            "Resolving every `](../…md)` in the tree.\n\n"
+            "The anchor reads `[sessions](sessions.md)'s AC-03 and the test\n"
+            "lands later`, which is a quotation.\n\n"
+            "But [this one](../really-gone.md) is a link.\n")
+
+        broken = links.dangling(base)
+        assert [h for _, h, _ in broken] == ["../really-gone.md"], broken
+
+
+def test_the_links_gate_blocks_on_a_live_brief_and_never_on_a_shipped_cut():
+    # Blocking is only safe because the steady state is zero — every folder move
+    # repairs its own links — and because a shipped cut is allowed to name things
+    # that have since been deleted.
+    import contextlib, io
+    from harness import report
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp) / "work"
+        shipped = root / "versions" / "complete" / "01-done" / "an-epic"
+        shipped.mkdir(parents=True)
+        (shipped / "epic.md").write_text("gone: [src](../../../../src/deleted.ts)\n")
+        os.environ["WORK_DIR"] = str(root)
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as out:
+                assert report.cmd_links({}) == 0, "a shipped cut must not block"
+            assert "never blocking" in out.getvalue()
+
+            live = root / "versions" / "02-open" / "an-epic" / "queue" / "a-task"
+            live.mkdir(parents=True)
+            (live / "task.md").write_text("see [rule](../../../../nowhere.md)\n")
+            with contextlib.redirect_stdout(io.StringIO()) as out:
+                assert report.cmd_links({}) == 1, "a live broken link must block"
+            assert "nowhere.md" in out.getvalue()
+        finally:
+            os.environ.pop("WORK_DIR", None)
+
+
 def test_links_are_repaired_by_what_they_pointed_at_not_by_what_they_say():
     from harness import links
     with tempfile.TemporaryDirectory() as tmp:
@@ -6394,7 +6516,8 @@ def test_an_epic_whose_plan_doc_is_gone_still_moves_into_a_cut():
 def test_releasing_a_cut_holding_an_epic_with_no_plan_doc_still_releases_it():
     # The unlink ran on every epic, so one without a plan doc raised — and it raised
     # AFTER `released:` was stamped, leaving the cut reading as released while every
-    # other epic kept the file release exists to remove.
+    # other epic went untouched. The stamp has the same shape of hazard: an epic with
+    # nothing to stamp must be skipped rather than read.
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         v = _tree(tmp)
@@ -6412,9 +6535,10 @@ def test_releasing_a_cut_holding_an_epic_with_no_plan_doc_still_releases_it():
 
         after = model.locate_version(root, "26-cut")
         assert after.released, "the cut never got its released stamp"
-        assert not (after.folder / "publish-under-your-name" / "epic.md").exists() \
-            and not (after.folder / "complete" / "publish-under-your-name" / "epic.md").exists(), \
-            "a plan doc survived the release"
+        plans = list(after.folder.rglob("epic.md"))
+        assert len(plans) == 1, "the epic that had a plan should still have exactly one"
+        assert plans[0].parent.name == "publish-under-your-name"
+        assert epic._RELEASED_MARKER in plans[0].read_text(), "the kept plan is unstamped"
 
 
 def test_a_shipped_criterion_delivered_by_a_filed_cut_is_still_covered():
@@ -7403,13 +7527,13 @@ def test_the_stop_hook_being_switched_off_silences_the_standing_too():
 
 
 
-def test_a_release_says_what_it_is_deleting_before_it_deletes_it():
-    # `release` has always printed "promote still-load-bearing decisions to the
-    # domain that owns them" — AFTER unlinking the files holding those decisions.
-    # Measured on 01-one-board: twelve plans, 450,405 bytes, about a hundred durable
-    # statements with no owner file, and the recovery commit reconstructed afterwards
-    # by hand with `git log --diff-filter=D`. The cost of a release is the plans that
-    # go with it, so it is named while they still exist.
+def test_a_release_says_what_it_is_stamping_shut():
+    # `release` has always printed "promote still-load-bearing decisions to the domain
+    # that owns them", and until 2026-09-12 it printed that AFTER unlinking the files
+    # holding those decisions. Measured on 01-one-board: twelve plans, 450,405 bytes,
+    # about a hundred durable statements with no owner file. The plans are now kept
+    # and stamped rather than deleted, so what the notice owes a reader changed with
+    # it: not a last call before the bytes go, but the argument for the sweep.
     with tempfile.TemporaryDirectory() as tmp:
         try:
             repo = _git_repo(tmp, push=False)
@@ -7432,22 +7556,22 @@ def test_a_release_says_what_it_is_deleting_before_it_deletes_it():
             with _work_dir(str(repo / "work")):
                 said = _capture_stdout(lambda: version.cmd_release({"name": "09-a-cut"}))
 
-            # The cost, in front of the person, in units they can weigh.
-            assert "DELETING 1 epic plan(s)" in said, said
+            # What is going quiet, in front of the person, in units they can weigh.
+            assert "STAMPING 1 epic plan(s)" in said, said
             assert "bytes" in said
             # WHICH sections can outlive the plan — and not the ones that cannot.
             assert "§Governance this implies" in said, said
             assert "§Plan" not in said, "slice ordering is supposed to die with the epic"
-            # Where it went, named at the moment it goes rather than reconstructed later.
-            assert head and head in said, f"expected the recovery commit {head}: {said}"
 
-            # And the claim is true: the plan is out of the tree and in that commit.
-            assert not (v / "an-epic" / "epic.md").exists()
-            kept = _git(repo, "show", f"{head}:work/versions/09-a-cut/an-epic/epic.md")
-            assert "a rule is owed" in kept.stdout, kept.stderr
+            # And the claim is true: the plan is still there, and stamped.
+            plan = v / "an-epic" / "epic.md"
+            assert plan.is_file(), "a released plan is kept, not deleted"
+            assert "a rule is owed" in plan.read_text()
+            assert epic._RELEASED_MARKER in plan.read_text()
 
-            # The instruction that follows no longer sends a reader to a deleted file.
-            assert "no longer in the tree" in said, said
+            # Nothing sends a reader to git for the text any more, because it is here.
+            assert "no longer in the tree" not in said, said
+            assert head not in said or "recoverable" not in said, said
         finally:
             events._PENDING.clear()
             config.apply(config.DEFAULTS)

package/harness/work.py

@@ -77,6 +77,9 @@ Subcommands:
     list --branch <ref>            the board as another branch has it (read-only)
     rules --task <name>            what constrains a task, derived
     align [--class <name>]         every misalignment class; REPORT-ONLY, exit 0
+    links [--fix]                  board links that point at nothing. Exits 1 when a
+                                   LIVE brief or governance file holds one, so a gate
+                                   can block; history is reported and never blocks
     wrap [--task <name>]           finish a session cleanly: what a machine knows
                                    about this run, then what to do. Writes NOTHING
     coverage [--feature <name>]    what a RUN proved vs what features promise
@@ -143,7 +146,7 @@ from harness import ids
 from harness.architecture import (cmd_domain_new, cmd_init, cmd_rules, cmd_system_new,
                                   cmd_where)
 from harness.coverage import cmd_coverage
-from harness.report import cmd_align, cmd_list, cmd_readme
+from harness.report import cmd_align, cmd_links, cmd_list, cmd_readme
 from harness.wrap import cmd_wrap
 from harness.config import (DEFAULTS, ConfigError, apply, cmd_applies, cmd_config,
                             cmd_context, cmd_method, cmd_remind, resolve)
@@ -167,7 +170,7 @@ SUBCOMMANDS = (
     "find", "list", "readme", "move", "plan", "session", "kickoff", "path", "code",
     "domain-new", "system-new", "where", "rules", "align", "wrap", "coverage",
     "migrate", "next", "status", "drop", "ask", "answer", "needs", "verify",
-    "observed", "log", "digest", "sync", "check",
+    "observed", "log", "digest", "sync", "check", "links",
 )
 
 
@@ -350,7 +353,7 @@ def _say(note: str) -> None:
 #: remembering to come back here.
 _READS = {"list", "find", "path", "code", "where", "rules", "status", "digest",
           "log", "needs", "align", "coverage", "readme", "config", "context",
-          "doctor", "kickoff", "remind", "applies", "wrap"}
+          "doctor", "kickoff", "remind", "applies", "wrap", "links"}
 
 
 def _reads_only(cmd: str, flags: dict) -> None:
@@ -514,6 +517,8 @@ def dispatch(cmd, pos, flags, cfg) -> int:
         return cmd_rules({**flags, "task": flags.get("task") or (pos[0] if pos else None)})
     if cmd == "align":
         return cmd_align(flags)
+    if cmd == "links":
+        return cmd_links(flags)
     if cmd == "wrap":
         return cmd_wrap(cfg, flags, _project_root(flags))
     if cmd == "coverage":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.113",
+  "version": "0.1.115",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -57,14 +57,14 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
     "@jarvis/agents": "1.0.0",
-    "@jarvis/errors": "1.0.0",
+    "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
+    "@jarvis/data": "0.1.0",
+    "@jarvis/errors": "1.0.0",
     "@jarvis/logger": "1.0.0",
+    "@jarvis/types": "1.0.0",
     "@jarvis/rpc": "1.0.0",
-    "@jarvis/anthropic": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
-    "@jarvis/data": "0.1.0",
-    "@jarvis/types": "1.0.0",
     "@jarvis/ui": "0.1.0",
     "@jarvis/vitest-config": "1.0.0"
   },