@aryacode/dsh-engineering 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.9.1] - 2026-10-27
+
+### Fixed
+
+- **0.9.0 could stop AryaCode from booting.** The new row was inserted with `id: resources`, and `resources`
+  is the name of a harness service other entries wait for; inserting a row under that id displaced the
+  provider, so the boot reported `44 entries did not activate` and the application had to start with plugins
+  disabled. The row is now `engineering-resources` (namespaced like every other non-product row), and a test
+  rejects any future row id that matches a harness service name.
+- **The resources row can no longer break a boot even if it fails.** Its `apply()` wraps registration and
+  skill mounting in a guard that reports and continues; a reference surface must never be load-bearing.
+- **The corpus is now actually shipped.** The assembler copied only `lib/` and `SKILL.md`, so the vendored
+  package had no `corpus/`, `index.json` or `SOURCE.json` and `engineering_reference` would have failed at
+  the first call. `scripts/assemble.mjs` now copies those files, and the packed artifact is checked for them.
 ## [0.9.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -69,7 +69,7 @@ down:
 | `ftview` | FactoryTalk View ME read, guidance and edits; optionally the Studio handoff | `edit` (on), `studio` (on) |
 | `mwi` | MotionWorks IEC session, reads, verify, guidance and the edits | `workspace` (empty), `edit` (on) |
 | `viewers` | ladder + ME display previews | — |
-| `resources` | the engineering corpus, the house-style profile and the `engineering-standards` skill; no project of its own | `reference` (on) |
+| `engineering-resources` | the engineering corpus, the house-style profile and the `engineering-standards` skill; no project of its own | `reference` (on) |
 | `optix` | FactoryTalk Optix Studio authoring and the NetLogic reader | `bridgeUrls` (8768), `bridgeToken` (empty), `allowWrites` (on), `allowDestructive` (on), `allowInvoke` (on), `preview` (on), `allowPreviewInput` (on), `cdpUrl`, `previewUrl`, `ocrExecutable` (empty), `ocrLanguage` (`eng`), `ocrTessdataDirectory` (empty), `netlogic` (on) |
 
 **Why the row list collapsed.** The Plugins page lists a bundle's rows flat and skips `cordis:group`

package/cordis.patch.yml

@@ -42,7 +42,7 @@
     # Rockwell, Yaskawa, HMI and craft rules), a house-style profile read from the
     # open project, and the engineering-standards skill that says to read both
     # before authoring. Disable it in a lean profile; it adds no product row.
-    - id: resources
+    - id: engineering-resources
       name: '@aryacode/dsh-engineering/resources'
 
     # FactoryTalk Optix: vendored like the other three products, so one install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",

package/vendor/resources/LICENSE-CONTENT.md

@@ -0,0 +1,17 @@
+# Content licence
+
+The pages under `corpus/` are written for this bundle. They summarise engineering practice and
+implementation rules; they do **not** reproduce the text of any standard or vendor manual.
+
+Each page names its basis in front matter (`basis:`). Those names are attribution, not endorsement:
+
+- **IEC 61131-3** — the programmable-controller languages the pages describe (ST, LD, FBD, SFC).
+- **ISA-101** — human-machine interface design, especially the high-performance HMI model.
+- **ISA-18.2** — alarm management lifecycle and presentation.
+- **Rockwell / Yaskawa / FactoryTalk** — vendor documentation and field practice for those products.
+
+Rule IDs (`CRAFT-NAME-01`, `VIEW-HPM-02`, …) identify this bundle's own rules. They are not the
+standards' clause numbers, and a finding that cites one is this bundle's opinion about your code, not a
+certification.
+
+Standards documents are copyrighted. If you need the normative text, obtain it from the issuing body.

package/vendor/resources/SOURCE.json

@@ -0,0 +1,6 @@
+{
+  "corpus": 1,
+  "built": "2026-10-27T16:39:24.478Z",
+  "digest": "49ea7864020a72c7affc8f13bbc353a21226e63c1d973111e05898a525dd91de",
+  "pages": 34
+}

package/vendor/resources/corpus/craft/craft-comments-and-intent.md

@@ -0,0 +1,29 @@
+---
+id: craft-comments-and-intent
+title: Comments that explain why
+domain: craft
+level: intro
+basis: [field practice]
+tags: [comments, intent]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-COMMENT-01, CRAFT-COMMENT-02, CRAFT-COMMENT-03]
+---
+## Principle
+
+A comment that repeats the code is noise; a comment that explains the decision is maintenance.
+
+## Rules
+
+- **CRAFT-COMMENT-01** Comment the intent and the constraint (`// 250 ms: debounce for a bouncing
+  proximity switch`), not the instruction.
+- **CRAFT-COMMENT-02** Every non-obvious rung gets a rung comment; every routine gets one line of purpose.
+- **CRAFT-COMMENT-03** Record the change reason and date where the project does that, and never leave
+  commented-out logic as the only record.
+
+## Apply
+
+Write the comment as if the reader has the drawing but not the meeting.
+
+## Anti-patterns
+
+`// set bit`; a wall of comments at the top that no one updates; TODOs without an owner.

package/vendor/resources/corpus/craft/craft-debounce-and-filtering.md

@@ -0,0 +1,29 @@
+---
+id: craft-debounce-and-filtering
+title: Debounce, hysteresis and filtering
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [filter, debounce, hysteresis]
+applies_to: [l5x, mwi]
+rules: [CRAFT-FILTER-01, CRAFT-FILTER-02]
+---
+## Principle
+
+Real sensors are noisy and real processes overshoot. Filter in the PLC with a stated time, not in the
+operator's head.
+
+## Rules
+
+- **CRAFT-FILTER-01** Debounce discrete inputs with a timer sized from the sensor's bounce, and document
+  the time next to the timer.
+- **CRAFT-FILTER-02** Use hysteresis for thresholds that would otherwise chatter, and keep the band in one
+  place per signal.
+
+## Apply
+
+When a value "flickers" on the HMI, find the filter time before adding another one downstream.
+
+## Anti-patterns
+
+Filters stacked three deep with no owner; a debounce so long it hides a real trip.

package/vendor/resources/corpus/craft/craft-fault-handling.md

@@ -0,0 +1,32 @@
+---
+id: craft-fault-handling
+title: Faults: detect, latch, annunciate, reset
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [faults, reset, diagnostics]
+applies_to: [l5x, mwi, optix]
+rules: [CRAFT-FAULT-01, CRAFT-FAULT-02, CRAFT-FAULT-03]
+---
+## Principle
+
+A fault is a fact about the machine, not a message. The logic must detect it, remember it, tell someone,
+and define recovery.
+
+## Rules
+
+- **CRAFT-FAULT-01** Detect at the source and set one bit for one cause; do not infer a fault from a
+  downstream symptom.
+- **CRAFT-FAULT-02** Latch with a reset that only succeeds when the cause is gone; a reset that always
+  clears is a way to run a broken machine.
+- **CRAFT-FAULT-03** Record first-out and the time, and surface it where the operator acts.
+
+## Apply
+
+For each fault, write the four sentences: what detects it, what it stops, how it is shown, how it is
+cleared.
+
+## Anti-patterns
+
+Faults that clear themselves on the next scan; one reset for unrelated faults; a fault with no operator
+message.

package/vendor/resources/corpus/craft/craft-naming.md

@@ -0,0 +1,30 @@
+---
+id: craft-naming
+title: Naming that survives the project
+domain: craft
+level: intro
+basis: [field practice]
+tags: [naming, readability]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-NAME-01, CRAFT-NAME-02, CRAFT-NAME-03]
+---
+## Principle
+
+Names are the interface between the code and everyone who will read it after you.
+
+## Rules
+
+- **CRAFT-NAME-01** One case convention per project (PascalCase for tags is common; follow the project).
+  Consistency matters more than the choice.
+- **CRAFT-NAME-02** Booleans read as assertions (`MotorRunning`, `DoorClosed`), not as questions or
+  negatives (`NotStopped`).
+- **CRAFT-NAME-03** Put units and ranges in the description, not hidden in the name (`Temp_C`, `Speed_mps`).
+
+## Apply
+
+When a name does not fit the project's scheme, prefer the project's scheme; when adding a new concept, add
+it to the scheme and document the prefix.
+
+## Anti-patterns
+
+`tmp`, `data`, `flag`; names that encode the wiring (`DI_3`); renaming a published tag without a migration.

package/vendor/resources/corpus/craft/craft-review-checklist.md

@@ -0,0 +1,29 @@
+---
+id: craft-review-checklist
+title: Pre-handover review checklist
+domain: craft
+level: practitioner
+basis: [field practice]
+tags: [review, handover, checklist]
+applies_to: [l5x, ftview, mwi, optix]
+rules: [CRAFT-REVIEW-01, CRAFT-REVIEW-02]
+---
+## Principle
+
+Handover is a review, not a save. Walk the same list every time, and record what was not checked.
+
+## Rules
+
+- **CRAFT-REVIEW-01** Before handover: every fault has a message and a reset, every screen has a way back,
+  every changed tag is documented, and the backup is taken and named.
+- **CRAFT-REVIEW-02** Distinguish "checked" from "not checked" in the handover note; an unchecked item is
+  not a pass.
+
+## Apply
+
+Run the product's own checks first, then `engineering_review`, then the human walkthrough with the
+operator.
+
+## Anti-patterns
+
+A handover that lists only what changed; signing off a screen nobody navigated.

package/vendor/resources/corpus/craft/craft-units-and-ranges.md

@@ -0,0 +1,32 @@
+---
+id: craft-units-and-ranges
+title: Units, ranges and engineering values
+domain: craft
+level: intro
+basis: [field practice]
+tags: [units, range, scaling]
+applies_to: [l5x, mwi, optix]
+rules: [CRAFT-UNIT-01, CRAFT-UNIT-02, CRAFT-UNIT-03]
+---
+## Principle
+
+Every number the operator sees should have a unit, a range and a resolution. A number without those is a
+guess.
+
+## Rules
+
+- **CRAFT-UNIT-01** Carry raw counts and engineering units as separate values with one documented
+  conversion.
+- **CRAFT-UNIT-02** State the valid range and what happens outside it (clamp, fault, ignore) at the
+  conversion point.
+- **CRAFT-UNIT-03** Display the unit next to the value and keep the decimal places consistent with the
+  resolution.
+
+## Apply
+
+When a value moves to a new screen, move its unit and range with it.
+
+## Anti-patterns
+
+Two conversions for one signal; a percentage displayed as a fraction; more decimal places than the sensor
+has.

package/vendor/resources/corpus/iec/iec-ld-fbd-equivalence.md

@@ -0,0 +1,31 @@
+---
+id: iec-ld-fbd-equivalence
+title: Ladder, FBD and ST: same logic, different reading
+domain: iec
+level: intro
+basis: [IEC 61131-3]
+tags: [ladder, fbd, st, translation]
+applies_to: [l5x, mwi]
+rules: [IEC-LANG-01, IEC-LANG-02]
+---
+## Principle
+
+The languages are notations, not designs. Choose the one that makes the intent obvious and keep one
+implementation of each behaviour.
+
+## Rules
+
+- **IEC-LANG-01** Ladder for permissives, interlocks and outputs an electrician will trace; ST for
+  arithmetic, loops and state machines; FBD for signal flow. Do not translate a whole routine because you
+  prefer another language.
+- **IEC-LANG-02** One behaviour, one implementation. A seal-in duplicated in LD and ST will diverge; if a
+  block is reused, make it an FB/AOI and call it.
+
+## Apply
+
+When reviewing inherited code, read it in its own language before proposing a rewrite. A "modernisation"
+that changes scan-order semantics is a behaviour change.
+
+## Anti-patterns
+
+ST one-liners that hide three outputs; ladder with arithmetic chains no one can trace.

package/vendor/resources/corpus/iec/iec-sequences-and-sfc.md

@@ -0,0 +1,32 @@
+---
+id: iec-sequences-and-sfc
+title: Sequences, steps and timeouts
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [sequence, sfc, step]
+applies_to: [mwi, l5x]
+rules: [IEC-SEQ-01, IEC-SEQ-02, IEC-SEQ-03]
+---
+## Principle
+
+A sequence is a state machine whose states are process steps. The difference is that each step has a
+completion condition and a timeout.
+
+## Rules
+
+- **IEC-SEQ-01** Give every step a timeout and a defined action on expiry. A sequence that can wait forever
+  is a fault waiting for an operator.
+- **IEC-SEQ-02** Separate the step advance from the step action: advance on `done OR timeout`, act on the
+  current step.
+- **IEC-SEQ-03** Make hold, abort and reset explicit transitions to named states, not flags that freeze
+  the sequence wherever it was.
+
+## Apply
+
+Draw the sequence (states and transitions) before coding it, and keep the drawing with the project. SFC is
+appropriate when the drawing is the specification; a `CASE` machine is simpler when steps share actions.
+
+## Anti-patterns
+
+Advancing on a timer alone; a reset that clears outputs without leaving the step.

package/vendor/resources/corpus/iec/iec-st-structure.md

@@ -0,0 +1,33 @@
+---
+id: iec-st-structure
+title: Structured Text that reads like a specification
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [st, structure, declarations]
+applies_to: [mwi, optix, l5x]
+rules: [IEC-ST-01, IEC-ST-02, IEC-ST-03]
+---
+## Principle
+
+A POU should be readable top to bottom without scrolling sideways: declarations grouped, one intent per
+block, no hidden state. The reader is a maintenance technician at 2 a.m., not the author.
+
+## Rules
+
+- **IEC-ST-01** Group declarations by role (`VAR_INPUT`, `VAR_OUTPUT`, `VAR`), then by purpose, with a
+  comment above each group. Do not interleave.
+- **IEC-ST-02** One POU, one responsibility. A POU that sequences, scales, filters and writes HMI data has
+  four reasons to change; split it.
+- **IEC-ST-03** No side effects in conditions. A call inside an `IF` that changes state makes the scan
+  order part of the logic; call it explicitly, one statement per line.
+
+## Apply
+
+Order the body: input conditioning, permissives, sequence or control, outputs, diagnostics. A reader can
+then stop at the block they need.
+
+## Anti-patterns
+
+Deeply nested `IF` (three levels or more) hiding permissives; magic numbers instead of named constants;
+declarations added wherever there was space.

package/vendor/resources/corpus/iec/iec-state-machines.md

@@ -0,0 +1,33 @@
+---
+id: iec-state-machines
+title: State machines that fail predictably
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [state-machine, case, sequence]
+applies_to: [mwi, l5x]
+rules: [IEC-SM-01, IEC-SM-02, IEC-SM-03]
+---
+## Principle
+
+A state machine is a contract: exactly one state is active, every transition has a cause, and an
+unexpected state is handled rather than ignored.
+
+## Rules
+
+- **IEC-SM-01** Use one integer or enumeration `step` for the active state and a `CASE` (ST) or
+  integer-compare chain (LD) to act on it. Do not scatter `IF step =` tests through the program.
+- **IEC-SM-02** Every `CASE` has an `ELSE` (or a default branch) that forces a known safe state and raises
+  a diagnostic. An out-of-range step must never leave outputs energised.
+- **IEC-SM-03** Entry actions run once on the transition; continuous actions live in the state body. Mixing
+  them makes a re-entry repeat motion.
+
+## Apply
+
+Name states after the machine condition (`Idle`, `Homing`, `Ready`, `Cutting`, `Faulted`), not after
+numbers in the HMI. Keep a parallel `stepTime` for timeouts.
+
+## Anti-patterns
+
+Two variables claiming to be the state; timers inside the transition condition; a `GOTO` around the
+`CASE`.

package/vendor/resources/corpus/iec/iec-task-model.md

@@ -0,0 +1,31 @@
+---
+id: iec-task-model
+title: Tasks, scan time and determinism
+domain: iec
+level: specialist
+basis: [IEC 61131-3]
+tags: [task, scan, watchdog]
+applies_to: [mwi, l5x]
+rules: [IEC-TASK-01, IEC-TASK-02, IEC-TASK-03]
+---
+## Principle
+
+The task schedule is part of the program. A control loop that moved to a slower task is a behaviour
+change even when the code is untouched.
+
+## Rules
+
+- **IEC-TASK-01** Put motion and fast interlocks in a fixed-rate task; put HMI handshakes and diagnostics in
+  a slower one. Document the rate next to the POU.
+- **IEC-TASK-02** No unbounded work in a cyclic task: no file I/O, no waiting loops, no long string
+  handling. Bound every loop.
+- **IEC-TASK-03** Size the watchdog from the measured worst case, not the average. A watchdog that fires
+  only under load is doing its job.
+
+## Apply
+
+Record for each task: period, priority, watchdog, worst measured scan, and what happens when it overruns.
+
+## Anti-patterns
+
+Copying a fast task into a slow one and accepting the jitter; hiding a blocking call behind a one-shot.

package/vendor/resources/corpus/iec/iec-types-and-scaling.md

@@ -0,0 +1,32 @@
+---
+id: iec-types-and-scaling
+title: Types, ranges and scaling without surprises
+domain: iec
+level: practitioner
+basis: [IEC 61131-3]
+tags: [types, scaling, real]
+applies_to: [mwi, l5x, optix]
+rules: [IEC-TYPE-01, IEC-TYPE-02, IEC-TYPE-03]
+---
+## Principle
+
+Most field faults blamed on "the PLC" are a divide by zero, an overflow, or a REAL compared with `=`.
+
+## Rules
+
+- **IEC-TYPE-01** Declare the narrowest type that holds the range, and say the range in the comment
+  (`INT 0..1000 mm`). Never rely on the default type.
+- **IEC-TYPE-02** Guard every division and scale: check the divisor, clamp the result, and handle the
+  out-of-range case explicitly.
+- **IEC-TYPE-03** Compare REALs with a tolerance, never with equality. For counters and positions, use
+  integers where the resolution allows.
+
+## Apply
+
+Keep one scale/offset pair per signal, in one place. If two blocks scale the same input, they will
+disagree.
+
+## Anti-patterns
+
+`INT` for a millisecond timer that can exceed 32 s; scaling in the HMI and again in the PLC; a REAL used
+as a state number.

package/vendor/resources/corpus/optix/optix-alarms-and-trends.md

@@ -0,0 +1,30 @@
+---
+id: optix-alarms-and-trends
+title: Alarms and trends in Optix
+domain: optix
+level: practitioner
+basis: [FactoryTalk Optix, ISA-18.2]
+tags: [alarms, trends]
+applies_to: [optix]
+rules: [OPTIX-ALM-01, OPTIX-ALM-02]
+---
+## Principle
+
+Alarms and trends are process evidence. Their configuration is part of the design, not a runtime
+afterthought.
+
+## Rules
+
+- **OPTIX-ALM-01** Configure alarm limits and priorities in the model (type or instance), so every
+  instance inherits a reviewed definition.
+- **OPTIX-ALM-02** Choose trend sampling from the process dynamics, and keep the same time base across
+  pens that will be compared.
+
+## Apply
+
+Review the alarm list as a document: condition, limit, priority, message, action. Trends should answer a
+specific question the operator or engineer has.
+
+## Anti-patterns
+
+Alarms enabled per instance with different limits; trend pens on unrelated time bases.

package/vendor/resources/corpus/optix/optix-bindings-and-expressions.md

@@ -0,0 +1,30 @@
+---
+id: optix-bindings-and-expressions
+title: Bindings and expressions
+domain: optix
+level: practitioner
+basis: [FactoryTalk Optix]
+tags: [bindings, expressions, converters]
+applies_to: [optix]
+rules: [OPTIX-BIND-01, OPTIX-BIND-02, OPTIX-BIND-03]
+---
+## Principle
+
+A binding moves a value; an expression computes one. Mixing them hides where a number comes from.
+
+## Rules
+
+- **OPTIX-BIND-01** Bind raw values point to point; put formatting and unit conversion in a formatter or a
+  converter with a name, not inline in the binding.
+- **OPTIX-BIND-02** Validate expressions with the expression tool before attaching them, and handle the
+  null/empty case explicitly.
+- **OPTIX-BIND-03** Keep one source of truth per value: do not bind and also write the same property from
+  NetLogic.
+
+## Apply
+
+When a value looks wrong, trace binding → converter → source before editing any of them.
+
+## Anti-patterns
+
+Long inline expressions in a property; two writers for one property; conversions that silently round.

package/vendor/resources/corpus/optix/optix-netlogic-usage.md

@@ -0,0 +1,29 @@
+---
+id: optix-netlogic-usage
+title: When to use NetLogic
+domain: optix
+level: specialist
+basis: [FactoryTalk Optix]
+tags: [netlogic, csharp]
+applies_to: [optix]
+rules: [OPTIX-NL-01, OPTIX-NL-02]
+---
+## Principle
+
+NetLogic is C# inside the HMI. Use it for what bindings cannot express, and keep it small enough to test.
+
+## Rules
+
+- **OPTIX-NL-01** Prefer bindings and expressions for display logic; use NetLogic for calculations, state
+  and integration that must run regardless of the visible screen.
+- **OPTIX-NL-02** Keep NetLogic free of UI lookups where possible: pass values in, return values out, so it
+  can be reasoned about without the screen.
+
+## Apply
+
+Check the NetLogic cheat-sheet snapshot for the lifecycle and API before writing a new script; the API is
+version-specific.
+
+## Anti-patterns
+
+NetLogic that duplicates PLC logic; scripts that block; UI code that reaches into other screens.

package/vendor/resources/corpus/optix/optix-ui-structure.md

@@ -0,0 +1,29 @@
+---
+id: optix-ui-structure
+title: Optix screens and reusable types
+domain: optix
+level: practitioner
+basis: [FactoryTalk Optix]
+tags: [screens, types, objects]
+applies_to: [optix]
+rules: [OPTIX-UI-01, OPTIX-UI-02]
+---
+## Principle
+
+Optix is object-oriented: types and instances, not copied panels. The screen is a composition of typed
+objects.
+
+## Rules
+
+- **OPTIX-UI-01** Model repeated equipment as a type with instances; screens reference the instance, never
+  a copy of its internals.
+- **OPTIX-UI-02** Keep screen composition (layout) separate from behaviour (bindings, NetLogic); a screen
+  that computes is harder to reuse.
+
+## Apply
+
+Read the type schema before creating objects; the object model decides what a binding can reference.
+
+## Anti-patterns
+
+Copy-pasted panels for each device; logic hidden in a display event; a type per device instance.

package/vendor/resources/corpus/rockwell/rockwell-aoi-and-udt.md

@@ -0,0 +1,32 @@
+---
+id: rockwell-aoi-and-udt
+title: AOIs and UDTs: reuse without hidden coupling
+domain: rockwell
+level: specialist
+basis: [Rockwell]
+tags: [aoi, udt, reuse]
+applies_to: [l5x]
+rules: [ROCK-AOI-01, ROCK-AOI-02, ROCK-AOI-03]
+---
+## Principle
+
+An AOI is a contract with every instance of it. Changing one changes the plant; that is the price of reuse
+and it must be deliberate.
+
+## Rules
+
+- **ROCK-AOI-01** Use an AOI when the logic repeats three or more times and the interface is stable. Two
+  copies are cheaper than a premature abstraction.
+- **ROCK-AOI-02** Put instance state in a UDT member, never in controller-scope globals. Two motors sharing
+  a global fault bit is a latent fault.
+- **ROCK-AOI-03** Version behaviour by adding parameters with defaults, not by editing existing pin
+  semantics; state the change in the AOI description.
+
+## Apply
+
+Document the AOI's states and timing in its description, and keep an instance list. When reviewing, check
+for AOIs with unused pins and for UDTs used as generic bags of tags.
+
+## Anti-patterns
+
+AOI with 40 pins; UDT reused for unrelated equipment; logic that depends on the AOI's internal scan order.

package/vendor/resources/corpus/rockwell/rockwell-fault-and-alarm-words.md

@@ -0,0 +1,31 @@
+---
+id: rockwell-fault-and-alarm-words
+title: Fault and alarm words
+domain: rockwell
+level: practitioner
+basis: [Rockwell]
+tags: [alarms, faults, words]
+applies_to: [l5x, ftview]
+rules: [ROCK-ALM-01, ROCK-ALM-02, ROCK-ALM-03]
+---
+## Principle
+
+An alarm is an operator decision, not a log entry. Grouping alarms into words is fine; hiding their cause
+is not.
+
+## Rules
+
+- **ROCK-ALM-01** One bit per cause, bit numbers fixed and documented; never renumber a published word.
+- **ROCK-ALM-02** Latch the first-out cause and keep it after the condition clears until the operator
+  acknowledges. A cleared bit teaches nothing.
+- **ROCK-ALM-03** Separate trip causes from warnings: trips stop equipment, warnings do not. Do not make
+  every bit a trip.
+
+## Apply
+
+Map each alarm bit to one HMI message and one severity. Check the mapping when an AOI is added.
+
+## Anti-patterns
+
+A word where bit 0 means "any fault"; alarms that reset themselves before the scan writes them; alarm text
+that names the block instead of the cause.