Skip to content

Deferred items from the /ship review of #3487 (docs-caps fail-open and symlinks, docs not in the receipt schema, --check-prose unwired, REVIEW_SCOPE_KEY_VERSION move) #3504

Open

Description

@capy-ai

Four items from the /ship review of #3487 (version-less repos, docs-audit record and caps, the frozen-scope paid case), each judged below the blocking floor (would fail a test, break production, or lose data or secrets) and set aside for a ruling rather than fixed in that PR. Same shape as #3485, which holds the deferred findings from #3484.

1. gstack-ship-receipt docs-caps --base fails open on an unrelated base-policy error, and follows symlinks

bin/gstack-ship-receipt (cmdDocsCaps): loadPolicyFromBase merges defaults whenever the base branch's .gstack/ship-policy.json has any validation error, and the command surfaces only docs.* errors. An unrelated invalid key on the base therefore zeroes the declared caps and the command prints DOCS_CAP: none declared and exits 0, so a repository with caps declared can pass Step 14.5 with none measured. The size read also follows symlinks (fs.statSync), so a cap on a path that is a link measures the target, which may live outside the docs root. Proposed: surface every base-policy error as POLICY_SOURCE_UNAVAILABLE (refuse, never default) and measure with lstatSync, treating a symlink as over.

2. docs is not in the receipt schema

gstack-ship-receipt write --docs records docs: { status, scope[, exception] } on the receipt and orderReceipt places it, but ARTIFACT_SCHEMAS['ship-receipt'] in lib/headless-artifacts.ts does not declare the key, so validateReceipt neither requires nor type-checks it, and a hand-edited receipt with a malformed docs object validates. Proposed: add docs to the schema with the three statuses and the four exception strings, optional for receipts written before DOCS_CAPS_KEY_VERSION.

3. gstack-ship-receipt read --check-prose has no caller

lib/ship-receipt-prose.ts compares the counters a PR body quotes with the receipt's integers (RECEIPT_PROSE_MISMATCH), and docs/ship-policy.md says data PRs run it before READY, but no /ship step or section invokes it (the module's header comment names a Step 19 that does not run it). Proposed: either call it from the pr-body section after write --body, or from gstack-ship-queue ready, and fix the header comment.

4. REVIEW_SCOPE_KEY_VERSION moved from 1.91.249.0 to 1.91.256.0

lib/ship-policy.ts now introduces review_scope at 1.91.256.0 (the release that shipped #3481), where #3481's branch had named 1.91.249.0. A policy that pinned min_gstack_version between the two (1.91.249.0 ≤ v < 1.91.256.0) while declaring review_scope is now rejected by the compat check on this gstack, although it was accepted by the gstack it was written against. No released gstack carried the 1.91.249.0 value, so no shipped policy should be affected; the ruling wanted is whether a key version may ever move after a branch names it, and whether the compat check should treat the older value as an alias.

Refs #3485, #3487.

Activity

  1. capy-ai commented on Oct 27, 2026

    @capy-ai
    ContributorAuthor

    #3515 (v1.91.279.0) lands the below-floor rulings table in docs/review-policy.md#rulings-below-the-floor and the 'On record' lead-judgment ground in scripts/resolvers/review-army.ts. The remaining items here stay open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions