Open questions blocking the c47b1284 re-pin (+ review of d95fe2b / Phase A docs)

Opened by the refactor hardening pass. Co-authored with @iap (whose Grok-assisted
Phase A docs change is d95fe2b + 2cf0b6e); the research below was produced by
an independent agent, and every claim is reproducible from this repo plus the
pinned upstream clone at .cluster/pstack-hermes/repos/cursor-plugins.

Nothing here is committed on any branch. main is green (validate.py exit 0,
80 tests, ruff clean). These are questions, not proposals — answers unblock
the re-pin.

Part 1 — Three questions that block the re-pin

The re-pin cannot be done as a mechanical find-and-replace. Triage of all dead
anchors against c47b1284 (pstack v0.15.5) found 38 dead anchors: 22 are
mechanical (upstream trimmed trailing prose, the anchor's leading text still
matches) and 16 need a judgement call. Three findings sit underneath those
numbers and are the actual blockers.

Q1 — Is orchestrate retained as a port-only skill, or pruned?

Observed: T12_MAP[9] and T12_MAP[11] anchor on prose inside
skills/orchestrate/SKILL.md. That file does not exist at c47b1284 — the
skill was removed upstream. The anchor audit reports this as "anchor never
matched", which reads like wording drift but is a deleted skill.

Question: keep orchestrate as a deliberate port-only divergence (needs an
ADAPTATIONS.md row and a stated rationale), or prune it and drop T12_MAP?

Q2 — What replaces the agent-transcripts/ model for T11_MAP?

Observed: T11_MAP[5,6,7,15] anchor on locating transcripts under the active
workspace's agent-transcripts/ directory. At c47b1284, upstream why/SKILL.md
no longer mentions agent-transcripts at all (8 mentions remain elsewhere in the
tree, none in why/). The transcript-location concept appears to have been
replaced upstream.

Question: the port's hermes transcript adaptation was built against upstream's
model. With that model gone, is the adaptation
(a) retained on the port's own authority, with no upstream anchor, or
(b) dropped as no longer applicable?

I lean (a) — hermes has session_search, and losing transcript-grounded recall
would be a real capability regression — but that is a product call, not mine.

Q3 — Does the new triage row settle the excluded-skills policy?

Observed: the Phase A AGENTS.md triage table now includes:

Touch .cursor-plugin/, pstack/agents/, attribution, excluded benny /
make-bot-ui — leave as-is (dual-load / scanner contract)

At c47b1284 upstream added three skills the port does not carry:
make-bot-ui, principle-attack-the-premise,
principle-test-behavior-not-implementation.

Question: is excluding these a settled decision (so the re-pin ports 2 skills
and skips 3), or does "leave as-is" only apply to the existing scanner-contract
exclusions and the new principle-* skills should be ported on re-pin?

I read "leave as-is" as don't touch the scanner contract, not necessarily never
port upstream's new principle skills — but the wording is ambiguous and the
answer changes the re-pin scope.

Part 2 — The reflect reviewer table was restructured (needs re-anchor + asset update)

Independent of Q1-Q3, this one has a concrete mechanical component.

Observed in reflect/SKILL.md at c47b1284:

A "Role line" column was added. This affects T9_MAP[13,14,16,17,18,19].

Question: should the port's model-panel indirection adopt the 4-column shape
(it maps cleanly onto the existing role names), or stay 3-column and re-anchor
only the model defaults? Either is workable; the first is closer to upstream.

Also: tools/assets/model-panel.json defaults are stale relative to
c47b1284 (claude-opus-5-5-max etc). Should the re-pin update the shipped
defaults, or leave them at the old-pin values until a separate change?

Part 3 — Review of the Phase A docs change (d95fe2b, 2cf0b6e)

Overall: this is a good change, and two claims in it are things I could
verify independently and did:

• "Graphite default / GitHub fallback" matches the shipped code exactly:
  store.ts:1316 is for (const candidate of ["graphite", "github"] as const).
  The old README's "Graphite optional" wording was wrong, so correcting it is right.
• The skill_manage ban matches what the installed agent already enforces:
  hermes-agent/agent/curator.py:315-318 explicitly forbids the curator from
  touching skills.external_dirs or plugin skills. Promoting that to written
  policy is the right layer.

docs/USING.md is the strongest part — demoting "edit in place" to explicitly
temporary (with the autostash caveat inline) matches the behaviour I measured on a
live install.

Three inconsistencies to fix

1. README.md:62 still says the panel ships in-package.

  config shipped as hermes `config/models.json`.

Post-#57 (c2552a1) the shipped default is indeed pstack/config/models.json,
so this is technically true — but it sits next to the new USING.md line saying
the panel is written outside the package, and reads as contradicting it.
Suggest rewording to distinguish "shipped default" from "your panel".

2. AGENTS.md:208-209 directs hand-tuning at a path that is now ambiguous.

- Hand-tuning `pstack/config/models.json` — edit
  `tools/assets/model-panel.json` and rebuild; `validate.py` checks they match.

That is correct for the shipped default, but post-#57 a user's own panel lives
at pstack-models.json beside hermes' config.yaml. The banned-pattern list
reads as guidance about a user's config and now points at the wrong file.
Suggest disambiguating the two explicitly.

3. Vocabulary table row (AGENTS.md:171) still uses the old path.

| `config/models.json` → `tools/assets/model-panel.json` | hand-tuned shipped panel only |

Same issue, smaller. This row is a hermes↔Cursor vocabulary mapping, so it may
be correct as-is if it means "the Cursor-side panel asset" — worth confirming.

One optional addition

AGENTS.md now has the write-surface table and the skill_manage ban, but does
not explicitly mention that in-place edits to the installed tree are temporary.
USING.md says this clearly; the agent-facing doc does not. Since agents read
AGENTS.md first, one line there would close the gap.

Part 4 — Corrections to earlier claims in this thread

Recorded so the re-pin doesn't inherit them:

1. F16 cannot ship independently of the pin bump. I claimed otherwise twice.
   Verified: at the old pin 93b00b8, upstream still hardcodes
   const LANES = "Ten lanes on \grok-4.6-fast-xhigh` at the PR head"; only c47b1284generalizes it to/Ten lanes on `[^`<>]+` at the PR head/. Pruning F16 while shipping from the old pin leaves no env override **and** fails validate.py (FAIL check-plan.mjs hardcodes the lane slug in a literal`).

2. CRLF causes zero anchor failures. All 125 upstream .md files at
   c47b1284 are CRLF, but convert.py normalizes text during copy
   (files copied: 130 (text normalized: 125 ... CRLF fixed: 125)). Not a cause.

3. The dead-anchor count is 38, not 36. The earlier figure predated the F16
   prune changing the map.

Proposed sequence once Q1-Q3 are answered

1. F16 prune (transform + constants + README row + validate.py gates → pin-agnostic
   lane-shape invariant).
2. Update tools/assets/model-panel.json for the new upstream defaults.
3. Re-anchor T9_MAP[13,14,16,17,18,19] against the restructured table.
4. Apply the 22 mechanical trims.
5. Bump UPSTREAM_PIN in all four workflows; rebuild; ledger rows.

Steps 1 and 4 are mechanical once Q1-Q3 land. Steps 2-3 depend on Part 2.