@carecard/jwt-read 3.1.17 → 3.1.18

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

@@ -1,70 +1,57 @@
 ---
 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.'
+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.'
 ---
 
 # Pull Request Create
 
 ## 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 origin/development.
+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.
+- 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 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.
-
-## Relevant Files And Directories
-
-- Git branch state in this repository
-- GitHub pull requests viewed with `gh`
-- repository validation commands and `.husky` scripts
-
-## Coding Principles
-
-- Preserve the repository structure, naming style, module system, and local helper patterns.
-- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
-- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
-
-## Testing Expectations
-
-- Run repository validation before PR creation or merge when code behavior changed.
-- Confirm the branch is clean except intended changes before finishing.
-
-## Safety Constraints
-
-- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task requires it.
-- Do not revert or overwrite user changes; stage only requested skill or instruction files.
-- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
-
-## Commit Continuation Rule
-
-Do not amend commits unless the user explicitly asks. If
-hook, formatter, documentation, skill, validation, or review follow-up changes
-appear after a commit, stage only the intended files and make a new commit with
-a clear message.
+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`, and
-GitHub CLI must be available and authenticated.
+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 current branch is `development`, `main`, `master`, or detached.
+- 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.
-- `origin/development` cannot be fetched.
+- Neither `origin/development` nor `origin/main` exists.
 
 ## Workflow
 
@@ -80,30 +67,26 @@ Do not continue automatically when:
    gh auth status
    ```
 
-2. Pull a fresh development reference from the remote without leaving the
-   source branch:
+2. Select the pull request base branch. Prefer `development`; use `main` only
+   when `origin/development` is absent:
 
    ```sh
-   git fetch origin development --prune
-   ```
-
-   Use `origin/development` as the source of truth. If a local `development`
-   branch exists and is not checked out, it may be fast-forwarded to match the
-   remote without forcing history:
-
-   ```sh
-   git fetch origin development:development
+   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
+     base="development"
+   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
+     base="main"
+   else
+     echo "No origin/development or origin/main branch exists."
+     exit 1
+   fi
+   git fetch origin "$base" --prune
    ```
 
-   If that local branch update fails because `development` has diverged or is
-   checked out in another worktree, do not force it. Continue using
-   `origin/development` for validation.
-
-3. Check whether the current branch can merge with latest development without
+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/development >/tmp/pull-request-create-merge-tree.out
+   if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-create-merge-tree.out
    then
      merge_conflict_detected=false
    else
@@ -111,11 +94,11 @@ Do not continue automatically when:
    fi
    ```
 
-4. If a merge conflict is detected, try rebasing on latest development:
+4. If a merge conflict is detected, try rebasing on the latest base:
 
    ```sh
    if [ "$merge_conflict_detected" = true ]; then
-     if git rebase origin/development; then
+     if git rebase "origin/$base"; then
        git push --force-with-lease -u origin "$branch"
      else
        git rebase --abort
@@ -127,62 +110,58 @@ Do not continue automatically when:
    fi
    ```
 
-   Do not resolve rebase conflicts unless the user explicitly asks. If the
-   rebase fails, abort it and stop.
+   Do not use `--no-verify`; pre-push hooks must run. Do not resolve rebase
+   conflicts unless the user explicitly asks.
 
-5. Inspect the branch changes before writing the PR title:
+5. Verify the remote branch matches local `HEAD`:
 
    ```sh
-   git log --reverse --format='%s' origin/development..HEAD
-   git diff --stat origin/development...HEAD
+   local_sha="$(git rev-parse HEAD)"
+   remote_sha="$(git ls-remote --heads origin "$branch" | awk '{print $1}')"
+   test "$local_sha" = "$remote_sha"
    ```
 
-   Create a concise, descriptive title from the actual changes. Remove words
-   such as `draft`, `[draft]`, `Draft:`, and `WIP`. Do not leave a generic title
-   such as "updates", "changes", or "draft PR".
+6. Inspect the branch changes before writing the PR title:
 
-6. Reuse an existing open PR for this branch when present:
+   ```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 development \
+     --base "$base" \
      --state open \
      --json number \
      --jq '.[0].number // empty')"
    ```
 
-7. If there is no PR, create one against `development` and capture the new PR
-   number:
+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 development \
+     --base "$base" \
      --head "$branch" \
      --title "$title" \
      --body "$body")"
    pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
    ```
 
-   Keep the body factual. Mention the main changes and validation commands
-   that were actually run.
-
-8. If a PR exists, mark it ready when it is a draft:
+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
-   ```
-
-9. Update the PR title after create/reuse so it is descriptive and contains no
-   draft wording:
-
-   ```sh
    gh pr edit "$pr_number" --title "$title"
    ```
 
-10. Final response should include the PR URL, whether a rebase was performed,
-    whether an existing PR was reused or marked ready, and any validation that
-    could not be run.
+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.

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -1,56 +1,38 @@
 ---
 name: github-pr-merge-cleanup
-description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: reviewing remote mergeability, validating, merging, closing, deleting, or cleaning up a pull request branch.'
+description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: pushing a branch, creating a missing PR, reviewing mergeability, validating, merging, deleting, or cleaning up a pull request branch.'
 ---
 
 # Pull Request Merge Close
 
 ## Purpose
 
-After the user explicitly asks for remote Git or GitHub PR work, review, validate, merge, close, delete branch, and clean local state for a GitHub pull request targeting origin/development.
+After the user explicitly asks for remote Git or GitHub PR work, push the
+branch, create a missing PR when needed, review, validate, merge, delete the
+branch when allowed, and clean local state for a GitHub pull request targeting
+`development`, or `main` when `development` is absent.
 
 ## When To Use
 
-- Use only when the user explicitly asks to review mergeability, validate, merge, close, or clean up a GitHub pull request branch.
+- Use only when the user explicitly asks to push, review mergeability,
+  validate, merge, close, or clean up a GitHub pull request branch.
 
 ## When Not To Use
 
-- Do not use for creating a new pull request; use the PR create/update skill.
-- Do not use when the user only asks for local code changes without PR merge work.
+- Do not use for PR-only creation/update work without a merge request; use the
+  PR create/update skill.
+- Do not use when the user only asks for local code changes without PR merge
+  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.
-
-## Relevant Files And Directories
-
-- Git branch state in this repository
-- GitHub pull requests viewed with `gh`
-- repository validation commands and `.husky` scripts
-
-## Coding Principles
-
-- Preserve the repository structure, naming style, module system, and local helper patterns.
-- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
-- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
-
-## Testing Expectations
-
-- Run repository validation before PR creation or merge when code behavior changed.
-- Confirm the branch is clean except intended changes before finishing.
-
-## Safety Constraints
-
-- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task requires it.
-- Do not revert or overwrite user changes; stage only requested skill or instruction files.
-- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
-
-## Commit Continuation Rule
-
-Do not amend commits unless the user explicitly asks. If
-hook, formatter, documentation, skill, validation, or review follow-up changes
-appear after a commit, stage only the intended files and make a new commit with
-a clear message.
+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
 
@@ -60,8 +42,8 @@ branch available locally or on `origin`.
 
 Default terms:
 
-- Base branch: `development` when `origin/development` exists, otherwise the
-  repository default branch.
+- Base branch: `development` when `origin/development` exists, otherwise
+  `main` when `origin/main` exists.
 - Target branch: the current branch unless the user names another branch.
 - Pull request: the open PR whose head is the target branch and whose base is
   the base branch.
@@ -72,35 +54,86 @@ Do not continue automatically when:
 - The target branch is detached or is the base branch.
 - The working tree has uncommitted changes that are not part of the requested
   PR cleanup.
-- No open PR exists for the target branch.
+- Neither `origin/development` nor `origin/main` exists.
 - A rebase or validation fix would require behavior changes instead of coding
   criteria cleanup.
 
+If no open pull request exists for the target branch and selected base, create
+one as part of the merge workflow when the user requested push/PR/merge
+completion.
+
 ## Workflow
 
-1. Capture the base branch, target branch, PR number, and protection state:
+1. Capture the base branch, target branch, and authentication state:
 
    ```sh
    gh auth status
-   base="development"
-   git ls-remote --exit-code --heads origin development >/dev/null 2>&1 || \
-     base="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
+   if git ls-remote --exit-code --heads origin development >/dev/null 2>&1; then
+     base="development"
+   elif git ls-remote --exit-code --heads origin main >/dev/null 2>&1; then
+     base="main"
+   else
+     echo "No origin/development or origin/main branch exists."
+     exit 1
+   fi
    target_branch="$(git branch --show-current)"
    test -n "$target_branch"
    test "$target_branch" != "$base"
    git status --short
+   ```
+
+   If the user names a target branch, use that branch instead of the current
+   branch. If the target branch is not local but exists on `origin`, create a
+   local branch from the remote head before continuing:
+
+   ```sh
+   if ! git show-ref --verify --quiet "refs/heads/$target_branch"; then
+     git fetch origin "$target_branch:$target_branch"
+   fi
+   git switch "$target_branch"
    git fetch origin "$base" --prune
-   pr_number="$(gh pr list --head "$target_branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
-   test -n "$pr_number"
-   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
    ```
 
-   If the PR head branch is not local, create a local branch from the remote
-   head before continuing.
+2. Push the target branch to the same remote branch name. Do not use
+   `--no-verify`; pre-push hooks must run.
 
-2. Check mergeability before changing history:
+   ```sh
+   git push -u origin "$target_branch"
+   local_sha="$(git rev-parse HEAD)"
+   remote_sha="$(git ls-remote --heads origin "$target_branch" | awk '{print $1}')"
+   test "$local_sha" = "$remote_sha"
+   ```
+
+3. Reuse an existing open PR for this exact branch/base pair, or create one
+   when none exists:
+
+   ```sh
+   pr_number="$(gh pr list \
+     --head "$target_branch" \
+     --base "$base" \
+     --state open \
+     --json number \
+     --jq '.[0].number // empty')"
+
+   if [ -z "$pr_number" ]; then
+     git log --reverse --format='%s' "origin/$base..HEAD"
+     git diff --stat "origin/$base...HEAD"
+     pr_url="$(gh pr create \
+       --base "$base" \
+       --head "$target_branch" \
+       --title "$title" \
+       --body "$body")"
+     pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
+   fi
+   ```
+
+4. Mark draft PRs ready and check mergeability before changing history:
 
    ```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 view "$pr_number" --json mergeStateStatus,mergeable,headRefName,baseRefName
    if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-merge-tree.out
    then
@@ -110,7 +143,7 @@ Do not continue automatically when:
    fi
    ```
 
-3. If a merge conflict is detected, rebase the target branch on the fresh base
+5. If a merge conflict is detected, rebase the target branch on the fresh base
    branch. Abort and stop if the rebase conflicts:
 
    ```sh
@@ -125,33 +158,14 @@ Do not continue automatically when:
    fi
    ```
 
-   Do not resolve rebase conflicts unless the user explicitly asks.
-
-4. Load and apply all relevant repository skills before merging:
-   - Read the repository's `.agents/skills/**/SKILL.md` files that apply to the
-     changed code, plus shared workspace standards when present.
-   - Compare the target branch against the base with
-     `git diff --stat "origin/$base...HEAD"` and inspect changed files.
-   - Check whether the target branch satisfies the applicable coding,
-     architecture, validation, security, and style criteria from those skills.
-   - Run the validation commands required by the skills and repository hooks.
-   - If criteria are not met and the fix does not change functionality, make the
-     minimal cleanup, stage only intended files, commit to the target branch,
-     and push the target branch.
-   - If meeting the criteria would change behavior, stop and report the gap.
-
-5. Confirm the PR is still mergeable after validation changes:
-
-   ```sh
-   git fetch origin "$base" --prune
-   git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-final-merge-tree.out
-   gh pr checks "$pr_number"
-   ```
+6. Load and apply all relevant repository skills before merging, then confirm
+   the PR is still mergeable after any validation changes.
 
-6. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
+7. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
    not protected:
 
    ```sh
+   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
    if [ "$protected" = true ]; then
      gh pr merge "$pr_number" --squash --admin
    else
@@ -159,17 +173,27 @@ Do not continue automatically when:
    fi
    ```
 
-7. Clean up the local repository after merge:
+8. If the merge succeeded and the remote branch still exists while unprotected,
+   delete it explicitly:
 
    ```sh
-   git fetch origin "$base" --prune
+   if [ "$protected" != true ] && git ls-remote --exit-code --heads origin "$target_branch" >/dev/null 2>&1; then
+     git push origin --delete "$target_branch"
+   fi
+   ```
+
+9. Clean up the local repository after merge:
+
+   ```sh
+   git fetch origin --prune
    git switch "$base"
    git pull --ff-only origin "$base"
    git branch -d "$target_branch" || git branch -D "$target_branch"
    git ls-remote --heads origin "$target_branch"
    ```
 
-8. Final response should include the PR URL, whether a rebase was performed,
-   what validation and skill checks ran, whether any cleanup commit was added,
-   whether the remote target branch was deleted or protected, and whether local
-   development is up to date.
+10. Final response should include the PR URL, selected base branch, whether a
+    rebase was performed, what validation and skill checks ran, whether any
+    cleanup commit was added, whether the remote target branch was deleted or
+    protected, whether the local target branch was deleted, and whether local
+    base branch is up to date.

package/.agents/skills/pkg-jwt-read-jwt-middleware-library/SKILL.md

@@ -104,6 +104,8 @@ depend on those folders being present.
 - Extraction of `sub`/clientId and other claims from JWT objects.
 - Expiration checks and TTL calculations.
 - Request attachment behavior for authenticated JWT objects and visitor tokens.
+- Request attachment behavior for compact scoped authorization-context JWTs
+  from `X-Authorization-Context` as `req.userAuthorization`.
 - Server-auth request attachment behavior that normalizes introspected claims
   into `req.jwt.payload` with `authMode: "server-auth"` and
   `auth_mode: "server-auth"`.
@@ -130,6 +132,13 @@ must check expected issuer, audience, subject, and lifetime. Do not add
 CareCard-specific replacement claims when a registered JWT claim covers the
 same meaning.
 
+Scoped authorization-context JWTs from `X-Authorization-Context` are independent
+from the primary `Authorization` JWT. They must attach to
+`req.userAuthorization`, not `req.jwt`, and they should be read as raw JWT
+header values rather than `Bearer` tokens. Existing JWT and server-auth
+middleware may accept an optional trailing `userAuthorization` options object;
+preserve legacy behavior when that option is omitted.
+
 ## Role Mapping Layer
 
 `lib/jwtRoles.js` owns translation between internal role codes and human-readable
@@ -171,7 +180,8 @@ role names, such as `ad` and `admin`.
 ## Types And API Contracts
 
 - Model JWT header, payload, server-auth introspection claims, request
-  attachment, visitor attachment, role, and context shapes explicitly in
+  attachment, visitor attachment, user authorization attachment, role, and
+  context shapes explicitly in
   `index.d.ts`.
 - Prefer `AuthenticatedRequest`, `JwtHeader`, `JwtPayload`, `JwtParts`,
   `JwtRequestObject`, `VisitorRequestObject`, and `JwtContext` over loose