@carecard/validate 3.28.0 → 3.29.0

package/.agents/skills/carecard-must-do/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: carecard-must-do
+description: 'Non-negotiable startup requirements for every agent, including Codex, Claude, other assistants, and delegated agents. Load first whenever beginning or resuming any task to govern questions, visible working copies, and agent-named branches.'
+---
+
+# CareCard Must Do
+
+## Mandatory for every agent
+
+Every agent must read and follow this skill before beginning or resuming work
+in this repository. This applies regardless of provider, product, model, role,
+or invocation method, including Codex, Claude, other assistants, and delegated
+agents. Planning, questions, read-only investigation, coding, review,
+documentation, validation, and Git operations are all covered.
+
+Load this skill first, then the repository's mandatory engineering standards,
+then the specialist skills relevant to the task. Continue applying these rules
+throughout the task. When entering another repository, read its local copy.
+When delegation is already authorized, give delegated agents this same startup
+requirement. An agent without automatic skill discovery must open this file
+explicitly; its lack of discovery support is not an exemption.
+
+## Explain the issue and solutions before asking
+
+Before every user-facing question, including a clarification, preference,
+approval request, or question presented through a tool, explain:
+
+- the relevant facts and what is uncertain or needs to change;
+- the issue and why the user's answer is needed;
+- the viable solutions or next steps and their practical consequences; and
+- the recommended solution and the reason for that recommendation.
+
+Make the explanation detailed enough for a first-year engineering student to
+understand. Define necessary technical terms and distinguish observed facts
+from assumptions. Explain concrete effects rather than relying on unexplained
+jargon. Do not invent alternatives when only one practical next step exists.
+
+Present the question after the explanation. Resolve discoverable facts through
+appropriate inspection before asking the user to supply them. This requirement
+does not create a reason to ask unnecessary questions or repeat an approval
+already granted for the action.
+
+## Keep the working repository visible
+
+Make changes in the normal repository directory the user is working in. Do not
+routinely replace it with a clone, linked worktree, detached checkout, or other
+working copy under `/tmp`, a system temporary directory, a cache, or a hidden or
+undisclosed location. A branch names a line of work; a worktree or clone creates
+another working directory. Do not use either to hide where changes are made.
+
+A separate working directory is permitted only for a compelling technical
+reason, such as isolation that is necessary to protect unrelated active work.
+Before creating it, explain why the normal checkout cannot safely serve the
+task, disclose the exact directory and branch, and explain how the finished
+work will remain accessible in the normal repository. Convenience alone is
+not a compelling reason. This disclosure adds no separate approval step;
+existing authorization requirements still apply.
+
+Keep ownership and handoff explicit, preserve unrelated work, and clean up only
+resources owned by the task when cleanup is authorized. Ordinary temporary
+logs, build artifacts, and test fixtures are permitted when they are not used
+as an undisclosed replacement working repository.
+
+## Work on an agent-named branch
+
+Before changing repository files, create and switch to a task-specific branch
+named `<agent-name>/<task-name>` in the owning repository. Use the agent's
+recognizable lowercase name and a descriptive task name, such as
+`codex/carecard-must-do`, `claude/fix-login`, or `junie/update-validation`.
+Reuse an existing agent-named branch only when continuing that same task.
+Read-only investigation and planning do not require creating a branch.
+
+Identify the repository directory and working branch before making changes.
+Preserve existing commits and unrelated local changes. Start new work from
+freshly fetched `origin/main`, or rebase continuing work onto it when needed.
+Fetch again before every source-branch push and rebase when the branch does
+not already contain the latest `origin/main`.
+
+Follow the repository's remaining Git, validation, and authorization rules.
+Branch creation does not authorize pushing, merging, or deleting branches.
+Never delete local or remote `main`, and never force-push to remote `main`.
+
+## 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](../carecard-workspace-standards/SKILL.md)
+for the mandatory TDD and code organization rules.

package/.agents/skills/carecard-workspace-standards/SKILL.md

@@ -7,6 +7,9 @@ Non-negotiable root-cause solution rule: Always identify and solve the verified
 
 # CareCard Workspace Standards
 
+First read [carecard-must-do](../carecard-must-do/SKILL.md); it is mandatory for every agent and task.
+Then read the [repository engineering standards](../pkg-validate-coding-standards-and-best-practices/SKILL.md) before following this workflow.
+
 Mandatory companion: load
 `$pkg-validate-coding-standards-and-best-practices` before this skill for every
 task in this repository.
@@ -53,7 +56,7 @@ Use before modifying, testing, reviewing, or debugging any CareCard workspace re
 ## When To Use
 
 - Use before modifying, testing, reviewing, or debugging any CareCard workspace repository or cross-repository contract.
-- Use as the first shared context before selecting narrower repository-specific skills.
+- Use as shared context after `carecard-must-do` and the repository engineering standards, before selecting narrower specialist skills.
 
 ## When Not To Use
 
@@ -172,7 +175,14 @@ config.
 
 ## 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`.
 
 ## Commit Continuation Rule
 
@@ -183,37 +193,31 @@ making a new commit in the affected repository.
 
 ## 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`.
+Work from the owning repository root and stage only intended guidance changes.
+Use freshly fetched `origin/main` as the default base. Start `<agent-name>/<task-name>`
+from it, or rebase existing work when it does not already contain the latest
+`origin/main`. An explicit user instruction to use the current or another
+working branch overrides the default `<agent-name>/<task-name>` selection.
+
+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.
 
 ## Shared Packages And API Contracts
 

package/.agents/skills/github-pr-create-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-pr-create-update
-description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating or updating a PR, or marking a PR ready from the current repository branch into development or main.'
+description: 'Use when asked to push, create, update, or ready a GitHub pull request. Default to main, fetch origin/main at the start and before source pushes, rebase when needed, and preserve main from deletion or force pushes.'
 ---
 
 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.
@@ -17,172 +17,137 @@ Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade,
 
 Non-negotiable code organization rule: Functions with the same or equivalent behavior must use the same or clearly corresponding descriptive names across CareCard repositories, and equivalent functionality must live in files with the same names within each repository's established architecture. No backward compatibility names, aliases, or duplicate locations are allowed.
 
-## Purpose
-
-After the user explicitly asks for remote Git or GitHub PR work, create,
-update, verify, push, and mark ready a GitHub pull request from the current
-repository branch into `development`, or into `main` when `development` is
-absent.
-
-## When To Use
-
-- Use only when the user explicitly asks to create, update, push for, or mark
-  ready a GitHub pull request from the current repository branch.
-
-## When Not To Use
-
-- Do not use for merging or deleting an already-approved pull request; use the
-  merge cleanup skill.
-- Do not use for ordinary local commits that do not involve GitHub PR work.
-
-## 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.
-
-## Scope
-
-Use this skill from the root of the repository whose current branch contains
-the intended PR changes. The repository must have `origin/development` or
-`origin/main`, and GitHub CLI must be available and authenticated.
-
-Default terms:
-
-- Base branch: `development` when `origin/development` exists; otherwise
-  `main` when `origin/main` exists.
-- Source branch: the current branch unless the user names another branch.
-
-Do not continue automatically when:
-
-- The source branch is `development`, `main`, `master`, or detached.
-- The working tree has uncommitted changes. Explain that a PR only includes
-  committed changes and ask the user whether to commit or stash them.
-- `gh auth status` fails.
-- Neither `origin/development` nor `origin/main` exists.
-
-## Workflow
-
-1. Capture the source branch and run preflight checks:
-
-    ```sh
-    branch="$(git branch --show-current)"
-    test -n "$branch"
-    test "$branch" != "development"
-    test "$branch" != "main"
-    test "$branch" != "master"
-    git status --short
-    gh auth status
-    ```
-
-2. Select the pull request base branch. Prefer `development`; use `main` only
-   when `origin/development` is absent:
-
-    ```sh
-    remote_base_refs="$(git ls-remote --heads origin development main)"
-    remote_query_status=$?
-    if [ "$remote_query_status" -ne 0 ]; then
-      printf 'Unable to inspect origin base branches (exit %s).\n' "$remote_query_status" >&2
-      exit "$remote_query_status"
-    fi
-    case "$remote_base_refs" in
-      *"refs/heads/development") base="development" ;;
-      *"refs/heads/main") base="main" ;;
-      *)
-        printf '%s\n' "No origin/development or origin/main branch exists." >&2
-        exit 1
-        ;;
-    esac
-    git fetch origin "$base" --prune
-    ```
-
-3. Check whether the current branch can merge with the latest base without
-   changing the worktree:
-
-    ```sh
-    if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-create-merge-tree.out
-    then
-      merge_conflict_detected=false
-    else
-      merge_conflict_detected=true
-    fi
-    ```
-
-4. If a merge conflict is detected, try rebasing on the latest base:
-
-    ```sh
-    if [ "$merge_conflict_detected" = true ]; then
-      if git rebase "origin/$base"; then
-        git push --force-with-lease -u origin "$branch"
-      else
-        git rebase --abort
-        echo "Rebase conflicted; aborted without pushing."
-        exit 1
-      fi
-    else
-      git push -u origin "$branch"
-    fi
-    ```
-
-    Do not use `--no-verify`; pre-push hooks must run. Do not resolve rebase
-    conflicts unless the user explicitly asks.
-
-5. Verify the remote branch matches local `HEAD`:
-
-    ```sh
-    local_sha="$(git rev-parse HEAD)"
-    remote_sha="$(git ls-remote --heads origin "$branch" | awk '{print $1}')"
-    test "$local_sha" = "$remote_sha"
-    ```
-
-6. Inspect the branch changes before writing the PR title:
-
-    ```sh
-    git log --reverse --format='%s' "origin/$base..HEAD"
-    git diff --stat "origin/$base...HEAD"
-    ```
-
-7. Reuse an existing open PR for this exact branch/base pair when present:
-
-    ```sh
-    pr_number="$(gh pr list \
-      --head "$branch" \
-      --base "$base" \
-      --state open \
-      --json number \
-      --jq '.[0].number // empty')"
-    ```
-
-8. If there is no PR, create one against the selected base and capture the new
-   PR number:
-
-    ```sh
-    pr_url="$(gh pr create \
-      --base "$base" \
-      --head "$branch" \
-      --title "$title" \
-      --body "$body")"
-    pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
-    ```
-
-9. If a PR exists, mark it ready when it is a draft, then keep the title
-   descriptive:
-
-    ```sh
-    is_draft="$(gh pr view "$pr_number" --json isDraft --jq '.isDraft')"
-    if [ "$is_draft" = "true" ]; then
-      gh pr ready "$pr_number"
-    fi
-    gh pr edit "$pr_number" --title "$title"
-    ```
-
-10. Final response should include the PR URL, selected base branch, whether a
-    rebase was performed, whether an existing PR was reused or marked ready,
-    and any validation that could not be run.
+## Default Git Policy
+
+Apply these defaults unless the user explicitly specifies otherwise. The
+prohibition on deleting or force-pushing `main` always applies.
+
+1. Use `main` as the PR base and freshly fetched `origin/main` as the source of
+   truth. `origin/HEAD`, a stale local `main`, and the presence of `development`
+   do not change this default. If remote `main` is missing or cannot be fetched,
+   report the blocker instead of selecting another base.
+2. At task start, fetch `origin/main`, then create new work from that commit or
+   rebase the existing working branch onto it when needed. Honor an explicit
+   working-branch instruction; it changes branch selection, not freshness.
+3. Fetch again before every source-branch push. Rebase when the working branch
+   does not already contain the latest `origin/main`; a clean mergeability
+   check is not proof that rebasing is unnecessary. If it already contains that
+   commit, no rebase is needed. The direct `development` replacement below is a
+   ref synchronization, not a source-branch rebase.
+4. Squash-merge into remote `main` after the applicable validation passes.
+   Administrator privileges may be used to merge without GitHub reviews; they
+   do not authorize bypassing required checks. Verify the merge, then delete
+   the merged source branch remotely and locally.
+5. Fetch the latest remote `main` after merging and fast-forward local `main`
+   to that commit. Preserve divergent local work and report a blocked update
+   rather than discarding it.
+6. Replace branches named exactly `development`, locally and remotely, with
+   the latest remote `main` commit. Use an explicit, observed-commit
+   `--force-with-lease` for a non-fast-forward remote update. Create a missing
+   counterpart when local or remote `development` exists; leave repositories
+   with neither unchanged. If `development` was the merged source, recreate
+   it from the new `main` after deleting it. Other working branches are not
+   development synchronization targets.
+7. Never delete local or remote `main`, and never force-push to remote `main`,
+   including with `--force-with-lease`, a forced refspec, or a mirror push.
+   Check the exact destination ref before every deletion or forced update.
+
+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`.
+
+## Prepare The Working Branch
+
+Work from the owning repository root. Inspect status, the current branch,
+upstream, and worktrees before changing refs. Preserve unrelated changes and
+existing commits; do not reset a working branch to discard its work. Use the
+user-named branch, or the current source branch for a single-repository task.
+If starting new work while on `main`, create a task branch from fresh
+`origin/main`. Do not use `main` or the selected base as a PR source branch.
+Stop if the source branch cannot be resolved or HEAD is detached.
+
+Fetch the authoritative ref explicitly:
+
+```sh
+git fetch origin refs/heads/main:refs/remotes/origin/main
+```
+
+For an existing working branch, check whether it includes the fetched commit:
+
+```sh
+if git merge-base --is-ancestor origin/main HEAD; then
+  printf '%s\n' 'Working branch already contains the latest origin/main.'
+else
+  ancestry_result=$?
+  if [ "$ancestry_result" -ne 1 ]; then
+    exit "$ancestry_result"
+  fi
+  git rebase origin/main
+fi
+```
+
+Repeat the fetch and ancestry check before every source-branch push, including
+pushes after validation fixes. If rebasing changes the validated inputs, rerun
+the affected validation. Preserve successful evidence for unchanged inputs.
+If a rebase conflicts, abort only the rebase started by this task and report
+the conflict; do not push or discard work. Preserve any pre-existing Git
+operation and dirty worktree rather than trying to reset through it.
+
+Before rebasing a published source branch, record its remote commit and verify
+that its existing work is accounted for locally. Reconcile unincorporated
+remote work before rewriting it. Use a normal push for a new branch or a
+fast-forward update. When a rebase requires rewriting the remote source, use
+an explicit lease tied to the recorded source commit:
+
+```sh
+if [ -z "$source_branch" ] || [ "$source_branch" = main ]; then
+  printf '%s\n' 'Refusing to delete or force-update main or an unnamed branch.' >&2
+  exit 1
+fi
+git push --set-upstream \
+  --force-with-lease="refs/heads/$source_branch:$observed_source_commit" \
+  origin "HEAD:refs/heads/$source_branch"
+```
+
+Resolve `source_branch` and `observed_source_commit` from verified repository
+state before using this example. Do not replace a rejected lease with
+`--force` or retry against a new expected commit without inspecting the remote
+change. Keep hooks enabled. Verify that the remote source commit equals the
+local commit after a successful push.
+
+## Create Or Update The Pull Request
+
+1. Confirm GitHub authentication, the intended source branch, and the clean,
+   committed changes included in the PR. Load the owning repository skills and
+   run their applicable validation. Stage and commit only authorized changes;
+   preserve supplied branch names, titles, commit messages, and PR text.
+2. Prepare and push the source branch using the fresh-main procedure above.
+3. Find the open PR for that source. Reuse the exact source/base match. If
+   automation created the task PR against `development`, retarget that PR to
+   `main` and recheck its diff and checks instead of creating a duplicate.
+   Honor an explicit user-selected base; do not silently retarget that choice.
+4. Create a missing PR against `main` when PR creation is authorized. Use a
+   file for a multiline body with `gh pr create --body-file` or
+   `gh pr edit --body-file`. Do not create an empty PR for a source already
+   represented in the base; report the no-op and perform only authorized
+   cleanup supported by merge or content-equivalence evidence.
+5. Mark draft PRs ready in the authorized create/update/ready or merge workflow,
+   while preserving an explicit request to keep the PR as a draft. Keep the title factual and preserve exact user-supplied text.
+   A create/update-only request ends with the PR; it does not authorize merging.
+
+## Reporting
+
+Report the repository, working branch, fetched main commit, whether rebasing
+was needed, validation results, push result, PR URL and state, administrator
+merge use, source cleanup, final checkout, and main/development commit parity.
+Distinguish merged, unchanged, not applicable, and blocked repositories. Give
+the exact failing command and reason for an incomplete step. Do not amend
+commits unless explicitly requested; use additive commits for follow-up work.
 
 ## TDD And Validation
 

package/.agents/skills/github-pr-create-update/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
-    display_name: 'GitHub PR Create Or Update'
-    short_description: 'Create, update, verify, push, and mark ready a GitHub pull request from the current repository branch into origin/development'
-    brand_color: '#0F766E'
-    default_prompt: 'Use $github-pr-create-update when this task matches the skill scope.'
+  display_name: 'GitHub PR Create Or Update'
+  short_description: 'Create, update, and ready pull requests into main'
+  brand_color: '#0F766E'
+  default_prompt: 'Use $github-pr-create-update when this task matches the skill scope.'