[JSdotNet]

Closes #763

Summary

Finishes item 4, the last open part of #763 (items 1–3 are on main as 0db704f). 4a: deletes the five vendored Aspire skills under .agents/skills/aspire* (4,002 lines from aspire agent init on 2026-08-05, pinned to Aspire 13.4 while the repository is on 13.6.1, linking files that do not exist, loaded by no wrapper) and repoints run-backlog/SKILL.md at aspire <command> --help and the Aspire MCP docs tools. A new AgentContextPointerTests fact requires every .agents/skills entry to have a .claude/skills wrapper naming its path. 4b: the multi-account design doc was built in PR #493, so what it decided — per-call account resolution, never storing a gh token, the rejected alternatives (gh auth switch, GH_TOKEN injection, dropping GhCliTransport) — becomes proposed local ADR 0031, and .claude/design/ is deleted. tech/ai-development.md and technology-graph.md drop their Aspire-skills mentions. No file under src/ changes.

Decision taken without asking (follow it, or ask for the alternative)

Question. Item 4: should the five vendored Aspire skills under .agents/skills/aspire* be wrapped or deleted, and should .claude/design/multi-account-settings.md move into .devbook/arc42/ or be deleted?

Chosen. 4a: delete all five vendored Aspire skills, the whole 4002-line set, and repoint run-backlog/SKILL.md:28 to aspire --help and the Aspire MCP docs tools. Add an AgentContextPointerTests fact that every .agents/skills entry has a .claude/skills wrapper. 4b: write what the design doc decided into a new local ADR 0031 (status: proposed, built in PR #493), list it in adr/README.md and 09-architecture-decisions.md, and delete the design doc and the .claude/design/ folder.

Alternative. 4a: keep the five skills and give each a .claude/skills/aspire*/SKILL.md wrapper and a .github/skills wrapper. Name them in context-loading.md and CLAUDE.md as vendored output of aspire agent init, never hand-edited, and refresh them by re-running it. 4b: delete the design doc outright with no ADR, relying on git history, ADR 0021 and tech/desktop.md#github-cli.

Why the choice. The vendored set is the same kind of stale pointer this issue exists to remove. It is pinned to Aspire 13.4 while Directory.Packages.props is on 13.6.1. It links to aspireify and three reference files that are not in the repository. No commit has touched it since aspire agent init on 2026-08-05. No flow or wrapper loads it. The Aspire MCP server is bound in .mcp.json, and csharp-coding:aspire in the stack covers the same CLI guidance against the live version. Wrapping it would put five long descriptions into every session's skill list. It would also commit the repository to keeping 4000 lines of third-party text current. The repository-specific rules (--isolated, never trust the exit code, scoped stop) already live in run-backlog/SKILL.md. For the design doc: it was still amended on 2026-10-13 to record a security-relevant reversal, the borrowed gh token. It holds rejected alternatives that no devbook chapter holds: gh auth switch, GH_TOKEN injection, and dropping GhCliTransport. Deleting it outright would lose the reasons a future change needs, and keeping it in .claude/ leaves an unaddressed orphan that still says 'ready to implement'. Under devbook-arc42.md a decision lives in arc42/adr/, so a short ADR is the home for it. ADR 0021 and tech/desktop.md already hold the sync and mechanism halves, so the new ADR records only the rest.

To follow the alternative instead. For 4a, the alternative restores .agents/skills/aspire* with git revert or aspire agent init. It adds five .claude/skills and five .github/skills wrappers, reverts the run-backlog line and the two tech chapter edits, and changes the new test from 'none unwrapped' to 'all five wrapped and named in context-loading.md'. For 4b, it drops ADR 0031 and its two index entries and keeps only the deletion of .claude/design/.

Acceptance criteria

• 1. No .agents/skills/aspire* directory exists — test: AgentContextPointerTests.Every_agents_skill_has_a_claude_skills_wrapper_that_names_its_path (fails for any unwrapped skill folder, so it catches a reintroduced vendored folder) plus No_context_file_or_devbook_chapter_names_a_retired_pointer("skills/aspire") (the vendored files contained that string)
• 2. No context, .github or devbook file contains skills/aspire or 'Aspire skills'; run-backlog names aspire <command> --help and the Aspire MCP docs tools — test: AgentContextPointerTests.No_context_file_or_devbook_chapter_names_a_retired_pointer("skills/aspire" and "Aspire skills") and AgentContextPointerTests.The_run_procedure_points_at_the_aspire_cli_help_and_the_mcp_docs_tools
• 3. Every .agents/skills entry has a .claude/skills//SKILL.md wrapper naming its path, enforced by a new fact — test: AgentContextPointerTests.Every_agents_skill_has_a_claude_skills_wrapper_that_names_its_path
• 4. .claude/design/ is gone and nothing names multi-account-settings, guarded by a test case — test: AgentContextPointerTests.No_design_document_folder_sits_under_dot_claude and No_context_file_or_devbook_chapter_names_a_retired_pointer("multi-account-settings")
• 5. ADR 0031 exists with the required meta, sections and recorded content — not proved by a test: DevbookMetadataGateTests and the devbook checks prove the meta blocks are valid. No test checks the ADR's sections or what it records; that was checked by reading.
• 6. ADR 0031 is listed in adr/README.md (proposed) and in 09-architecture-decisions.md — not proved by a test: Checked by reading. The devbook checks resolve the links but do not require the entries.
• 7. The tech chapters no longer mention Aspire skills, and their meta blocks are valid — test: AgentContextPointerTests.No_context_file_or_devbook_chapter_names_a_retired_pointer("Aspire skills"); meta validity by DevbookMetadataGateTests
• 8. The three node devbook checks pass — not proved by a test: Run by hand: all three exit 0, and the advisory count is 429, unchanged from HEAD. DevbookMetadataGateTests and DevbookBuilderParityTests partly cover the same ground in the test suite.
• 9. dotnet test reports AgentContextPointerTests and DevbookMetadataGateTests green with a non-zero count, and DevbookBuilderParityTests stays green — test: AgentContextPointerTests + DevbookMetadataGateTests: 20 of 20 passed; DevbookBuilderParityTests: 3 of 3 passed
• 10. No file under src/ changes — not proved by a test: Checked with git diff (0 files under src/). This is a property of the diff, not something a test checks.

Testing

• Command: cd "D:/iswp/763-vendored-skills-and-design-doc" && dotnet build Backlog.WithoutAppHeads.slnf --configuration Release -p:TreatWarningsAsErrors=true && dotnet test --solution Backlog.WithoutAppHeads.slnf --no-build --configuration Release --max-parallel-test-modules 1 --parallel none --results-directory <scratchpad>/tr763 ; plus node .devbook/_tools/devbook-meta/build.mjs --check ; node tools/devbook/check-metadata.mjs ; node tools/devbook/build-database.mjs --check
• Passed 16254, failed 0; repair attempts 0.
• Owner session, after the review fixes: After the ADR fix, both devbook checks pass (build.mjs --check; check-metadata.mjs: 0 blocking).

Review

• Fixed in the owner session: major — ADR 0031 said every path other than repos/, orgs/ and users/ takes the default account, but GitHubSettings.ChoiceForSearch routes a search/ call by its q= qualifier (repo: as that repository, org:/user: as the owner's shared binding). The flowchart and §1 now record that rule.
• Left open, minor (tests/Backlog.ArchitectureTests/AgentContextPointerTests.cs:171): The new theory No_context_file_or_devbook_chapter_names_a_retired_pointer copies the body of the existing No_agent_context_file_names_a_known_dead_pointer theory (the scan, the Contains check, the relative-path projection and the assert message) and only widens the file set. The class now has two retired-pointer lists, and each scans a different set of files. Failure scenario: someone writes orch-context or pr-jsdotnet back into a .devbook chapter or a .github instruction file. The older theory scans only the agent context files, so nothing catches it, while multi-account-settings in the same place does fail. The next person to retire a pointer also has to pick one of two homes with different coverage.

What could not be proved

• ADR 0031's content was checked by reading against GitHubSettings.AccountForPath; no test checks what an ADR records. It is proposed although PR Read Claude and GitHub usage from several accounts #493 already built it — accepting it is yours.
• Deleting the vendored skills is reversible but aspire agent init would re-vendor them; the new wrapper fact then fails until each gets a wrapper, which is the intended guard.

Merge Danger

Door. Two-way: a revert restores the skills and the design doc. No code, data or setting changes.

Blast radius. local — agent context (the run-backlog procedure and the skill list) and the arc42 decision records.

Assumptions taken instead of asking

• Assumed the ADR number is 0031, since the owner says draft PRs feat(devbook): render Archify artifacts on demand instead of committing them #1294 and feat(security): seal stored third-party credentials with DPAPI #1295 claim 0029 and 0030. If either of those is abandoned, the number is unaffected because records are never renumbered.
• Assumed the new ADR is marked status: proposed even though PR Read Claude and GitHub usage from several accounts #493 already built the decision, as the run policy requires. Its Status section says it was built in PR Read Claude and GitHub usage from several accounts #493 and awaits the owner's acceptance.
• Assumed .agents/skills/aspire/rules/ and .agents/skills/aspire/skills/ are untracked or empty: find -type f shows no files in them. They go with the folder.
• Assumed the .devbook/ edits (ADR 0031, both index entries, the two tech chapters) ride in the same pull request as the flow-code change, as the run brief directs, rather than in a separate flow-spec PR.
• Assumed nothing in the product's instruction-discovery code or its tests (InstructionSourceDiscoveryTests) depends on this repository's own .agents/skills/aspire*. A grep of *.cs found no reference.
• The wrapper rule is strict: an .agents/skills procedure named X must have .claude/skills/X/SKILL.md, and that wrapper must contain the procedure's path (.agents/skills/X.md or .agents/skills/X/). The run-backlog wrapper wraps no .agents procedure, so the rule does not apply to it.
• ADR 0031 does not name the deleted design doc's filename. Criterion 4 forbids multi-account-settings in any devbook chapter, so the ADR calls it 'an implementation design document' and points to PR Read Claude and GitHub usage from several accounts #493 and git history.
• ADR 0031 follows this repository's numbered local ADR convention and the shape of ADR 0028 (a Status section, and status: proposed in the meta). It does not follow the per-concern, unnumbered record shape in devbook-arc42.md, because every local ADR here is numbered and the task names 0031. The section is titled 'Considered options' rather than the repository's usual 'Rejected', as the acceptance criteria ask.
• The design's §7b, reading several session folders on one machine, was never built: LocalAgentSessionSource still reads the two default folders. ADR 0031 records the boundary (session folders are never kept in claude.json) and says plainly that the multi-folder part is decided but not built.
• On the Consequences point about repositories under one owner bound to different accounts, the ADR says only that whether Settings should warn was left open. I did not verify whether the current Settings UI warns.
• The ModuleAssemblyReferenceTests failure in the full architecture run was treated as environmental. It reports that the module assemblies are not built (Debug, net10.0) in this worktree, and this change touches no code.

---

Opened as a draft by an attended run of delivery-schedule:schedule-issue-sweep (2026-10-15), told by the owner to decide without asking and to name the choice and the alternative.

🤖 Generated with Claude Code