@azure-id/orc 1.6.0 → 1.7.1

package/templates/skills/_shared/rules/INDEX.md

@@ -0,0 +1,107 @@
+<!-- orc-rules:index -->
+
+# ORC RULES — the anti-slop baseline
+
+> **READ-ONLY.** Everything in this folder ships with ORC and changes only with
+> `orc update`. Nothing in ORC writes here, and `orc rules set --pack …` is
+> refused by name.
+>
+> Your own rules live in `.claude/orc/rules.md`. Write them with
+> `orc rules add --priority P0 --text "…"`, or in `orc ui` ▸ **Rules**.
+
+ORC generates a lot of text and a lot of code. Both come out carrying the same
+recognisable defaults: prose that says nothing in a confident shape, and code
+that is longer, more defensive and more abstract than the task asked for. These
+packs are the filter.
+
+**This is a filter, not a style guide.** It prescribes no voice, no aesthetic
+and no architecture. It rejects technique without purpose, and it never invents
+direction of its own.
+
+---
+
+## The packs
+
+| Pack | File | Ids | Rules | Layer | Applies to |
+|---|---|---|---|---|---|
+| **Writing** | `writing.md` | `OSW-01…23` | 23 | `writing` | every word an agent writes |
+| **Code** | `code.md` | `OSC-01…22` | 22 | `code` | source an agent writes or edits |
+| **Delivery** | `delivery.md` | `OSD-01…10` | 10 | `core` | what an agent reports about its own work |
+| **UI** | `ui.md` | `OSU-01…10` | 10 | `ui` | front-end work only, added **per task** |
+
+**65 rules.** `orc rules --json` is the count's only source. Never compute it
+here, and never compute it in a skill.
+
+Credits, licences and what was taken from whom: `CREDITS.md`, or
+`orc rules credits`.
+
+---
+
+## The three tiers
+
+| Tier | Meaning | On a finding |
+|---|---|---|
+| **HARD** | Absolute. No exception, no purpose that redeems it. | A finding. |
+| **PURPOSE** | The technique is allowed. It needs a written one-line reason. | Missing reason is a finding; the technique is not. |
+| **LOCK** | A consistency requirement. | Reported, never blocking. |
+
+The tier system is Miqdad Badjuber's (`miqdadbadjuber/anti-slop`). The mechanism
+it exists for: a ban list alone leaves a void, and a model fills a void with its
+most generic output. A purpose gate asks for the reason instead, which is the
+only thing that separates craft from default.
+
+---
+
+## Precedence — three layers, and the order never changes
+
+```
+1.  PROJECT CODE HOUSE RULES        ../phases/house-rules.md + the project's CLAUDE.md P0
+    ├ scope: CODE and agent BEHAVIOUR only
+    └ beats everything below it, always
+
+2.  USER RULES                      .claude/orc/rules.md    (P0 > P1 > P2)
+    └ beats the ORC rules OUTRIGHT on any conflict
+
+3.  ORC RULES                       these packs — read-only
+```
+
+**Layer 1 is code-only.** The house card governs how a change is made: surgical,
+simple, honest, in-slice. It says nothing about the words an agent writes, so it
+never overrules a writing rule — it does not speak about prose at all.
+
+**Layer 2 wins outright over layer 3.** A user rule that contradicts an ORC rule
+disables that ORC rule for this project. This is never silent: the agent returns
+`rules_overridden[]` naming the ORC id and the user line that replaced it, and
+the preflight prints the count. A silent override is the one outcome nobody can
+audit.
+
+---
+
+## The boundary
+
+Rules govern **what is written and how it reads**, and **what shape of code is
+acceptable**. They can never change how a lane **runs**: the scoring, the wave
+order, the gates, the dispatch contract, the ship rules, or any lane's
+structural and safety rules.
+
+A rule that asks for one of those comes back as `unsupported_request` and is
+relayed as a gap. **Never a guessed compromise.**
+
+**There is no fake validator here.** The CLI cannot parse intent, so it does not
+pretend to. It does not detect a user rule that would break a structural rule.
+It **declares** the boundary — in `orc rules`, at the top of every dispatched
+slice, and in the panel. This is the same decision `orc doc rules` made, and for
+the same reason: a validator that sometimes works is worse than none.
+
+---
+
+## What reads these packs
+
+- `orc rules slice --lane <lane>` is the **only** assembler. No skill builds the
+  card itself, so no two lanes can drift.
+- `../phases/rules.md` is the phase that injects it.
+- `orc rules lint` checks the mechanically checkable subset and says, in every
+  mode, how many rules it did **not** check.
+- `/orc-doc` reads **none** of this. That lane has its own ledger, written with
+  `orc doc rules`, and its own frozen-per-document mechanic. The two surfaces
+  never mix.

package/templates/skills/_shared/rules/code.md

@@ -0,0 +1,229 @@
+<!-- orc-rules:pack id=code prefix=OSC layer=code -->
+
+# ORC RULES · Code (`OSC`)
+
+> **READ-ONLY.** This file ships with ORC and changes only with `orc update`.
+> Your own rules go in `.claude/orc/rules.md`, and **yours win** wherever the two
+> disagree.
+
+**Applies to** source an agent writes or edits.
+
+**Precedence note.** The project's CODE house rules
+(`../phases/house-rules.md` and the project's own `CLAUDE.md` P0) beat this pack
+and beat the user ledger. This pack never restates a house rule; where one
+already covers the ground, the rule below cites it.
+
+**Source.** Andrej Karpathy's `CLAUDE.md` ·
+[`BioInfo/slopless`](https://github.com/BioInfo/slopless) ·
+Miqdad Badjuber — [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop), the `antislop-code` skill (MIT) ·
+[Specification and Detection of LLM Code Smells](https://arxiv.org/html/2512.18020v1) ·
+[AI-Generated Smells](https://arxiv.org/html/2605.02741v1) ·
+[Investigating the Smells of LLM Generated Code](https://arxiv.org/pdf/2510.03029).
+Full attribution in `CREDITS.md`.
+
+---
+
+### OSC-01 · HARD · A comment never restates the code
+
+Delete a comment that repeats what the next line, the declaration or the
+signature already shows: `// Initialize the variable` above `let count = 0`,
+`// User class` above `class User {}`, `const userAge = 25; // User age is 25`.
+
+It doubles the reading load and adds nothing. Remove the comment. Leave the code.
+
+### OSC-02 · HARD · No decorative separator
+
+No banner built from repeated characters, no ALL-CAPS section label, no
+box-drawn header: `// ==========`, `// -------- WORKFLOW --------`,
+`/* ---- ROUTES ---- */`.
+
+The decoration is the message, and the message is "generated". Use one plain
+line, or nothing.
+
+Checked by `orc rules lint`.
+
+### OSC-03 · HARD · No workflow narration
+
+No `// Step 1: Validate input`, `// Step 2: Process`, `// First…`, `// Next…`,
+`// Finally…`. The control flow is already visible.
+
+If the flow is genuinely hard to follow, that is a structure problem, not a
+missing comment.
+
+Checked by `orc rules lint`.
+
+### OSC-04 · HARD · No empty label
+
+No `// Main logic`, `// Core logic`, `// Business logic`, `// Helper function`,
+`// Entry point`, `// Error handling`, `// Note: this is important`,
+`// Important: please read`.
+
+The label names a category, not a fact. "Note: retries happen only on 5xx" earns
+its place. "Note: this is important" does not.
+
+Checked by `orc rules lint`.
+
+### OSC-05 · HARD · A TODO names a task
+
+No `// TODO: improve this`, `// Future improvements`, `// Additional
+optimization can be added here`, `// Add more validation`.
+
+A vague TODO names a feeling, not a task. Keep a TODO only when it says what to
+do and carries enough context to act on. Otherwise delete it.
+
+Checked by `orc rules lint`.
+
+### OSC-06 · HARD · No decorative emoji in code
+
+No emoji as decoration in a comment, a log line or an identifier: `// ✅
+Validation`, `// 🚀 Performance`, `// 🔒 Security`. Emoji is visual noise in
+source, and that exact set is the generated vocabulary.
+
+Carve-out: a string the product actually renders to a user, and a test asserting
+on it.
+
+Checked by `orc rules lint`.
+
+### OSC-07 · HARD · No end markers
+
+No `} // end if`, `# End of function`, `// End processOrder`. The closing brace
+already ends the block.
+
+Checked by `orc rules lint`.
+
+### OSC-08 · LOCK · One line per comment
+
+One line. Two only when the second carries a new fact. Never three.
+
+A person leaves a note; a generator writes a case. Cut the reasoning chain, the
+issue number and the version history. Keep the constraint: the platform trap,
+the silent failure, the protocol rule, the performance cost.
+
+**Value is not length.** A comment that legitimately earns its place still does
+not earn a paragraph.
+
+### OSC-09 · HARD · Comments explain why, never what
+
+Never strip a comment that carries: business logic and intent · an architectural
+decision · a security consideration · a performance trade-off · concurrency
+behaviour · a protocol detail · an API contract · a workaround · an edge case or
+assumption · a licence or legal notice.
+
+```js
+// Stripe may retry webhook deliveries for up to three days.
+// Ignore duplicate events using the event ID.
+```
+
+That comment stays. A comment earns its place when it explains something the
+code does not already show.
+
+### OSC-10 · HARD · No speculative abstraction
+
+Minimum code that solves the stated problem. No helper for a one-time operation.
+No abstraction for a single call site. No configurability nobody asked for. No
+design for a hypothetical future requirement.
+
+Three similar lines of code beat a premature abstraction.
+
+### OSC-11 · HARD · No defence against impossible states
+
+No error handling, fallback or validation for a scenario that cannot happen.
+Trust internal code and framework guarantees.
+
+Validate at system boundaries only: user input, external APIs, parsed files, and
+anything crossing a process boundary.
+
+### OSC-12 · HARD · No backwards-compatibility shim
+
+When the code can just change, change it. No feature flag, no compatibility
+layer, no `_unused` rename, no re-export of a moved type, no `// removed`
+tombstone.
+
+If it is unused, delete it completely.
+
+### OSC-13 · HARD · Surgical
+
+Every changed line traces directly to the request. Do not improve adjacent code,
+comments or formatting. Do not refactor what is not broken. Do not add
+docstrings or type annotations to code you did not change.
+
+Cites house card rule 1. Where the house card and this rule differ, the house
+card wins.
+
+### OSC-14 · HARD · Pre-existing dead code: mention, do not delete
+
+Remove the imports, variables and functions **your** change left unused. Report
+any other dead code you notice; do not remove it unless asked.
+
+### OSC-15 · PURPOSE · Method length
+
+A function longer than the file's own norm is split, or the reason is written in
+one line.
+
+Stronger models write longer methods, not shorter ones: they consolidate complex
+logic into a single procedural block because that is locally the most probable
+continuation. This rule is the counterweight.
+
+### OSC-16 · PURPOSE · No Modular Mirage
+
+New files that spread one behaviour across the tree produce structural
+modularity with no semantic cohesion. If a change adds files, the reason each
+boundary exists is written in one line.
+
+Separating files is not the same as separating concerns.
+
+### OSC-17 · PURPOSE · No God class, no branch sink
+
+No "manager" or "service" class that centralises every branch. No class whose
+response set spans most of the module. Where one is genuinely right, write the
+reason.
+
+### OSC-18 · HARD · Look before you write a helper
+
+Before adding a helper, a util, a formatter or a validator, search for the one
+that already exists. Redundant reimplementation is the most expensive slop in
+this pack: it compiles, it passes, and it doubles the maintenance surface
+silently.
+
+### OSC-19 · HARD · Match the existing style
+
+Match the surrounding code's naming, comment density, error handling and file
+layout, even where you would do it differently. The cached project pattern
+(`orc pattern`) is the reference when one exists.
+
+### OSC-20 · PURPOSE · LLM-calling code is pinned and bounded
+
+When the task writes code that calls a model, each of these is done or the
+reason is written:
+
+- Pin the model **version**, never a bare provider alias.
+- Set `temperature` explicitly. Provider defaults differ and change.
+- Bound max tokens, timeouts and retries. Unbounded is not "no limit", it is an
+  unknown limit.
+- Send a system message.
+- Enforce a structured output schema where the caller expects fields.
+
+### OSC-21 · HARD · No unrequested artifact files
+
+Do not create a file nobody asked for: `SUMMARY.md`, `IMPLEMENTATION_NOTES.md`,
+`CHANGES.md`, `NOTES.md`, `*_final`, `*_v2`, `*_new`, `*.bak`, `*.old`.
+
+Report in the return. Do not leave a file behind as the report.
+
+Checked by `orc rules lint` on new files.
+
+### OSC-22 · HARD · Introduce no OWASP Top 10 weakness
+
+Injection, broken access control, insecure deserialisation, secrets in source,
+missing authorisation on a new endpoint, unvalidated redirect. If you notice
+insecure code you wrote, fix it in the same slice and say so in the return.
+
+---
+
+## Not a ban — keep these
+
+- Every comment on the `OSC-09` list, at whatever length its facts require.
+- Validation at a real system boundary (`OSC-11` is about impossible states, not
+  about untrusted input).
+- An abstraction with two or more real call sites today.
+- Defensive code the project's own pattern already established (`OSC-19` wins).

package/templates/skills/_shared/rules/delivery.md

@@ -0,0 +1,114 @@
+<!-- orc-rules:pack id=delivery prefix=OSD layer=core -->
+
+# ORC RULES · Delivery (`OSD`)
+
+> **READ-ONLY.** This file ships with ORC and changes only with `orc update`.
+> Your own rules go in `.claude/orc/rules.md`, and **yours win** wherever the two
+> disagree.
+
+**Applies to** what an agent reports about its own work: a subagent return, a
+phase report, a gate verdict, a ship summary, and what it says in chat.
+
+This pack is in the **`core`** layer, so it rides in every slice of every lane
+that carries rules at all. Prose style is optional in some lanes. Honesty is not.
+
+**Source.** [`ehmo/slopkit`](https://github.com/ehmo/slopkit), the `slopgent`
+skill · Miqdad Badjuber — [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop) R-35 ·
+[`BioInfo/slopless`](https://github.com/BioInfo/slopless) quality gates.
+Full attribution in `CREDITS.md`.
+
+---
+
+### OSD-01 · HARD · Separate what changed from what is verified
+
+Two different facts, always reported as two facts.
+
+```
+Edited verifyToken at auth.ts:42. Tests not run yet.
+```
+
+Not "fixed the token bug". Editing is an observation. Fixing is a claim, and a
+claim needs a run behind it.
+
+### OSD-02 · HARD · Never report an unrun tool
+
+Never say a command ran, a test passed, a build succeeded, a file was read or a
+page was fetched when it did not happen in this session. Not as a summary, not
+as a plan restated in the past tense, not as an inference from the diff.
+
+This is the single most damaging rule in the pack to break, because everything
+downstream trusts it.
+
+### OSD-03 · HARD · No invented confidence
+
+Cut "this should work now", "definitely fixed", "should be perfect", "that ought
+to do it". Confidence is reported from evidence or it is not reported.
+
+Say what you observed and what remains unknown.
+
+### OSD-04 · HARD · Cut empty hedges, keep load-bearing caveats
+
+The two look alike and are opposites.
+
+- **Empty hedge**, cut it: "this might possibly help", "hopefully that works".
+- **Load-bearing caveat**, keep it: "this only covers the JSON path; the
+  multipart branch is untested", "this assumes the column is already indexed".
+
+The test is whether a reader could act on it. Scope, risk and uncertainty are
+load-bearing. A "be concise" instruction cuts both; this rule cuts one.
+
+### OSD-05 · HARD · No apology theatre
+
+State the cause and the fix. No "I apologise for the confusion", no "you're
+absolutely right, my mistake", no paragraph of contrition before the correction.
+
+One correction, plainly, then continue.
+
+### OSD-06 · LOCK · An estimate names its driving variable
+
+Never anchor on human-effort time ("this would take a developer two days").
+Name what actually creates the uncertainty — file count, test-suite size, build
+repetitions, number of call sites — then pin it with a measurement where one
+exists.
+
+### OSD-07 · LOCK · No trailing recap
+
+No closing paragraph restating what was just done. The user reads the diff and
+the return. A recap is a second copy of information they already have.
+
+Report what is **unfinished**, **unverified** or **decided**. Not what is visible.
+
+### OSD-08 · HARD · An honest partial beats a false done
+
+Report what is unmet. Never round up, never mark a criterion met because
+everything around it is. A task that is 80% done is reported as 80% done with
+the missing 20% named.
+
+Cites house card rule 6.
+
+### OSD-09 · LOCK · One issue at a time
+
+When raising a problem that needs the user, raise one. A list of five concerns
+in one turn gets one answer covering none of them.
+
+Exception: a batch the user explicitly asked to be batched, and a round of
+questions in an interview phase, where the format is the point.
+
+### OSD-10 · HARD · No verification theatre
+
+A PASS with no record of what was actually exercised is not a PASS.
+
+Report the check element by element: the command that ran and its exit code, the
+test names, the click-through if it was a UI, the file and line for each
+criterion. If the deliverable could not be run, say so and say that the check
+was code inspection instead. Never imply a run that did not happen.
+
+---
+
+## Not a ban — keep these
+
+- Every caveat on the `OSD-04` load-bearing list.
+- An explicit "I do not know" or "I did not check".
+- A one-line correction of a real earlier error.
+- The exact command, path, error code and exit status. Those are the evidence,
+  and they are never clutter.

package/templates/skills/_shared/rules/ui.md

@@ -0,0 +1,139 @@
+<!-- orc-rules:pack id=ui prefix=OSU layer=ui -->
+
+# ORC RULES · UI (`OSU`)
+
+> **READ-ONLY.** This file ships with ORC and changes only with `orc update`.
+> Your own rules go in `.claude/orc/rules.md`, and **yours win** wherever the two
+> disagree.
+
+**Applies to** front-end work only. This pack rides **per task**, never per lane:
+the orchestrator adds it to a slice whose declared files are front-end. A UI rule
+in a backend slice is tokens paid for nothing.
+
+**This is a filter, not a style guide.** It prescribes no colour, no typeface and
+no layout. It rejects **technique without purpose**. Where the project has a
+design direction — a `DESIGN.md`, a brand guide, a design system — that
+direction is the identity and this pack only filters on top of it. A bold palette
+is identity. A blue-to-purple gradient chosen because it was the default is slop.
+
+**Source.** Miqdad Badjuber — [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop), rules R-01 to R-38 (MIT).
+Full attribution in `CREDITS.md`.
+
+---
+
+### OSU-01 · HARD · No dead controls
+
+Every interactive element does something real, or it does not exist:
+
+- a link or button that reaches a destination that exists
+- a modal that opens and closes, and closes on `Escape`
+- a toggle that changes state
+- an external action (`mailto:`, a real URL)
+- a form that submits and shows feedback
+
+A button that does nothing is a defect, not decoration. A nav item pointing at a
+section that does not exist is the same defect. If it cannot have a destination
+yet, remove it, or label it "Coming soon" **and** leave a `TODO` that names the
+task (`OSC-05`).
+
+### OSU-02 · HARD · Three states minimum
+
+Any view that displays data has an **empty** state, a **loading** state and an
+**error** state. A UI built only for the ideal condition is not finished.
+
+These are not extras. They are part of the view.
+
+### OSU-03 · HARD · Accessible by default
+
+- WCAG AA contrast: 4.5:1 for body text, 3:1 for large text (18px+). Test across
+  the whole area the text crosses, not one point.
+- Every interactive element reachable with `Tab` and `Shift+Tab`, in visual
+  order, and operable with `Enter` or `Space`.
+- Every focused element has a visible focus indicator.
+- Never `outline: none` or `outline: 0` without a better replacement.
+
+A UI that needs a mouse is unfinished.
+
+Partly checked by `orc rules lint` (`outline: none` with no replacement).
+
+### OSU-04 · HARD · Real content or an honest placeholder
+
+No fabricated testimonial, statistic, customer logo, team member, review, or
+security or compliance claim. No number without a real source.
+
+A placeholder is written as what it is: `[REAL DATA]`, `[LOGO]`, "Coming soon".
+Never disguised as final.
+
+**An empty section beats a fabricated one.** If there are no testimonials, there
+is no testimonials section.
+
+### OSU-05 · LOCK · No generic CTA
+
+"Get Started", "Learn More", "Try Now", "Explore", "Discover" name no action.
+Name the action: "Start the free trial", "Watch the 2-minute demo", "Create an
+account".
+
+### OSU-06 · HARD · No buzzword UI copy
+
+Never in shipped interface text: "AI Powered" · "Next Generation" ·
+"Revolutionary" · "Seamless" · "Cutting Edge" · "Intelligent" · "Ultimate" ·
+"Powerful" · "Effortless" · "Supercharged".
+
+Say what it does. Show evidence, not adjectives.
+
+Checked by `orc rules lint`.
+
+### OSU-07 · PURPOSE · Decoration needs a written reason
+
+Each of these is **allowed** and fails only as an unexplained default. Write the
+one-line reason it serves hierarchy, identity or readability:
+
+- gradient as a primary colour (blue→purple, blue→cyan, purple→pink especially)
+- glassmorphism · **dose cap: at most two elements**, never navbar + cards +
+  modal + sidebar together
+- glow · **dose cap: at most two elements**
+- capsule badge with no real status behind it
+- a button arrow as every button's identity
+- grid, dot, blueprint or graph-paper background
+- sparkle, star, magic, lightning, diamond, orb or robot as a feature icon
+- an animation stack (fade-up + float + scale + bounce) on everything
+- a generic illustration set with no connection to the product
+
+A gradient that separates one level of hierarchy from another is craft. The same
+gradient covering the page is slop. The technique is not the problem.
+
+### OSU-08 · LOCK · Do not clone a named product
+
+Do not build a visual that copies another product's look unless the user asked
+for it by name. References are inspiration, not a template.
+
+Models default to cloning the products that dominate their training data. Notice
+when that is what is happening.
+
+### OSU-09 · HARD · Mobile is part of the design
+
+No horizontal overflow. Text stays inside its container. Cards do not collide or
+clip. The navbar stays usable. Tap targets meet 44px. Spacing stays consistent
+across breakpoints.
+
+Responsiveness is not an add-on and not a follow-up task.
+
+### OSU-10 · HARD · Every decision has a one-line reason
+
+Before calling a UI done, write one line for each major decision: why this
+colour, this layout, this typeface, this spacing, this card, this icon.
+
+If the reason cannot be written in one line, the decision is not settled. This
+is the keystone of the pack — it is what `OSU-07` checks against, and it is the
+whole mechanism by which "technique with purpose" is distinguishable from
+"technique by default".
+
+---
+
+## Not a ban — keep these
+
+- Anything the project's own design direction specifies. Identity is not slop.
+- A technique with its reason written. That is the pass condition, not an
+  exception to it.
+- A deliberate uniform layout, when uniformity is the stated choice rather than
+  the default that happened.