Plan: Skill Activation Boundaries

Initial Situation

Issue #206 reports over-broad model discovery for React Doctor, TDD, and Verify Behavior, plus React Doctor changed-scope commands that rely on an unrelated inferred base. The accepted spec is retained at Harness commit 3e7d3836c4e54917ecf13debb2f93e01fe8d982d.

architecture_applicability: local: the work changes discovery metadata and command guidance at existing skill seams. It does not move owners, add composition, or create cross-domain dependencies.

Decision Ledger

• Locked: reusable skills are authored only in /home/stefan/repos/skills on main, committed, pushed, then synchronized into Harness.
• Locked: React Doctor automatic discovery is React-runtime-specific or explicit.
• Locked: changed scans resolve and pass the checked-out branch's configured upstream as --base.
• Locked: TDD discovery requires explicit TDD/test-first/RED-GREEN intent or unresolved behavior design.
• Locked: Verify Behavior is selected by deliberate Debugging Phase or Implement Spec orchestration, not direct top-level automatic discovery.
• Locked: #206 remains stacked on the final #205 branch head; Astra is excluded.
• Parked: Linear delivery projection. Exact readback found no existing #206 item and no fitting active CLI V* milestone; V4.3 is complete and V4.4 is historical with no assigned issues. Provider mutation was zero.

Solution Shape

Treat installed skill frontmatter and documented command examples as the public interface. Protect that interface with one focused source-repository contract test, make the smallest agent-guidance edits under Writing for Agents, publish the authoritative source commit, then synchronize and document the resulting Harness baseline delta.

Dependency and Wave Graph

Wave 1: T1 authoritative shared-skill RED/GREEN
           |
           v
Wave 2: T2 Harness synchronization, docs, release evidence

Each wave has one task because T2 requires the immutable pushed source commit produced by T1.

Tasks

T1: Tighten authoritative skill activation contracts

• depends_on: []
• location: /home/stefan/repos/skills
• owned_paths: skills/frameworks/react/react-doctor/**, skills/agnostic/quality/tdd/SKILL.md, skills/agnostic/planning/verify-behavior/SKILL.md, skills/phases/debugging-phase/SKILL.md, skills/agnostic/planning/implement-spec/SKILL.md, tests/skill-activation-boundaries.contract.test.mjs, and tests/verify-behavior.contract.test.mjs
• wave_boundary: wave-1-authoritative-source
• description: On exact branch main, preserve unrelated dirty files; add a focused contract test, capture RED, edit skill metadata/body with Writing for Agents, capture GREEN, run affected source tests, commit only owned files with a conventional commit, push, and report the exact source SHA.
• validation: node --test tests/skill-activation-boundaries.contract.test.mjs tests/verify-behavior.contract.test.mjs; node --test tests/*.test.mjs; git diff --check.
• status: Completed
• log: RED-first contract added by non-Astra worker; focused GREEN passed 7/7. Review repair 1 made every changed-scan command self-contained. Comment repair preserved orchestrator reachability, added the Codex implicit-invocation boundary, and published immutable shared source tag sync/issue-206-skill-activation-boundaries-cc04228 at cc042289af6ffa19775ef253f08fcc9404892651.
• files edited/created: React Doctor skill/reference, TDD skill, Verify Behavior skill, tests/skill-activation-boundaries.contract.test.mjs, and tests/verify-behavior.contract.test.mjs in wearedevpunks/skills.
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: Configured Linear CLI project has no fitting active V* milestone and no existing #206 placement; Write Backlog returned zero mutations.
• assigned_skills: writing-for-agents, tdd, codebase-design
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Keep trigger pointers branch-complete and concise; co-locate command resolution guidance and avoid duplicated meaning.
  • skill: tdd applicable_behavior: Add one public skill-contract test first and record its real failing assertions before editing skill guidance.
  • skill: codebase-design applicable_behavior: Treat frontmatter discovery and explicit caller text as the stable public seam; keep policy local to each owning skill.
• tdd_status: required
• tdd_target: Installed skill contracts reject broad discovery triggers, require explicit React Doctor base selection, and retain only deliberate Verify Behavior caller routes.
• red_command: node --test tests/skill-activation-boundaries.contract.test.mjs
• expected_red_failure: Pre-fix React Doctor and TDD metadata contain broad feature/bugfix triggers, changed-scope commands omit explicit upstream --base, and Verify Behavior remains directly model-discoverable.
• green_command: node --test tests/skill-activation-boundaries.contract.test.mjs tests/verify-behavior.contract.test.mjs
• reason_not_testable:
• red_evidence: Test-only state was observed before skill edits; expected failures covered broad React Doctor/TDD metadata, missing explicit base, and model-discoverable Verify Behavior.
• green_evidence: The original focused suite passed 7/7 at source commit e780042. After comment repair, the two focused contracts passed 8/8 and the expanded verifier set passed 16/16 at source commit cc042289af6ffa19775ef253f08fcc9404892651.
• codebase_design_notes: No new abstraction. Frontmatter is the discovery seam; Debugging Phase and Implement Spec are orchestration adapters.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: Agent-consumed static contracts are exercised by source tests.
• runtime_evidence:
• runtime_cleanup: none

T2: Synchronize and retain Harness distribution evidence

• depends_on: [T1]
• location: /home/stefan/.codex/worktrees/d58c/harness-intelligence
• owned_paths: apps/cli/scripts/sync-skills-repo.mjs, apps/cli/src/scripts/sync-skills-repo.test.ts, generated apps/cli/skills/** changes from bun run sync:skills, local synchronization receipt, BASELINE_CHANGELOG.md, docs/README.md, docs/runbooks/hi-cli-scaffolding.md, this spec folder
• wave_boundary: wave-2-harness-distribution
• description: Run the repository sync from T1's pushed SHA, verify the exact receipt, document the activation/base-selection behavior, add reviewed Unreleased baseline notes, run affected Harness checks and release classification, and update durable implementation notes.
• validation: focused apps/cli/src/scripts/sync-skills-repo.test.ts; bun run sync:skills; exact receipt SHA equals T1; diff -qr /home/stefan/repos/skills/skills apps/cli/skills; bun run release:classify -- --base team/stefan/issue-205-effect-backend-structure --head HEAD; git diff --check.
• status: Completed
• log: Harness defaults to immutable source tag sync/issue-206-skill-activation-boundaries-cc04228 at cc042289af6ffa19775ef253f08fcc9404892651; bun run sync:skills passed; receipt and byte-for-byte mirror comparison passed; focused pin test passed 1/1. Release classification passed from a workspace-local temporary directory with releaseKind: baseline and no classification error.
• files edited/created: canonical pin/test, generated apps/cli/skills/** delta, baseline changelog, docs/README.md, and docs/runbooks/hi-cli-scaffolding.md.
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: Configured Linear CLI project has no fitting active V* milestone and no existing #206 placement; Write Backlog returned zero mutations.
• assigned_skills: writing-for-agents, tdd, codebase-design
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Verify generated agent guidance preserves the authoritative trigger and command contracts exactly.
  • skill: tdd applicable_behavior: Reuse T1 RED/GREEN evidence; generated-only synchronization is not a second behavior implementation.
  • skill: codebase-design applicable_behavior: Verify the synchronized distribution keeps one authoritative source and identical consumer seams.
• tdd_status: not_applicable
• tdd_target: Generated synchronization and release bookkeeping preserve T1's already-proven public contract.
• red_command:
• expected_red_failure:
• green_command: focused Harness skill checks selected from synchronized paths
• reason_not_testable: Generated-code, documentation, and release-bookkeeping task; behavior RED/GREEN belongs to T1.
• red_evidence:
• green_evidence: Focused Harness pin test passed 1/1; source receipt equals cc042289af6ffa19775ef253f08fcc9404892651; the cached immutable-tag source and distributed mirror are byte-identical; wiki projection checks pass; release classification passed as baseline-only against the #205 base.
• codebase_design_notes: The sync boundary is an adapter from shared authoritative skill source to Harness consumers; no consumer-side policy edits.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: Static agent guidance and generated receipt, with no application runtime surface.
• runtime_evidence:
• runtime_cleanup: none

Testing Strategy

T1 runs one vertical RED/GREEN contract through the installed skill text seam, followed by the existing Verify Behavior caller contract. T2 proves source-to-consumer identity and baseline-only release classification. No browser verification applies.

Risks and Mitigations

• Concurrent #205 work changes the shared source or stack parent: re-read skills/main, preserve unrelated files, and rebase #206 onto #205's final published head before PR creation.
• Existing Verify Behavior tests assert model invocation: update the superseded assertion in the same RED/GREEN slice while retaining explicit caller checks.
• Broad Harness gates may expose pre-existing failures: run focused checks, retain exact unrelated output, and do not expand scope.
• Sync may pull unrelated source commits from concurrent stack work: verify receipt and classify every generated delta before committing.

Research and Review

Readonly source inspection covered the three discovery seams, both explicit Verify Behavior callers, existing contract tests, repository sync ownership, and current Linear placement. No external library behavior is involved. A non-Astra planning-discovery worker confirmed the graph, the explicit-caller interpretation of discovery-disabled Verify Behavior, the Harness pin files, and the generated mirror boundary.

Unresolved Questions

None blocking. A future product-planning run may establish a new CLI V* milestone and project this planning-only graph without changing implementation identity.