docs(north-star): promise the trash, core debug details, and tool credit only when a command needs them #447

Outside the plan: Pascal assigned this card on 2026-11-03, through the grooming of Epic 16. Its pull request says that it is outside the plan.

Problem

The principles promise features that core does not give:

• Principle 4 in docs/north-star/principles.md says: "Deleted files go to the OS trash." No user command deletes a file today. The rule index marks P09 "Prose only".
• docs/north-star/contract/global-flags.md line 15 says that NCLY_DEBUG=1 adds internals, timings, and child commands. In core, no code reads it. Only transcript uses it (extensions/transcript/python/transcript.py lines 61-64, protocol.go line 104).
• global-flags.md line 13 says that --verbose adds step details on stderr. Core passes the flag to extensions, but ncly -v doctor core writes no line on stderr.
• Principle 10 says that the help of a wrapping command names the tool. The rule index marks P24 "Prose only".

Goal

Each of these texts promises only what the code does. Each feature comes when a command needs it, through the SDK.

Pascal chose this on 2026-11-03 (option 2a).

Acceptance rules

1. The pull request adds three ideas with the next free 6xx IDs (COR-629, COR-630, and COR-631 at 318978e). Each idea gives its revisit condition:
   • OS trash through the SDK: the first command that deletes a user file
   • Debug and verbose details from core: the first core command that needs them
   • Tool credit in the help of sdk/wrap (sdk/wrap/wrap.go): the next wrapping command
2. Principle 4 says that the first command that deletes a user file sends it to the OS trash, through the SDK. It links the trash idea.
3. global-flags.md says that core adds no details today, and that an extension adds details when it needs them. It keeps what transcript does, and links the debug idea.
4. Principle 10 says that the help of a wrapping command names the tool once sdk/wrap supports it. It links the credit idea.
5. In the rule index, the rows P09 and P24 give their condition and link their idea.
6. No code changes.

Examples

• Success: a reader of principles.md cannot expect a trash that no command uses.
• Failure: a text still says "Deleted files go to the OS trash" with no condition.

Check

just check passes, with the rule index checks. The texts above no longer promise the features without a condition.

by Opus-5.5 via Claude Code