feat(story contracts): declare and derive ## Entry Point / ## Seams

[agarwal-ishaan]

Refs #2391

Problem

pdd test --from-story can generate a behavioural test — one that imports the callable, invokes it, and asserts the contract's ## Oracle / ## Negative Cases as Python expressions over result. It routes to that generator on the presence of a ## Entry Point heading (pdd/story_test_generation.py:288).

The contract template does not offer that section, so almost nothing declares it: 1 of 34 contracts has ## Entry Point, and 0 have ## Seams. The behavioural path is effectively unreachable, and every other story falls through to a text-pinning test that never executes the code it is about.

Change

Template. user_stories/contracts/template.contract.md now declares ## Entry Point and ## Seams, states the consequence of omitting them, and warns that a partial block is rejected rather than silently downgraded. ## Oracle now says its bullets must be Python expressions over result when an Entry Point is present.

Deterministic derivation. Contract generation derives the section from the story's linked prompt rather than asking a model for it: the prompt→code mapping supplies the module, and the prompt's own <pdd-interface> supplies the callable. No LLM involved, so the result is checkable rather than guessed. #2391 suggested <pdd-interface> as the natural source; doing it in Python is what keeps it ungated (see below).

Emitted only when unambiguous — one linked prompt declaring exactly one callable. This is deliberate and conservative:

• a partial block is worse than none: the generator routes on heading presence, so a declared-but-incomplete Entry Point turns pdd test --from-story into a hard error (pdd#1889 C-F7)
• a guessed callable produces a confidently wrong behavioural test, which is worse than a documentary one because it looks like real cover

Measured on this repo, it currently fires on 0 of 34 stories: 20 link more than one prompt, 10 link a prompt with no <pdd-interface> (CLI-shaped prompts), 3 declare several callables. That is the intended behaviour of the restriction, not a defect — the cases it declines are the ones where it would produce the error below.

Two findings that change what #2391 asks for

1. The issue's step 2 is gated work. It proposes teaching _llm_generate_story_contract to populate the sections. The section vocabulary is not read from the template — it is hardcoded in the meta-prompt's <output_format> (pdd/prompts/generate_story_contract_LLM.prompt:64-100); template.contract.md is a separate human-facing document. So that step means editing a managed prompt, which invalidates its CONTRACT-SHA256 and needs the two-phase transition docs/ci.md requires. Deriving in Python sidesteps that entirely.

2. ## Entry Point alone is not enough, and alone it breaks things. The behavioural generator requires ## Oracle bullets to be Python expressions — _assertion_from_bullet (pdd/story_test_generator.py:84) ast.parses each one and raises otherwise. Every existing contract has prose there, because the meta-prompt asks for prose (## Oracle / These details matter for pass/fail: / - <detail>).

Repro — a contract with ## Entry Point and a prose Oracle:

ValueError: Story test generation requires Oracle/Negative Cases bullets to be
Python assertion expressions; got: 'selected workflow: agentic bug vs manual bug repair'

So adding an Entry Point to a contract whose Oracle is prose converts a working (if weak) generation into a hard error — the same failure the no-partial-blocks rule avoids, arriving through a different door. Entry Point and Oracle-as-expressions have to change together, and the Oracle format lives in the gated meta-prompt.

This is why the derivation is restricted to the case that cannot break: the missing sections are a symptom, and the binding constraint is that contracts are authored in prose while the behavioural generator needs expressions.

Deliberately not done: backfilling existing contracts

#2391 suggests backfilling opportunistically. Adding a section changes the contract text, which changes story_bundle_hash(), which invalidates the PDD_STORY_HASH recorded in every linked test — staling them all at once. Combined with the prose-Oracle problem above, a backfill today would stale the suite and break generation for the stories it touched. That is a migration deserving its own change.

Tests

9 new tests in tests/test_story_contract_entry_point.py covering derivation (single callable), each refusal path (several prompts, several callables, no interface, no prompts root), and insertion (before ## Oracle, no-op when already declared, appended when absent). 213 tests pass across the story, generation and coverage suites.

The new test file gets a .pdd/sync-ownership.json rule, and the ownership digest is re-pinned in pdd/sync_core/manifest.py with the previously authorized head kept alongside the new pair, per the multi-head convention already used there.

Relationship to the other story work

Independent of #2390 (story verification engine) and #2392 (silent traceability fallback) — this branch is cut from main and touches different files. #2392 makes the fallback visible; this makes the behavioural path reachable; neither fully closes the gap until the Oracle format changes.

[gltanaka]

Tier A, full-diff review: CHANGES REQUESTED. Issue #2391 is real and still needs a fix: the behavioral route introduced by #1867 is effectively unreachable from normal contract generation. The deterministic-binding direction here is preferable to guessing, but this head does not yet produce valid or safely executable behavioral contracts, is conflicting with current main, and has a failing required Unit Tests check.

I reproduced the prose-Oracle hard failure, required-argument invocation failure, and contract-sync downgrade through the actual generation handoff. I also audited the protected prompt transition, architecture/prompt artifacts, related #2393/#2397 work, and current CI. See the six inline findings.

Artifact gaps remain after those blockers: architecture.json does not declare the new public derive_contract_entry_point surface or describe the behavior (either make it private or update <pdd-interface> and sync architecture), and the generated-contract reference in pdd/docs/prompting_guide.md still omits ## Entry Point / ## Seams and still demonstrates prose Oracle bullets. The .pdd profile/rotation files are present, but the same-PR authority transition violates docs/ci.md and the ownership digest is stale.

Validation: tests/test_story_contract_entry_point.py passes (11 tests); the focused story suites reached 82 passes with one unrelated local subprocess/import contamination; both protected rollout-policy failures reproduce locally; GitHub's full unit job reports 16,336 passed / 2 failed; JSON parsing and git diff --check pass. Contributor evidence is not sufficient end-to-end because it tests helpers and hand-authored valid contracts, not generated contract → pdd test --from-story → pytest. Before re-review, add a realistic safe generation-to-pytest test that is green on correct behavior and red after mutation, plus a regeneration test preserving the executable contract. PR #2397 directly overlaps this implementation and is also changes-requested; consolidate on one approach rather than merging both.

[gltanaka]

P1: This injects ## Entry Point into output from generate_story_contract_LLM.prompt, but that meta-prompt still mandates prose Oracle/Negative bullets (- <detail>, - <forbidden outcome ...>). Heading-presence routing then sends the contract to _assertion_from_bullet, which rejects the prose. I reproduced ValueError: ... requires Oracle/Negative Cases bullets to be Python assertion expressions; got: 'returned value shape'. Validate the complete executable spec before insertion and omit Entry Point unless it is valid, or land the safely constrained executable Oracle format through the required prompt-governance sequence. Add generated-contract → --from-story coverage.

[gltanaka]

P1: Every derived invocation discards required arguments. The new test fixture declares checkout_total(a, b) and then explicitly accepts args: []; passing that derived contract through generated pytest reproduces TypeError: checkout_total() missing 2 required positional arguments. Do not infer fixture values. Auto-derive only callables with zero required arguments, or require an explicitly authored invocation contract.

[gltanaka]

P1 security: This newly advertises executable Python expressions, while downstream validation only uses ast.parse(..., mode="eval") and splices the expression verbatim into pytest. Calls such as __import__(...).system(...) are accepted. Once this PR injects Entry Point, issue-derived LLM text can cross into executable test code. Use a structured predicate format or a strict AST allowlist limited to result, literals, subscriptions, boolean/comparison operators, and explicitly safe helpers; reject calls/imports/unsafe attributes before writing the contract.

[gltanaka]

P1: sync_user_story_contract() calls this path with extra_prompt_paths=[] even though it parses primary_refs. I reproduced a successful forced sync of a story linked to one valid prompt/source/callable and the regenerated contract had no Entry Point, silently downgrading the next --from-story generation to text-pin mode. Resolve the story metadata refs against prompts_root, pass those paths here during sync, and add a preservation regression test.

[gltanaka]

P1 governance/security: This candidate-specific state makes authority installed and consumed by this same PR appear valid. The branch simultaneously changes the managed prompt, adds/retire-reissues rotation authority, updates the final profile, and adds this verifier acceptance. docs/ci.md:31-57 explicitly forbids installing and consuming a row in one PR. Remove this self-authorization; first merge a Phase A containing only the exact dormant authority with prompt/profile bytes unchanged, then consume those protected bytes in a rebased Phase B.

[gltanaka]

P1: This pin does not match the checked-in .pdd/sync-ownership.json. Both local validation and required CI compute a18bfe5b655527387ad151a3042a4a0ac8f60250645e18eaf740c9d853e6965d, not b3b5ed...; the bridge falls through and the eight repaired metadata paths lose ordinary ownership. Rebase on current main, reconcile the four protected-state conflicts, pin the exact resulting bytes through the authorized sequence, and rerun the full policy suite.