Scoped Agent Guidance Authoring Contract Implementation Notes

Current Status

Implementation and distribution are complete. npm @punks/cli@3.1.11, git tag and GitHub release v3.1.11, and baseline/stable/2026.08.11-scoped-agent-guidance were published from 2b78de4abfc30eea4306ce033bf0c60d6658866d. Registry, release-asset, stable authority, compatibility, and isolated installed-consumer readbacks prove AC-016, so the spec is Implemented.

Implemented Surfaces

• The docs/workspace prompt renderer now requires structure-first local coding standards derived from production code, passing tests, schemas, configuration, manifests, and behavior-enforcing generators or scripts. It records conflict precedence and omits unresolved patterns instead of inventing a convention.
• Universal rules stay inline. Conditional rules require recognizable task triggers, exact relative links, and scope-owned Markdown authored in the same continuation. The contract creates no deeper AGENTS.md files and does not add disclosed references to specialist guidanceFiles.
• Every selected non-phase scoped skill receives one Skill | What / when row derived from its complete installed SKILL.md. Generated specialist guidance consumes that table instead of the former flat primary-skills line.
• create-plan selects exact matching What / when rows across every touched scope and loads each selected skill's complete installed SKILL.md before planning.
• opensrc/README.md is emitted and managed even when no package-specific source guide is selected. Every final scoped prompt links the index with a third-party-library trigger.
• Root/shared prompt contracts and existing project-authored nested prompts retain their previous ownership.
• The canonical shared hi-cli Scaffold guidance was changed source-first in wearedevpunks/skills at a035487d4f48fdcb9dbd19cb29b58d108b8bf4c4, then the exact intended guidance bytes were synchronized into the bundled CLI skill.
• Root and private wiki scaffold documentation now describe the shipped authoring contract and Source Guide behavior.

Validation Evidence

Deviations and Decisions

• A baseline-only release cannot distribute the executable renderer change, so the package advances from the already-published 3.1.10 to 3.1.11 before the compatible stable baseline.
• The shared-skill repository's current main branch contained unrelated skill drift relative to the Harness-pinned lineage. The hi-cli edit was based on that pinned lineage, tested there, and synchronized without importing the unrelated changes.
• Documentation remains discovery context only. Normative scoped conventions come from current code evidence, matching the accepted requirements.
• Protected validation exposed release-policy inventory drift after main advanced. The repair changed only the stale expectations; focused policy tests now match the exact baseline, protected, and collected title counts. The later protected main run exposed two temporary test-harness file races after 995 passing ordinary tests. The user explicitly waived the test portion of release publication; build and package-integrity verification remained in force.
• The first baseline publish attempt inherited a restricted GH_TOKEN from the production environment and stopped at GitHub release creation with HTTP 403. The idempotent retry removed only GitHub token overrides, used the authenticated gh keychain, uploaded both assets, and committed stable revision 24.

Release Proof

1. npm package: @punks/cli@3.1.11; latest=3.1.11; next=3.1.11.
2. Executable release: v3.1.11 at 2b78de4abfc30eea4306ce033bf0c60d6658866d.
3. Stable baseline: baseline/stable/2026.08.11-scoped-agent-guidance at the same commit, authority revision 24, compatibility >=3.1.11 <4.
4. Published package and baseline readbacks are complete. No release mutation remains.