Files
gstack/docs/autoplan-guard-troubleshooting.md
T
f30b7b788a v1.91.13.0 fix: severe bug wave (autoplan guard, land-and-deploy CI gate, project identity, gbrain, review gates) (#3013)
* fix(land-and-deploy): never merge over red, pending or missing CI (#2995)

/land-and-deploy gated only on required checks, so a repo with none
(every GitHub Free private repo, any repo without branch protection)
skipped the CI wait and could merge over red CI. The verdict now comes
from bin/gstack-ci-gate, a tested helper bound to the head SHA: all
checks by default, cancel/unknown buckets fail, NO_CHECKS needs explicit
per-head approval, and both merge commands (including --auto) run only
after a PASS for the same SHA they pin with --match-head-commit.

Co-authored-by: harshitgavita-07 <harshit.gavita@gmail.com>

* fix(slug): give nested-group projects their own state bucket and verify checkpoint identity (#3003, #2901)

gstack-slug kept only the last two remote path segments, so
customer-a/product/repo and customer-b/product/repo shared one bucket
and /context-restore could present another project's checkpoint.

- One canonical-remote rule (bash + TS, golden vectors) used by all six
  resolvers: lowercased host, no userinfo/port/.git, Azure DevOps and
  Bitbucket Server normalized. 3+ segment remotes get
  <last-two>-<16 hex>; two-segment remotes (all of GitHub) are unchanged.
- Versioned sticky cache (v2:) keeps cache hits git-free.
- context-save stamps the credential-free remote and root;
  context-restore only treats this project's checkpoints as latest,
  reports foreign/unverified ones first, and treats a different root
  with the same remote (Conductor handoff) as information.
- gstack-slug --adopt-legacy copies only files the user confirms.
- question-preference-hook reads the same versioned cache, so never-ask
  preferences fire; unknown identity asks instead of auto-deciding.

* fix(gbrain): brain context loads, managed sync works, memory sync stops duplicating (#2883, #2985, #2922)

- brain-context-load called 'gbrain list_pages' (an MCP tool name), so
  every skill's brain context was 0 bytes. It now uses 'gbrain list'
  with gbrain's real filter flags, and prints one line when queries fail.
- The code-stage sync always passes --no-pull (managed gbrain >= 0.51
  refuses without it); a gbrain that rejects the flag fails with an
  upgrade message and is never retried without it. stderr is streamed
  with a bounded tail and quoted in failure summaries.
- /sync-gbrain gains --sources (and GSTACK_MEMORY_INGEST_SOURCES); by
  default it skips types already synced through a federated curated
  source, so curated pages stop being re-duplicated.

Co-authored-by: Vitor Cepeda Lopes <vitor@vitorcepedalopes.com>
Co-authored-by: harshitgavita-07 <harshit.gavita@gmail.com>

* fix(codex,cso): clean Codex reviews stop failing; semgrep and trivy SARIF results import (#2769, #3011)

- Codex review gate is PASS / FAIL / UNVERIFIED. Untagged output (what
  a clean 'codex review --base' prints) is UNVERIFIED, not FAIL, and
  never a false PASS; P2/P3-only output passes.
- import-sarif resolves semgrep's undeclared %SRCROOT% and trivy's
  ROOTPATH (including git-URL targets) through explicit, captured
  mappings; declared bases must sit inside the source root or the
  run's checkout, URIs are percent-decoded, and rejected results are
  counted with rule, base and path instead of silently dropped.

* fix: version strings are not IPs, failed update checks are not 'up to date', private security reporting (#2856, #2786, #2984)

- The pre-push redact hook exempts a root VERSION file that is only a
  version string and the version token in CHANGELOG release headings;
  the engine allowlist is untouched.
- gstack-update-check caches an unreadable remote as CHECK_FAILED with
  a short TTL instead of UP_TO_DATE; /gstack-upgrade never reports
  'latest' after a failed check.
- SECURITY.md points reporters at GitHub private vulnerability
  reporting.
- pr-title-sync (pull_request_target, write token) pins actions/checkout
  to a reviewed SHA.

* fix(autoplan): publication guard accepts real Claude Code journals (#3007, #3009, #2968, #2977, #2986, #3006)

The guard required a session journal to start with a user message, but
Claude Code starts it with SessionStart hook attachments (and a forked
compacted session starts with a compact_boundary), so every phase was
denied for anyone with a SessionStart hook. Windows path spellings
(C:/, /c/, drive case) were rejected too.

- Reader accepts the captured startup, compact, clear and fork shapes
  (claude 2.1.284 fixture), computes root uniqueness over every
  candidate, and returns typed reason codes instead of one string.
- Hard denials (competing root, foreign cwd, sidechain, agent, cycle,
  malformed, identity) say what happened and how to run the reviews by
  hand; unflushed journals still retry.
- A well-formed, stable journal whose root shape is unrecognized now
  warns ('phase publication was NOT verified') and continues, without
  overriding Claude Code's own permission check; no bypass switch.
- Windows paths fold before validation, so '..' is still rejected.
- Periodic drift canary runs the reader on fresh journals from the
  pinned claude.

Co-authored-by: Charles M Berg <77517285+CharlesBerg85@users.noreply.github.com>
Co-authored-by: laurenbdaniels-coder <264343335+laurenbdaniels-coder@users.noreply.github.com>
Co-authored-by: Jordan Mayer <176445995+maydaycyber@users.noreply.github.com>
Co-authored-by: elmesery-dev <elmesery.dev@gmail.com>

* v1.91.13.0: severe bug fix wave release notes, stale gbrain verbs in docs

* test: seed the versioned slug cache in the memory-injection deny case (#2901)

The preference hook now resolves the project bucket from gstack-slug's
v2 slug-cache entry instead of basename(cwd); this fixture still wrote
preferences under the basename bucket without the entry the skill
preamble always writes first.

* fix: full-suite follow-ups for the fix wave

- gstack-slug's --help heredoc is over 512B, so it gets the BASH_COMPAT=50
  pipe-deadlock guard like the other bins.
- Refresh the codex/factory ship goldens for the plan-gates slug change.
- The periodic lane gains the autoplan journal drift canary (107 paid
  files); raise the eval-slices cap to 25 so every slice still starts
  at once until its recorded duration lets the planner pack it.

* fix(plan-eng-review): clearer Step 0 sequencing, write routes and section outputs

The workflow judge scored plan-eng-review's instructions at
actionability 3.67 (bar 4) on text unchanged from main. Resolve the
ambiguities it named together, without changing any gate or output:
Step 0 names the Read's order and keeps one STOP; the pending-call,
read-only, forbidden-write and failed-save rules become one Write
routes block; header/label limits and grid checks are concrete;
Performance gets a checklist; each section has a stated output shape;
Lake Score is defined. Same total length (parity cap).

---------

Co-authored-by: harshitgavita-07 <harshit.gavita@gmail.com>
Co-authored-by: Vitor Cepeda Lopes <vitor@vitorcepedalopes.com>
Co-authored-by: Charles M Berg <77517285+CharlesBerg85@users.noreply.github.com>
Co-authored-by: laurenbdaniels-coder <264343335+laurenbdaniels-coder@users.noreply.github.com>
Co-authored-by: Jordan Mayer <176445995+maydaycyber@users.noreply.github.com>
Co-authored-by: elmesery-dev <elmesery.dev@gmail.com>
2026-10-02 11:11:00 -07:00

5.3 KiB

/autoplan publication guard: troubleshooting

/autoplan installs a PreToolUse hook (autoplan/bin/phase-publication-hook) at its phase boundaries. Before it lets a phase entry Read (or a reviewer Agent dispatch) run, it reads this session's own Claude Code journal (~/.claude/projects/<project>/<session>.jsonl) and checks that the previous phase's report was published as parent assistant text.

To do that it must first prove which journal records belong to this session. It walks the record chain from the first conversation turn up to its root. When it cannot prove ownership it reports a code. This page explains each code and what to do.

Every message from the guard names the code and the Claude Code version that wrote the journal. Include both when you report a problem.

Supported journal roots

The guard accepts exactly one root per journal file:

  • A user message with no parent (sessions without hooks).
  • An unbroken chain of message-less SessionStart hook attachments (hook_success, hook_additional_context, ...) that starts at a null parent and ends at the first user turn. Claude Code writes this when any SessionStart hook is installed, including hooks that plugins add. It also writes one after /clear.
  • A compact_boundary record whose logical parent is not in the file, but only when it is the file's first record. Claude Code writes this when you resume a compacted session with --fork-session.

--continue, --resume and /compact append to the same journal, and the guard follows them through their existing parent links.

The real journals these rules were checked against (startup with two SessionStart hooks, /compact, /clear, and --resume --fork-session after a compact) came from Claude Code 2.1.284. A redacted copy is in test/fixtures/claude-native-journal-roots-2.1.284.json. A periodic CI canary, autoplan-journal-drift, captures fresh journals from the pinned Claude Code and checks the reader still accepts them.

Hard denials

The journal shows a conflict, so retrying cannot help. The guard denies the phase entry.

Code Cause
competing_root The journal has more than one conversation root, or two records share one UUID.
foreign_cwd The journal's root was written in another project directory, after spelling and symlinks are taken into account. Linked git worktrees of the project are accepted.
sidechain The first turn or its ancestry is a sidechain (subagent) record, not the parent session.
agent The conversation ancestry passes through a subagent record.
cycle The journal's parent links form a loop.

What to do: run the review phases by hand: /plan-ceo-review, then /plan-devex-review, then /plan-eng-review. Or start a new Claude Code session in the project directory and run /autoplan again. If a fresh session gets the same code, open an issue with the code and Claude Code version.

Retry denials

The guard has not reached a conclusion. The message ends with "no missing-publication conclusion has been made". Retry the same tool.

Code Cause
(none) The journal does not yet hold the records the guard needs. This includes the current tool call, or an ancestor record Claude Code has not written yet.
changing Claude Code was writing the journal during every read in the 2-second window.
identity The journal path, its directories or the file itself failed the identity checks: for example a symlink, a foreign session, or the wrong directory layout.
malformed A complete journal line is not valid JSON or UTF-8, or its records contradict each other.

If a retry keeps failing with the same code, use the fallback above.

Unverified phase entry (unrecognized_shape:<detail>)

The guard found a journal root it does not recognize. This usually means Claude Code changed its journal format. In this one case the guard does not block you, but only when all of the following hold:

  • every journal line parses,
  • the journal is identical across two reads,
  • the current tool call is already in the journal, and
  • the only problem is the unrecognized root shape.

The phase entry then goes ahead without a permission decision from the guard, so Claude Code's own permission check still runs. You see:

[autoplan] phase publication was NOT verified for this session (journal shape unrecognized_shape:...)

The model gets the same notice, with a reminder to publish each phase report. unrecognized_shape:cwd_spelling means the journal's directory is the same folder as the project, spelled differently.

If any other condition fails, or a hard code also applies, the guard denies instead.

Each unverified entry adds one line to <state root>/analytics/autoplan-guard.jsonl (normally ~/.gstack/analytics/autoplan-guard.jsonl). The line holds the code, the Claude Code version and the record types at the journal root. It never holds content. A failure to write this log never changes the guard's decision. Please include that line when you report the new shape.

There is no environment variable that turns the guard off.

Windows paths

Claude Code and Git Bash can spell one path as C:\x, c:\x, C:/x or /c/x. The guard treats these as the same path. It does not resolve . or .., so a path containing them is still rejected.