feat: add strategy-aware benchmark artifacts

[mikeylong]

Summary

• add canonical guidance strategies for generation sessions and handoff artifacts
• add strategy-aware comparison and benchmark reporting semantics
• update generator-facing docs for prompt-summary vs json-primary vs unguided flows

Testing

• pnpm --filter @surfaces/interfacectl-cli build
• pnpm --filter @surfaces/interfacectl-cli test -- test/generation-session.test.mjs test/generation-benchmark.test.mjs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
interfacectl	Error		Mar 14, 2026 6:49pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 339e2e9655

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep session strategy immutable when preparing handoff

This command persists sessionForHandoff back to session.json, which includes the override values for guidanceStrategy and baseHandoffPath; if prepare-generation-handoff is run after attempts exist, it can retroactively relabel the session strategy and handoff path for all later summaries/comparisons even though earlier attempts were produced under a different strategy. Because buildGenerationSessionSummary reports the session-level strategy, this mutates benchmark evidence instead of just emitting an alternate handoff artifact.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Align advertised init tool values with runtime validation

init-generation-session help now claims --tool accepts local-llm, but ensureSessionTool still only allows codex|cursor, so using the documented local-llm value fails with an input error. This creates a broken CLI contract for users who rely on --help output.

Useful? React with 👍 / 👎.

[mikeylong]

Holding this PR as superseded-in-place for now. The current branch is stale and the repo is still receiving a standalone failing Vercel status that is not part of the allowed landing path. The intended next step is to remove that stale repo-level Vercel integration, cut a fresh replacement benchmark PR from current main, and then close this PR with a link to the replacement.

[mikeylong]

Refreshed this PR against current main on March 14, 2026. This PR remains the merge vehicle for the benchmark/session work; it is no longer being treated as superseded.

Local verification on the refreshed branch:

• pnpm --filter @surfaces/interfacectl-cli build
• pnpm --filter @surfaces/interfacectl-cli test -- test/generation-session.test.mjs test/generation-benchmark.test.mjs

Current blocker is still external to the branch content: GitHub is attaching a failing plain Vercel status to this repo from the org-wide Vercel app installation, and the current token here is org-admin but not org-owner, so I could not remove or narrow that installation from the CLI/API. Once that owner-level settings fix is applied, this PR is ready to continue as the benchmark merge vehicle.