boost-skill-cli 1.2.181__tar.gz → 1.2.183__tar.gz

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.181
+Version: 1.2.183
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.181'
-__version_tuple__ = version_tuple = (1, 2, 181)
+__version__ = version = '1.2.183'
+__version_tuple__ = version_tuple = (1, 2, 183)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/commands/intelligence.py

@@ -155,7 +155,12 @@ def _install_generated(name: str, text: str, yes: bool = False) -> None:
     with tempfile.TemporaryDirectory(prefix="boost-gen-") as td:
         src = Path(td) / name
         src.mkdir()
-        (src / "SKILL.md").write_text(text, encoding="utf-8")
+        # newline="\n": install_from_path copies this into the canonical
+        # store and records util.sha256_dir over it, which hashes read_bytes.
+        # Every comparison against that hash is local today, so this is
+        # latent rather than live — but the digest it stamps into the lock
+        # would otherwise depend on which OS generated the skill.
+        (src / "SKILL.md").write_text(text, encoding="utf-8", newline="\n")
         try:
             res = store.install_from_path(src, name=name, tap_label="local")
         except BoostError as err:
@@ -799,7 +804,11 @@ def cmd_evolve(argv: list[str]) -> int:
     if not args.apply:
         out.info(out.role("re-run with --apply to write these changes", "muted"))
         return 0
-    skill_md.write_text(new, encoding="utf-8")
+    # newline="\n": the next line hashes this file's bytes, and the store is
+    # what gets symlinked into every agent's skills dir. Same latent class as
+    # the generated-skill write above — nothing compares across machines
+    # today, and the recorded digest should not depend on one either way.
+    skill_md.write_text(new, encoding="utf-8", newline="\n")
     entry["sha256"] = util.sha256_dir(store.skill_store_dir(args.name))
     entry["updated_at"] = util.now_iso()
     entry["version"] = new_ver

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/commands/pkg.py

@@ -506,7 +506,40 @@ def cmd_install(argv: list[str]) -> int:
     # one of them used to bind it: the preview returns early, so a `pbase`
     # assigned inside `if args.dry_run:` is unbound by the time the run path
     # reports prerequisites. `None` for every scope but `--local`.
-    pbase = scopes.resolve_base(args.scope)
+    pbase, pbase_kind = (scopes.project_base()
+                         if args.scope == scopes.SCOPE_PROJECT
+                         else (None, None))
+    # Said once, before anything is written, and naming the directory. An
+    # unmarked tree has no project root to walk up to, so this call is what
+    # decides where the project *is* — and `proj/src` stays a different project
+    # from `proj` for every command afterwards. The warning is the difference
+    # between that being a decision and being a surprise. It warns and does
+    # not redirect, so it fires in both shapes: with an older project above it
+    # names that one, and with nothing above it says a new one starts here.
+    # The single silent case is a lock at this very directory, where `above`
+    # comes back equal to `pbase` — the project being used is the one already
+    # here, and there is nothing to tell anybody.
+    if pbase is not None and pbase_kind == scopes.BASE_UNMARKED:
+        # `project_lock_root` is advisory and decides nothing: it only lets
+        # the warning NAME the project the user probably meant. Resolution
+        # stays on version control markers alone, because moving the base up
+        # to an ancestor lock orphans the rules and workflows recorded below
+        # it — see that function for what verification reproduced.
+        above = scopes.project_lock_root(pbase)
+        if above is not None and above != pbase.resolve():
+            out.warn("there is already a boost project at `%s`, and --local "
+                     "here starts a second one — cd there if you meant that "
+                     "one" % above, wrap=True)
+        elif above is None:
+            # "between here and your home directory", not "at or above here":
+            # the walk stops at `$HOME` without testing it, so a dotfiles repo
+            # at `~/.git` — a setup `project_root`'s own docstring calls out —
+            # is a marker above this directory that it may not use. Claiming
+            # otherwise sent the reader to `~`, where the same command refuses.
+            out.warn("nothing between `%s` and your home directory marks a "
+                     "project — no git/hg/svn checkout, no "
+                     ".boost/skill-lock.json — so --local starts a new one "
+                     "here" % pbase, wrap=True)
     only = _check_agents(args.agent)
     multi = len(args.names) > 1
     entries, failed = [], 0

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/commands/team.py

@@ -594,9 +594,24 @@ def cmd_protocol(argv) -> int:
         paths.ensure_dirs()
         shim = paths.launcher()
         script = _handler_script()
+        # newline="\n" because this artifact is a bash script and bash is a
+        # non-Python parser reading it byte for byte. The write sits *above*
+        # the platform branch below, so unlike the Linux .desktop file it
+        # does run on Windows, where the stub at the end of this command
+        # tells the user to invoke the script themselves.
+        #
+        # Which CR failure bites is shell-specific and is deliberately not
+        # claimed here: "bad interpreter: bash\r" is kernel binfmt_script
+        # behaviour, and Windows has no kernel shebang support, so under
+        # Git Bash the shebang is likely tolerated while under WSL the
+        # launcher path is unexecutable for unrelated reasons. The URL route
+        # is ruled out — `_parse_boost_url` goes through `urlparse`, which
+        # strips CR. What is left is simply that the file is wrong, which is
+        # reason enough for a one-keyword pin.
         script.write_text("#!/usr/bin/env bash\n"
                           "# boost:// URL handler — invoked with the URL as $1\n"
-                          'exec "%s" protocol open "$1"\n' % shim, encoding="utf-8")
+                          'exec "%s" protocol open "$1"\n' % shim,
+                          encoding="utf-8", newline="\n")
         script.chmod(script.stat().st_mode | stat.S_IEXEC)
         out.ok("wrote handler script %s" % _tilde(script))
         if system == "Darwin":

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/core/complete.py

@@ -614,9 +614,30 @@ def plan_uninstall(shell: str) -> RcPlan:
 
 def apply(plan: RcPlan) -> Path:
     """Write ``plan``'s result. A no-op when it changes nothing, so an rc file
-    keeps its mtime (and its place in the user's backups) on a repeat run."""
+    keeps its mtime (and its place in the user's backups) on a repeat run.
+
+    ``newline="\\n"`` because the reader here is **bash**, which does not
+    fold. The damage is worse than a stray character: measured on bash 3.2
+    and zsh, a CRLF rc file does not merely mangle tokens, it stops parsing
+    — ``fi\\r`` gives ``syntax error: unexpected end of file``, so nothing
+    after the user's first ``if`` or ``for`` runs at all.
+
+    This rewrites the user's **whole** ``~/.bashrc`` or ``~/.zshrc``, not
+    only the lines boost added, so an unpinned write on Windows re-endings a
+    file boost does not own — ``tests (windows-latest, 3.14)`` measured
+    ``b'export A=1\\r\\neval "$(boost _complete)"\\r\\n'`` from a one-line
+    rc. Pinning cuts the same way: it normalizes the whole file to LF,
+    including lines boost never wrote, which is what bash wants and is still
+    a change beyond boost's own three. The one shell that might forgive CRLF
+    is MSYS2/Cygwin bash with ``shopt igncr``, which is off by default.
+
+    Idempotence is unaffected either way: :func:`_read_rc` reads through
+    universal newlines, so the next run compares LF to LF and reports no
+    change — which is also why boost would never repair a file it had
+    mangled, and would keep saying "already wired" over it.
+    """
     if plan.changes:
-        plan.path.write_text(plan.after, encoding="utf-8")
+        plan.path.write_text(plan.after, encoding="utf-8", newline="\n")
     return plan.path
 
 

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/core/scopes.py

@@ -22,10 +22,10 @@ from __future__ import annotations
 import os
 import re
 from contextlib import suppress
-from pathlib import Path
+from pathlib import Path, PurePosixPath, PureWindowsPath
 
 from ..errors import BoostError
-from . import paths
+from . import paths, projectlock
 
 SCOPE_USER = "user"
 SCOPE_PROJECT = "project"
@@ -48,6 +48,12 @@ PROJECT_MARKERS = (".git", ".hg", ".svn")
 # before it is ever joined — the same rule the canonical store applies.
 _SAFE_NAME = re.compile(r"[A-Za-z0-9._-]+")
 
+# How :func:`project_base` decided, so a caller can tell the two apart without
+# walking the tree a second time and risking a different answer than the walk
+# that actually chose the directory.
+BASE_VCS = "vcs"            # a PROJECT_MARKERS entry at or above the start
+BASE_UNMARKED = "unmarked"  # none — the start directory becomes a project
+
 
 def project_root(start=None) -> Path | None:
     """Nearest enclosing project root at or above ``start`` (default: cwd).
@@ -58,8 +64,8 @@ def project_root(start=None) -> Path | None:
     repo's ``.claude/skills``, not create a stray one three levels down.
 
     **This is the marker walk, not the answer to "where is the project".** That
-    is :func:`resolve_base`, which adds the unmarked-directory fallback, and it
-    is what every caller should use — a command that asks this one directly
+    is :func:`resolve_base`, which adds the unmarked-directory fallback on top
+    of it, and it is what every caller should use — a command that asks this one directly
     disagrees with ``install --local`` about whether an unmarked directory is a
     project, which is how ``verify``/``list``/``doctor``/``uninstall`` came to
     deny skills that ``install`` had just written and ``sync`` could still see.
@@ -87,27 +93,74 @@ def project_root(start=None) -> Path | None:
     return None
 
 
-def resolve_base(scope: str, base=None, start=None) -> Path | None:
-    """Directory a scope materializes under — ``None`` for user scope.
+def project_lock_root(start=None) -> Path | None:
+    """Nearest ancestor at or above ``start`` that already holds a project lock.
+
+    **This does not decide where anything is written.** It is an advisory
+    answer to "is there already a boost project up there?", used by
+    ``install --local`` to name it in the warning it prints when it is about
+    to start a new one. :func:`project_base` is what decides the directory,
+    and it consults version control markers and nothing else.
+
+    It is deliberately not in the resolution path, and the reason is worth
+    recording because the roadmap card that produced this function proposed
+    putting it there. Moving the resolved base *up* to an ancestor lock
+    orphans every rule and workflow already recorded *below* it: those are
+    kept in the **user** lock tagged with an absolute ``base``
+    (``store._install_rule``), and ``--local`` eligibility is
+    :func:`owns` against the base resolved right now. So one
+    ``install <skill> --local`` at ``proj`` would make a rule installed at
+    ``proj/src`` invisible to ``list --local`` and unremovable by
+    ``uninstall --local`` — from ``proj/src`` as much as from ``proj`` — with
+    ``uninstall`` saying "installed in proj/src, not in this project" to
+    somebody standing in ``proj/src``. Verification reproduced that end to
+    end. The walk also only ever engages for skills: ``_install_rule`` and
+    ``_install_workflow`` write no project lock at all, so it would fix one
+    kind of three.
+
+    **The marker is the lock file, not the ``.boost`` directory**, and that is
+    the whole reason this can exist beside the note on :data:`PROJECT_MARKERS`
+    refusing ``.boost``. boost's own state dir is ``~/.boost`` and it holds a
+    ``config.json``, a ``cache/`` and a ``state/`` — never a
+    ``skill-lock.json``, which only :mod:`.projectlock` writes and only into a
+    project. So the one directory a ``.boost`` marker would have wrongly
+    claimed is the one this never matches, and ``$HOME`` is refused outright
+    below regardless.
+    """
+    try:
+        here = Path(start).resolve() if start is not None else Path.cwd().resolve()
+    except OSError:
+        return None
+    try:
+        home = Path(paths.home()).resolve()
+    except OSError:
+        home = None
+    for d in (here, *here.parents):
+        if home is not None and d == home:
+            return None
+        if projectlock.exists(d):
+            return d
+    return None
 
-    An explicit ``base`` always wins, so a re-materialization driven by a lock
-    record (``update``, ``sync``) lands where the original install did rather
-    than in whatever directory the command happens to be run from.
 
-    Project scope with no explicit base resolves the nearest project root, and
-    falls back to ``start``/cwd when there is none — an unmarked directory is
-    still a perfectly good place to put a project's skills, and refusing would
-    only be pedantry. The one directory that is never an acceptable fallback is
-    ``$HOME``: writing "project" files there means writing into the very dirs
-    user scope owns, so callers get ``None`` and can say so.
+def project_base(start=None) -> tuple[Path | None, str | None]:
+    """Where project scope materializes, **and how that was decided**.
+
+    One walk, one answer. ``install --local`` has to warn when it is the call
+    that creates the project, and re-deriving *that* in the command layer
+    would mean a second walk that can disagree with the one that chose the
+    directory — the exact shape of the reader/writer split ``fix(scope)``
+    closed. So the decision is made once, here, and the reason travels with
+    it. (The command layer does call :func:`project_lock_root` afterwards, to
+    name an existing project in the warning text. That one decides no
+    destination, so it cannot disagree with anything.)
+
+    Returns ``(None, None)`` when there is nowhere to put a project — standing
+    in ``$HOME``, or with no working directory at all.
     """
-    if base:
-        return Path(base)
-    if scope != SCOPE_PROJECT:
-        return None
     found = project_root(start)
     if found is not None:
-        return found
+        return found, BASE_VCS
     if start is not None:
         here = Path(start)
     else:
@@ -118,11 +171,37 @@ def resolve_base(scope: str, base=None, start=None) -> Path | None:
             # under the process. `project_root` has always answered None here;
             # this must too, or the readers that now come through this function
             # crash where they used to print a user-scope answer and exit 0.
-            return None
+            return None, None
     with suppress(OSError):
         if here.resolve() == Path(paths.home()).resolve():
-            return None
-    return here
+            return None, None
+    return here, BASE_UNMARKED
+
+
+def resolve_base(scope: str, base=None, start=None) -> Path | None:
+    """Directory a scope materializes under — ``None`` for user scope.
+
+    An explicit ``base`` always wins, so a re-materialization driven by a lock
+    record (``update``, ``sync``) lands where the original install did rather
+    than in whatever directory the command happens to be run from.
+
+    Project scope with no explicit base defers to :func:`project_base`: the
+    nearest version control root, else ``start``/cwd — an unmarked directory
+    is still a perfectly good place to put a project's skills, and refusing would only be
+    pedantry. The one directory that is never an acceptable fallback is
+    ``$HOME``: writing "project" files there means writing into the very dirs
+    user scope owns, so callers get ``None`` and can say so.
+
+    This keeps the path and drops the kind. A caller that needs to know
+    *which* of the three answered — ``install --local`` warns when it is the
+    call that creates the project — takes the pair from :func:`project_base`
+    rather than walking again.
+    """
+    if base:
+        return Path(base)
+    if scope != SCOPE_PROJECT:
+        return None
+    return project_base(start)[0]
 
 
 def owned_by(entries: dict, base) -> dict:
@@ -330,14 +409,40 @@ def parent_matches_spelling(base, rel: str) -> bool:
     The leaf itself is deliberately left unresolved. A materialization that
     *is* a symlink is boost's own, and ``util.remove_path`` unlinks it without
     following it — judging it by what it points at is the bug one layer down.
+
+    **Absolute is asked of both platforms, not of the one running.** A plain
+    ``Path(rel)`` is a ``WindowsPath`` on Windows, where ``/etc/passwd``
+    carries no drive and ``is_absolute()`` is therefore ``False``. The join
+    then yields ``C:\\etc\\passwd`` — outside the base — and *both sides of
+    comparison leave it the same way*, so the walk agrees with itself and this
+    answers True for a path that is not in the repo at all. All three
+    ``tests (windows-latest, 3.1x)`` jobs said so the first time these clauses
+    were tested directly. The mirror case is a drive letter or a UNC path,
+    which ``PurePosixPath`` does not call absolute either. A lock is a
+    committed file and the machine that wrote a row need not be the one
+    reading it, so the spelling to refuse is whatever is absolute *anywhere*.
+    A posix directory genuinely named ``C:`` is refused as collateral, which
+    is the safe direction for a guard whose other answer hands ``rmtree`` a
+    target.
+
+    **The NUL is refused by name, on both arguments.** Relying on ``realpath``
+    to raise is relying on the half of the behaviour that differs: posix
+    raises ``ValueError`` and the ``except`` catches it, Windows does not
+    raise and the guard returned True. ``base`` is checked as well as ``rel``
+    because it has the same provenance — ``store`` derives it from the lock's
+    own recorded ``base`` — and none of the ``rel`` clauses can see it.
     """
-    if not rel or not isinstance(rel, str) or Path(rel).is_absolute():
+    if not rel or not isinstance(rel, str):
+        return False
+    if PurePosixPath(rel).is_absolute() or PureWindowsPath(rel).is_absolute():
         return False
     try:
+        if "\x00" in rel or "\x00" in os.fspath(base):
+            return False
         anchor = Path(os.path.realpath(base))
         return Path(os.path.realpath((Path(base) / rel).parent)) == (
             anchor / rel).parent
-    except (OSError, ValueError):
+    except (OSError, TypeError, ValueError):
         return False
 
 

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_cli/core/util.py

@@ -187,7 +187,8 @@ def try_lock(path, stale_after: float = 300.0):
         yield False
         return
     try:
-        with contextlib.suppress(OSError), os.fdopen(fd, "w") as f:
+        with contextlib.suppress(OSError), os.fdopen(
+                fd, "w", encoding="utf-8") as f:
             fd = None                      # fdopen owns it now
             f.write(str(os.getpid()))
         yield True
@@ -209,13 +210,38 @@ def atomic_write_text(path: Path, text: str, encoding: str = "utf-8") -> None:
     complete new one atomically replaces it. This is the corruption-safe
     substitute for a bare ``Path.write_text`` on any file boost must not lose —
     the lock file, the config, the pulse journal.
+
+    ``newline="\\n"`` is load-bearing, and it is the one line here that a
+    Linux run cannot check. Text mode translates ``"\\n"`` to the platform
+    separator on write, so on Windows this wrote CRLF into seventeen of the
+    nineteen — measured, not predicted: ``tests (windows-latest, 3.14)`` on
+    this branch's parent commit reported ``assert b'\\r' not in
+    b'a\\r\\nb\\r\\n'`` against the test below. The other two
+    (``rag.py``'s BM25 index and rerank cache) pass bare ``json.dumps`` and
+    emit no literal newline at all, so the pin is inert for them.
+
+    **The reader that makes it matter is git, and only one call site hands
+    it anything.** ``projectlock.write`` stamps
+    ``<repo>/.boost/skill-lock.json``, which that module's own docstring
+    says "is meant to be **committed** … git is its history". Everything
+    else here is read back through ``json`` or ``read_text``, both of which
+    fold. It is explicitly **not** ``sha256_dir``: all eighteen of those
+    call sites hash a ``copytree``-populated skill dir or a tap clone, never
+    a file this function wrote — an earlier draft of this paragraph claimed
+    otherwise and was wrong.
+
+    ``tests/unit/test_text_io_names_its_encoding.py``'s
+    ``TestAPinnedWriterReallyEmitsLF`` asserts on bytes rather than on the
+    presence of this keyword, because an AST check proves only that it is
+    spelled. That test arrived with this change, so it corroborates the pin
+    rather than independently motivating it.
     """
     path = Path(path)
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, tmp = tempfile.mkstemp(dir=str(path.parent),
                                prefix="." + path.name + ".", suffix=".tmp")
     try:
-        with os.fdopen(fd, "w", encoding=encoding) as f:
+        with os.fdopen(fd, "w", encoding=encoding, newline="\n") as f:
             f.write(text)
             f.flush()
             os.fsync(f.fileno())

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.181
+Version: 1.2.183
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/boost_skill_cli.egg-info/SOURCES.txt

@@ -693,6 +693,7 @@ docs/roadmap/items/the-links-concurrency-cap-did-not-hold.md
 docs/roadmap/items/the-model-back-off-mixes-two-clocks.md
 docs/roadmap/items/the-scale-corpus-refreshed-the-wrong-rows.md
 docs/roadmap/items/the-shard-job-that-could-not-finish.md
+docs/roadmap/items/the-shard-model-has-no-per-job-fixed-cost.md
 docs/roadmap/items/the-windows-test-cap-is-five-minutes-from-the-measurement.md
 docs/roadmap/items/theme-asset-linting-stylelint-eslint.md
 docs/roadmap/items/tier3-ceiling-unreachable-at-default-n.md

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/docs/roadmap/items/project-scope-in-an-unmarked-tree-does-not-walk-up.md

@@ -2,15 +2,15 @@
 id: project-scope-in-an-unmarked-tree-does-not-walk-up
 board: code
 section: dx
-status: planned
+status: inflight
 category: CLI · Bug
 complexity: M
 impact: Med
 wow: 2
-note: install --local from a subdirectory of an unmarked project creates a second lock there
+note: (c) shipped; (a) built, reproduced as a regression and withdrawn — it orphans the rules and workflows recorded below the lock it walks up to, and engages for one item kind of three
 order: 236
-owner:
-pr:
+owner: loop/project-scope-walks-up
+pr: 1034
 title: "Project scope in an unmarked tree does not walk up, so <code>src/</code> becomes its own project"
 ---
 <code>scopes.resolve_base</code> walks up for a VCS marker and, finding none, falls back to the
@@ -35,7 +35,26 @@ the nearest ancestor that is not <code>$HOME</code> &middot; too greedy, it woul
 sibling directories. Option (c): keep today's behaviour and say so &middot; have
 <code>install --local</code> warn once when it is about to create a project in a directory with no VCS
 marker, naming the directory, so the second lock is a decision rather than a surprise. (c) is the
-cheapest and the most honest; (a) is worth pairing with it for every command after the first.
+cheapest and the most honest; (a) looked worth pairing with it for every command after the first.
+
+<b>(c) shipped alone &middot; (a) was built, reproduced as a regression, and withdrawn.</b> The lock
+walk exists (<code>scopes.project_lock_root</code>) but is <em>advisory</em>: it lets the warning name
+the project above you, and decides no destination. Putting it in the resolution path broke two things
+the sketch above did not anticipate. First, <b>it orphans the records below it</b> &middot; a rule or
+workflow installed with <code>--local</code> lives in the <em>user</em> lock against an absolute
+<code>base</code>, and <code>--local</code> eligibility is <code>scopes.owns</code> against the base
+resolved <em>now</em> &mdash; so one <code>install &lt;skill&gt; --local</code> at <code>proj</code>
+made a rule at <code>proj/src</code> invisible to <code>list --local</code> and unremovable by
+<code>uninstall --local</code>, from <code>proj/src</code> as much as from <code>proj</code>, with the
+refusal naming the directory the user was standing in and the two error messages giving mutually
+unsatisfiable instructions. Second, <b>it engages for one kind of three</b> &middot;
+<code>_install_rule</code> and <code>_install_workflow</code> write no
+<code>.boost/skill-lock.json</code> at all, so a tree holding only those never gains the marker, which
+is also why the warning (c) adds can never be silenced there. The first is pinned by
+<code>test_a_rule_below_an_ancestor_lock_is_still_removable_locally</code>, which fails the moment the
+walk is put back; the second is a property of the installers rather than of this change, so nothing
+here asserts it. Making the walk safe means giving rules and workflows a project boundary of their
+own, and that is a different card.
 
 Found by the adversarial verification of PR #998, which reproduced it end to end. <code>$HOME</code>
 is still never a project and deletion is still gated by <code>resolve_in_base</code>, so this is a

{boost_skill_cli-1.2.181 → boost_skill_cli-1.2.183}/docs/roadmap/items/shard-weights-do-not-predict-the-job-timeout.md

@@ -2,7 +2,7 @@
 id: shard-weights-do-not-predict-the-job-timeout
 board: code
 section: trust
-status: inflight
+status: shipped
 category: CI · Bug
 complexity: M
 impact: High
@@ -78,17 +78,50 @@ hide which had happened.
 <b>It reproduces the failure it was derived to predict.</b> Six shards at these weights:
 37.8 median minutes &times; 1.91 = a <b>72.3-minute tail</b> against a real worst job of
 <b>72.5</b> &mdash; 96% of the cap. <code>plan --explain --timeout-minutes 75</code> now prints
-that and exits 1. The matrix moved to <b>eight</b>, where the same arithmetic gives 28.4 &times;
-1.91 = <b>54.2 min, 72% of the cap</b>; the largest unit (4,063,161 ms) still fits inside an even
-share (5,543,280 ms), so the speedup cap is a full 8.00x and more shards cost nothing but runner
-slots. <code>tests/unit/test_mutation_shard_count.py</code> pins the shard count across
+that and exits 1. The matrix moved to <b>eight</b> and then, once the weights were
+re-anchored, to <b>twelve</b>, where the same arithmetic gives 28.5 &times; 1.91 = <b>54.4 min,
+72% of the cap</b>; the largest unit still fits inside an even share, so the speedup cap is the
+full width and more shards cost nothing but runner slots. <code>tests/unit/test_mutation_shard_count.py</code> pins the shard count across
 <code>ci.yml</code> and <code>mutation-weights-refresh.yml</code> (<code>timeout-minutes</code>
 cannot be read through <code>${{ }}</code>, so agreement is asserted rather than derived), and
 re-runs the headroom check on the committed pack every build &mdash; a pack that would be
 cancelled now fails in the <code>test</code> job in milliseconds.
 
-<b>Not fixed here, and now its own card:</b> a <code>cancelled</code> <code>ci</code> on main is
-still silent. <code>ci-failure-alert</code> gates on
-<code>conclusion == 'failure'</code>, so the run that skipped the release notified nobody either
-&mdash; see <code>cancelled-ci-on-main-is-silent-and-skips-the-release</code>.
+<b>Twelve has now run, and it cost more than the plan said &mdash; which is the finding this
+card closes on.</b> Over the 24 jobs of the two twelve-shard runs (<code>d7027cf8</code> and
+main's <code>58ace415</code>) the observed p50 is <b>34.6 min</b> against the 28.5 predicted, and
+the worst job <b>55.8</b> against the 54.4-minute tail those runs' own gate printed: 74% of the
+cap. That exceedance is not new, and the tempting reading &mdash; that twelve is where the tail
+estimate first broke &mdash; is wrong in the flattering direction. Replay every run's gate as it
+actually stood &mdash; that commit's
+own script against its own weights &mdash; and the predicted tail has been beaten at <b>four of
+the six runs on record</b>: +1.1, +0.4 and <b>+8.9</b> at eight shards (<code>dd416340</code>,
+54.2 predicted against a 63.1 worst) and +1.4 at twelve. The largest miss on record belongs to
+eight.
+
+<b>The width stands on that measured 74%. What does not stand is the margin the planner
+prints.</b> On the weights committed since (#1032, a re-timing of the same mutants)
+<code>plan --shards 12</code> said a 25.2-minute median and a 48.0-minute tail, 64% of the cap
+&mdash; so that pack, asked about the run its own weights were timed from, under-predicted that
+job by <b>7.8 minutes</b>. (#1038 has since re-timed the weights from the twelve-shard run on
+<code>6fd38785</code>; <code>plan</code> now prints 26.2 / 50.1 min, 67% of the cap. That era's
+shortfall is against <em>that</em> run's jobs, not the 55.8 above.) That is the prospective basis, which is the one that matters before
+the next run and is <em>not</em> comparable to the replay figures above. Scored on the observed
+median at the committed <code>TAIL_MULTIPLIER</code> the pack is 34.6 &times; 1.91 = 66.0 min,
+<b>88% of the cap</b>.
+
+<b>So the cap question is answered by a model that is the wrong shape, not merely mis-fitted.</b>
+Graded against weights measured at its own width, eight implies a <code>RUNNER_EFFICIENCY</code>
+of 0.832 and twelve implies 0.593 &mdash; 40% apart, and no single multiplicative constant is
+both. The median falling only to 0.83 of itself where division through the origin predicts 0.667
+says the same thing without reference to any weights at all.
+
+<b>Not fixed here, and now its own card:</b> the model has no per-job <em>fixed</em> cost, so it
+flatters every width above the one it was fitted at &mdash; see
+<code>the-shard-model-has-no-per-job-fixed-cost</code>. Still tracked separately, and no longer
+by the mechanism this card first described: a <code>cancelled</code> <code>ci</code> on main used
+to notify nobody, because <code>ci-failure-alert</code> gated on <code>conclusion ==
+'failure'</code>. #1025 inverted that to the negation of the green set, so a cancellation does
+alert now &mdash; see <code>cancelled-ci-on-main-is-silent-and-skips-the-release</code> for what
+is left of it.
 

boost_skill_cli-1.2.183/docs/roadmap/items/the-shard-model-has-no-per-job-fixed-cost.md

@@ -0,0 +1,82 @@
+---
+id: the-shard-model-has-no-per-job-fixed-cost
+board: code
+section: trust
+status: planned
+category: CI · Model
+complexity: M
+impact: Med
+wow: 3
+note: the plan divides by every shard added, so it flatters every width above the one it was fitted at
+order: 367
+owner:
+pr:
+title: "The shard model runs through the origin, so <code>plan</code> gets more optimistic with every shard added"
+---
+<b>The cleanest statement of it needs no weights at all.</b> Going from eight shards to twelve,
+a model that divides work by the shard count predicts the median job falls to <b>0.667</b> of
+itself. It fell to <b>0.83</b> &mdash; 41.8 min over the 24 jobs of the three eight-shard runs to
+34.6 over the 24 jobs of the two twelve-shard runs. Correcting for the one thing the weights
+do say &mdash; #1032 re-timed the same mutants 0.884&times; cheaper &mdash; moves the prediction
+to <b>0.589</b> and widens the gap, so the uncorrected figure is the conservative one. No value
+of <code>RUNNER_EFFICIENCY</code> produces either, because the error is in the shape and not in the
+constant: <code>runner_minutes</code> is <code>weight / (RUNNER_WORKERS &times;
+RUNNER_EFFICIENCY)</code>, linear through the origin, and what is missing is a per-job
+<em>fixed</em> cost.
+
+<b>Graded like for like, the two widths disagree by 40%.</b> Each width has to be scored against
+weights measured at that width: #1029's 66,708,651 ms total was measured on an eight-shard run,
+and #1032's 58,969,820 was re-timed from CI run 37200431822 &mdash; which is
+<code>58ace415</code>, one of the two twelve-shard runs being graded. On that footing eight
+implies an efficiency of <b>0.832</b> and twelve implies <b>0.593</b>. Reading both against one
+frozen total hides this, and understates the gap as 24%.
+
+<b>C is large and five routes do not agree on how large.</b> They differ in whether they use
+medians or machine-minute sums, and in whether #1032's 0.884x re-timing is read as the work
+really getting cheaper between the two widths: <b>20.2</b> and <b>24.2</b> min a job from the two
+p50s, <b>14.4</b> and <b>19.8</b> from the matrix totals (347.6 machine-minutes at eight over
+four runs, 404.9 at twelve over two), and <b>26.9</b> from the six-to-eight step of 2026-10-02
+&mdash; 287.2 &rarr; 341.0 machine-minutes two hours apart with the width the only change. So
+<b>C is 14 to 27 min a job</b>. A two-point solve is exactly determined and therefore not
+falsifiable; fitting C needs a third width, not more runs at twelve.
+
+<b>And C cannot be bolted on beside the efficiency, which is the part that makes this a card
+rather than a one-line patch.</b> Subtract any C in that range from the matrix total and the
+parallel work left over implies a speedup above four on a four-vCPU runner: C = 14.4 leaves 232.4
+min against 1,111.8 weight-minutes, which is <b>4.78</b> effective workers, and C = 24.2 leaves
+154.0, which is <b>7.22</b>. An efficiency over 1.0 is a contradiction, not a tight fit, so the
+weights overstate real serial work by roughly the same factor and
+<code>PLANNED_TOTAL_MS</code> cannot serve as the fixed reference a re-fit is measured against.
+A hypothesis, named as one because it has not been measured: mutmut times each mutant while four
+of them run at once, so a per-mutant duration may already carry the contention
+<code>RUNNER_EFFICIENCY</code> exists to apply.
+
+<b>The naive remedy is worse than the status quo, so it is worth writing down as refuted.</b>
+Adding C to the existing conversion with the committed efficiency &mdash; <code>C +
+runner_minutes(w)</code> at C = 20, each width on its own weights as this card requires &mdash;
+predicts <b>62.7 min at eight</b> against an observed 41.8 and <b>45.2 at twelve</b> against an
+observed 34.6: over-predicting by <b>50%</b> and <b>31%</b>. The bias is not even, which is the
+point &mdash; a fixed term added to an unchanged efficiency does not just shift the answer, it
+gets the width dependence wrong in the other direction. The tail it produces at twelve is
+<b>86.2 min, 115% of the cap</b>: the planner would refuse the width CI
+runs green today. C and <code>RUNNER_EFFICIENCY</code> have to move together, and whatever they
+do to the predicted median then has to be reconciled with
+<code>TAIL_MULTIPLIER</code>, whose over-estimate is currently covering for the median being low.
+
+<b>It is not CI setup, and that is the cheap half to check.</b> Stepping all 24 twelve-shard jobs
+through the Actions job API, everything that is not the <code>mutate shard</code> step is a
+median <b>0.5 min</b> &mdash; the 1.7% the constant's docstring already measured at six, still
+true. So the fixed cost is inside mutmut: a baseline test run (the <code>tests</code> job on
+those two runs took 7.8 and 8.6 min) and per-job mutant collection are the candidates, and
+neither has been measured. Measuring them would turn the 14-27 range into a mechanism.
+
+<b>Why it matters even though nothing is red.</b> Twelve sits at 74% of the cap empirically and
+the gate passes. But <code>plan</code> reported 64% on #1032's pack against that same
+measured 74%, and goes on reporting around half the cap at sixteen &mdash; 48% on #1032's weights, 50% on
+#1038's &mdash; where the real floor is <code>C &times;
+TAIL_MULTIPLIER</code> however many shards are added. So the one question the planner exists to
+answer &mdash; "is this width safe?" &mdash; is answered optimistically for every width above the
+fitted one, and the answer gets more optimistic the further you go. Until C is fitted,
+<code>test_the_committed_width_has_actually_run</code> refuses a <code>SHARDS</code> nothing has
+been observed at, and <code>test_todays_pack_under_predicts_the_worst_twelve_shard_job</code>
+pins the 7.8-minute shortfall so it cannot drift unnoticed.