@xn-intenton-z2a/agentic-lib 7.1.89 → 7.1.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.1.89",
+  "version": "7.1.90",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/agents/agent-apply-fix.md

@@ -12,12 +12,24 @@ to build) and the tests pass and the main at least doesn't output an error.
 Your goal is mission complete — if the mission can be fully accomplished while fixing this issue,
 do it. Don't limit yourself to the minimal fix when you can deliver the whole mission in one pass.
 
-The repository has a website in `src/web/` that uses the JS library. If a fix affects library
-exports or behaviour, also update the website files to stay in sync.
+## All Code Must Change Together
 
-**Both unit tests AND behaviour tests must pass.** If the project has a `test:behaviour` npm script
-(typically Playwright-based, testing the website), run it after your changes. If the behaviour test
-expects elements like `#demo-output`, `#lib-name`, or `#lib-version`, ensure the website provides them.
+A fix is never just one file. These layers form a single unit — if you change one, check all the others:
+
+- **Library source** (`src/lib/main.js`) — the core implementation
+- **Unit tests** (`tests/unit/`) — test every function at the API level with exact values and edge cases
+- **Website** (`src/web/index.html` and related files) — imports and calls the library to demonstrate features
+- **Website unit tests** (`tests/unit/web.test.js`) — verify HTML structure and library wiring
+- **Behaviour tests** (`tests/behaviour/`) — Playwright tests that load the website in a real browser
+  and verify features work at a high navigational level (demo output visible, interactive elements work)
+
+If the failure is in one layer, the fix often requires coordinating changes across multiple layers.
+For example, if a unit test fails because a function signature changed, the website and behaviour tests
+that use that function also need updating. A full test suite (unit + behaviour) runs after your fix
+regardless — each failed attempt consumes transformation budget, so get it right in one pass.
+
+**Both unit tests AND behaviour tests must pass.** The project runs `npm test` (unit tests) and
+`npm run test:behaviour` (Playwright). Both are gated — your fix must pass both.
 
 ## Merge Conflict Resolution
 

package/src/agents/agent-discussion-bot.md

@@ -56,7 +56,7 @@ When relaying supervisor responses back to the user, present them naturally as y
 Users can ask for new features or mission changes through this discussion thread:
 
 - **Feature requests** — When a user says "add feature X" or "I want Y", acknowledge the request and pass it to the supervisor to create a GitHub issue. The pipeline will pick it up and implement it.
-- **Re-seed requests** — When a user says "change the mission to Z" or "re-seed with plot-code-lib", explain that this requires running `npx @xn-intenton-z2a/agentic-lib init --purge --mission <name>`. List the available missions if asked: hamming-distance, fizz-buzz, roman-numerals, string-utils, dense-encoding, cron-engine, owl-ontology, plot-code-lib, time-series-lab, lunar-lander, empty. Note that re-seeding resets all source code, issues, and discussions.
+- **Re-seed requests** — When a user says "change the mission to Z" or "re-seed with plot-code-lib", explain that this requires running `npx @xn-intenton-z2a/agentic-lib init --purge --mission <name>`. List the available missions if asked: hamming-distance, fizz-buzz, roman-numerals, string-utils, dense-encoding, cron-engine, owl-ontology, plot-code-lib, time-series-lab, lunar-lander, c64-emulator, ray-tracer, markdown-compiler, empty. Note that re-seeding resets all source code, issues, and discussions.
 - **Website feedback** — The project has a website that uses the JS library, published via GitHub Pages. If a user comments on the website, pass feedback to the supervisor to create an issue for the pipeline to address.
 
 ## Website Awareness

package/src/agents/agent-issue-resolution.md

@@ -9,6 +9,27 @@ Do as much as you can all at once. Your goal is mission complete — if the miss
 accomplished in this single transform, it should be. Deliver all acceptance criteria, tests, website,
 docs, and README in one pass. Only leave work for a follow-up if it genuinely cannot fit.
 
+## All Code Must Change Together
+
+Every transform produces a coordinated set of changes across all layers. These are NOT independent —
+they form a single unit that must be internally consistent:
+
+- **Library source** (`src/lib/main.js`) — the core implementation. All exported functions, types, constants.
+- **Unit tests** (`tests/unit/`) — test every function and edge case at the API level. These bind to the
+  detail: exact return values, error types, boundary conditions, parameter validation.
+- **Website** (`src/web/index.html` and related files) — a working demo that imports and calls the library.
+  The website is the public face of the library and should show its features in action.
+- **Website unit tests** (`tests/unit/web.test.js`) — verify the website HTML structure and library wiring.
+- **Behaviour tests** (`tests/behaviour/`) — Playwright tests that load the website in a real browser and
+  verify it works end-to-end. These test at a high navigational level: can a user see the demo output?
+  Do the interactive elements work? Is the library identity displayed?
+- **Documentation** (`docs/`, `README.md`) — evidence, examples, and user-facing docs.
+
+If you change a function signature in the library, you MUST also update: the unit tests that call it,
+the website code that uses it, the web tests that check for its output, and any behaviour test assertions
+that depend on it. A partial change that updates the library but not the tests will fail — and there will
+be a full test run after your changes regardless, consuming budget on each failure.
+
 ## Tests Must Pass
 
 Your changes MUST leave all existing tests passing. If you change function signatures, return values, or
@@ -21,10 +42,19 @@ When writing both tests and implementation:
 - Ensure the implementation passes those tests before delivering
 - Do not write tests with different expectations than the implementation produces
 
-**Both unit tests AND behaviour tests must pass.** If the project has a `test:behaviour` npm script
-(typically Playwright-based, testing the website), run it after your changes. If your changes affect
-the website (`src/web/`) or library exports, ensure the behaviour test still finds the expected
-elements (e.g. `#demo-output`, `#lib-name`, `#lib-version`).
+**Both unit tests AND behaviour tests must pass.** The project runs `npm test` (unit tests) and
+`npm run test:behaviour` (Playwright). Both are gated — your changes must pass both.
+
+### Test philosophy
+
+- **Unit tests** bind to the detail: exact return values, error types, edge cases, parameter validation.
+  Every exported function should have unit test coverage.
+- **Behaviour tests** demonstrate features at a high navigational level through the website. They verify
+  that a user visiting the site can see the library working: demo output appears, interactive elements
+  respond, the library identity is displayed. Aim to show features through behaviour tests rather than
+  just testing internal APIs — if a feature is worth building, it's worth demonstrating on the website.
+- **Web unit tests** verify the HTML structure: expected elements exist (`#demo-output`, `#lib-name`,
+  `#lib-version`), scripts load, and the library is wired in correctly.
 
 Follow the linting guidelines and the formatting guidelines from the included config.
 
@@ -55,6 +85,8 @@ automatically (from `docs/` via `npm run build:web`).
 - **Use the library**: Import the library (or its browser-compatible parts) and call its functions on the page
 - **Show real results**: Display actual output from library functions, not placeholder text
 - When you add or change library functions, update the website to reflect them
+- **Demonstrate features**: Each significant library feature should be visible and usable on the website.
+  Behaviour tests will verify these demonstrations work, so make them testable (use IDs, structured output).
 
 ### Guidelines
 

package/src/agents/agent-maintain-features.md

@@ -27,4 +27,9 @@ Features must be achievable in a single software repository not part of a corpor
 The feature spec should be a multiline markdown with a few level 1 headings.
 The feature must be compatible with the mission statement in MISSION.md and ideally realise part of the value in the mission.
 The feature must be something that can be realised in a single source file (as below), ideally just as a library, CLI tool or possibly an HTTP API in combination with infrastructure as code deployment.
-The repository also has a website in `src/web/` that uses the JS library. When proposing features, consider both the library API and how the feature could be shown on the website.
+The repository also has a website in `src/web/` that uses the JS library. When proposing features, consider:
+- The library API (`src/lib/main.js`) and its exports
+- How the feature could be demonstrated on the website — features should be visible and interactive
+- Unit tests (`tests/unit/`) that verify exact behaviour at the API level
+- Behaviour tests (`tests/behaviour/`) that verify features work at a high navigational level through the website
+- All layers (library, tests, website, web tests, behaviour tests) must change together in a single transform

package/src/agents/agent-ready-issue.md

@@ -3,7 +3,19 @@ Please review the GitHub issue and determine if it should be enhanced, closed or
 If the issue is relevant to the mission statement and features:
 
 1. Decide if the issue should be refined, closed or if no operation is needed.
-2. Update the issue description with testable acceptance criteria derived from MISSION.md. Include ALL of: implementation, tests matching MISSION.md acceptance criteria, website updates, docs/evidence, and README. The issue should ask for mission complete — if the entire mission can be accomplished in a single transform, the acceptance criteria should cover everything. Only scope down if the mission is genuinely too large for one pass.
+2. Update the issue description with testable acceptance criteria derived from MISSION.md. Include ALL of:
+   - **Library implementation** (`src/lib/main.js`) — the core functions and exports
+   - **Unit tests** (`tests/unit/`) — tests that bind to the detail: exact return values, error types, edge cases
+   - **Website updates** (`src/web/`) — demonstrate the feature on the website so users can see it working
+   - **Behaviour tests** (`tests/behaviour/`) — Playwright tests that verify the feature works at a high
+     navigational level through the website (e.g. demo output is visible, interactive elements respond).
+     Prefer demonstrating features through behaviour tests rather than only testing internal APIs.
+   - **Web tests** (`tests/unit/web.test.js`) — verify HTML structure and library wiring
+   - **Docs/evidence** (`docs/`) and **README** updates
+   The issue should ask for mission complete — if the entire mission can be accomplished in a single
+   transform, the acceptance criteria should cover everything. Only scope down if the mission is
+   genuinely too large for one pass. Emphasise that all layers must change together because a full
+   test suite runs after the transform.
 3. Enhance the issue by adding relevant library documents as issue comments that support implementation.
 
 If the issue is irrelevant to the mission statement or features:

package/src/agents/agent-review-issue.md

@@ -1,16 +1,23 @@
-Does the combination source file, test file, website files, README file and dependencies file resolve the following issue? Check that the solution satisfies the issue's acceptance criteria and moves the mission toward complete.
+Does the combination of library source, unit tests, website, web tests, behaviour tests, README,
+and dependencies resolve the following issue? Check that the solution satisfies the issue's
+acceptance criteria and moves the mission toward complete.
 
 An issue is NOT resolved unless ALL of the following are true:
-1. The implementation exists and matches what the issue asks for
-2. Tests exist that specifically test the implemented functionality (seed-only identity tests do NOT count)
+1. The **library source** (`src/lib/main.js`) has the implementation and matches what the issue asks for
+2. **Unit tests** (`tests/unit/`) exist that specifically test the implemented functionality
+   (seed-only identity tests do NOT count). Tests bind to the detail: exact return values, error types, edge cases.
 3. Tests match the acceptance criteria in MISSION.md — the mission is the source of truth
 4. Tests and implementation are consistent — test expectations must match what the code actually returns (casing, types, formats)
+5. The **website** (`src/web/`) has been updated to demonstrate the new/changed library features
+6. **Web tests** (`tests/unit/web.test.js`) verify the website structure and library wiring
+7. **Behaviour tests** (`tests/behaviour/`) demonstrate features at a high navigational level through the
+   website — a user visiting the site can see the feature working (not just that the API exists internally)
 
-If any of these are missing, the issue is NOT resolved — keep it open or create a follow-up issue for the gap. Do not close an issue just because implementation code exists without matching tests.
+If any of these are missing, the issue is NOT resolved — keep it open or create a follow-up issue for the gap.
+Do not close an issue just because implementation code exists without matching tests and website updates.
 
-If the mission could have been fully accomplished in this transform but the solution only partially addresses it, note this gap and suggest a follow-up issue for the remaining work.
-
-Note: The repository has a website in `src/web/` that uses the JS library. When reviewing, check that website files are updated alongside library changes.
+If the mission could have been fully accomplished in this transform but the solution only partially addresses it,
+note this gap and suggest a follow-up issue for the remaining work.
 
 When reviewing, also check that evidence artifacts exist under `docs/` for implemented features.
 If a feature works but has no evidence (no example outputs, test results, or walkthroughs in `docs/`),

package/src/seeds/zero-package.json

@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.89"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.90"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",