feat: the goal is a pointer — amp, v4 status, portfolio continuity, proxy stance by leojkwan · Pull Request #263 · firstbitelabsllc/shadow

leojkwan · 2026-08-07T22:52:20Z

Why (owner directive 2026-08-07, P0)

"a goal may be iterating over 10 different projects and you need to be within 4k characters — way too small to have all details. a goal prompt MUST MUST MUST be a pointer to the durable plan data source where shadow stores its plans."

What

shadow amp [--repo PATH] [--plan PATH] [--task ~hash] [--max-chars N] — projects one paste-ready goal block from a repository-owned PLAN.md. Deterministic: no LLM, no network; same plan, same block.

Pointer first: PLAN.md @ branch@sha in <origin> — section \"### <milestone>\", with the standing law the plan wins and state your ref.
One resume row + its proof: cycle-law selection (in_progress first, else first needs-clear pending).
Honcho as pattern, not store: a new optional milestone - tools: line (grammar § Milestone law; lint-transparent by construction) carries per-milestone skills/tooling knowledge IN the plan; amp projects it verbatim.
Budget enforced: default 4,000 chars; optional parts drop from the bottom (rails → contradictions → gates → DoD → tools); pointer + resume never drop; a resume row that alone busts the budget is a hard error pointing at READ-FIT.
Goal chaining enforced by the tool: a fully-completed plan exits 1 with mint the successor — which promptly caught this repo's own plan (M3 closed with no Shadow successor row; M4 is that successor).
Person-gated rows named so a seat never claims one; open Contradictions counted.

Dogfood

bin/shadow amp on this repo's own plan emits M4's goal block at 1,233/4,000 chars with resume ~c9ut — the next cut this PR names: shadow status still validates the killed v3 outcome schema (250/250 fleet plans report needs a valid Brief / outcome must be a string while lint passes them on v4 grammar).

Gates

npm run test:py — 162 OK (12 new amp tests: selection, needs-gating, in_progress preference, --task, budget truncation order, impossible-budget error, CLI exit codes)
npm run test:js — 4 passed · npm run docs:build — clean · npm run verify — rc=0

Not in this PR

~c9ut (status v3 cut) — named as the plan's resume row, separate bounded change.
The DoD ~s4ip is owner-gated: tagged release + installed-mount proof.

Note

Medium Risk
Changes default shadow status discovery/fallback and couples status to amp parsing, so regressions affect every cold-start entry point; mitigated by broad new Python tests and deterministic, read-only projection logic.

Overview
Adds shadow amp, a deterministic CLI that projects a ≤4k paste-ready goal block from PLAN.md (authority ref + milestone section, one resume row + proof, optional milestone - tools:, budget trimming, +UNCOMMITTED when dirty, and stall/“mint successor” semantics). Wired through bin/shadow, SKILL.md, and docs/reference/amp.md; grammar now documents the milestone - tools: line.

shadow status no longer mislabels v4 plans with the retired v3 Brief errors: it reuses the amp parser for resume/milestone/stall/Plan health, adds portfolio fallback (SHADOW_PORTFOLIO_ROOT / ~/Development) with --no-portfolio-fallback and guards so a broken local PLAN.md does not mask behind the fleet board.

Product/docs shift: README reframed around proxy identity and the loop; AGENT.md adds the proxy stance; new host-integration (static 15-line standing goal) and honcho (pattern-not-store) reference pages. PLAN.md records M4/M5 milestones and proof lines for this work.

^{Reviewed by Cursor Bugbot for commit 21d46f9. Bugbot is set up for automated code reviews on this repo. Configure here.}

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

leojkwan · 2026-08-07T22:52:25Z

@graphite review

leojkwan · 2026-08-08T18:47:34Z

Pushed ~c9ut (the plan's resume row): shadow status is now v4-aware. It validated only the retired v3 outcome schema — 250/250 fleet plans reported needs a valid Brief / outcome must be a string while shadow lint passed them. v4 plans route through the amp parser (one parser, two projections — status and amp cannot disagree), render Project/Mode/milestone-progress/resume/proof; v3 plans keep the legacy view. Dogfood: shadow status on this repo now prints M4 at 2/4 with resume ~c9ut — the output was its own proof. 168 py tests OK (3 new pins: schema-error regression, cwd-independence, JSON shape). Remaining open row is the DoD ~s4ip: tagged release + installed-mount proof, owner-gated.

leojkwan · 2026-08-09T02:04:18Z

Pushed f4c012e — M5, built from the 2026-08-08 car session where a blank voice workspace answered "which project should I attach it to?"

Gap 1 — same board from anywhere: shadow status in a plan-less directory now falls back to the portfolio root (SHADOW_PORTFOLIO_ROOT, default ~/Development) with a stderr banner. Explicit --root and --no-portfolio-fallback never fall back. 3 test pins including the exact car repro (blank cwd → portfolio renders).

Gap 2 — honcho: docs/reference/honcho.md records the v4 ruling once — pattern not store, a map of what carries each honcho function, and a spike path if the ruling should ever change. The question now costs a link, not a re-derivation.

Gap 3 — README: rewritten around the real product — proxy identity, continuity, amp, the refusals.

Gap 4 — proxy stance + out of the box: AGENT.md law now includes the proxy stance (never open empty, never ask which-project, chief-of-staff moves unprompted, chat-is-projection). docs/reference/host-integration.md ships the static 15-line standing goal pasteable into ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md / Cursor rules — same text for every seat; only what the plans point at changes.

Gates: 171 py + 4 js + docs + verify green; plan lint 0 blocking. M5 is 5/6 — the DoD is a real remote/voice cold-start against the next tagged release, owner-gated.

A real goal may iterate over ten projects; no 4k goal prompt can carry that detail. shadow amp projects one paste-ready, budget-enforced goal block from a repository's PLAN.md: authority ref + section (the plan wins), the one resume row with its proof, the milestone's optional '- tools:' line (pattern not store — the honcho knowledge lives in the plan), person-gated rows, and the standing rails. Deterministic, no LLM, no network. Optional parts drop from the bottom to fit; the pointer and resume never drop. Selection follows cycle law: in_progress first, else first needs-clear pending. Exits 1 with a mint-the-successor message on a completed plan — goal chaining enforced by the tool. Grammar gains the optional milestone '- tools:' line (lint-transparent). M4 added to PLAN.md with proofs run fresh in this commit; ~c9ut names the shadow-status v3 outcome-schema contradiction as the next cut. Gates: test:py 162 OK incl 12 amp tests, test:js 4, docs:build, npm run verify rc=0.

…reported every grammar-clean plan shadow status validated ONLY the retired v3 outcome schema, so all 250 fleet plans reported 'needs a valid Brief / outcome must be a string' while shadow lint passed them. v4 plans now route through the shadow-amp parser (one parser, two projections - status and amp can never disagree about the current milestone or resume row) and render Project/Mode/milestone-progress/resume/proof; legacy v3 plans keep the old view unchanged. discover_plans emits root-relative paths - resolved against the scan root, pinned by a cwd-independence test. ~c9ut flipped with proof in this commit. 168 py tests OK.

…w, static standing goal, honcho ruled once, README tells the truth Built from the owner's 2026-08-08 car session (Codex voice, remote), where a blank workspace answered 'which project should I attach it to?' - the exact anti-pattern. (1) shadow status gains a portfolio fallback: empty cwd scan falls back to SHADOW_PORTFOLIO_ROOT (default ~/Development) with a stderr banner; explicit --root and --no-portfolio-fallback never fall back; 3 new test pins. (2) AGENT.md gains the proxy stance: never open empty, never ask which-project, the chief-of-staff moves (amp, goal-mint, adversarial challenge, codify, archive) are Shadow's own unprompted moves, the standing goal is static, chat is projection / plans are memory. (3) docs/reference/honcho.md answers the recurring memory-store question once, with the v4 ruling, a function map, and a spike path to revisit. (4) docs/reference/host-integration.md ships the out-of-box wiring: the 15-line STATIC standing goal pasteable into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and Cursor rules, plus mktemp-d verification. (5) README rewritten around the real product: proxy identity, continuity, amp, the refusals. Gates: 171 py (3 new), 4 js, docs:build, npm run verify all green; plan lint 0 blocking. M5 5/6; DoD is a real remote/voice cold-start on the next tagged release, owner-gated.

…inst repo; status milestone derives from the resumed row; broken local plan blocks the portfolio fallback Each verified real before fixing, each pinned by a regression test. (1) amp: relative --plan now resolves against --repo, never cwd - a decoy PLAN.md in the caller's directory can no longer be read in place of the project plan. (2) status: the Milestone line derives from the SAME row _select resumes (amp's row), restoring the shared-parser guarantee; first-open-milestone is only the fallback when nothing is selectable. (3) status: the portfolio fallback fires only when NO PLAN.md exists under the scan root (existence walk mirrors discover_plans' pruning) - a plan that failed ingestion now blocks fallback with 'exists but failed to load' instead of being masked by a healthy board.

…the block, judgment layers on top

leojkwan · 2026-08-09T02:24:10Z

Rebased onto v4.0.3 main and addressed all three Bugbot findings — each verified real, each fixed with a regression pin (184 py tests green post-rebase):

Relative --plan ignores repo (High) — confirmed: resolved against cwd. Now resolves against --repo; test proves a decoy PLAN.md in the caller's cwd is never read.
Status milestone disagrees with amp (High) — confirmed: the Milestone line derived "first open milestone" independently of _select. It now derives from the SAME (milestone, row) tuple amp resumes; two-milestone fixture pins it (needs-blocked M1, in_progress in M2 → labeled M2).
Fallback masks broken local plan (Medium) — confirmed: discover_plans silently skips a plan that raises. Fallback now fires only when NO PLAN.md exists under the root (existence walk mirrors discover's pruning); a chmod-000 plan yields "exists but failed to load — fix it (shadow lint)" and no fallback, pinned.

Also reconciled with #264: SKILL.md § Shape a goal now names shadow amp as its executable — the prose method and the deterministic projector are one feature. README merge keeps #262's verified requirements (Node 20+) under the M5 identity.

cursor

Stale comment

Left a non-blocking comment (not approving): Cursor Bugbot completed with unresolved findings on the latest commit (including a high-severity amp resume/gate selection issue), so human review is needed. No reviewers were assigned — the only collaborator with ownership of these paths is the PR author.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

Owner ruling 2026-08-09: a machine's board is its own plan set; continuity between machines is git - never a synced chat, served dashboard, or another machine's board impersonated. A plan-less machine says so and works through git remotes. ~vcar's pass condition updated to match: the remote car seat must open ITS board or name the boundary, not show this machine's.

cursor

Stale comment

Left a non-blocking comment (not approving): Cursor Bugbot skipped on the latest commit while two earlier findings remain unresolved (including a high-severity amp resume/person-gate issue), so human review is needed. No reviewers were assigned — no eligible non-author reviewers were available for these paths.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 803bd7451f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…s stall from done Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 384c9f0. Configure here.}

cursor

Stale comment

Left a non-blocking comment (not approving): Cursor Bugbot skipped on the latest commit and an unresolved Bugbot finding remains, so human review is needed. No reviewers were assigned — no eligible non-author reviewers were available for these paths.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

…metadata, unread rows never read as done Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

cursor

Approved: Cursor Bugbot passed on the latest commit with no unresolved Bugbot findings requiring human review. No reviewers were assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

A v4-SHAPED plan is not a v4-VALID plan. _parse skips rows it cannot match, so a plan whose only open work sits in a malformed row rendered as 'nothing left to do' and sent the operator away. Status now lints and refuses to claim completion while a blocking finding stands, saying so instead. Deliberately additive: #264's 'Plan health' line already states the count, so no second line was added - only the completion claim is guarded. Two pins: hidden-work plan never says 'mint the successor'; a clean complete plan still does. Also: --in-flight reintroduced the absolute-path leak (P2) by storing str(plan_path); it now carries the root-relative discovery path, so a portfolio board never prints the operator's home directory. Verified already-fixed upstream in #264 and left alone: person-gated rows excluded from auto-resume (_gated), and the dirty-plan pointer (+UNCOMMITTED in both the pointer and a block warning). 214 tests OK.

leojkwan · 2026-08-09T03:37:13Z

Resolved all four Codex threads — each verified before resolving, not resolved to unblock:

Person-gated rows in auto-resume (P1) — already fixed upstream in feat(skill): goal shaping (amp) ships inside Shadow — v4.0.3 #264 (_gated in _select); confirmed present, left alone.
Dirty plan vs advertised ref (P1) — already fixed upstream: _pointer returns (pointer, dirty), stamps +UNCOMMITTED, and the block carries an explicit warning. Confirmed wired end to end.
v4 classified without lint (P1) — was real, now fixed. A v4-shaped plan is not a v4-valid plan: _parse skips rows it cannot match, so a plan whose only open work sat in a malformed row briefed as "nothing left to do." Status now lints and refuses to claim completion while a blocking finding stands. Deliberately additive — feat(skill): goal shaping (amp) ships inside Shadow — v4.0.3 #264's Plan health line already reports the count, so only the completion claim is guarded, no duplicate line. Two pins: a hidden-work plan never says "mint the successor"; a clean complete plan still does.
Absolute paths leak the home directory (P2) — already fixed upstream via display_path, but my new --in-flight view reintroduced it with str(plan_path). Now carries the root-relative discovery path.

Fixes are on the stacked branch (#268) since it contains this work plus the npm removal; 214 tests green.

A v4-SHAPED plan is not a v4-VALID plan. _parse skips rows it cannot match, so a plan whose only open work sits in a malformed row rendered as 'nothing left to do' and sent the operator away. Status now lints and refuses to claim completion while a blocking finding stands, saying so instead. Deliberately additive: #264's 'Plan health' line already states the count, so no second line was added - only the completion claim is guarded. Two pins: hidden-work plan never says 'mint the successor'; a clean complete plan still does. Also: --in-flight reintroduced the absolute-path leak (P2) by storing str(plan_path); it now carries the root-relative discovery path, so a portfolio board never prints the operator's home directory. Verified already-fixed upstream in #264 and left alone: person-gated rows excluded from auto-resume (_gated), and the dirty-plan pointer (+UNCOMMITTED in both the pointer and a block warning). 214 tests OK.

@codesmith-bot

…268) Owner ruling 2026-08-09: **"no more no npm ever again."** npm auth (E401) was the only thing blocking v4.1.0 — this deletes the dependency instead of waiting on a login. ## The finding that made it cheap The entire Node dependency tree existed to run **four substring checks**. `browser/tests/unit/app.test.mjs` only ever `readFileSync`'d three static files and asserted `toContain` — no DOM, no runtime — while pulling vitest + happy-dom + vue + vitepress. Ported to `tests/test_browser_shell.py`, assertion for assertion. ## Deleted → replaced | deleted | replaced by | |---|---| | `package.json`, lockfile, vitest, playwright, vitepress configs | — | | `npm install -g` | `install.sh` — clone → symlink into `~/.local/bin` + the three host skill roots; `git pull` is the update | | npm `files` allowlist | `.gitattributes` `export-ignore` (same guarantee, git-native) | | `npm pack` + `npm install` verification | `git archive` + a real `install.sh` run — **stronger**: it proves a stranger can clone-and-install | | 4 vitest tests | 4 Python tests, verbatim | | playwright e2e | dropped — `browser/server.py` keeps 28 Python tests; board ruled non-essential 2026-08-07 | Migrated off `package.json`: doctor identity, public-ready metadata gate, release verifier + its tests, python-resolution test — all now read `plugin.json` + `VERSION` + git origin. ## It enforces itself `NoNodeDependency` fails if a package manifest reappears at the root, or if `npm`/`npx` is invoked anywhere in `bin/`, `scripts/`, or `.github/`. This is why npm cannot come back by drift. ## Gates - **201 Python tests OK** (was 184 + the ports), with no node involved - plan lint 0 blocking · release verifier **OK (4.0.3, 80 files, sha256 7fe6ff81…)** - CI rewritten to two node-free jobs; one performs the documented stranger install Stacks on #263 (rebase after it merges). DoD ~rel1 is yours: `git pull && bash install.sh && shadow doctor` on both machines, then the car test.  --- <a href="https://app.blacksmith.sh/firstbitelabsllc/codesmith/shadow/pr/268"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"><source media="(prefers-color-scheme: light)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-light-v2.svg"><img alt="View with [code]smith" src="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"></picture></a> <sup>Need help on this PR? Tag <code>@codesmith-bot</code> with what you need. Autofix is enabled.</sup>    --- > [!NOTE] > **High Risk** > Breaking install and release mechanics for all consumers, plus new `shadow throw` paths that commit and push `PLAN.md`; regressions would block releases or mis-route resumed work across chats. > > **Overview** > **v4.1.0** ships a **Git/Bash/Python-only** product: **npm, lockfile, Vitest, Playwright, and VitePress** are removed; install is **`bash install.sh`** (symlink + skill mounts), updates are **`git pull`**, and release shape is **`.gitattributes` `export-ignore`** plus **`git archive`** verification with a real stranger **`install.sh`** run. > > **CI and docs** drop Node entirely: Python unittest + plan lint, **`shadow-release-package.py`**, public-ready grep, and a documented stranger install replace **`npm test`**, docs build, and e2e. Identity gates (**doctor**, public-ready, release verifier) read **`plugin.json` + `VERSION` + git origin** instead of **`package.json`**. **`tests/test_browser_shell.py`** ports the old static-file checks and adds **`NoNodeDependency`** so manifests or **`npm`/`npx`** in tooling fail the build. > > **Multi-conversation dispatch:** new **`shadow throw`** claims a pending row, appends **`THROWN`**, commits **`PLAN.md`**, pushes, and prints the goal block; **`shadow amp`** skips thrown rows for auto-resume; **`shadow status --in-flight`** lists claimed work portfolio-wide; **`shadow status`** surfaces blocking lint and won’t imply “complete” on invalid plans. **AGENT.md** / **grammar.md** document row-first dispatch and the THROWN discriminator. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit d36134c. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

cursor Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread scripts/shadow-amp.py Outdated

cursor Bot reviewed Aug 8, 2026

View reviewed changes

Comment thread scripts/shadow-status.py

leojkwan changed the title ~~feat(amp): shadow amp — the goal is a pointer to the durable plan~~ feat: the goal is a pointer — amp, v4 status, portfolio continuity, proxy stance Aug 9, 2026