@azure-id/orc 0.55.0

package/templates/skills/orc-doc/references/plain-language.md

@@ -0,0 +1,66 @@
+# Writing a human can actually read (P0)
+
+Both the writer and the checker are held to this. The free half is measured by
+`orc doc lint`; the rest is what the checker grades each section for.
+
+## The rules
+
+1. **Write for the audience named in D4**, not for the model that wrote it.
+2. **One idea per sentence.** Average ≤ 20 words. Any sentence over 35 words is
+   a lint finding, with its line number.
+3. **Common words beat precise-sounding ones.** *use* not *utilise*, *start* not
+   *initiate*, *about* not *regarding*, *use* not *leverage*, *before* not
+   *prior to*.
+4. **Every acronym is expanded on first use** — "service level objective (SLO)".
+   The lint catches unexpanded ones by scanning for capitalised runs, and it
+   already knows the ones every technical reader has.
+5. **Active voice.** "The service retries the call", not "the call is retried" —
+   the passive hides who does it, and in a runbook that is the whole point of
+   the sentence.
+6. **No unexplained internal jargon.** A term the D4 audience would not know is
+   either replaced or defined in the glossary. The checker flags it either way.
+7. **Facts go in tables**, not in a paragraph listing six things.
+8. **Say the thing first.** Each section opens with its conclusion; the
+   reasoning follows.
+9. **Never invent a fact.** What is not in `context.md` or `context-sources.md`
+   is **not written at all** — it comes back as a gap and is raised with the
+   user. The deliverable carries content only, so it never carries ORC's own
+   uncertainty markers. Filler that reads like a fact is the worst possible
+   output of this lane; a `> **Open:**` line left in the reader's document is
+   the second worst.
+10. **Non-English output is held to the same bar in that language** — short
+    sentences, common words, acronyms expanded. Technical terms with no natural
+    translation stay in English and are glossed once.
+
+## Why the checker is `low` effort — deliberately
+
+`orc-doc-checker-opus-5-low` reads a short range and answers a bounded question:
+*does this text do what its section is for, in words this audience knows,
+without inventing anything?*
+
+Low effort is the **right instrument** for that, not a cost compromise. A
+harder-thinking checker reasons its way past a gap a real reader would trip on —
+the same reasoning that pins `/orc-challenge`'s cold reader at `low`. **Nothing
+may "upgrade" it later.**
+
+## What the lint measures, and what it does not
+
+| Free (`orc doc lint`) | Judgment (the checker) |
+|---|---|
+| average sentence length, and the longest one with its line | whether the section does what its purpose says |
+| long-word ratio | whether the declared audience can act on it |
+| acronyms used without being expanded | whether a term needs the glossary |
+| passive constructions (a pattern match) | whether a sentence hides its actor in a way that matters |
+| leftover `TODO` / `TBD` / `???` | whether something is asserted that nothing supports |
+
+**Free checks run before paid ones. Always.** The lint's findings ride in the
+checker's slice, so no model ever spends a token counting sentences — and the
+checker never re-reports one.
+
+## Two honesty rules the lint prints about itself
+
+1. **A readability signal is a SIGNAL, not a verdict.** A long sentence is not
+   automatically a defect. It never blocks anything.
+2. **It is English-specific and heuristic.** Passive-voice detection is a
+   pattern match and a syllable count is an estimate. It says so, once, on its
+   own output.

package/templates/skills/orc-doc/references/portable-markdown.md

@@ -0,0 +1,74 @@
+# Portable Markdown — the rules `document.md` is held to
+
+Enforced two ways: **`orc doc lint`** (free, deterministic, mechanical) and the
+checker (judgment). Every rule below came from a real product limit, not from
+taste — see `import-targets.md` for where each one comes from.
+
+| Rule | Why |
+|---|---|
+| ATX headings only, exactly one H1, no skipped levels | Every importer's outline builder depends on it. A setext (underlined) heading is invisible to most of them |
+| **Max depth H3** under `--target notion` (and under `generic`) | Notion has three heading levels. An H4 silently becomes bold text |
+| **No hard-wrapped paragraphs — one paragraph, one line** | A hard wrap at 80 columns becomes a line break INSIDE a Notion or Docs paragraph. This is the single most common import-mangling bug |
+| No raw HTML, no HTML comments in the deliverable | Some importers render them as literal text |
+| Simple pipe tables only — no nesting, no colspan, no ragged rows | Everything else survives an import; these do not |
+| ` ``` ` fences only, with a language tag | `~~~` and indented code blocks convert unreliably |
+| No `[[wikilinks]]`, no footnotes, no definition lists | Obsidian-only / Pandoc-only syntax |
+| Task lists `- [ ]` are allowed | Notion, GitHub and Docs all handle them |
+| Images: a relative path **and** alt text, plus a one-line text description beside it | Images do not travel through most imports. The description is what survives |
+| **YAML front matter OFF by default**, ON for `--target docusaurus` / `hugo` / `jekyll` | Notion and Docs render it as visible junk at the top of the page; a static-site generator will not render the page without it |
+| No emoji in headings (the body is fine) | Some importers slug headings and mangle the anchors |
+
+## The one that is worth repeating
+
+**One paragraph is one line.** Not "prefer long lines" — one line. A writer that
+hard-wraps at 80 columns produces a document that reads perfectly in a terminal
+and arrives in Notion as a column of broken fragments. `orc doc lint` reports
+it once per paragraph, as an ERROR.
+
+## Where a gap goes, and why it is not in the document
+
+**The deliverable carries content only.** No `> **Open:**`, no
+`> **Assumption:**`, no note callout, no HTML comment — not in `document.md`, and
+not in any file under `sections/`.
+
+This does **not** relax the never-invent-a-fact rule; it changes only where the
+honesty is written down. ORC still refuses to make something up. What is not in
+`context.md` or `context-sources.md` is **not written at all**:
+
+| what it is | where it goes |
+|---|---|
+| nobody has decided this yet | `orc doc log <slug> --kind gap --sections <id> --text "the fraud limit has not been decided"` → `gaps.md`, and it is raised with the user |
+| I had to assume it to write the sentence | the same, and it is raised with the user |
+| which option we chose, and why | `orc doc log <slug> --kind decision --text "…"` → the journal |
+| the template's `<!-- purpose: … -->` lines | stripped at compile — they are instructions for the writer |
+
+**Why the reversal.** A PRD that arrives in Notion with three `> **Open:**`
+blockquotes in it is a PRD the reader has to filter. The gap is real and worth
+recording; it just is not part of what the reader came for. And a *stub* section
+that is nothing but an Open line is worse than an absent one — under
+`orc doc compile --partial` a missing section is simply **absent**, and named
+loudly outside the document.
+
+**It is enforced in four places**, and none of them is a silent rewrite:
+
+1. **The writer never emits one** — uncertainty goes in its return's `gaps[]`.
+2. **`orc doc lint`'s `annotation-in-body` is an ERROR.** The rule matches an
+   EXACT, narrow set — `> **Open:**`, `> **Assumption:**`, `> **Note (ORC):**`,
+   an `orc-doc:` fence — and **nothing else**. A user's own line beginning
+   "Note:" is content and is never flagged. A narrow rule that is always right
+   beats a broad one that argues with the author.
+3. **`compile` REPORTS them and never silently strips.** They come back in
+   `annotations[]` with a line and a fix. We cannot tell whose line it is, and a
+   silent strip can delete a real sentence. The one exception is the explicit
+   `orc doc compile --strip-annotations`.
+4. **The section state no longer sniffs the body.** Existence and hashes decide
+   it, which was always strictly more reliable than a text match.
+
+## Severity
+
+`orc doc lint` returns `error` and `warn`:
+
+- **`error`** — the document will be visibly wrong in the target. It blocks the
+  handoff line ("this is ready to import").
+- **`warn`** — a readability or portability signal. It is reported, never
+  blocking. A signal is not a verdict.

package/templates/skills/orc-doc/references/resume-protocol.md

@@ -0,0 +1,228 @@
+# Resuming — the contract that makes a document survive a session
+
+> **The context is gathered once and frozen.** A resumed session reads
+> `context.md` from disk; it never re-interviews the user for what session 1
+> already settled. **a lane that re-asks a frozen question** has broken this
+> contract.
+
+## Entry
+
+```
+/orc-doc resume                      → lists every document with its status line
+/orc-doc resume prd-checkout-refund  → prefix match; an ambiguous prefix lists candidates
+```
+
+`orc doc list --json` supplies the list. It may only claim what the disk proves:
+`document.md` missing means **"not started"**, never "failed".
+
+## The resumed session's first four moves
+
+1. `orc doc status <slug> --json` (0 nothing to do · 1 something to do · 2
+   unknown slug) and **`orc doc parts <slug> --json`** — which works BEFORE a
+   single compile has ever run, because the section files ARE the progress.
+2. **Read `context.md` and `outline.md`. NOT the document.**
+3. **Detect the user's own edits.** Sections whose live hash ≠ the hash
+   `doc.json` recorded are `user-edited`. Say so, **by section name**. A part
+   with no recorded hash at all is `unconfirmed` — a wave killed mid-flight —
+   and it is re-written, never shipped.
+4. **HARD STOP and ask what should change.**
+
+```
+Picking up: PRD — checkout refunds (started 13-08-2026, cycle 2).
+I have read the context you gave me — you do not need to repeat it.
+
+  Sections:  17 planned · 14 written · wave 5 of 7
+  You edited since last time: §02 Summary, §08 Requirements   ← I will not touch these unless you say so
+  Not written yet: §12 Risks · §13 Rollout
+  document.md is 2 sections behind sections/ — rebuilding it is free.
+
+What should change?  (a section to rewrite, something to add, a finding to fix,
+or "finish the rest")
+```
+
+**No change request → no work.** The lane stops there. Regenerating a document
+nobody asked to change is the most expensive possible way to do nothing.
+
+## `RESUME.md` — the P0 hand-back
+
+Written by **the lane itself, never by a dispatched agent** — a dispatch inside
+a stop sequence lets a stop fail because a subagent did.
+
+**v0.49.5 — the CLI writes it, and it is never behind.** `orc doc resume-file
+<slug>` composes the whole page from `doc.json`, and `doc.json` refreshes it on
+**every** write, so it exists from `orc doc init` onward. This replaces a rule
+the orchestrator had to remember at every stop, which is the bet this repo has
+already lost twice (the v0.32.0 narration lesson): a hand-back you are TOLD to
+write at every stop is the hand-back that goes missing on the one run that
+mattered — the one a usage limit killed.
+
+**Rule 16 — `every question points at RESUME.md`.** Before ORC asks the user
+anything, it runs `orc doc resume-file <slug>` and ends the message with that
+file's path and the line to paste. A user who has to remember where they were is
+a user who does not come back.
+
+The page is written for someone who does not read code: what this document is,
+where the files are, what is not written yet, what happens next, and the one
+line to paste. Nothing in it needs interpreting.
+
+**It lives at `{run_dir}/{slug}/RESUME.md`** — the registered v0.42.0 home, and
+the ONLY place `listRuns()` looks. It is not in the document folder, and there is
+no second copy there: two copies is two ideas, and they drift. Anyone browsing
+the folder gets the same line from `orc doc status`.
+
+```markdown
+# Resume this document
+
+Paste this line into a new Claude Code session, in this project:
+
+    /orc-doc resume prd-checkout-refund-130826
+
+Where it stands:  /orc-doc · PRD · cycle 2 · 14 of 17 sections written · phase D6 · wave 5 of 7
+
+- Sections:   orc/orc-doc/prd-checkout-refund-130826/sections/   ← the source of truth
+- Document:   document.md is a BUILD ARTIFACT — `orc doc compile` rebuilds it, free
+- Context:    context.md  (the new session reads this first — you do not repeat yourself)
+- Not written yet: §12 Risks · §13 Rollout
+
+## What the new session will do
+1. Read context.md and doc.json. It will NOT re-ask what you already answered.
+2. Start at wave 6, and re-read NOTHING it already wrote.
+3. Ask you what should change. **It will not touch the document until you say.**
+```
+
+**The `Where it stands:` line is at COLUMN 0.** Never `## Where it stands:` —
+`parseStands` is line-anchored, so a heading prefix means it never matches, and
+that single line is what `orc doc list`, `orc resume` and `orc run list` all
+parse. There is a test that feeds this exact template to the real parser.
+
+**One generator, not two.** The whole file comes from `orc doc resume-file`,
+which builds the `Where it stands:` line with the same function `orc doc status`
+uses. Never assemble your own copy of either. The CLI computes, the skill points
+at the result, and the two can then never disagree.
+
+## The wave hand-back (P0, every wave)
+
+```
+Wave 2 of 7 done — 6 of 17 sections written.
+
+  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/01-data-model.md    142 L
+  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/02-api-surface.md   118 L
+  orc/orc-doc/acme-prd-170826/sections/05-rollout.md                           96 L
+
+Read them now if you want to redirect — nothing later is bought yet.
+See it as one file (free):   orc doc compile acme-prd-170826 --partial
+
+To carry on — new session, or after your usage limit resets:
+
+    /orc-doc resume acme-prd-170826
+
+Everything needed is on disk. The next session starts at wave 3 and re-reads
+nothing it already wrote.
+
+The full picture, in plain words:
+    .claude/orc/run/acme-prd-170826/RESUME.md
+```
+
+**Every message that asks the user something ends with those last two lines**
+(rule 16) — a gate, a wave stop, a revision round, an offer. The path is what
+`orc doc resume-file` just printed; never type one from memory.
+
+## The hand-back mention (P0, every cycle)
+
+After **every** cycle that touched the document — the first run and every
+resume — this is the last thing on screen, always in this shape:
+
+```
+Saved to  orc/orc-doc/prd-checkout-refund-130826/sections/   (the source of truth)
+          orc/orc-doc/prd-checkout-refund-130826/document.md (rebuilt, free)
+
+Editing it yourself is expected — go ahead. When you want to carry on, even in a
+brand-new chat, paste this line:
+
+    /orc-doc resume prd-checkout-refund-130826
+
+The full picture is in that folder's RESUME.md — it remembers the context, the
+audience and what is still open, so you never have to explain it twice.
+```
+
+Then the two things this lane offers but never does:
+
+```
+Not staged, not committed. If your team should see it:
+    git add orc/orc-doc/prd-checkout-refund-130826/
+
+Want it graded before you send it? In a NEW session:
+    /orc-challenge orc/orc-doc/prd-checkout-refund-130826/document.md
+```
+
+`/orc-challenge` is offered and never run from here. It is the same separation
+its own contract already enforces from the other side: a session that wrote the
+thing cannot honestly grade it.
+
+## The user's edits are sacred
+
+A `user-edited` section is **never** rewritten without an explicit instruction
+naming it. If a finding lands inside one, the finding is *reported* and the fix
+is *offered*, never applied. Overwriting a human's paragraph is unrecoverable
+from this lane's side — the part file is gone, and their wording with it.
+
+## `changelog.md`
+
+One entry per cycle, appended, newest last. It is the answer to "what did the
+last session actually do", and it is written by the lane, not derived:
+
+```markdown
+## Cycle 2 — 14-08-2026
+- You asked: tighten §04 Goals and add the fraud limit to §12.
+- Changed: sections/04-goals-and-metrics.md (rewritten, 22 → 18 lines), sections/12-risks.md (one row added).
+- Untouched: §02 and §08 — you edited those yourself.
+- Not written yet: §13 Rollout.
+```
+
+An Open question or an Assumption does NOT go here and does not go into the
+document. It goes into the journal as a gap —
+`orc doc log <slug> --kind gap --sections <id> --text "…"` — and the CLI derives
+`gaps.md` from that. The deliverable carries content only.
+
+---
+
+## The journal — what you asked for, in order (v0.48.1)
+
+`changelog.md` above is **lane-written prose**. The journal is the **derived**
+companion, and the two are not the same thing: one is a narrative someone wrote,
+the other is a merge of four sources with the provenance of every row attached.
+
+```
+orc doc log     <slug> --kind request|decision|gate|note|gap --text "…" [--sections a,b] [--source user|/orc-grill|/orc-brainstorm]
+orc doc journal <slug> [--json]
+```
+
+| `origin` | source | what it is |
+|---|---|---|
+| `recorded` | `journal[]` | the user's own words, **verbatim** |
+| `derived` | `cycles[]` | a write / check / edit / compile cycle — a machine fact |
+| `derived` | the ship / unship records | a machine fact |
+| `observed` | a section that turned `user-edited` | a machine fact, no text |
+
+**It never invents an entry.** A cycle that ran with nothing logged renders as
+an explicit gap — *"cycle 2 ran · no request was recorded for it"* — and **never**
+a plausible reconstruction from file mtimes. **a lane that invents a journal entry**
+has broken this contract. Same honesty rule as `/orc-pact`'s
+**UNCHECKABLE**: not knowing is an answer, and faking it teaches people to
+distrust the rows that are real.
+
+**Call `orc doc log` at D1 with the user's words verbatim.** A resumed session
+reads the journal to answer *"what have I been asking for?"*, and a paraphrase
+there is the same failure as a paraphrase in `context.md` — it is where a
+resumed session quietly starts writing a different document.
+
+## Resuming is a loop now, not a memory
+
+The resumed session's moves are unchanged — `orc doc status`, `orc doc parts`,
+read `context.md` and `outline.md` (**not the document**), name what the user
+edited, then HARD STOP and ask. After that, **`orc doc next <slug> --json` says
+what happens next** and this lane does exactly that, until it exits 1.
+
+Nothing about the pipeline is remembered across the gap any more. That is the
+point: a session resumed months later in a fresh context has the same
+information as the one that started it.

package/templates/skills/orc-doc/references/templates/collaboration.md

@@ -0,0 +1,118 @@
+<!-- orc-doc:template collaboration — the shipped base template.
+
+     two or more teams agreeing who owns what and how they will talk; RACI is the spine
+
+     Every `<!-- purpose: … -->` line is an instruction for the WRITER and is
+     STRIPPED at compile — it never reaches document.md. A required section with
+     no material is NOT written: it comes back as a gap, lands in gaps.md, and is
+     raised with you. The deliverable carries content only — never a silent
+     omission, never invented filler, and never ORC's own bookkeeping.
+
+     A template is a floor, not a cage. Your own template REPLACES this one
+     entirely (`orc doc init … --template <path>`); the two are never merged.
+-->
+
+# <document title>
+
+## Document info
+
+<!-- purpose: owner, version, date, the teams it binds -->
+
+| Field | Value |
+|---|---|
+| Title |  |
+| Owner |  |
+| Status | draft \| in review \| approved |
+| Version | 0.1 |
+| Date |  |
+| Reviewers |  |
+
+## Purpose and scope
+
+<!-- purpose: what this agreement covers, and what it does not -->
+
+## Parties
+
+<!-- purpose: a table: team, what they bring, named contact, time zone -->
+
+| Team | What they bring | Named contact | Time zone |
+|---|---|---|---|
+|  |  |  |  |
+
+## Shared goal and definition of success
+
+<!-- purpose: one goal both sides would state the same way -->
+
+## Ownership split (RACI)
+
+<!-- purpose: a table — row = deliverable or decision, column = team -->
+
+| Deliverable or decision | Team A | Team B |
+|---|---|---|
+|  | R | C |
+
+R responsible · A accountable · C consulted · I informed.
+
+## Interfaces between us
+
+<!-- purpose: what each side hands over, in what format, by when -->
+
+| What is handed over | From | To | Format | By when |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## Decision rights and escalation path
+
+<!-- purpose: who decides, who breaks a tie, and how fast -->
+
+| Decision | Who decides | Who breaks a tie | How fast |
+|---|---|---|---|
+|  |  |  |  |
+
+## Communication plan
+
+<!-- purpose: channel, cadence, meeting, status format -->
+
+| Channel | What it is for | Cadence |
+|---|---|---|
+|  |  |  |
+
+## Dependencies and critical dates
+
+<!-- purpose: a table, with the owner of each date -->
+
+| Dependency | Owner | Date | What breaks if it slips |
+|---|---|---|---|
+|  |  |  |  |
+
+## Decision log
+
+<!-- purpose: a table: date, decision, who decided, why -->
+
+| Date | Decision | Who decided | Why |
+|---|---|---|---|
+|  |  |  |  |
+
+## Risks
+
+<!-- purpose: each with an owner and a mitigation -->
+
+| Risk | Impact | Owner | Mitigation |
+|---|---|---|---|
+|  |  |  |  |
+
+## Open questions
+
+<!-- purpose: each with an owner -->
+
+| Question | Owner | Answer needed by |
+|---|---|---|
+|  |  |  |
+
+## Revision history
+
+<!-- purpose: a table: version, date, author, what changed -->
+
+| Version | Date | Author | What changed |
+|---|---|---|---|
+| 0.1 |  |  | First draft |

package/templates/skills/orc-doc/references/templates/prd.md

@@ -0,0 +1,133 @@
+<!-- orc-doc:template prd — the shipped base template.
+
+     cover → problem → goals → requirements → risks → rollout, the shape every current template converges on
+
+     Every `<!-- purpose: … -->` line is an instruction for the WRITER and is
+     STRIPPED at compile — it never reaches document.md. A required section with
+     no material is NOT written: it comes back as a gap, lands in gaps.md, and is
+     raised with you. The deliverable carries content only — never a silent
+     omission, never invented filler, and never ORC's own bookkeeping.
+
+     A template is a floor, not a cage. Your own template REPLACES this one
+     entirely (`orc doc init … --template <path>`); the two are never merged.
+-->
+
+# <document title>
+
+## Document info
+
+<!-- purpose: title, owner, status, version, date, reviewers — as a table -->
+
+| Field | Value |
+|---|---|
+| Title |  |
+| Owner |  |
+| Status | draft \| in review \| approved |
+| Version | 0.1 |
+| Date |  |
+| Reviewers |  |
+
+## Summary
+
+<!-- purpose: what we are building, in three sentences -->
+
+## Problem and context
+
+<!-- purpose: who hurts, and what the evidence is -->
+
+## Goals and success metrics
+
+<!-- purpose: each metric with a baseline and a target -->
+
+| Goal | Metric | Baseline today | Target | By when |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## Non-goals
+
+<!-- purpose: what this deliberately does not do -->
+
+## Users and jobs to be done
+
+<!-- purpose: who they are and what they are trying to get done -->
+
+| Who they are | What they are trying to get done | What stops them today |
+|---|---|---|
+|  |  |  |
+
+## Scenarios and user stories
+
+<!-- purpose: the concrete paths through the product -->
+
+## Functional requirements
+
+<!-- purpose: numbered FR-1…, each with a priority -->
+
+| ID | Requirement | Priority | Notes |
+|---|---|---|---|
+| FR-1 |  | must \| should \| could |  |
+
+## Non-functional requirements
+
+<!-- purpose: performance, security, privacy, accessibility, i18n, compliance -->
+
+| Area | Requirement | How it is measured |
+|---|---|---|
+| Performance |  |  |
+| Security |  |  |
+| Privacy |  |  |
+| Accessibility |  |  |
+| Internationalisation |  |  |
+| Compliance |  |  |
+
+## Experience and flows
+
+<!-- purpose: links to designs, described in words for readers who cannot open them (optional — drop it at the outline gate if nobody asked for it) -->
+
+## Dependencies and assumptions
+
+<!-- purpose: what has to be true, and who else is involved -->
+
+| What has to be true | Who owns it | What we do if it is not |
+|---|---|---|
+|  |  |  |
+
+## Risks and open questions
+
+<!-- purpose: each with an owner -->
+
+| Risk or question | Impact | Owner | What we will do |
+|---|---|---|---|
+|  |  |  |  |
+
+## Rollout and measurement plan
+
+<!-- purpose: how it reaches users and how we know it worked -->
+
+## Milestones
+
+<!-- purpose: a table: milestone, due, status -->
+
+| Milestone | Due | Status |
+|---|---|---|
+|  |  |  |
+
+## Out of scope for this release
+
+<!-- purpose: explicitly deferred, so nobody re-litigates it -->
+
+## Glossary
+
+<!-- purpose: every term the audience would not already know (optional — drop it at the outline gate if nobody asked for it) -->
+
+| Term | What it means here |
+|---|---|
+|  |  |
+
+## Revision history
+
+<!-- purpose: a table: version, date, author, what changed -->
+
+| Version | Date | Author | What changed |
+|---|---|---|---|
+| 0.1 |  |  | First draft |