spec: make portable core line budget advisory

[yihanzhu]

Closes #174

G2 amendment

The operator ruled that implementation line count is a planning and reviewability signal, not a hard product constraint. The merged spec had made 400 net lines a pass/fail gate, so the first plan preflight correctly stopped under the text then in force.

This amendment changes only three places in work/portable-core-contracts/spec.md:

• R14 now requires evidence-based size estimates and cohesive review units without a numeric pass/fail gate;
• the old 400-line allocation becomes the preflight's normal-format working range of about 800–1,100 lines;
• the matching risk says size never trades away behavior, proof, readability, or safety.

Unchanged hard gates

• All five documents, shared refs, three capabilities, five permissions, commands, relations, status/evidence rules, and downstream handoffs are byte-for-byte unchanged outside those budget paragraphs.
• Complete behavior and adversarial tests remain required.
• Jq 1.6 stays pinned; one canonical schema source and one shell front door remain required.
• Code golf, generated long lines, duplicate schemas, a second parser, system-jq drift, tests that reuse production logic as their oracle, and reduced negative coverage remain forbidden.
• This intent keeps one deterministic implementation branch/PR. The evidence-based 800–1,100 line estimate is an explicit exception to the soft review-size guide; line count alone does not force a split. The plan must organize clear commits/review sections, while any actual concern or scope expansion returns to the artifact gate.
• No validator or live profile activates before the full contract and integration proof are accepted.
• Human merge only.

Review

Independent implementability and security/compliance reviews of the exact amendment are clean. Both confirmed that softening the number does not soften contract behavior, tests, CI, review, activation, or authority boundaries.

Formal round-0 found that the first draft let a plan ask for multiple implementation PRs, which conflicted with the accepted intent and deterministic branch convention. Round-1 removes that escape: this intent keeps one ystack/impl/portable-core-contracts branch/PR; any split requires separately accepted child intents before planning or code. Independent implementability and compliance reviews of that exact fix are clean.

Formal round-1 then found that keeping one estimated 800–1,100 line PR still needed an explicit disposition against the repository's soft 300–400 line guide. The operator ruled that line count is not a hard constraint. Round-2 records this as a review-size exception only; it adds clear commit/review-section requirements and leaves every safety, proof, scope, and merge gate unchanged.

Formal round-2 reviewed exact head 117687c302c7a8370cc8049604cb27fbdcd2b861 against base a296940d802ae4dfcdfeac3d6c56f0f5f6874f4c and found no actionable regression: #175 (comment). GitHub CI is green on the same head.

Exact-head proof

Clean isolated worktree at 117687c302c7a8370cc8049604cb27fbdcd2b861 against base a296940d802ae4dfcdfeac3d6c56f0f5f6874f4c:

• spec stage scope: only work/portable-core-contracts/spec.md changed;
• required sections and intent blob: passed;
• structure check: passed;
• ShellCheck 0.11.0: passed;
• north-star resolver: 74 passed, 0 failed;
• north-star gate/consumer: 226 passed, 0 failed;
• models parser: 63 passed, 0 failed;
• degraded-review gates: 91 passed, 0 failed;
• pending-stage, round-cap, and quota tests: passed;
• rename/doctor cases: 27 passed, 0 failed;
• rename gate and git diff --check: passed.

Merging this PR accepts only the delivery-budget amendment. It does not accept a plan, implementation, multi-PR shape, live activation, or agent merge authority.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 69d70ce
Reviewed-base: a296940
reviewer: operator-default @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/175-78222/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The amendment permits a multi-PR implementation that conflicts with the accepted intent and the initiative's deterministic branch model. The delivery scope must be reconciled before this spec can safely guide planning.

Review comment:

• [P1] Keep delivery inside the accepted one-PR scope — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.4HxjCYvzfM/work/portable-core-contracts/spec.md:79-80
  If preflight concludes that one PR is too large, this now permits multiple implementation PRs even though the accepted intent.md requires one reviewable implementation PR, and the repository defines only one deterministic ystack/impl/<slug> branch. Approval at plan time does not amend that G1 constraint, so extra PRs would lack a valid artifact and branch chain. Keep this to one PR or rescope the slices through accepted intents before planning.

[cloudflare-workers-and-pages]

Deploying ystack with    Cloudflare Pages

Latest commit:	117687c
Status:	✅  Deploy successful!
Preview URL:	https://8f7d310e.fabrica-6yx.pages.dev
Branch Preview URL:	https://ystack-spec-portable-core-co-luff.fabrica-6yx.pages.dev

View logs

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: ac48b33
Reviewed-base: a296940
reviewer: operator-default @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/175-6717/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The amended spec requires a single implementation PR despite estimating a change far above the repository's stated PR-size budget. The delivery shape should be split or reduced before planning proceeds.

Review comment:

• [P2] Split the implementation to honor the PR budget — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.dPXy3w8DGe/work/portable-core-contracts/spec.md:79-82
  When implementation follows this spec's own 800–1,100 line estimate, requiring one implementation PR conflicts with AGENTS.md's ~300–400 net-line budget and its instruction to split larger changes. The fallback here only applies when cohesion fails, so a cohesive change that is two to three times over budget must still stay in one PR; define accepted child scopes now or reduce the planned scope.

[yihanzhu]

Operator ruling — line count is not a hard constraint

The operator ruled that implementation line count is not a hard product or safety constraint.

For this accepted single concern:

• the implementation remains one deterministic ystack/impl/portable-core-contracts branch/PR, as required by the intent and artifact convention;
• the evidence-based 800–1,100 line estimate is an explicit exception to the repository's soft 300–400 line review-size guide;
• line count alone does not force a semantic split or new PR;
• the plan must organize the one PR into clear commits and review sections so each responsibility can be checked independently;
• any concern or scope expansion still returns to the artifact gate;
• complete behavior, readable code, complete adversarial tests, pinned jq, CI, independent review, no partial activation, and human merge remain hard requirements.

Round-2 is limited to recording this review-size ruling. It does not change any contract behavior or authorize implementation.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 117687c
Reviewed-base: a296940
reviewer: operator-default @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/175-54464/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The spec consistently replaces the unrealistic hard line cap with an advisory estimate while preserving the single-concern requirement, artifact gate, test coverage, independent review, CI, and safety boundaries. No actionable regression is introduced.

[yihanzhu]

Final handoff — amendment review clean, CI green

Head 117687c302c7a8370cc8049604cb27fbdcd2b861 passed every exact-head local gate and GitHub CI against base a296940d802ae4dfcdfeac3d6c56f0f5f6874f4c.

Formal round-2 found no actionable regression: #175 (comment)

The final amendment changes only work/portable-core-contracts/spec.md. It makes the line estimate advisory and records an explicit soft review-size exception for one deterministic implementation PR. It does not change contract behavior or waive tests, readability, pinned jq, CI, independent review, no-partial-activation, or human merge.

merge-ready is applied. Merging accepts only this narrow G2 amendment; it does not accept a plan or implementation. Human merge only.