fix: bundle-aware default-scope resolution + open-world doc counts (2.5.30)

[apackeer]

Problem

On a plugin-only install (core scopes deselected via plugin selection), several code paths still hardcode core scope defaults: the orchestrator's run-stage DEFAULT_SCOPE params and intent-birth's "poc" fallback crash with "Unknown scope" or route to a disabled scope. Separately, shipped agent-facing prose asserts closed-world counts ("all 32 stages", fixed persona lists) that any plugin install falsifies. On a bundle-only default install, short task prompts can therefore crash at birth or route into an unintended large scope.

What changes

Upstream already carries selectionAwareDefaultScope (sole-enabled-plugin fallback + descriptive errors); this PR adds the remaining bundle-aware behavior:

• New scope frontmatter key freeform_default: true - a plugin scope can nominate itself as the freeform/default fallback. Checked before the sole-plugin heuristic in selectionAwareDefaultScope, so it also holds in mixed installs.
• resolveDefaultScope(preferred) wrapper, and the remaining hardcoded sites routed through it: orchestrate buildRunStageDirective / emitRunStageForSlug DEFAULT_SCOPE params, utility handleIntentBirth "poc", and the init-runner prose.
• Open-world prose: softened only claims that are provably false under plugin selection (stage-protocol "all 32 stages" -> the compiled graph; principles scope list; onboarding plugins note; the "11 domain experts" persona bullets across all 5 harness SKILL.md files). Generated tables and stable counts untouched.

Out of scope: inferScopeFromText keyword-routing behavior remains byte-identical; the open-world routing path remains the adaptive composer (t67's 28 pins green).

Testing

• New t257-default-scope-resolver, including a plugin-only-install fixture proving intent-birth's "poc" preference resolves to an enabled scope instead of crashing, explicit invalid environment-scope validation, and a compile-time ambiguity guard for multiple enabled freeform defaults.
• smoke+unit: 179 files, 0 failed (t67 28/28, t68, t191, t225, t239 all green). Integration: green except pre-existing base reds (t66, t89) + two contention flakes that pass green-alone.
• package.ts --check, typecheck clean; coverage registry + ratchet regenerated.

Note for maintainers: version/CHANGELOG re-bump expected when landing after sibling PRs.

[leandrodamascena]

Thanks for closing the plugin-only default-scope failure and proving the core-only path remains unchanged. I saw the focused tests and all repository gates pass.

Two items should be addressed before merge:

1. [P2] Preserve invalid env-scope validation (core/tools/aidlc-lib.ts:3880)
   selectionAwareDefaultScope(envScope) now treats any unknown AWS_AIDLC_DEFAULT_SCOPE value as a request for the nominated fallback. In a mixed core/plugin install, a typo exits successfully and selects the plugin scope. This contradicts docs/guide/13-customization.md:66 and aidlc-utility.ts:5286-5291, which promise that invalid values fail before state initialization. Please distinguish internal fallback literals such as feature/poc from explicit unknown environment values.

2. [P2] Document freeform_default (docs/harness-engineering/04-scopes.md:33)
   This introduces plugin-author-facing scope frontmatter, but the scope schema documentation does not mention it. Please add the field, its selection semantics, and its uniqueness expectation to the scope/plugin authoring documentation.

Non-blocking: multiple enabled freeform_default claimants currently select the alphabetically first scope silently. A compile-time ambiguity guard would make plugin composition safer.

[apackeer]

Addressed both review findings at head 8b799f76:

1. Explicit invalid AWS_AIDLC_DEFAULT_SCOPE values still fail validation. Bundle-aware fallback applies only when the caller's internal core default (feature or poc) is disabled or absent; it does not turn an unknown environment value into a valid plugin default.
2. docs/harness-engineering/04-scopes.md now documents freeform_default, its selection precedence, and the requirement that at most one enabled scope nominate itself.

I also closed the non-blocking ambiguity case: graph compilation now rejects multiple enabled freeform_default: true claimants and names them instead of silently choosing alphabetically.

Regression coverage pins explicit-env typo rejection, nominated fallback selection, and multiple-claimant rejection. The reported contract, smoke/unit, changelog, and package-parity checks are green. The branch now needs a rebase and version-slot refresh against current v2 before re-review.

[apackeer]

Rebased onto the current v2 branch and force-pushed with lease. The release metadata is now consistently 2.5.30 across the changelog, README badge, authored version source, generated distributions, commit headline, and PR title (2.5.27 is reserved by #646, 2.5.28 by #664, and 2.5.29 by #661).

Validation completed locally:

• bash tests/run-tests.sh --smoke --unit: 181 files, 4,457 assertions, 0 failures
• bun run check: package parity, all TypeScript configs, and Biome passed
• git diff --check passed

@leandrodamascena, rereview requested.

[leandrodamascena]

Thanks for addressing the review findings thoroughly. I rechecked the updated head and confirmed:

• Unknown AWS_AIDLC_DEFAULT_SCOPE values fail with the canonical validation error.
• Installed-but-disabled scope names still use the intended plugin fallback.
• freeform_default is documented across the scope and plugin-authoring references.
• Multiple enabled nominations are rejected during graph compilation.

The focused tests, package parity, typecheck, lint, and local merge validation all pass. No remaining findings from my review.