diff --git a/docs/install/models-and-effort.md b/docs/install/models-and-effort.md index 3e905bb15..3ae2fb528 100644 --- a/docs/install/models-and-effort.md +++ b/docs/install/models-and-effort.md @@ -21,6 +21,9 @@ change to be: a quick stub or a small revise needs little, while a net-new design, a cross-cutting change, or a stub whose premise needs tracing through the code is worth your strongest model at higher effort. +`docket-export` also runs inline at your session's model and effort; it runs one export and needs +no particular model. + To change the model or effort an autonomous skill runs at: **1. Edit your global config.** Pins live in the `agents:` block of your global @@ -103,7 +106,8 @@ are forked — a forked subagent has no channel to the human (Claude Code withho the two interactive brainstorm skills (`docket-new-change`, `docket-groom-next`) and `docket-finalize-change` (which keeps a real prompt — the multi-candidate batch confirmation — so a headless drive is authorized by -[naming ids](../guide/landing-changes.md) instead) do not. +[naming ids](../guide/landing-changes.md) instead) do not, and neither does `docket-export`, which +posts through your session's own tools and may ask you before a private-repository post. **The two invocation paths.** **Dispatch** — launching a named agent to do a step and waiting for it to return — is one way to reach a pinned wrapper; a plain skill-invoke, forked, is the other. Both diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 121b1f840..15b303b9d 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -47,8 +47,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th - **`docket open`** — open the board, or a change's record, spec, plan, results, or pull request, as a GitHub page or from the local metadata checkout. Without an id it opens the change whose branch is checked out. With `--export` it writes a clean Markdown copy of a change, spec, plan, - or results file, free of docket's links and generated blocks, and opens that copy. Details: - `docket open --help`. + or results file, free of docket's links and generated blocks, and opens that copy. Agent + sessions reach the export through the `docket-export` skill. Details: `docket open --help`. - **`docket pr`** — publish the ready-for-review pull request for an in-progress change's tested head. Verbs: `docket pr --help`. - **`docket repository`** — initialize, migrate, check, and repair the docket repository diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 78e0da3b7..36fcff5f7 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1750,6 +1750,16 @@ selection, the bootstrap guard, and the branch model. writes, or git operations, and it is injected into most generated wrappers rather than run as an agent. +### docket-export + +The skill an agent session uses to hand a change, spec, plan, or results file to anything outside +docket. It runs the `open` operation's export (`--export --print --json`) and passes the clean copy +to a file or another tool, never the raw file. In a private repository it also rewrites what the +export leaves that names docket, checks the result, and shows you before → after before posting. + +**Used for:** putting a spec or other artifact into a ticket, document, or message from an agent +session. It runs inline, because it posts with your session's own tools and may ask you first. + ### docket-finalize-change The close-out sequencer for an approved or merged PR. It retargets stacked children, rebases, @@ -1828,8 +1838,8 @@ Only skills that never need the human mid-run are forked, because a forked subag back to the human. The forked skills are `docket-status`, `docket-adr`, `docket-implement-next`, and `docket-auto-groom` (`context: fork` + `agent:` frontmatter). -**Used for:** explaining why `docket-new-change`, `docket-groom-next`, and `docket-finalize-change` -run inline. A headless finalize is authorized by naming ids instead. +**Used for:** explaining why `docket-new-change`, `docket-groom-next`, `docket-export`, and +`docket-finalize-change` run inline. A headless finalize is authorized by naming ids instead. ### Harness @@ -1853,6 +1863,8 @@ every harness. It is program data, not user config, and each harness block is co abort-and-report rule: implement-next, auto-groom, finalize-change, status, adr, build-task, and review. **Interactive** skills (`docket-new-change`, `docket-groom-next`) stay inline at the session model, because the conversation with you is the point. They only advise a model at startup. +`docket-export` also stays inline, because it posts with your session's own tools and may ask you +first. **Used for:** knowing which skills you can dispatch and walk away from, and which need you at the keyboard. @@ -2357,6 +2369,7 @@ docket development install --source ~/dev/docket - [docket-build](#docket-build) - [docket-build-task](#docket-build-task) - [docket-convention](#docket-convention) +- [docket-export](#docket-export) - [docket-finalize-change](#docket-finalize-change) - [docket-groom-next](#docket-groom-next) - [docket-new-change](#docket-new-change) diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index c0a2d2219..cd9291ad3 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -18,6 +18,7 @@ Each line names one skill directory under `skills/` and its job. - **docket-build** — the build role: route each plan task to a tier worker and run one full-suite gate at the end. - **docket-build-task** — the per-task worker contract: one plan task from focused test through one commit. - **docket-convention** — the shared contract: config, layout, manifest and ADR format, lifecycle, branch model (pure reference). +- **docket-export** — export a change, spec, plan, or results file through docket's own export, or put one into another tool; in a private repository it also rewrites docket references out and shows you before posting. - **docket-finalize-change** — close a change out: merge if approved, verify, archive, clean up, refresh the board. - **docket-groom-next** — groom the next needs-grooming change to build-ready through an interactive brainstorm. - **docket-implement-next** — implement the next build-ready change end to end to an open PR with no human interaction. diff --git a/docs/superpowers/specs/2026-10-22-invoke-the-artifact-export-from-an-agent-session-design.md b/docs/superpowers/specs/2026-10-22-invoke-the-artifact-export-from-an-agent-session-design.md new file mode 100644 index 000000000..a2ce353da --- /dev/null +++ b/docs/superpowers/specs/2026-10-22-invoke-the-artifact-export-from-an-agent-session-design.md @@ -0,0 +1,87 @@ +# Invoke the artifact export from an agent session — design + +Change 0578 — Invoke the artifact export from an agent session + +Change #578, groomed 2026-10-22. + +## Problem + +#561 added `docket open [] --export`, which writes a clean Markdown copy of a docket artifact for readers who do not use docket. Only a person typing the command in a shell reaches it. When an agent is asked to export one of these artifacts, or to put one into another tool — for example, add a spec as a comment on, or the body of, an existing Jira ticket through an MCP integration — nothing tells it the command exists, or that docket content needs cleaning before it leaves the repository at all. Daniel has seen this on another machine more than once: the agent never used the export, did not know the content needed sanitizing, and the result still carried everything the export removes. + +The export itself is complete. The capability catalog's `open` entry already lists `--export`, `--output-path`, `--print`, and `--warnings`; `--print` writes the copy without launching a viewer; `--json` returns the written path and the warnings as fields. What is missing is (1) anything that makes an agent find it, and (2) for a private repository, a way past what the export deliberately leaves: it never rewrites prose, so a sentence that names docket stays as written (reported as a mention), as do ADR numbers and bare `#N`. In a private repository the team must never see docket, and a post to an outside tool cannot be taken back; the PR leak check does not run on exports. + +## Goal + +An agent session that is asked to export a docket change, spec, plan, or results file, or to put one anywhere outside docket, runs the real export — the same code the CLI runs — and never builds its own copy. In a private repository, what leaves contains no trace of docket. + +## Non-goals and anti-goals + +- **No change to the export.** `docket open --export`, its output, its flags, and its catalog entry stay as they are. No new catalog entry or command. +- **No agent** (my call). A dispatched agent would start a fresh context for one command, and the dispatch rule in the managed instructions block would then route every export request through it. The skill must also run where the person's posting tools are and must be able to ask the person. +- **No sending logic.** The skill never posts anything itself and carries nothing specific to Jira or any other tool. Posting is done by the agent's own tools (an MCP integration, for example). +- **Not in `docket-convention`** (Daniel agreed). The convention is read only after something loads it, and an export request loads nothing; making its description match "export" would pull about 52 KB into context for one command, and the convention is declared pure reference (no procedure). +- **Not in the always-loaded instructions block.** Every session would pay for it, and that block is about dispatching agents and the run tracker. +- **No `docket --help` change** (my call). +- **No rewrite pass in a shared repository** (Daniel's decision). There the team can already see docket on the metadata branch, and in docket's own repository the word is the subject. +- **Anti-goal: the agent redoing the export's work by hand,** or reworking words beyond the private-repository rewrite pass below. + +## The skill: `docket-export` + +A new skill directory, `skills/docket-export/`, holding one `SKILL.md`. + +- **Inline.** Frontmatter carries `name` and `description` only — no `context: fork`, no `agent:`. It runs in the requesting agent's own context because it must reach that agent's tools (the MCP integration that posts) and must be able to ask the person; a forked skill can do neither. No generated agent wrapper and no Cursor dispatch rule. +- **No convention load** (my call, for size). The skill resolves what it runs itself: `docket capabilities --json` (the one docket spelling a skill may hard-code), check `protocol_version` is 1, and take the `argv` of the entries it uses (`open`, `repository.prepare`, and `diagnostic.config` if the builder reads `leak_check.match_word` from it). If the `docket` binary is missing or an entry is absent, the agent says the docket install is broken and stops — never a hand-made export. +- **Distributed body.** Skills install at user level, so the skill is present in every session on the machine, in repositories that use docket and ones that do not. Its body states nothing true only of this repository. + +### The description (what makes an agent find it) + +It must match both kinds of request: exporting a docket change, spec, plan, or results file, and putting one into anything outside docket (a ticket or comment in another tool, a document, a message, an email). Approximate wording, final wording the builder's: "Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a Jira ticket body or comment, a document, a message — so its content comes from docket's own export, never the raw file or a hand cleanup." + +### What the skill tells the agent + +1. **Never build an export by hand, and never send the raw file.** +2. **Learn the repository's visibility** from the `repository.prepare` context (`visibility`: `shared` or `private`). The export runs the same prepare internally, so this adds no new side effect. + - The directory is not a docket repository (not a git repository, or no docket set up — a fresh repository): the skill does not apply. The agent says the content is not a docket artifact in one line and handles the request without the skill (my call). + - Any other refusal, so visibility is unknown: treat the repository as private (my call — a leak cannot be undone, and this keeps the export usable while the metadata checkout needs attention). +3. **Run the export:** ` [] --export --print --json`, where `` is `change`, `spec`, `plan`, or `results` and `` is the change the person named (omitted, `open` uses the checked-out change, as it does today). Always `--print`, so no viewer opens — the person may not be at the screen; they can ask the agent to open the file. Always `--json`. Never `--warnings` unless the person asked for a filter on a file request; the default (`all`) is what the rewrite pass reads. + - **File request** ("export the spec for 9"): the export's default destination (`~/Downloads` on macOS, the home directory on Linux), or `--output-path` when the person names a place. + - **Outside-tool request** ("add the spec for 9 as a comment on PROJ-123"): `--output-path` set to a fresh temporary directory (`mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`), so the person's Downloads folder does not collect one file per post. The temporary file stays where it is (my call); its path is reported so the person can see exactly what went out. +4. **Failure** — `result` is anything other than `applied`, or there is no `exported_path` (for example `invalid-state` / `artifact-unset` when the change has no spec yet): tell the person the `message` and post nothing. Never fall back to the raw file or a hand cleanup (Daniel's decision). This holds in both kinds of repository. +5. **Shared repository** (Daniel's decision): no rewrite pass and no approval step. Hand the exported text to the target unchanged — on a file request, the file is the result. Any `leftovers` (rare) go out as they are and are named in the report afterwards. +6. **Private repository — rewrite pass, automatic** (Daniel's decision). When the export reported any `leftovers` or `mentions`, the agent edits the exported copy in place so that nothing the convention's private-repository writing rule bans remains, and every edited line reads naturally to an outside reader: + - fix each leftover (remove the marker, unwrap the link, drop the stamp line, …); + - rewrite each line on the `mentions` list so it no longer names docket or dckt (for example "the docket gate runs the suite" → "the test gate runs the suite"); a mention inside code is generalized or dropped, at the agent's judgment; + - rewrite docket's own ADR numbers (ADRs in the repository's docket ADR ledger) and docket change numbers the export left as written (for example "per ADR-0012") into what they refer to, or drop them — the person's team cannot open them (my proposal; Daniel did not object). The team's own ADRs stay, for the reason the private leak check ignores ADR references (ADR-0144), and so does a `#N` that is not a docket change id (a Jira or PR number). How the agent tells a docket ADR from the team's own is the builder's (for example, whether the id exists in the docket ADR directory of the metadata checkout). + - `leak_check.match_word: false` (the repository lets the bare word "docket" through its leak check) also exempts the bare word here (my call — config keys behave uniformly); "dckt", markers, ids, and ADR numbers are still handled. + - Only these lines change; no other rewording, summarizing, or "fixing". +7. **Private repository — check.** Search the rewritten copy for "docket" and "dckt" as whole words, case-insensitive, code included — the same word rule as the export's `mentions` list (bare "docket" exempt under `match_word: false`). Any hit: stop, show the person the path and the lines, and post nothing until they decide. +8. **Private repository — show, then post.** If the rewrite pass changed anything, show the person every change as before → after and post only after they say go (Daniel's decision). If nothing needed rewriting, post straight away. On a file request the same pass and check apply — the file goes to outsiders too — and the before → after list comes with the path, with no stop (nothing is posted). +9. **Posting the text.** Read the file at `exported_path` (after the rewrite pass, in a private repository) and hand its text to the target tool unchanged. When the tool needs a different format (Jira's own markup, for example), convert the formatting only, never the words. When the person asks for a summary or an excerpt ("just the Goals section"), work from this copy, never the raw file (my call). When the text is too long for the target, tell the person and ask whether to split it or attach the file (my call). The skill adds no stop beyond the ones above; whatever confirmation the agent's harness already asks before an outward post is unchanged. +10. **Report back:** the path, whether an existing file was replaced (`replaced`), any warnings, and (private) the before → after list. + +Out of the skill's reach, said in one line so the agent does not improvise: the board and pull requests have no export; a person who explicitly asks for the raw file is asking for something else. + +## Docs + +- `docs/reference/skills-and-agents.md`: the Skills list gains `docket-export`. +- `docs/reference/cli.md`: the `docket open` entry gains one sentence saying agent sessions reach the export through the `docket-export` skill. +- Any other sentence that enumerates docket's skills or its inline (no-wrapper) skills — the convention's *Agent layer* paragraph ("the two **interactive** skills … stay inline") is one — includes `docket-export`; raise the convention's word budget if that needs it. Find the sites by a whole-repository grep, not from this list. + +## Tests + +- The skill is picked up from `skills/` like the others, with no hand-kept list; regenerate the embedded assets (`go generate ./internal/assets/`) and confirm with the existing install tests that it installs into every configured harness the way the other skills do. +- A new row in the per-skill size table (`skillBudgets` in `internal/repoguard/budgets_test.go`). +- Existing guards apply unchanged, notably `TestCapabilitySurface` (no hard-coded docket argv besides `docket capabilities --json`) and the shell rules for agent-executed Markdown. +- Pin the skill's load-bearing rules the way `internal/repoguard/prose_contracts_test.go` pins other skills' rules, and mutation-test each pin. At least: never build by hand or send the raw file; a failed export posts nothing; shared repositories get no rewrite pass and no stop; private repositories get the rewrite pass, the word check, and a before → after stop when anything was rewritten; unknown visibility counts as private. +- The whole suite at the gate. + +## Left to the builder + +- The exact description and body wording, within the steps above. +- How the skill reads `leak_check.match_word` (for example `diagnostic.config`'s effective value). +- Which of the skill's rules get pinned beyond the list above, and how. + +## Relations + +- Discovered from #561 (the export); builds on #542 (`docket open`). +- The private-repository rules come from #532 (ADR-0144: the private writing rule, the leak check, and `leak_check.match_word`). diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 62b5dc46d..f8df0551b 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:1420334f0532bba222a5815126a5540db849ce1ea8dfd6400ec5259f6857ee0d", + "asset_set_id": "sha256:ed92c875853423025ab9e290850a0a559ce537417838caf8b3ebd718aa90d88e", "entries": [ { "path": ".docket.example.yml", @@ -322,15 +322,15 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 52566, - "sha256": "5fd96420bb0abc33d780c58bdcc04e140e7c221ea1142e762f255811d810f234" + "size": 52586, + "sha256": "ba1892e869dff673e1f4e4248032213830d9a19fb57613cef33a3a1e9d2010f2" }, { "path": "skills/docket-convention/references/agent-layer.md", "role": "skill", "mode": 420, - "size": 14369, - "sha256": "15e5e34f2f4393344ce132bf08fbdb6abd76f1ced723ee77da594f5d9efe67cb" + "size": 14389, + "sha256": "e20ea5e319c3e8129e7976d7ee8ec56948aed358958417b117197386401f84f2" }, { "path": "skills/docket-convention/references/close-out.md", @@ -353,6 +353,13 @@ "size": 14893, "sha256": "6ee36fdb39e1fc16cf8088e3aca841c2d2b3ed49e6ec8e1e0aafaecc27bb0724" }, + { + "path": "skills/docket-export/SKILL.md", + "role": "skill", + "mode": 420, + "size": 6739, + "sha256": "a8e37531802ec220a34d5c32f07d9a142fde0f396b1f116eec7af2d3732d4d6a" + }, { "path": "skills/docket-finalize-change/SKILL.md", "role": "skill", diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 2cfc8e310..abe793e4f 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -102,7 +102,7 @@ The *Skill layer*'s **missing-skill rule** and `halt` are two conditions with tw ### Agent layer — model/effort-pinned subagents -Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`) stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). +Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`) and `docket-export` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). A wrapper is a thin installed file: it carries the resolved `model` and `effort`, when they resolve, and lists the skill and `docket-convention` in its skills list; the skill body stays the single source of behavior. Because a subagent cannot pause to ask a human, every autonomous wrapper carries an **abort-and-report** rule: an unmet precondition or blocking ambiguity is surfaced and stopped on — never turned into an interactive prompt. The Go install generates each wrapper from the compiled built-in model/effort table plus the global configuration's overrides, and installs it at user level, never per repository. A **directly-invoked** autonomous skill is still routed to its pinned wrapper by a harness dispatch mechanism, so the pin holds either way; mechanics live in [`references/agent-layer.md`](references/agent-layer.md). diff --git a/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md b/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md index d06db04b0..4a58b233c 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md +++ b/internal/assets/embedded/tree/skills/docket-convention/references/agent-layer.md @@ -196,7 +196,7 @@ four headless-safe autonomous skills (`docket-status`, `docket-adr`, `docket-imp carry `context: fork` + `agent: docket-` frontmatter in their `SKILL.md`, forking a directly-invoked skill into the same pinned wrapper — inert in every other harness. **Fork-exclusion principle:** only skills that never need the human mid-run are forked, since a forked subagent has no channel back to the human; the two interactive -skills stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills and `docket-export` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission classifier (ADR-0043). A forked skill-invoke (`/docket-status`) and an explicit agent dispatch (`@docket-status`, or a subagent dispatch diff --git a/internal/assets/embedded/tree/skills/docket-export/SKILL.md b/internal/assets/embedded/tree/skills/docket-export/SKILL.md new file mode 100644 index 000000000..2644e4433 --- /dev/null +++ b/internal/assets/embedded/tree/skills/docket-export/SKILL.md @@ -0,0 +1,60 @@ +--- +name: docket-export +description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a Jira ticket body or comment, a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. +--- + +# docket-export + +Docket artifacts carry links, generated blocks, and references that mean nothing outside docket, and the export writes a clean Markdown copy of them. Use it every time a change, spec, plan, or results file leaves docket. **Never build an export by hand, and never send the raw file.** + +This skill runs inline, in your own session: you post with your own tools, and you ask the person directly where a step below says to. + +## 1. Resolve the operations + +Run `docket capabilities --json` as its own call — the one docket spelling this skill hard-codes. Check that `protocol_version` is 1 and take the `argv` of the entries `open`, `repository.prepare`, and `diagnostic.config`. If the binary is missing or an entry is absent, tell the person their docket installation is broken and stop — never a hand-made export. + +## 2. Learn the visibility + +Run the `repository.prepare` argv with `--repo-dir --json` as its own call and read `context.visibility` (`shared` or `private`). + +- The directory is not a git repository (`result` is `invalid-input` with an empty `repository_state`), or `repository_state` is `fresh` (no docket set up): this is not a docket artifact. Say so in one line and handle the request without this skill. +- Any other refusal or error: the visibility is unknown, so **treat the repository as private**. A leak cannot be undone. + +In a private repository, also run the `diagnostic.config` argv with `--repo-dir --json` and read `effective.leak_check.match_word.value`. When it cannot be read, treat it as `true`. + +## 3. Run the export + +Run the `open` argv as ` [] --export --print --json --repo-dir `, where `` is `change`, `spec`, `plan`, or `results` and `` is the change the person named (omit it to use the change whose branch is checked out). Always `--export --print --json`: `--print` opens no viewer — the person may not be at the screen, and can ask you to open the file. Never pass `--warnings` unless the person asked for a filter on a file request; the default reports everything the private pass reads. + +- **File request** ("export the spec for 9"): the export's default destination, or `--output-path ` when the person names one. +- **Outside-tool request** ("add the spec for 9 as a comment on PROJ-123"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. + +**A failed export posts nothing.** If `result` is not `applied` or there is no `exported_path`, tell the person the `message` and stop. Never fall back to the raw file or a hand cleanup. This holds in every repository. + +## 4. Shared repository + +**A shared repository gets no rewrite pass and no stop.** Hand the exported text to the target unchanged; on a file request the file is the result. Any `leftovers` go out as they are and are named in your report. + +## 5. Private repository + +Nothing that names docket may leave. + +1. **Rewrite pass.** When the export reported any `leftovers` or `mentions`, edit the exported copy in place until it holds none of these: the words "docket" or "dckt", docket marker comments, `Docket-` trailers, `.docket` or `dckt` paths, change ids or change references from docket, ADR numbers from docket's ledger, or references to the backlog or board. Every edited line must read naturally to an outside reader. + - Fix each leftover: remove the marker, unwrap the link, drop the stamp line. A `stray-marker` leftover (it carries `source_line`, not `line`) is already gone from the copy: name it in the report, never edit for it. + - Rewrite each line on the `mentions` list so it no longer names docket or dckt ("the docket build gate runs the suite" becomes "the build gate runs the suite"). A mention inside code is generalized or dropped, at your judgment. + - When `leak_check.match_word` is `false`, the bare word "docket" may stay; "dckt", markers, ids, and ADR numbers are still handled. + - Change only these lines: no other rewording, summarizing, or fixing. + + **Always rewrite docket's ADR numbers and change numbers, whether or not the export reported `leftovers` or `mentions`** — the export never reports them, so search the whole copy on every private export. Rewrite each into what it refers to, or drop it; the person's team cannot open them. An ADR is docket's when a file for its number exists under `/`, and a `#N` is one of docket's changes when a record for that id exists under `/` (paths from the prepare context). When the prepare context is unavailable, treat every ADR number and every `#N` or four-digit change id as docket's, or ask the person. The team's own ADRs stay, and so does a `#N` that is not one of docket's changes, such as a Jira or pull request number. +2. **Word check.** Search the rewritten copy for "docket" and "dckt" as whole words, case-insensitive, code included (the bare word "docket" is exempt when `leak_check.match_word` is `false`). Any hit: stop, show the person the path and the lines, and post nothing until they decide. +3. **Show, then post.** If the rewrite pass changed anything, show the person every change as before → after and **post only after they say go**. If nothing needed rewriting, post straight away. A file request gets the same pass and check — the file goes to outsiders too — and the before → after list comes with the path, with no stop, since nothing is posted. + +## 6. Post + +Read the file at `exported_path` (after the rewrite pass, in a private repository) and hand its text to the target unchanged. When the target needs another format, such as Jira's own markup, convert the formatting only, never the words. A summary or excerpt the person asks for ("just the Goals section") is made from this copy, never the raw file. When the text is too long for the target, tell the person and ask whether to split it or attach the file. Whatever confirmation your harness already asks before an outward post is unchanged. + +## 7. Report + +Report the path, whether an existing file was replaced (`replaced`), any warnings, and, in a private repository, the before → after list. + +The board and pull requests have no export. A person who explicitly asks for the raw file is asking for something else. diff --git a/internal/harness/inventory_test.go b/internal/harness/inventory_test.go index 24069d1d2..457dab5c8 100644 --- a/internal/harness/inventory_test.go +++ b/internal/harness/inventory_test.go @@ -308,7 +308,7 @@ func TestSkillDirsFromEmbedded(t *testing.T) { t.Errorf("SkillDirs not strictly sorted at %d: %q then %q", i, got[i-1], d) } } - for _, known := range []string{"docket-build", "docket-build-task", "docket-convention"} { + for _, known := range []string{"docket-build", "docket-build-task", "docket-convention", "docket-export"} { if !want[known] { t.Fatalf("bundle no longer carries the %q skill; the fixture assumption is stale", known) } diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 730f70231..554ad1ed7 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -199,13 +199,14 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 353, 7257}, // 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) + {"docket-convention/SKILL.md", 353, 7259}, // 0578: docket-export joins the inline skills (353/7257 -> 353/7259); 0575: reclaim and the claim lease are retired (361/7377 -> 353/7257); 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. - {"docket-convention/references/agent-layer.md", 214, 1990}, // 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) + {"docket-convention/references/agent-layer.md", 214, 1991}, // 0578: docket-export joins the inline skills (214/1989 -> 214/1991); 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) {"docket-convention/references/close-out.md", 174, 1722}, // 0567: a carried child whose stack relationship can't be proven stays pending (destination-mismatch) (174/1711 -> 174/1722); 0567: a carried stacked child is retried like any done change and stays pending (carry-unproven) with no delete advice (174/1704 -> 174/1711); 0559: change.complete is the third done driver; finalize.cleanup's no-PR path; kill takes --request and is not idempotent (141/1347 -> 174/1701); 0559: the sweep retries only a leftover worktree (174/1701 -> 174/1704); 0531: the metadata worktree and remote come from the repository.prepare context (141/1349 -> 141/1347); 0502: "loop" means /loop only (144/1375 -> 144/1374); 0502: one metadata layout — the docket branch and the .docket/ worktree (144/1376 -> 144/1375); 0502: the scripts/.md contract pointer becomes the schema operation (144/1374 -> 144/1376); 0502: the terminal-publication step is deleted (240/2150 -> 144/1374); 0474: reference renamed (ADR-0129 row 59a); ceilings unchanged; 0502: drop change citations and Go v1 narration (144/1374 -> 144/1356); 0502: the docket-source test citations are deleted (144/1356 -> 141/1349) {"docket-convention/references/learnings.md", 69, 487}, // 0535: promotion lands in the private instructions file in a private repository (66/457 -> 69/487); 0502: one metadata layout — the docket branch and the .docket/ worktree (66/455 -> 66/457); 0502: learning.record/learning.update are the writers; the capacity section is deleted (84/580 -> 66/455) {"docket-convention/references/stacked-changes.md", 227, 2290}, // 0571: a root carries exactly the children merged into it, stacked-merged or implemented; any other child never blocks it (223/2217 -> 227/2290); 0567: carried children are cleaned right after the root once their work is proven (219/2173 -> 223/2217); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (214/2149 -> 219/2173); 0502: typed operations and binary-emitted findings replace the Bash-era names (213/2125 -> 214/2149); 0502: the deferred descendant-publication sentence is deleted (215/2140 -> 213/2125); 0327: +carry-preservation contract prose (see note above) + {"docket-export/SKILL.md", 60, 1116}, // 0578 review: export fallbacks for a missing prepare context, stray-marker leftovers, and a non-git directory (60/1063 -> 60/1116); 0578 review: the private ADR/change-number rewrite runs on every private export (59/1038 -> 60/1063); 0578: new — the inline export skill {"docket-finalize-change/SKILL.md", 242, 6269}, // 0571: the children-retarget-required closeout bullet is deleted; root-archived names who is carried (243/6254 -> 242/6269); 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) {"docket-finalize-change/references/gate-failure.md", 162, 2107}, // 0571: the children-retarget-required closeout halt is deleted (162/2111 -> 162/2107); 0532 review: the gate-agent payload names Visibility (161/2109 -> 162/2111); 0515 review: the refused-notes fallback names every dropped note in the final report (160/2098 -> 161/2109); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (153/2005 -> 160/2098); 0515: the repair sign-off is retired; a green repair merges (160/2086 -> 153/2005); 0517: the repaired-head evidence.record carries --owner finalize (159/2081 -> 160/2086); 0502 review: clear-block re-reads the revision after the block lands (157/2062 -> 159/2081); 0502: repair sign-off records finalize.block before publishing the repaired head (155/2028 -> 157/2062); 0502: the embedded-bundle rule is conditioned on docket's own repository (155/2024 -> 155/2028); 0502: "loop" means /loop only (155/2027 -> 155/2024); 0502: repair sign-off is the human running finalize.clear-block; the marker lifecycle names what removes it (154/2013 -> 155/2027); 0502: the repaired head is re-gated through the gate driver (148/1937 -> 154/2013); 0497: +wait-for-the-leftover-group sentence (146/1901 -> 148/1937); 0493: the gate relaunch is retired (145/1892 -> 146/1901); 0491: the run id is retired (145/1894 -> 145/1892); 0490: the shared-slot note became the shared worktree-lock note (147/1901 -> 145/1894); 0411: +reconciliation-write exception section and abort-set carve-out (ceilings 135/1472 -> 147/1901); 0413: +conflicted_paths-lists-authored-only rule in the resolver-report section (line ceiling 133 -> 135, word ceiling 1465 -> 1472); 0419: +repair-attempt budget payload and rewired repair contract prose (word ceiling 1450 -> 1465); 0349: +reserve-before-dispatch resolver protocol prose; 0375: +worktree-slot note for the scopeless finalize gate (120/1300 -> 133/1450) {"docket-groom-next/SKILL.md", 77, 2310}, // 0573: trivial retired; the brainstorm is told the artifact is always a spec (78/2377 -> 77/2310); 0560 review: a revise that sets or lifts a hold changes the row's readiness (78/2370 -> 78/2377); 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) diff --git a/internal/repoguard/export_skill_test.go b/internal/repoguard/export_skill_test.go new file mode 100644 index 000000000..a8a60a48e --- /dev/null +++ b/internal/repoguard/export_skill_test.go @@ -0,0 +1,102 @@ +package repoguard + +import ( + "errors" + "io/fs" + "os" + "path/filepath" + "reflect" + "regexp" + "strings" + "testing" +) + +// frontmatterKeyLine matches a top-level frontmatter key at column 0. +var frontmatterKeyLine = regexp.MustCompile(`^([a-z_]+):`) + +// skillFrontmatterKeys returns the top-level keys between the first `---` line +// and the next `---` line, in file order. It errors when the content does not +// open with `---` or the frontmatter has no closing fence. +func skillFrontmatterKeys(content string) ([]string, error) { + lines := strings.Split(content, "\n") + if len(lines) == 0 || strings.TrimRight(lines[0], "\r") != "---" { + return nil, errors.New("no opening frontmatter fence") + } + var keys []string + for _, line := range lines[1:] { + line = strings.TrimRight(line, "\r") + if line == "---" { + return keys, nil + } + if m := frontmatterKeyLine.FindStringSubmatch(line); m != nil { + keys = append(keys, m[1]) + } + } + return nil, errors.New("no closing frontmatter fence") +} + +// frontmatterValue returns the one-line value of key in the first frontmatter block. +func frontmatterValue(content, key string) string { + lines := strings.Split(content, "\n") + for _, line := range lines[1:] { + line = strings.TrimRight(line, "\r") + if line == "---" { + break + } + if strings.HasPrefix(line, key+":") { + return strings.TrimSpace(strings.TrimPrefix(line, key+":")) + } + } + return "" +} + +// TestExportSkillIsInline pins docket-export as an inline skill: frontmatter +// carries exactly name and description (no fork, no agent), and no agent +// wrapper exists. A forked skill could not reach the session's posting tools +// or ask the person. +func TestExportSkillIsInline(t *testing.T) { + root := guardRoot(t) + body := readRepoFile(t, "skills/docket-export/SKILL.md") + keys, err := skillFrontmatterKeys(body) + if err != nil { + t.Fatalf("skills/docket-export/SKILL.md frontmatter: %v", err) + } + if want := []string{"name", "description"}; !reflect.DeepEqual(keys, want) { + t.Errorf("frontmatter keys = %v, want exactly %v (an inline skill: no context, no agent)", keys, want) + } + if got := frontmatterValue(body, "name"); got != "docket-export" { + t.Errorf("name = %q, want docket-export", got) + } + desc := collapseWS(frontmatterValue(body, "description")) + for _, clause := range []string{ + "export a docket change, spec, plan, or results file", + "put one into anything outside docket", + } { + if !strings.Contains(desc, clause) { + t.Errorf("description lacks %q: %q", clause, desc) + } + } + _, err = os.Stat(filepath.Join(root, "agents", "docket-export.md")) + switch { + case err == nil: + t.Errorf("agents/docket-export.md exists; docket-export is an inline skill with no wrapper") + case !errors.Is(err, fs.ErrNotExist): + t.Errorf("stat agents/docket-export.md: %v (fail closed)", err) + } + + t.Run("non_vacuity", func(t *testing.T) { + got, err := skillFrontmatterKeys("---\nname: x\ndescription: y\ncontext: fork\nagent: x\n---\nbody\n") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if want := []string{"name", "description", "context", "agent"}; !reflect.DeepEqual(got, want) { + t.Errorf("keys = %v, want %v", got, want) + } + if _, err := skillFrontmatterKeys("name: x\n"); err == nil { + t.Errorf("no opening fence was accepted") + } + if _, err := skillFrontmatterKeys("---\nname: x\n"); err == nil { + t.Errorf("no closing fence was accepted") + } + }) +} diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index dbed28e8a..9a92564c3 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1508,6 +1508,38 @@ var alignmentContracts = []proseContract{ "an untracked driver has no verdict and stops on every `halted`", }, absent: []string{"The driver's decision is binary"}}, + // change 0578 — the inline export skill: never a hand-built or raw export; + // a failed export posts nothing; shared repositories get no rewrite pass and + // no stop; private (or unknown) repositories get the rewrite pass, the word + // check, and a before → after stop. + {sentinel: "change_0578_export_skill", file: "skills/docket-export/SKILL.md", + present: []string{ + "**Never build an export by hand, and never send the raw file.**", + "`--export --print --json`", + "**A failed export posts nothing.**", + "If `result` is not `applied` or there is no `exported_path`, tell the person the `message` and stop", + "Never fall back to the raw file or a hand cleanup", + "the visibility is unknown, so **treat the repository as private**", + "this is not a docket artifact", + "**A shared repository gets no rewrite pass and no stop.**", + "**Rewrite pass.** When the export reported any `leftovers` or `mentions`, edit the exported copy in place", + "Search the rewritten copy for \"docket\" and \"dckt\" as whole words, case-insensitive, code included", + "show the person every change as before → after and **post only after they say go**", + }, + absent: []string{"context: fork", "agent: docket-export"}}, + // 0578 review: the export reports neither ADR numbers nor bare #N, so the private + // ADR/change-number rewrite runs on every private export, not only on leftovers or mentions. + {sentinel: "change_0578_export_skill", file: "skills/docket-export/SKILL.md", + present: []string{ + "**Always rewrite docket's ADR numbers and change numbers, whether or not the export reported `leftovers` or `mentions`**", + "the export never reports them, so search the whole copy on every private export", + }}, + {sentinel: "change_0578_export_skill", file: "skills/docket-convention/SKILL.md", + present: []string{"(`docket-new-change`, `docket-groom-next`) and `docket-export` stay inline"}}, + {sentinel: "change_0578_export_skill", file: "docs/reference/cli.md", + present: []string{"Agent sessions reach the export through the `docket-export` skill."}}, + {sentinel: "change_0578_export_skill", file: "docs/reference/skills-and-agents.md", + present: []string{"- **docket-export** —"}}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 2cfc8e310..abe793e4f 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -102,7 +102,7 @@ The *Skill layer*'s **missing-skill rule** and `halt` are two conditions with tw ### Agent layer — model/effort-pinned subagents -Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`) stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). +Each **autonomous** docket skill can run as a model/effort-pinned **subagent** instead of inline at the session model. The autonomous skills get a wrapper — `docket-implement-next`, `docket-auto-groom`, `docket-finalize-change`, `docket-status`, `docket-adr`, `docket-build-task` (shared by its four tier agents), and `docket-review` (shared by its three tier wrappers); the two **interactive** skills (`docket-new-change`, `docket-groom-next`) and `docket-export` stay inline and run at the session model. `docket-convention` is not an agent — it is listed in the skills list of every wrapper except these: `docket-brainstorm-consultant` (ADR-0022), **`docket-plan-writer`**, the `docket-build-*` tier workers, and the `docket-review-*` tier wrappers. Of these wrapper-bearing exceptions the plan-writer performs exactly one docket metadata operation (`change.attach-plan`) and the others perform none — a boundary each worker contract's own *Scope* states normatively; the consultant wraps nothing at all (see *Composition*). A wrapper is a thin installed file: it carries the resolved `model` and `effort`, when they resolve, and lists the skill and `docket-convention` in its skills list; the skill body stays the single source of behavior. Because a subagent cannot pause to ask a human, every autonomous wrapper carries an **abort-and-report** rule: an unmet precondition or blocking ambiguity is surfaced and stopped on — never turned into an interactive prompt. The Go install generates each wrapper from the compiled built-in model/effort table plus the global configuration's overrides, and installs it at user level, never per repository. A **directly-invoked** autonomous skill is still routed to its pinned wrapper by a harness dispatch mechanism, so the pin holds either way; mechanics live in [`references/agent-layer.md`](references/agent-layer.md). diff --git a/skills/docket-convention/references/agent-layer.md b/skills/docket-convention/references/agent-layer.md index d06db04b0..4a58b233c 100644 --- a/skills/docket-convention/references/agent-layer.md +++ b/skills/docket-convention/references/agent-layer.md @@ -196,7 +196,7 @@ four headless-safe autonomous skills (`docket-status`, `docket-adr`, `docket-imp carry `context: fork` + `agent: docket-` frontmatter in their `SKILL.md`, forking a directly-invoked skill into the same pinned wrapper — inert in every other harness. **Fork-exclusion principle:** only skills that never need the human mid-run are forked, since a forked subagent has no channel back to the human; the two interactive -skills stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission +skills and `docket-export` stay inline, and `docket-finalize-change` stays unforked — its headless merge is gated by a permission classifier (ADR-0043). A forked skill-invoke (`/docket-status`) and an explicit agent dispatch (`@docket-status`, or a subagent dispatch diff --git a/skills/docket-export/SKILL.md b/skills/docket-export/SKILL.md new file mode 100644 index 000000000..2644e4433 --- /dev/null +++ b/skills/docket-export/SKILL.md @@ -0,0 +1,60 @@ +--- +name: docket-export +description: Use when asked to export a docket change, spec, plan, or results file, or to put one into anything outside docket — a Jira ticket body or comment, a document, a message, an email — so its content comes from docket's own export, never the raw file or a hand cleanup. +--- + +# docket-export + +Docket artifacts carry links, generated blocks, and references that mean nothing outside docket, and the export writes a clean Markdown copy of them. Use it every time a change, spec, plan, or results file leaves docket. **Never build an export by hand, and never send the raw file.** + +This skill runs inline, in your own session: you post with your own tools, and you ask the person directly where a step below says to. + +## 1. Resolve the operations + +Run `docket capabilities --json` as its own call — the one docket spelling this skill hard-codes. Check that `protocol_version` is 1 and take the `argv` of the entries `open`, `repository.prepare`, and `diagnostic.config`. If the binary is missing or an entry is absent, tell the person their docket installation is broken and stop — never a hand-made export. + +## 2. Learn the visibility + +Run the `repository.prepare` argv with `--repo-dir --json` as its own call and read `context.visibility` (`shared` or `private`). + +- The directory is not a git repository (`result` is `invalid-input` with an empty `repository_state`), or `repository_state` is `fresh` (no docket set up): this is not a docket artifact. Say so in one line and handle the request without this skill. +- Any other refusal or error: the visibility is unknown, so **treat the repository as private**. A leak cannot be undone. + +In a private repository, also run the `diagnostic.config` argv with `--repo-dir --json` and read `effective.leak_check.match_word.value`. When it cannot be read, treat it as `true`. + +## 3. Run the export + +Run the `open` argv as ` [] --export --print --json --repo-dir `, where `` is `change`, `spec`, `plan`, or `results` and `` is the change the person named (omit it to use the change whose branch is checked out). Always `--export --print --json`: `--print` opens no viewer — the person may not be at the screen, and can ask you to open the file. Never pass `--warnings` unless the person asked for a filter on a file request; the default reports everything the private pass reads. + +- **File request** ("export the spec for 9"): the export's default destination, or `--output-path ` when the person names one. +- **Outside-tool request** ("add the spec for 9 as a comment on PROJ-123"): `--output-path` set to a fresh directory from `mktemp -d "${TMPDIR:-/tmp}/docket-export.XXXXXX"`, so the person's downloads folder does not collect one file per post. Leave the file there and report its path. + +**A failed export posts nothing.** If `result` is not `applied` or there is no `exported_path`, tell the person the `message` and stop. Never fall back to the raw file or a hand cleanup. This holds in every repository. + +## 4. Shared repository + +**A shared repository gets no rewrite pass and no stop.** Hand the exported text to the target unchanged; on a file request the file is the result. Any `leftovers` go out as they are and are named in your report. + +## 5. Private repository + +Nothing that names docket may leave. + +1. **Rewrite pass.** When the export reported any `leftovers` or `mentions`, edit the exported copy in place until it holds none of these: the words "docket" or "dckt", docket marker comments, `Docket-` trailers, `.docket` or `dckt` paths, change ids or change references from docket, ADR numbers from docket's ledger, or references to the backlog or board. Every edited line must read naturally to an outside reader. + - Fix each leftover: remove the marker, unwrap the link, drop the stamp line. A `stray-marker` leftover (it carries `source_line`, not `line`) is already gone from the copy: name it in the report, never edit for it. + - Rewrite each line on the `mentions` list so it no longer names docket or dckt ("the docket build gate runs the suite" becomes "the build gate runs the suite"). A mention inside code is generalized or dropped, at your judgment. + - When `leak_check.match_word` is `false`, the bare word "docket" may stay; "dckt", markers, ids, and ADR numbers are still handled. + - Change only these lines: no other rewording, summarizing, or fixing. + + **Always rewrite docket's ADR numbers and change numbers, whether or not the export reported `leftovers` or `mentions`** — the export never reports them, so search the whole copy on every private export. Rewrite each into what it refers to, or drop it; the person's team cannot open them. An ADR is docket's when a file for its number exists under `/`, and a `#N` is one of docket's changes when a record for that id exists under `/` (paths from the prepare context). When the prepare context is unavailable, treat every ADR number and every `#N` or four-digit change id as docket's, or ask the person. The team's own ADRs stay, and so does a `#N` that is not one of docket's changes, such as a Jira or pull request number. +2. **Word check.** Search the rewritten copy for "docket" and "dckt" as whole words, case-insensitive, code included (the bare word "docket" is exempt when `leak_check.match_word` is `false`). Any hit: stop, show the person the path and the lines, and post nothing until they decide. +3. **Show, then post.** If the rewrite pass changed anything, show the person every change as before → after and **post only after they say go**. If nothing needed rewriting, post straight away. A file request gets the same pass and check — the file goes to outsiders too — and the before → after list comes with the path, with no stop, since nothing is posted. + +## 6. Post + +Read the file at `exported_path` (after the rewrite pass, in a private repository) and hand its text to the target unchanged. When the target needs another format, such as Jira's own markup, convert the formatting only, never the words. A summary or excerpt the person asks for ("just the Goals section") is made from this copy, never the raw file. When the text is too long for the target, tell the person and ask whether to split it or attach the file. Whatever confirmation your harness already asks before an outward post is unchanged. + +## 7. Report + +Report the path, whether an existing file was replaced (`replaced`), any warnings, and, in a private repository, the before → after list. + +The board and pull requests have no export. A person who explicitly asks for the raw file is asking for something else.