chore: update branch from main

.bob/rules-agent/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Critical Coding Rules
+
+- Every source file **must** start with the IBM copyright block (`Copyright <year> IBM Corporation. / SPDX-License-Identifier: Apache2.0`)
+- Rule implementations (`functions/`) and rule definitions (`rules/`) are separate files — both are required for every rule; adding only one will cause test failures
+- Both `functions/index.js` and `rules/index.js` are manual barrel files — new entries must be added to both
+- New rules must also be registered in `packages/ruleset/src/ibm-oas.js`
+- Rule `given` JSONPath expressions must NOT use implicit `.[]` recursion (e.g., `$.paths.[*]` is invalid; use `$.paths[*]`) — enforced by `test/meta/rule-style.test.js`
+
+## Rule Function Conventions
+
+- The logger must be lazily initialized at first call using `context.rule.name` (the rule ID is not available at module load time):
+  ```js
+  let ruleId, logger;
+  module.exports = function(input, _opts, context) {
+    if (!logger) {
+      ruleId = context.rule.name;
+      logger = LoggerFactory.getInstance().getLogger(ruleId);
+    }
+  };
+  ```
+- Rule functions return an array of `{ message, path }` objects (or `[]`), not throw errors
+- Import shared utilities from `@ibm-cloud/openapi-ruleset-utilities`, internal utils from `'../utils'`
+- Use `validateNestedSchemas()` / `validateComposedSchemas()` / `validateSubschemas()` from utilities to recurse into schemas (don't manually recurse)
+
+## Adding Rules: Required Checklist
+
+1. `src/functions/<name>.js` — implementation
+2. `src/rules/<name>.js` — Spectral rule object
+3. Export in `src/functions/index.js`
+4. Export in `src/rules/index.js`
+5. Register (with severity) in `src/ibm-oas.js`
+6. Test file at `test/rules/<name>.test.js`
+7. Scoring rubric entry in `packages/validator/src/scoring-tool/rubric.js`
+8. Documentation entry in `docs/ibm-cloud-rules.md`
+
+Missing any step causes silent omission from the ruleset, test failures, or an unscored rule.
+
+## Test Patterns
+
+- Always start from `makeCopy(rootDocument)` and mutate — never mutate `rootDocument` directly
+- Use `testRule(ruleId, rule, document)` for integration-style rule tests (full Spectral pipeline)
+- Use `unitTestRule(ruleId, rule, input)` when you need to bypass `given`/`formats` (e.g., testing the function directly with a partial schema)
+- Severity codes are numbers: `error=0, warning=1, info=2, hint=3` — assert with `severityCodes.error` not the string `'error'`
+- `all-schemas-document.js` provides a document with schemas in every possible location — useful for coverage tests
+
+## Running Tests
+
+```bash
+# Single test file from root
+npm run jest --workspace packages/ruleset -- --testPathPattern="string-attributes"
+
+# All tests in a workspace
+npm run test-ruleset
+
+# With verbose output
+cd packages/ruleset && npx jest --verbose test/rules/string-attributes.test.js
+```

.bob/rules-ask/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Codebase Navigation
+
+- `packages/ruleset/src/functions/` — rule *implementations* (the JS functions Spectral calls)
+- `packages/ruleset/src/rules/` — rule *definitions* (Spectral rule objects with `given`, `severity`, etc.)
+- These are intentionally separate: a function can be reused across multiple rules
+- `packages/utilities/src/collections/index.js` — canonical JSONPath location collections reused by many rules (e.g., `requestBodySchemas`, `responseSchemas`, `schemas`)
+- `packages/ruleset/src/utils/` — ruleset-private utilities (not exported publicly)
+- `packages/utilities/src/utils/` — public utilities exported as `@ibm-cloud/openapi-ruleset-utilities`
+
+## Documentation Locations
+
+- Rule docs: `docs/ibm-cloud-rules.md` (main reference for all IBM Cloud rules)
+- Migration guide: `Migration-Guide.md`
+- Utilities API: auto-generated from JSDoc via `npm run generate-utilities-docs`
+- Types for utilities: auto-generated via `npm run generate-utilities-types` (outputs to `packages/utilities/types/`)
+
+## Counterintuitive Structure
+
+- The root `package.json` version (`0.0.0`) is a placeholder — actual package versions are in each workspace's `package.json`
+- `packages/ruleset/src/ibm-oas.js` is the entry point for the ruleset (`main` field), not `src/index.js`
+- The `app/` directory at the root is unrelated to the npm packages — it contains separate application code
+- Test utilities at `packages/ruleset/test/test-utils/` are not published; `root-document.js` is the shared baseline API for all rule tests

.bob/rules-plan/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Architectural Constraints
+
+- **Rules are stateless** — Spectral re-runs rule functions per document node; no state should be stored outside the lazy logger/ruleId initialization pattern
+- **Functions vs Rules separation is intentional** — a single function (e.g., `enumCasingConvention`) can back multiple rule definitions; don't merge them
+- **`resolved: true` vs `resolved: false`** in rule definitions changes whether `$ref`s are dereferenced before the function runs — rules using `validateNestedSchemas()` require `resolved: true` (it cannot traverse `$ref`s)
+- **`formats: [oas3]`** on a rule means it only runs for OpenAPI 3.x; omitting `formats` runs it on all versions — most IBM rules should specify `oas3`
+- The ruleset extends Spectral's built-in `oas` ruleset with overrides; some Spectral rules are deliberately turned off in `ibm-oas.js`
+
+## Dependency Architecture
+
+```
+packages/validator
+  └── @ibm-cloud/openapi-ruleset (packages/ruleset)
+       └── @ibm-cloud/openapi-ruleset-utilities (packages/utilities)
+```
+
+Circular dependencies would break workspace linking — utilities must have no dependency on ruleset or validator.
+
+## Adding Rules: Required Checklist
+
+1. `src/functions/<name>.js` — implementation
+2. `src/rules/<name>.js` — Spectral rule object
+3. Export in `src/functions/index.js`
+4. Export in `src/rules/index.js`
+5. Register (with severity) in `src/ibm-oas.js`
+6. Test file at `test/rules/<name>.test.js`
+7. Scoring rubric entry in `packages/validator/src/scoring-tool/rubric.js`
+8. Documentation entry in `docs/ibm-cloud-rules.md`
+
+Missing any step causes silent omission from the ruleset, test failures, or an unscored rule.
+
+## Commit & Release
+
+- Commits must follow Angular commit message format (`feat:`, `fix:`, `docs:`, etc.)
+- `semantic-release` auto-generates CHANGELOG and publishes to npm based on commit messages
+- Breaking changes require `BREAKING CHANGE:` footer in commit body to trigger major version bump