@carecard/validate 3.28.0 → 3.30.0

package/.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md

@@ -1,10 +1,32 @@
 ---
 name: pkg-validate-coding-standards-and-best-practices
-description: 'Mandatory for every pkg-validate task, including analysis, clarification, planning, implementation, review, debugging, documentation, public API work, skill maintenance, and validation. Use before every narrower skill.'
+description: 'Use after carecard-must-do. Mandatory for every pkg-validate task, including analysis, clarification, planning, implementation, review, debugging, documentation, public API work, skill maintenance, and validation. Use before every narrower skill.'
 ---
 
 # Pkg Validate Coding Standards And Best Practices
 
+## Release 1.1.1 and production data
+
+CareCard Release 1.1.1 is the production baseline. Seeding with
+`--seed-release-data` is complete. Production cluster data, database rows,
+and stored user files will be preserved going forward. There will be no
+complete user-data wipeout and re-creation.
+
+Future production changes must use data-preserving migrations. Do not replay
+the completed initialization or run reset, rollback, or seed workflows as part
+of ordinary production deployment.
+
+## Commit and merge documentation and skills with the task
+
+In each owning repository, include all task-related documentation, plans, and
+skill changes in the same commit as the related task changes. Merge them
+together into remote `main`. Do not leave changed documentation or skills
+uncommitted or unmerged, and do not declare the task complete until their
+inclusion in the merged commit is verified. Preserve unrelated work.
+
+First read [carecard-must-do](../carecard-must-do/SKILL.md); it is mandatory for every agent and task.
+Then apply this engineering standard before selecting narrower skills.
+
 ## JavaScript And TypeScript Style Contract
 
 - Require braces around every optional control-flow body through ESLint core
@@ -40,7 +62,7 @@ cross-repository end-to-end testing is its explicit responsibility.
 
 ## Mandatory Use And Authorities
 
-Load this skill before doing any work in `pkg-validate`, including read-only
+After `carecard-must-do`, load this skill before doing any work in `pkg-validate`, including read-only
 and documentation-only work. Then load every narrower skill that owns the
 affected package contract.
 
@@ -172,6 +194,12 @@ them unused and replaced.
 
 ## Completion
 
+Reuse the current working branch for every follow-up request, even when the
+subject changes or the working tree is clean. Create a branch only when no
+working branch exists or the checkout is on `main` or `development`. Otherwise,
+fetch remote `main` HEAD and rebase the same working branch onto that fetched
+commit, preserving its commits and uncommitted work.
+
 1. Review each changed repository's diff and status independently.
 2. Run focused runtime, type, and coverage tests, then all broader checks
    required by local skills.
@@ -181,7 +209,15 @@ them unused and replaced.
    none exists, run the strongest repository-native focused validation.
 5. Fix every in-scope failure at its root cause and rerun the exact command.
 6. Report exact commands, results, limitations, and remaining risk.
-7. Do not perform remote Git or GitHub operations unless explicitly requested.
+7. Fetch the latest `origin/main` at task start and before every source-branch
+   push; these required fetches need no separate approval. Create
+   `<agent-name>/<branch-name>` from it only when no working branch exists or the
+   current branch is `main` or `development`. Otherwise rebase the current branch
+   onto it, preserving
+   existing commits and uncommitted changes, and build subsequent task commits
+   on that same branch. Commits, pushes, PR mutations, and branch cleanup still
+   require an authorized task. Never delete local or remote `main` or
+   force-push to remote `main`.
 
 ## TDD And Validation
 

package/.agents/skills/pkg-validate-validation-library/SKILL.md

@@ -200,41 +200,51 @@ and remaining risk.
 
 ## Remote Git Operations Guardrail
 
-Do not run remote Git or GitHub operations unless the current user request explicitly asks for them. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would help but was not requested.
+Fetches needed to establish a fresh `origin/main` at task start and before a
+source-branch push are authorized without a separate approval question. Commits,
+pushes, PR mutations, and branch cleanup require an authorized task; a request
+for local work alone does not authorize publication. An authorized squash merge
+into `main` includes the merged-source cleanup, local `main` update, and
+`development` synchronization below unless the user explicitly says otherwise.
+Never delete local or remote `main`, or force-push to remote `main`, including
+with `--force-with-lease`.
 
 ## Agent Guidance Git Workflow
 
-When this skill or any repository-owned `.agents` guidance changes, use the
-repository's agents-only Git workflow:
-
-1. Work from the affected repository root and confirm only intended `.agents`
-   files changed.
-2. Use `development` as the base branch when `origin/development` exists;
-   otherwise use the repository's default base branch, usually `main`.
-3. Create or update `feature/codex` from the updated remote base branch and
-   commit all the changed `.agents` guidance files there.
-4. Push `feature/codex`, create or reuse a pull request into the base branch,
-   and mark the pull request ready for review with `gh pr ready <number>`.
-5. Squash-merge with administrator privileges and delete the remote branch:
-
-   ```sh
-   gh pr merge <number> --squash --admin --delete-branch
-   ```
-
-6. After merge, update the local base branch and remove the local feature
-   branch:
-
-   ```sh
-   git fetch origin <base> --prune
-   git switch <base>
-   git pull --ff-only origin <base>
-   git branch -d feature/codex
-   git ls-remote --heads origin feature/codex
-   ```
-
-Do not commit or push `.agents` guidance changes directly from `development`
-or `main`. Do not stage unrelated files, generated output, dependency folders,
-build artifacts, logs, or `.DS_Store`.
+Reuse the current working branch for every follow-up request, even when the
+subject changes or the working tree is clean. Create a branch only when no
+working branch exists or the checkout is on `main` or `development`. Otherwise,
+fetch remote `main` HEAD and rebase the same working branch onto that fetched
+commit, preserving its commits and uncommitted work.
+
+Work from the owning repository root and stage only intended guidance changes.
+Fetch fresh `origin/main` at task start. Create `<agent-name>/<branch-name>`
+from it only when no working branch exists or the current branch is `main` or
+`development`. Otherwise keep
+and rebase the current branch onto it, preserving existing commits and
+uncommitted changes. Build subsequent task commits on that same branch, even
+for a different task or a clean working tree. Honor explicit user
+working-branch instructions.
+
+Fetch again before every source-branch push and rebase only when the branch
+does not already contain the latest `origin/main`. Required fetches need no
+separate approval; commits, pushes, PR mutations, and cleanup require an
+authorized task. A local guidance edit does not authorize publishing it.
+
+For an authorized merge, create or reuse the PR into `main`, run applicable
+validation, and squash-merge; administrator privileges may be used without
+GitHub reviews. Verify the merge and delete its source branch remotely and
+locally after checking for newer unmerged work. Then fast-forward local `main`
+and replace local and remote branches named exactly `development` with the
+latest remote `main` commit, using an explicit observed-commit
+`--force-with-lease` remotely. Create a missing development counterpart when
+either existed; leave repositories with neither unchanged. If development was
+the merged source, recreate it from the new main. Verify commit parity and
+cleanup; preserve dirty worktrees and report conflicts or rejected leases.
+
+Never delete local or remote `main` or force-push to remote `main`, including
+with `--force-with-lease`. Guard exact destination refs before deleting or
+forcing any branch. Do not amend commits or stage unrelated files.
 
 ## Fail-Closed Test Lifecycle Audit
 

package/.codex/AGENTS.md

@@ -1,5 +1,17 @@
 # Codex Instructions For pkg-validate
 
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](../.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](../.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
+
 ## Non-negotiable Codex banked-reset requirement
 
 - Never use or consume a banked Codex rate-limit reset automatically.
@@ -133,10 +145,10 @@ The `pkg-*` directories are reusable CareCard packages. Shared API response, err
 - Use coverage reports only as diagnostics for potentially untested observable behavior. Percentages for lines, branches, functions, and statements are not functional evidence and must not determine test assertions. Never add implementation-detail tests to preserve a metric or lower thresholds to hide a failing check; report any conflict with the behavior-only policy.
 - Keep tests readable and domain-specific. Prefer explicit helper names over generic test utilities that hide important behavior.
 - Use existing test frameworks and layouts:
-    - JavaScript `api-*`: usually Mocha, Supertest, `test/index.test.js`, and Docker-backed Postgres scripts.
-    - TypeScript `api-*`: usually Jest and `tests/index.test.ts`.
-    - `pkg-*`: Mocha plus TypeScript type tests where present.
-    - `app-dashboard`: Vitest, React Testing Library, mock API tests, and Selenium for end-to-end flows.
+  - JavaScript `api-*`: usually Mocha, Supertest, `test/index.test.js`, and Docker-backed Postgres scripts.
+  - TypeScript `api-*`: usually Jest and `tests/index.test.ts`.
+  - `pkg-*`: Mocha plus TypeScript type tests where present.
+  - `app-dashboard`: Vitest, React Testing Library, mock API tests, and Selenium for end-to-end flows.
 - For database tests, use existing seed, migration, rollback, and cleanup patterns. Keep tests isolated and make cleanup reliable even after failures.
 - Add tests for API success responses, validation errors, auth/authz errors, JWT errors, not-found/conflict cases, and unexpected error handling when those paths change.
 - For frontend changes, test rendered UI, public HTTP or network outcomes, navigation, accessibility, and user-visible flows at the narrowest practical level first. Use focused non-test dependency checks for validation, transform, query, mutation, hook, and module organization.

package/AGENTS.md

@@ -1,4 +1,16 @@
-# Codex Instructions
+# Agent Instructions
+
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
 
 ## Non-negotiable Codex banked-reset requirement
 

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# Repository Agent Instructions
+
+## Mandatory startup for every agent
+
+Every agent, including Codex, Claude, other assistants, and delegated agents,
+must read and follow [carecard-must-do](.agents/skills/carecard-must-do/SKILL.md)
+before beginning or resuming any task. This includes planning, questions,
+read-only investigation, coding, review, documentation, and validation.
+
+Then load the [repository engineering standards](.agents/skills/pkg-validate-coding-standards-and-best-practices/SKILL.md)
+and the specialist skills relevant to the task.
+An agent without automatic skill discovery must open the skill explicitly;
+the requirement applies regardless of the agent platform.
+
+Also read [AGENTS.md](AGENTS.md) for the full repository instructions.
+
+## Existing repository isolation contract
+
+Non-negotiable repository isolation rule: Every repository must run its Husky
+hooks and tests using only files, code, fixtures, dependencies, and services
+contained within that repository. Tests and Husky scripts must not import,
+require, read, execute, or otherwise depend on sibling repositories or paths
+outside the repository root. app-e2e-tests is the only exception because
+cross-repository end-to-end testing is its explicit responsibility.
+
+Also apply [$carecard-workspace-standards](.agents/skills/carecard-workspace-standards/SKILL.md)
+for the mandatory TDD and code organization rules.
+
+## Existing test-preservation policy
+
+The TDD and validation requirements are non-negotiable and cannot be
+overridden. The separate pre-existing-test protection still requires the
+user's fresh, explicit permission for each exact proposed test modification.
+
+A pre-existing test—defined as any test present before work on the current task
+begins—must not be deleted, disabled, skipped, weakened, excluded from execution,
+or otherwise removed. A pre-existing test must not be modified without the
+user's explicit approval for the exact proposed change. If changing a
+pre-existing test is believed necessary, stop before making the change and
+request approval. The request must identify every affected test, describe the
+precise proposed modification, provide detailed technical justification, and
+explain all known or reasonably foreseeable regression risks. Until approval is
+granted, leave every pre-existing test unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/validate",
-  "version": "3.28.0",
+  "version": "3.30.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -47,7 +47,7 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.28.0"
+    "@carecard/common-util": "3.30.0"
   },
   "nyc": {
     "all": true,
@@ -67,6 +67,6 @@
     "glob": "13.0.6",
     "minimatch": "10.2.6",
     "serialize-javascript": "7.0.5",
-    "js-yaml": "4.3.1"
+    "js-yaml": "4.3.2"
   }
 }

package/readme.md

@@ -1,5 +1,19 @@
 # @carecard/validate
 
+## Release 1.1.1 and production data
+
+CareCard Release 1.1.1 is the production baseline. Seeding with
+`--seed-release-data` is complete. Production cluster data, database rows,
+and stored user files will be preserved going forward. There will be no
+complete user-data wipeout and re-creation.
+
+Future production changes must use data-preserving migrations. Do not replay
+the completed initialization or run reset, rollback, or seed workflows as part
+of ordinary production deployment.
+
+The [completed seed inventory and verification record](https://github.com/CareCard-ca/cc-seed-data/blob/main/plans/production-seed-result.md)
+documents the accepted release baseline and verification limitations.
+
 Non-negotiable test order invariance rule: Every test must pass independently of which tests run before or after it, and the suite must pass in every execution order. Each test must establish the state it needs, isolate mutable state, and clean up state it owns; it must never rely on another test's setup, mutations, or cleanup. Default test, CI, and Husky commands must use the test framework's ordinary ordering and must not force randomized ordering. Random-order execution is an explicit diagnostic only, and every failure it exposes must be fixed at the root cause.
 
 Non-negotiable root-cause solution rule: Always identify and solve the verified root cause, use the stronger solution, and deliver a correct, durable, production-quality result. Never treat a temporary workaround, resource increase, retry, suppression, bypass, or symptom-only patch as completion. Validate the root-cause fix against the real failing workflow and prove the end state.