opensquid 0.5.395

package/packs/builtin/examples/multi-clause-drift-detector/skills/drift/skill.yaml

@@ -0,0 +1,60 @@
+# Example — not load-bearing. Worked example for docs/skill-grammar-guide.md.
+#
+# Demonstrates a single structured `if:` clause replacing the prose-only
+# rule documented in ../../BEFORE.md. Exercises three new H-grammar
+# features in one expression:
+#
+#   1. logical `&&` and `||`               — compound clauses
+#   2. allow-listed `len()` function       — array length over primitive results
+#   3. dotted path access on primitive results (`drift_hits.matched`)
+#
+# Primitive return shapes (verified against src/functions/ on 2026-05-25):
+#   text_pattern_match → { matched: string[], phrases: [{ phrase, offset }] }
+#   session_tool_history → { tools: string[], count: number }
+name: drift
+load: preload
+triggers:
+  - kind: stop
+rules:
+  - id: cite-memory-without-verifying
+    kind: track_check
+    process:
+      - call: text_pattern_match
+        args:
+          text_field: assistantText
+          patterns:
+            - per memory
+            - deferred
+            - i remember
+        as: drift_hits
+      - call: text_pattern_match
+        args:
+          text_field: assistantText
+          patterns:
+            - i checked
+            - i ran
+            - i confirmed
+        as: verifications
+      - call: session_tool_history
+        args:
+          scope: current_turn
+          filter_names:
+            - Bash
+            - Read
+            - Grep
+            - mcp__opensquid__recall
+            - mcp__opensquid__inspect_skill
+        as: tool_history
+      - call: verdict
+        if: 'len(drift_hits.matched) > 0 && len(verifications.matched) == 0 && tool_history.count == 0'
+        args:
+          level: warn
+          message: |-
+            Drift signal: assistant cited memory ("per memory" / "deferred" /
+            "i remember") without paired verification language and without
+            calling any verification tool this turn. Run a Bash/Read/Grep or
+            mcp__opensquid__recall/inspect_skill before citing memory.
+prose: |
+  Reference companion to BEFORE.md. The same logic, but enforced by the
+  evaluator at every Stop event instead of held only as guidance for the
+  agent to follow.

package/packs/builtin/examples/tool-history-correlator/BEFORE.md

@@ -0,0 +1,73 @@
+# Tool History Correlator — prose-only version (BEFORE)
+
+This file shows the rule as it would live **without** the H grammar's
+bracket-index access — as English guidance inside SKILL.md `prose:`.
+The next-door `skills/correlator/skill.yaml` is the **AFTER**: the
+same logic compiled to a single-line `if:` clause that the evaluator
+checks at every Stop event.
+
+---
+
+## The rule (prose form)
+
+When the assistant ends a turn (Stop event):
+
+- **IF** more than 5 Bash invocations were issued this turn, AND
+- the most-recent entry in the session tool history is in fact a Bash
+  call,
+
+**THEN** warn the assistant to consolidate consecutive Bash calls into
+one multi-line script (or a `&&`-chained one-liner) so the tool trace
+stays scannable in the transcript.
+
+## Why prose-only was insufficient
+
+The rule needs to access a structured primitive result:
+
+- Threshold comparison: `len(bash_history) > 5` (or `bash_history.count > 5`).
+- Element-identity check: the first element in `bash_history.tools` must
+  be the string `"Bash"`.
+
+Pre-H, the `if:` grammar accepted bare names + a fixed set of equality
+forms hard-coded in the evaluator's regex set. There was no path access
+deeper than a single dot, no array-index access at all, and no `len()`
+function. Any check that needed to read structured primitive output
+either lived as prose or was hoisted into a custom TypeScript primitive
+that did the comparison internally and returned a single boolean.
+
+## What the H grammar unlocks
+
+The AFTER form (`skills/correlator/skill.yaml`) collapses the rule into:
+
+```yaml
+if: 'bash_history.count > 5 && bash_history.tools[0] == "Bash"'
+```
+
+That clause exercises **two grammar features the pre-H regex set could
+not express**:
+
+1. **Numeric comparison on a dotted-path operand** (`bash_history.count > 5`)
+   — pre-H, the numeric-compare regex required a bare identifier on
+   the LHS. Dotted-path access on a comparison operand is new.
+2. **Bracket-index access** (`bash_history.tools[0]`) — pre-H had no
+   `[index]` syntax at all. Arrays could only be checked for emptiness
+   via the `length` special-case on the `length` property name.
+
+## Compression measure
+
+| Form                                        | LOC of the gate | Enforcement                             |
+| ------------------------------------------- | --------------- | --------------------------------------- |
+| Prose (this)                                | ~5 lines        | None — guidance only                    |
+| Custom primitive function in src/functions/ | ~20 lines TS    | Enforced, but requires runtime release  |
+| Structured `if:` with bracket-index access  | 1 line          | Enforced, pack-author authors and ships |
+
+## A note on the bracket-index check
+
+The second clause (`bash_history.tools[0] == "Bash"`) is technically
+redundant given the `filter_names: [Bash]` arg on the primitive call —
+if any tools matched, they're guaranteed Bash. The clause is kept as a
+**defensive check**: if a future task changes the primitive's filter
+semantics (e.g. fuzzy match), the rule fails closed rather than
+silently mis-firing. Pack authors regularly want this kind of
+belt-and-suspenders shape check inside their `if:` clauses; the H
+grammar makes it expressible.

package/packs/builtin/examples/tool-history-correlator/SKILL.md

@@ -0,0 +1,85 @@
+# tool-history-correlator — AFTER (structured)
+
+Three-file example demonstrating the structured-primitive-result access
+pattern enabled by the H grammar's path + bracket-index syntax.
+
+| File                           | Purpose                                                        |
+| ------------------------------ | -------------------------------------------------------------- |
+| `BEFORE.md`                    | Prose-only equivalent + custom-primitive alternative           |
+| `SKILL.md` (this file)         | Reader's guide — what the example demonstrates                 |
+| `manifest.yaml`                | Pack identity (`name` / `version` / `scope` / `goal`)          |
+| `skills/correlator/skill.yaml` | The structured rule itself — single `if:` clause does the work |
+
+## What this example demonstrates
+
+Accessing a primitive's structured return shape — both a scalar field
+(`.count`) and an array element (`.tools[0]`) — inside one `if:`
+clause. Two operator families the pre-H grammar could not express
+combine into a single readable condition.
+
+Reference clause:
+
+```yaml
+if: 'bash_history.count > 5 && bash_history.tools[0] == "Bash"'
+```
+
+## Grammar features exercised
+
+- **Dotted-path access on a comparison operand** — `bash_history.count`
+  feeds the LHS of a numeric comparison. Pre-H, numeric compare
+  required a bare identifier on the LHS.
+- **Bracket-index access (`[0]`)** — array element by integer index.
+  Pre-H, no `[...]` syntax existed.
+- **`&&` (logical AND)** — combine two clauses.
+- **`==` (strict equality)** — string-to-string identity check on
+  `bash_history.tools[0]`. Strict semantics per grammar guide §6
+  Gotchas; no JS-style coercion.
+
+## Primitive return shape used
+
+```typescript
+// src/functions/session_tool_history.ts (verified 2026-05-25)
+{ tools: string[]; count: number }
+```
+
+The example accesses both fields. If a future task changes either
+field name or type, the example must update in lockstep (and so must
+any production pack using the same primitive — the `# Example — not
+load-bearing` header is a self-warning).
+
+### Spec-vs-reality adjustment
+
+The original H.3 spec assumed the primitive returned `.calls[]` with
+each call carrying a `.name` field. The actual primitive returns a
+flat `tools: string[]` array of names. This example uses the real
+shape — `.tools[0]` is a string, not an object — per the H.3
+implementation note that spec example shapes must yield to primitive
+reality, not the other way around.
+
+## How to run it
+
+The example is **not** registered in any `active.json`. To exercise it
+in a dev session:
+
+```bash
+# 1. Validate it loads under the H.2 refinement
+node -e "import('./dist/packs/loader.js').then(m => m.loadPack('packs/builtin/examples/tool-history-correlator')).then(p => console.log('OK', p.skills.length, 'skill(s)'))"
+
+# 2. Run its fixtures via the test suite
+pnpm vitest run test/example-skills.test.ts
+```
+
+## Fixtures
+
+- `fixtures/many_bash.input.json` — 6 Bash calls in current turn →
+  expected: **1 warn verdict** (both clauses true).
+- `fixtures/few_bash.input.json` — 2 Bash calls in current turn →
+  expected: **0 verdicts** (count clause short-circuits the `&&`).
+
+## Why this example is in the docs
+
+It demonstrates the third operator family unlocked by the H grammar
+(indexing on primitive results) and shows the defensive-shape-check
+pattern pack authors regularly want to express — "the primitive
+returned what I asked for, AND the count exceeds my threshold." Both
+clauses in one line, evaluator-gated at every Stop event.

package/packs/builtin/examples/tool-history-correlator/fixtures/few_bash.expected.json

@@ -0,0 +1,3 @@
+{
+  "verdict": false
+}

package/packs/builtin/examples/tool-history-correlator/fixtures/few_bash.input.json

@@ -0,0 +1,10 @@
+{
+  "comment": "2 Bash calls in current turn — count clause false, && short-circuits → the if: clause evaluates false (rule does not fire).",
+  "if": "bash_history.count > 5 && bash_history.tools[0] == \"Bash\"",
+  "bindings": {
+    "bash_history": {
+      "tools": ["Bash", "Bash"],
+      "count": 2
+    }
+  }
+}

package/packs/builtin/examples/tool-history-correlator/fixtures/many_bash.expected.json

@@ -0,0 +1,3 @@
+{
+  "verdict": true
+}

package/packs/builtin/examples/tool-history-correlator/fixtures/many_bash.input.json

@@ -0,0 +1,10 @@
+{
+  "comment": "6 Bash calls in current turn — count clause true, identity clause true → the if: clause evaluates true (rule fires).",
+  "if": "bash_history.count > 5 && bash_history.tools[0] == \"Bash\"",
+  "bindings": {
+    "bash_history": {
+      "tools": ["Bash", "Bash", "Bash", "Bash", "Bash", "Bash"],
+      "count": 6
+    }
+  }
+}

package/packs/builtin/examples/tool-history-correlator/manifest.yaml

@@ -0,0 +1,18 @@
+# Example — not load-bearing. Demonstrates `len()` + numeric comparison +
+# bracket-index access on a primitive's array result. Ships under
+# packs/builtin/examples/ as educational material referenced from
+# docs/skill-grammar-guide.md.
+# NOT registered in any `active.json` and NOT loaded by the runtime
+# unless a user explicitly opts in by editing their scope's active.json.
+name: tool-history-correlator
+version: 0.1.0
+scope: universal
+goal: warn when a single turn issues an unusually large number of Bash invocations
+description: |
+  Worked example showing how to access structured primitive results
+  inside an `if:` clause via dotted path + bracket-index access.
+  Demonstrates the count-threshold + first-element identity pattern.
+
+  The prose-only equivalent ships alongside as `BEFORE.md`. The
+  structured rule lives in `skills/correlator/skill.yaml`.
+evolves: false

package/packs/builtin/examples/tool-history-correlator/skills/correlator/skill.yaml

@@ -0,0 +1,46 @@
+# Example — not load-bearing. Worked example for docs/skill-grammar-guide.md.
+#
+# Demonstrates accessing a primitive's structured return shape inside an
+# `if:` clause via dotted path + bracket-index access. The clause exercises:
+#
+#   1. numeric comparison (`>`)        — count threshold
+#   2. bracket-index access (`.tools[0]`) — array element by integer index
+#   3. string equality (`==`)          — first-element identity check
+#   4. logical `&&`                    — both clauses must hold
+#
+# Primitive return shape (verified against src/functions/session_tool_history.ts
+# on 2026-05-25):
+#   session_tool_history → { tools: string[], count: number }
+#
+# Note: the spec's original example assumed `.calls[]` with each call
+# carrying a `.name` field. The actual primitive returns a flat
+# `tools: string[]`, so this example accesses `bash_history.tools[0]`
+# (a string) directly. This is what the user's correction note flagged:
+# the example shape must match the real primitive, not the spec.
+name: correlator
+load: preload
+triggers:
+  - kind: stop
+rules:
+  - id: bash-heavy-turn
+    kind: track_check
+    process:
+      - call: session_tool_history
+        args:
+          scope: current_turn
+          filter_names:
+            - Bash
+        as: bash_history
+      - call: verdict
+        if: 'bash_history.count > 5 && bash_history.tools[0] == "Bash"'
+        args:
+          level: warn
+          message: |-
+            More than 5 Bash invocations this turn. Consider consolidating
+            with a single multi-line script (or a one-liner with &&) so the
+            tool trace stays scannable.
+prose: |
+  Reference companion to BEFORE.md. The bracket-index access on
+  `bash_history.tools[0]` is a sanity check that the filter actually
+  matched Bash entries — guards against future shape drift in the
+  primitive.

package/packs/builtin/focused-atomic-design/README.md

@@ -0,0 +1,21 @@
+# focused-atomic-design
+
+Opt-in focused pack encoding Atomic Design idioms (atoms → molecules →
+organisms → templates → pages; token-driven theming; one-component-per-file)
+as a discipline + recall surface.
+
+## Activation
+
+Auto-activates via `detected_by` when the project's filesystem matches any
+of the canonical atomic-design layouts (`src/components/atoms/` etc.).
+
+## What ships
+
+- **DOG.1 (this commit)**: manifest + foundation (no tools — methodology
+  pack) + detected_by (filesystem signals only).
+- **DOG.4**: seed lessons + verify gates.
+
+## See also
+
+- [`docs/pack-runtime.md`](../../../docs/pack-runtime.md) §1.2/§1.3/§1.4.
+- DOG.2 composes this pack into `frontend-react-19-atomic`.

package/packs/builtin/focused-atomic-design/manifest.yaml

@@ -0,0 +1,151 @@
+# focused-atomic-design — Atomic Design methodology.
+#
+# Focused pack — methodology-driven (no specific tool requirement; works with
+# any component library that follows the atoms/molecules/organisms taxonomy).
+# Aggregated into frontend-react-19-atomic (DOG.2).
+name: focused-atomic-design
+version: 0.1.0
+scope: domain
+goal: Encode Atomic Design idioms (atoms → molecules → organisms → templates → pages; token-driven theming; one-component-per-file) as opt-in discipline + recall surface.
+description: |
+  Focused pack — activates when filesystem layout shows atoms/molecules
+  directories. Methodology pack — no tool requirement. Aggregated into
+  frontend-react-19-atomic composite for the v1 dogfood demo. Skills land
+  in DOG.4.
+
+activation_scope: project
+
+foundation:
+  tools: [] # methodology pack — no specific tool requirement
+  domains:
+    - frontend
+    - design-systems
+  methodologies:
+    - atomic-design
+    - token-driven
+    - one-component-per-file
+
+detected_by:
+  # OR semantics — any of the canonical atomic-design layouts activates.
+  - kind: dir_exists
+    path: src/components/atoms
+  - kind: dir_exists
+    path: src/components/molecules
+  - kind: dir_exists
+    path: components/atoms
+  - kind: file_glob
+    pattern: 'src/components/atoms/**/*.tsx'
+    min_count: 1
+
+# DOG.4 — seed_lessons + verify_gates populated. Atomic Design idioms
+# encode the 5-level taxonomy + the rules that keep components
+# composable as the system grows.
+seed_lessons:
+  - title: 'Atoms are the smallest UI primitives; no app-specific logic'
+    body: |
+      An atom (Button, Input, Label, Icon) is the smallest functional
+      unit — props go in, JSX comes out. NEVER reach for app state,
+      router, or data fetching from an atom. Reuse across products
+      depends on atoms being "pure UI" — break that and the design
+      system fractures.
+    scope: user
+    tags: [atomic-design, atoms, design-system]
+    source: 'https://atomicdesign.bradfrost.com/chapter-2/#atoms'
+  - title: 'Molecules combine 2-5 atoms; one responsibility (form-field, search-box)'
+    body: |
+      A molecule (FormField = Label + Input + ErrorText, SearchBox =
+      Input + Button) groups atoms around ONE responsibility. If you
+      can name the responsibility in one phrase, it's a molecule. If
+      you need "and" / "or" you've drifted into organism territory —
+      split it.
+    scope: user
+    tags: [atomic-design, molecules, decomposition]
+    source: 'https://atomicdesign.bradfrost.com/chapter-2/#molecules'
+  - title: 'Organisms own composition; can hold ephemeral state but NOT app state'
+    body: |
+      An organism (Header, ProductCard, CommentThread) composes
+      molecules + atoms into a section of UI. May own ephemeral state
+      (open/closed, hovered) but NEVER global app state, routing, or
+      data fetching — that belongs to templates/pages. Otherwise you
+      can't preview the organism in Storybook without a mock for the
+      whole app.
+    scope: user
+    tags: [atomic-design, organisms, state-discipline]
+    source: 'https://atomicdesign.bradfrost.com/chapter-2/#organisms'
+  - title: 'Templates are layout-only; pages bind real data'
+    body: |
+      A template is an organism arrangement with NO real data — just
+      structure (e.g. HomeTemplate = Header + Hero + FeaturedGrid +
+      Footer). A page hydrates that template with real data + bindings
+      (HomePage = HomeTemplate({hero: latestPost, featured:
+      topProducts})). One template, many pages.
+    scope: user
+    tags: [atomic-design, templates, pages]
+    source: 'https://atomicdesign.bradfrost.com/chapter-2/#templates'
+  - title: 'One component per file; filename matches component name'
+    body: |
+      `Button.tsx` exports ONE Button. `Button/index.tsx` plus
+      `Button/Button.styles.ts` is acceptable but the index re-exports
+      ONE component. Co-locating multiple components in one file makes
+      barrel-imports messy and breaks tree-shaking for unused
+      sub-exports.
+    scope: user
+    tags: [atomic-design, file-layout, conventions]
+    source: 'https://atomicdesign.bradfrost.com/chapter-3/'
+  - title: 'Token-driven theming: no hex codes in component files'
+    body: |
+      Components reference design tokens (`var(--color-primary)`,
+      `theme.spacing.sm`) — never raw hex codes or px values inline.
+      Tokens centralize theming + dark/light mode + brand variants.
+      A grep for `#[0-9a-f]{6}` in component files should return
+      nothing.
+    scope: user
+    tags: [atomic-design, tokens, theming]
+    source: 'https://atomicdesign.bradfrost.com/chapter-2/#subatomic'
+  - title: 'Storybook the atom + molecule levels; integration-test the page level'
+    body: |
+      Atoms + molecules go in Storybook (visual + interaction tests).
+      Organisms + templates may go too. Pages get integration tests
+      (data binding, routing, real API). Mismatch causes pain:
+      page-level Storybook stories drift; atom-level integration
+      tests retest the design system.
+    scope: user
+    tags: [atomic-design, testing, storybook]
+    source: 'https://storybook.js.org/docs/get-started/why-storybook'
+
+verify_gates:
+  - name: no-hex-color-in-component-file
+    when:
+      event_kind: tool_call
+    # Component files should reference design tokens, not raw hex.
+    check: match(tool_args.content, "#[0-9a-fA-F]{6}\\b")
+    on_fail:
+      level: warn
+      message: |
+        focused-atomic-design: raw hex color detected. Reference a
+        design token (CSS var, theme value) instead — token-driven
+        theming is what keeps the system maintainable.
+  - name: no-app-state-import-in-atom
+    when:
+      event_kind: tool_call
+    # Atom files importing redux/zustand/react-query → discipline violation.
+    check: match(tool_args.file_path, "/components/atoms/")
+    on_fail:
+      level: warn
+      message: |
+        focused-atomic-design: atom file detected. If you're adding
+        an import here, verify it's not pulling in app state
+        (redux/zustand/react-query), router, or data-fetching —
+        those belong at the organism/template/page level.
+  - name: no-multiple-default-exports
+    when:
+      event_kind: tool_call
+    # Atomic design's one-component-per-file rule — flag content with
+    # more than one `export default`.
+    check: match(tool_args.content, "export default [\\s\\S]*export default")
+    on_fail:
+      level: warn
+      message: |
+        focused-atomic-design: multiple `export default` in one file.
+        Atomic design ships ONE component per file (filename matches
+        component name); split into separate files.

package/packs/builtin/focused-react-19/README.md

@@ -0,0 +1,36 @@
+# focused-react-19
+
+Opt-in focused pack encoding React 19+ idioms (Server Components, Actions,
+useOptimistic, hooks-of-hooks discipline) as a discipline + recall surface
+for codebases on React 19.
+
+## Activation
+
+Auto-activates via `detected_by` when `package.json` declares `react ^19` in
+`dependencies` OR `devDependencies`. Opt-in via project-scope or user-scope
+`active.json`:
+
+```json
+{ "packs": ["focused-react-19"] }
+```
+
+Or include as part of the `frontend-react-19-atomic` composite (DOG.2):
+
+```json
+{ "packs": ["frontend-react-19-atomic"] }
+```
+
+## What ships
+
+- **DOG.1 (this commit)**: manifest + `foundation` (tools/domains/methodologies)
+  - `detected_by` (npm-deps regex). No skills yet.
+- **DOG.4**: 5–10 seed lessons + 2–3 verify gates per pack-runtime.md
+  authoring conventions.
+
+## See also
+
+- [`docs/pack-runtime.md`](../../../docs/pack-runtime.md) §1.2 (foundation)
+  / §1.3 (activation_scope) / §1.4 (detected_by) — the schema fields this
+  pack populates.
+- DOG.2 composes this pack with `focused-typescript-strict` +
+  `focused-atomic-design`.