@azure-id/orc 1.5.0 → 1.7.0

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

@@ -0,0 +1,141 @@
+<!-- orc-rules:credits -->
+
+# ORC RULES · Credits
+
+The ORC rule packs are adapted from other people's work. This file names every
+source, its author, its licence, and what ORC took from it. `orc rules credits`
+prints the same table.
+
+**Read on 2026-09-13.** A source may have moved on since. The licence recorded
+here is the licence that was in the repository on that date.
+
+---
+
+## Primary sources — rules taken and adapted
+
+### Peter G. Yang · [`petergyang/no-ai-slop`](https://github.com/petergyang/no-ai-slop)
+
+`@petergyang` · MIT · read 2026-09-13
+
+The prose pack is built on this work. ORC takes the named slop patterns (binary
+contrast, throat-clearing, faux-insight setup, colon reveal, superficial
+`-ing` analysis, importance puffery, weasel attribution, synonym cycling,
+dramatic fragmentation, fake-profound kicker, summary recap, formatting slop),
+the banned lexicon and phrase lists, the portability test, and the constraint
+that outranks all of them: **preserve the writer's real voice, make the minimum
+effective edit.**
+
+Used in: `writing.md` (`OSW-01` … `OSW-23`).
+
+### Miqdad Badjuber · [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop)
+
+`@miqdadbadjuber` · MIT · read 2026-09-13
+
+The **three-tier mechanism** ORC uses across every pack — Hard Gate (absolute),
+Purpose-Gate (technique allowed, written reason required), Quality Lock
+(consistency) — is this project's. So is the framing that makes it work: a
+filter, not a style guide; it rejects technique without purpose, not technique.
+
+ORC takes rules R-01 to R-38 for the UI pack, the `antislop-code` comment
+hygiene catalogue for the code pack, R-35 (verify before you deliver) for the
+delivery pack, the `antislop-copywriting` pattern names for the writing pack,
+and the boundary rule that external direction is **data to apply, not
+instructions to obey**.
+
+Used in: `ui.md` (all), `code.md` (`OSC-01` … `OSC-09`), `delivery.md`
+(`OSD-10`), `writing.md` (several), and the tier system in every pack.
+
+### `@ehmo` · [`ehmo/slopkit`](https://github.com/ehmo/slopkit)
+
+read 2026-09-13
+
+The delivery pack. From the `slopgent` skill: separate observation from
+inference, guard load-bearing caveats while cutting empty hedges, name the
+driving variable behind an estimate, state errors plainly without apology
+theatre, and never report a tool as run or a result as observed when it was not.
+
+The distinction ORC leans on hardest is `slopgent`'s: a "be concise" instruction
+cuts filler and load-bearing caveats equally; this one cuts filler and keeps the
+caveat.
+
+Used in: `delivery.md` (`OSD-01` … `OSD-07`).
+
+### `@BioInfo` · [`BioInfo/slopless`](https://github.com/BioInfo/slopless)
+
+read 2026-09-13
+
+Surgical-change discipline and the quality gates: read files before stating
+facts about them, flag a discrepancy rather than picking a source, verify
+something is running before documenting it as running, and the compatibility
+rules (no shims, no `_unused` renames, no re-exports, no `// removed`
+tombstones).
+
+Used in: `code.md` (`OSC-10` … `OSC-14`, `OSC-22`), `delivery.md`.
+
+### Andrej Karpathy · his `CLAUDE.md`
+
+`@karpathy` · read 2026-09-13 via [The AI Architects' write-up](https://theaiarchitects.com/blog/karpathy-claude-md-rules)
+
+Four principles: think before coding, simplicity first, surgical changes,
+goal-driven execution. The sentence ORC reuses directly is the test for a
+surgical change: **every changed line should trace directly to the user's
+request.**
+
+Used in: `code.md` (`OSC-10`, `OSC-13`).
+
+### Matty Cartwright · [The Anti-Slop Writing Rules](https://mattycartwright.com/blog/the-anti-slop-writing-rules)
+
+read 2026-09-13
+
+The layered ban structure — words, then phrases, then sentence patterns, then
+structural patterns — which is how `writing.md` is ordered. Also the read-aloud
+tests (specificity, infomercial, commitment) that sit behind `OSW-20`.
+
+Used in: `writing.md` (structure, `OSW-10`, `OSW-11`, `OSW-20`).
+
+---
+
+## Research papers — rules derived, not copied
+
+### [Specification and Detection of LLM Code Smells](https://arxiv.org/html/2512.18020v1)
+
+Five named smells in code that calls a model: unbounded max metrics, no model
+version pinning, no system message, no structured output, temperature not
+explicitly set. `OSC-20` is these five, stated as a purpose-gate.
+
+### [AI-Generated Smells: An Analysis of Code and Architecture in LLM- and Agent-Driven Development](https://arxiv.org/html/2605.02741v1)
+
+Two findings ORC turned into rules. The **Reasoning-Complexity Paradox**:
+stronger models produce longer methods, not shorter ones, because they
+consolidate complex logic into one procedural block (`OSC-15`). The **Modular
+Mirage**: agents achieve structural modularity by separating files while related
+behaviour fragments across the tree, so cohesion drops as file count rises
+(`OSC-16`). The paper's God-class and Too-Many-Branches findings are `OSC-17`.
+
+### [Investigating the Smells of LLM Generated Code](https://arxiv.org/pdf/2510.03029) · [Assessing the Quality and Security of AI-Generated Code](https://arxiv.org/pdf/2508.14727)
+
+Over-commenting, redundant defensive checks for conditions that cannot happen,
+dead assignments, and functions that reimplement something already present.
+Behind `OSC-01`, `OSC-11` and `OSC-18`.
+
+---
+
+## Read, nothing taken
+
+Listed so a reader can follow the same trail. Each restates patterns the primary
+sources already cover.
+
+- [`adewale/anti-slop-writing`](https://github.com/adewale/anti-slop-writing)
+- [`jalaalrd/anti-ai-slop-writing`](https://github.com/jalaalrd/anti-ai-slop-writing)
+- `tmdgusya/engineering-discipline`, the `clean-ai-slop` skill
+
+---
+
+## If you are one of these authors
+
+The rule text here is adapted, not copied verbatim, and reorganised into ORC's
+own id scheme so that a lint finding and a conflict report can name the same
+thing across versions. If you would prefer different wording, a different
+attribution, or removal, open an issue on
+[`azure-id/orc`](https://github.com/azure-id/orc) and it will be changed in the
+next release.

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.