@carecard/auth-util 3.28.0 → 3.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/.agents/skills/carecard-must-do/SKILL.md +117 -0
  2. package/.agents/skills/carecard-workspace-standards/SKILL.md +46 -33
  3. package/.agents/skills/github-pr-create-update/SKILL.md +140 -167
  4. package/.agents/skills/github-pr-merge-cleanup/SKILL.md +214 -205
  5. package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md +42 -32
  6. package/.agents/skills/pkg-auth-util-coding-standards-and-best-practices/SKILL.md +39 -3
  7. package/.agents/skills/pkg-publish/SKILL.md +66 -7
  8. package/AGENTS.md +13 -1
  9. package/CLAUDE.md +43 -0
  10. package/package.json +4 -4
  11. package/readme.md +14 -0
package/.agents/skills/github-pr-merge-cleanup/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: github-pr-merge-cleanup
3
- 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.'
3
+ description: 'Use for authorized GitHub PR squash merge and source cleanup. Create a branch from fresh origin/main only without a working branch or from main or development; otherwise preserve and rebase the current branch for subsequent tasks. Delete merged source branches, and synchronize main and development without deleting or force-pushing main.'
4
4
  ---
5
5
 
6
6
  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,224 +17,233 @@ Non-negotiable error and warning rule: Never suppress, silence, hide, downgrade,
17
17
 
18
18
  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.
19
19
 
20
- ## Purpose
21
-
22
- After the user explicitly asks for remote Git or GitHub PR work, push the
23
- branch, create a missing PR when needed, review, validate, merge, delete the
24
- branch when allowed, and clean local state for a GitHub pull request targeting
25
- `development`, or `main` when `development` is absent.
26
-
27
- ## When To Use
28
-
29
- - Use only when the user explicitly asks to push, review mergeability,
30
- validate, merge, close, or clean up a GitHub pull request branch.
31
-
32
- ## When Not To Use
33
-
34
- - Do not use for PR-only creation/update work without a merge request; use the
35
- PR create/update skill.
36
- - Do not use when the user only asks for local code changes without PR merge
37
- work.
38
-
39
- ## Remote Git Operations Guardrail
40
-
41
- Do not run remote Git or GitHub operations unless the current user request
42
- explicitly asks for them. This includes `git fetch`, `git pull`, `git push`,
43
- `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr`
44
- command that creates, updates, readies, merges, closes, or cleans up a pull
45
- request. Do not infer permission from branch names, validation needs, prior
46
- workflow habits, or convenience; ask first when remote state would help but was
47
- not requested.
48
-
49
- ## Scope
50
-
51
- Use this skill from the root of the repository that owns the pull request. The
52
- repository must use GitHub CLI, have a remote base branch, and have the target
53
- branch available locally or on `origin`.
54
-
55
- Default terms:
56
-
57
- - Base branch: `development` when `origin/development` exists, otherwise
58
- `main` when `origin/main` exists.
59
- - Target branch: the current branch unless the user names another branch.
60
- - Pull request: the open PR whose head is the target branch and whose base is
61
- the base branch.
62
-
63
- Do not continue automatically when:
64
-
65
- - `gh auth status` fails.
66
- - The target branch is detached or is the base branch.
67
- - The working tree has uncommitted changes that are not part of the requested
68
- PR cleanup.
69
- - Neither `origin/development` nor `origin/main` exists.
70
- - A rebase or validation fix would require behavior changes instead of coding
71
- criteria cleanup.
72
-
73
- If no open pull request exists for the target branch and selected base, create
74
- one as part of the merge workflow when the user requested push/PR/merge
75
- completion.
76
-
77
- ## Workflow
78
-
79
- 1. Capture the base branch, target branch, and authentication state:
80
-
81
- ```sh
82
- gh auth status
83
- remote_base_refs="$(git ls-remote --heads origin development main)"
84
- remote_query_status=$?
85
- if [ "$remote_query_status" -ne 0 ]; then
86
- printf 'Unable to inspect origin base branches (exit %s).\n' "$remote_query_status" >&2
87
- exit "$remote_query_status"
88
- fi
89
- case "$remote_base_refs" in
90
- *"refs/heads/development") base="development" ;;
91
- *"refs/heads/main") base="main" ;;
92
- *)
93
- printf '%s\n' "No origin/development or origin/main branch exists." >&2
94
- exit 1
95
- ;;
96
- esac
97
- target_branch="$(git branch --show-current)"
98
- test -n "$target_branch"
99
- test "$target_branch" != "$base"
100
- git status --short
101
- ```
102
-
103
- If the user names a target branch, use that branch instead of the current
104
- branch. If the target branch is not local but exists on `origin`, create a
105
- local branch from the remote head before continuing:
106
-
107
- ```sh
108
- if ! git show-ref --verify --quiet "refs/heads/$target_branch"; then
109
- git fetch origin "$target_branch:$target_branch"
110
- fi
111
- git switch "$target_branch"
112
- git fetch origin "$base" --prune
113
- ```
114
-
115
- 2. Push the target branch to the same remote branch name. Do not use
116
- `--no-verify`; pre-push hooks must run.
117
-
118
- ```sh
119
- git push -u origin "$target_branch"
120
- local_sha="$(git rev-parse HEAD)"
121
- remote_sha="$(git ls-remote --heads origin "$target_branch" | awk '{print $1}')"
122
- test "$local_sha" = "$remote_sha"
123
- ```
124
-
125
- 3. Reuse an existing open PR for this exact branch/base pair, or create one
126
- when none exists:
127
-
128
- ```sh
129
- pr_number="$(gh pr list \
130
- --head "$target_branch" \
131
- --base "$base" \
132
- --state open \
133
- --json number \
134
- --jq '.[0].number // empty')"
135
-
136
- if [ -z "$pr_number" ]; then
137
- git log --reverse --format='%s' "origin/$base..HEAD"
138
- git diff --stat "origin/$base...HEAD"
139
- pr_url="$(gh pr create \
140
- --base "$base" \
141
- --head "$target_branch" \
142
- --title "$title" \
143
- --body "$body")"
144
- pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
145
- fi
146
- ```
147
-
148
- 4. Mark draft PRs ready and check mergeability before changing history:
149
-
150
- ```sh
151
- is_draft="$(gh pr view "$pr_number" --json isDraft --jq '.isDraft')"
152
- if [ "$is_draft" = "true" ]; then
153
- gh pr ready "$pr_number"
154
- fi
155
- gh pr view "$pr_number" --json mergeStateStatus,mergeable,headRefName,baseRefName
156
- if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-merge-tree.out
157
- then
158
- merge_conflict_detected=false
159
- else
160
- merge_conflict_detected=true
161
- fi
162
- ```
163
-
164
- 5. If a merge conflict is detected, rebase the target branch on the fresh base
165
- branch. Abort and stop if the rebase conflicts:
20
+ ## Default Git Policy
21
+
22
+ Reuse the current working branch for every follow-up request, even when the
23
+ subject changes or the working tree is clean. Create a branch only when no
24
+ working branch exists or the checkout is on `main` or `development`. Otherwise,
25
+ fetch remote `main` HEAD and rebase the same working branch onto that fetched
26
+ commit, preserving its commits and uncommitted work.
27
+
28
+ Apply these defaults unless the user explicitly specifies otherwise. The
29
+ prohibition on deleting or force-pushing `main` always applies.
30
+
31
+ 1. Use `main` as the PR base and freshly fetched `origin/main` as the source of
32
+ truth. `origin/HEAD`, a stale local `main`, and the presence of `development`
33
+ do not change this default. If remote `main` is missing or cannot be fetched,
34
+ report the blocker instead of selecting another base.
35
+ 2. At task start, fetch `origin/main`. Create `<agent-name>/<branch-name>`
36
+ from that commit only when no working branch exists or the current branch is
37
+ `main` or `development`.
38
+ Otherwise keep and rebase the current branch onto that commit, preserving
39
+ its existing commits and building subsequent task commits on top. Honor an
40
+ explicit working-branch instruction; it changes branch selection, not
41
+ freshness.
42
+ 3. Fetch again before every source-branch push. Rebase when the working branch
43
+ does not already contain the latest `origin/main`; a clean mergeability
44
+ check is not proof that rebasing is unnecessary. If it already contains that
45
+ commit, no rebase is needed. The direct `development` replacement below is a
46
+ ref synchronization, not a source-branch rebase.
47
+ 4. Squash-merge into remote `main` after the applicable validation passes.
48
+ Administrator privileges may be used to merge without GitHub reviews; they
49
+ do not authorize bypassing required checks. Verify the merge, then delete
50
+ the merged source branch remotely and locally.
51
+ 5. Fetch the latest remote `main` after merging and fast-forward local `main`
52
+ to that commit. Preserve divergent local work and report a blocked update
53
+ rather than discarding it.
54
+ 6. Replace branches named exactly `development`, locally and remotely, with
55
+ the latest remote `main` commit. Use an explicit, observed-commit
56
+ `--force-with-lease` for a non-fast-forward remote update. Create a missing
57
+ counterpart when local or remote `development` exists; leave repositories
58
+ with neither unchanged. If `development` was the merged source, recreate
59
+ it from the new `main` after deleting it. Other working branches are not
60
+ development synchronization targets.
61
+ 7. Never delete local or remote `main`, and never force-push to remote `main`,
62
+ including with `--force-with-lease`, a forced refspec, or a mirror push.
63
+ Check the exact destination ref before every deletion or forced update.
64
+
65
+ Fetches needed to establish a fresh `origin/main` at task start and before a
66
+ source-branch push are authorized without a separate approval question. Commits,
67
+ pushes, PR mutations, and branch cleanup require an authorized task; a request
68
+ for local work alone does not authorize publication. An authorized squash merge
69
+ into `main` includes the merged-source cleanup, local `main` update, and
70
+ `development` synchronization below unless the user explicitly says otherwise.
71
+ Never delete local or remote `main`, or force-push to remote `main`, including
72
+ with `--force-with-lease`.
73
+
74
+ ## Prepare The Working Branch
75
+
76
+ Work from the owning repository root. Inspect status, the current branch,
77
+ upstream, and worktrees before changing refs. Preserve unrelated changes and
78
+ existing commits; do not reset a working branch to discard its work. Honor the
79
+ user's explicit working-branch instruction. Create a new
80
+ `<agent-name>/<branch-name>` from fresh `origin/main` only when no working branch
81
+ exists or the current branch is `main` or `development`. Otherwise keep the current
82
+ branch, rebase it
83
+ onto fresh `origin/main`, and build the new task's commits on its existing
84
+ work. A different task or a clean working tree does not require a new branch.
85
+ Do not use `main` or the selected base as a PR source branch. Stop if the source
86
+ branch cannot be resolved or HEAD is detached.
87
+
88
+ Fetch the authoritative ref explicitly:
89
+
90
+ ```sh
91
+ git fetch origin refs/heads/main:refs/remotes/origin/main
92
+ ```
93
+
94
+ For an existing working branch, preserve any uncommitted changes and rebase
95
+ before starting task changes; restore any changes temporarily set aside:
96
+
97
+ ```sh
98
+ git rebase origin/main
99
+ ```
100
+
101
+ Before every source-branch push, including pushes after validation fixes,
102
+ fetch again and rebase when the branch does not already contain the latest
103
+ `origin/main`. If rebasing changes the validated inputs, rerun
104
+ the affected validation. Preserve successful evidence for unchanged inputs.
105
+ If a rebase conflicts, abort only the rebase started by this task and report
106
+ the conflict; do not push or discard work. Preserve any pre-existing Git
107
+ operation and dirty worktree rather than trying to reset through it.
108
+
109
+ Before rebasing a published source branch, record its remote commit and verify
110
+ that its existing work is accounted for locally. Reconcile unincorporated
111
+ remote work before rewriting it. Use a normal push for a new branch or a
112
+ fast-forward update. When a rebase requires rewriting the remote source, use
113
+ an explicit lease tied to the recorded source commit:
114
+
115
+ ```sh
116
+ if [ -z "$source_branch" ] || [ "$source_branch" = main ]; then
117
+ printf '%s\n' 'Refusing to delete or force-update main or an unnamed branch.' >&2
118
+ exit 1
119
+ fi
120
+ git push --set-upstream \
121
+ --force-with-lease="refs/heads/$source_branch:$observed_source_commit" \
122
+ origin "HEAD:refs/heads/$source_branch"
123
+ ```
124
+
125
+ Resolve `source_branch` and `observed_source_commit` from verified repository
126
+ state before using this example. Do not replace a rejected lease with
127
+ `--force` or retry against a new expected commit without inspecting the remote
128
+ change. Keep hooks enabled. Verify that the remote source commit equals the
129
+ local commit after a successful push.
130
+
131
+ ## Create Or Update The Pull Request
132
+
133
+ 1. Confirm GitHub authentication, the intended source branch, and the clean,
134
+ committed changes included in the PR. Load the owning repository skills and
135
+ run their applicable validation. Stage and commit only authorized changes;
136
+ preserve supplied branch names, titles, commit messages, and PR text.
137
+ 2. Prepare and push the source branch using the fresh-main procedure above.
138
+ 3. Find the open PR for that source. Reuse the exact source/base match. If
139
+ automation created the task PR against `development`, retarget that PR to
140
+ `main` and recheck its diff and checks instead of creating a duplicate.
141
+ Honor an explicit user-selected base; do not silently retarget that choice.
142
+ 4. Create a missing PR against `main` when PR creation is authorized. Use a
143
+ file for a multiline body with `gh pr create --body-file` or
144
+ `gh pr edit --body-file`. Do not create an empty PR for a source already
145
+ represented in the base; report the no-op and perform only authorized
146
+ cleanup supported by merge or content-equivalence evidence.
147
+ 5. Mark draft PRs ready in the authorized create/update/ready or merge workflow,
148
+ while preserving an explicit request to keep the PR as a draft. Keep the title factual and preserve exact user-supplied text.
149
+ A create/update-only request ends with the PR; it does not authorize merging.
150
+
151
+ ## Squash Merge And Delete The Source Branch
152
+
153
+ 1. Verify the PR base, source branch, source commit, draft state, mergeability,
154
+ and required validation. Push any authorized changes through the fresh-main
155
+ procedure first. Confirm checks apply to the commit being merged. Record
156
+ local and remote development presence and commit IDs before source cleanup.
157
+ 2. Squash-merge the verified source commit. Administrator privileges are
158
+ permitted to merge without reviews, with applicable checks still passing:
166
159
 
167
160
  ```sh
168
- if [ "$merge_conflict_detected" = true ]; then
169
- if git rebase "origin/$base"; then
170
- git push --force-with-lease -u origin "$target_branch"
171
- else
172
- git rebase --abort
173
- echo "Rebase conflicted; aborted without merging."
174
- exit 1
175
- fi
176
- fi
161
+ gh pr merge "$pr_number" --squash --admin \
162
+ --match-head-commit "$source_commit"
177
163
  ```
178
164
 
179
- 6. Load and apply all relevant repository skills before merging, then confirm
180
- the PR is still mergeable after any validation changes.
181
-
182
- 7. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
183
- not protected:
184
-
185
- ```sh
186
- protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected')"
187
- protection_query_status=$?
188
- if [ "$protection_query_status" -ne 0 ]; then
189
- printf 'Unable to inspect branch protection (exit %s).\n' "$protection_query_status" >&2
190
- exit "$protection_query_status"
191
- fi
192
- case "$protected" in
193
- true|false) ;;
194
- *)
195
- printf 'Unexpected branch protection value: %s\n' "$protected" >&2
196
- exit 1
197
- ;;
198
- esac
199
- if [ "$protected" = true ]; then
200
- gh pr merge "$pr_number" --squash --admin
201
- else
202
- gh pr merge "$pr_number" --squash --admin --delete-branch
203
- fi
204
- ```
165
+ Preserve a supplied squash message with `--subject` and, for remaining
166
+ lines, `--body-file`. Do not change repository rules to make a merge pass.
205
167
 
206
- 8. If the merge succeeded and the remote branch still exists while unprotected,
207
- delete it explicitly:
168
+ 3. Verify GitHub reports the PR as merged and record its squash commit. Fetch
169
+ `origin/main` and prove it contains that squash commit. A squash merge does
170
+ not preserve source commit IDs, so ordinary source ancestry alone is not
171
+ merge proof.
172
+ 4. Before deleting anything, verify the source is not `main`, the local source
173
+ has no newer unmerged work, and the remote source still equals the merged
174
+ source commit. Delete an existing remote source using a lease so a
175
+ concurrent push is not erased:
208
176
 
209
177
  ```sh
210
- if [ "$protected" != true ]; then
211
- remote_target_ref="$(git ls-remote --heads origin "$target_branch")"
212
- remote_query_status=$?
213
- if [ "$remote_query_status" -ne 0 ]; then
214
- printf 'Unable to inspect the remote target branch (exit %s).\n' "$remote_query_status" >&2
215
- exit "$remote_query_status"
216
- fi
217
- if [ -n "$remote_target_ref" ]; then
218
- git push origin --delete "$target_branch"
219
- fi
178
+ if [ -z "$source_branch" ] || [ "$source_branch" = main ]; then
179
+ printf '%s\n' 'Refusing to delete or force-update main or an unnamed branch.' >&2
180
+ exit 1
220
181
  fi
182
+ git push --force-with-lease="refs/heads/$source_branch:$source_commit" \
183
+ origin ":refs/heads/$source_branch"
221
184
  ```
222
185
 
223
- 9. Clean up the local repository after merge:
186
+ An already-absent remote branch needs no deletion. If branch protection or
187
+ a changed source prevents deletion, report cleanup as blocked; do not alter
188
+ repository protection or discard newly added commits.
189
+
190
+ 5. Switch safely off the source branch. Delete the verified merged local
191
+ source. `git branch -D -- "$source_branch"` is permitted only after the
192
+ explicit non-`main` guard and squash-merge proof; do not use an unconditional
193
+ `-d || -D` fallback. Preserve dirty or independently checked-out worktrees.
194
+ Confirm source absence locally and remotely. A merged `development` source
195
+ is subsequently recreated under the synchronization rule below.
196
+
197
+ ## Synchronize Main And Development
198
+
199
+ Run after an authorized squash merge into `main`, unless the user explicitly
200
+ changes the cleanup instructions. Do not reset development after a merge into
201
+ an explicitly selected different base.
202
+
203
+ 1. Fetch `origin/main` again. Fast-forward local `main` with
204
+ `git merge --ff-only origin/main` while on `main`, or create local `main`
205
+ from `origin/main` if missing. If local `main` diverges, preserve its commits
206
+ and report the blocked synchronization. Never force-push or delete `main`.
207
+ 2. Use the old local and remote `development` commit IDs and presence recorded
208
+ before source cleanup. If neither existed, report development sync
209
+ as not applicable. Otherwise ensure both refs point to the freshly fetched
210
+ `origin/main` commit, creating a missing counterpart. This intentionally
211
+ replaces divergent development history; preserve dirty worktrees and do
212
+ not apply it to any other working branch.
213
+ 3. Record `main_commit` from `origin/main` and `observed_development_commit`
214
+ from a successful remote query; use an empty expected value only when that
215
+ query proves the remote branch absent. Update the remote with an explicit
216
+ destination and lease:
224
217
 
225
218
  ```sh
226
- git fetch origin --prune
227
- git switch "$base"
228
- git pull --ff-only origin "$base"
229
- git branch -d "$target_branch" || git branch -D "$target_branch"
230
- git ls-remote --heads origin "$target_branch"
219
+ git push \
220
+ --force-with-lease="refs/heads/development:$observed_development_commit" \
221
+ origin "$main_commit:refs/heads/development"
231
222
  ```
232
223
 
233
- 10. Final response should include the PR URL, selected base branch, whether a
234
- rebase was performed, what validation and skill checks ran, whether any
235
- cleanup commit was added, whether the remote target branch was deleted or
236
- protected, whether the local target branch was deleted, and whether local
237
- base branch is up to date.
224
+ Skip a push when the remote ref already equals `main_commit`. A rejected
225
+ lease requires inspecting concurrent changes before attempting another
226
+ update. Do not use a broad force push or mirror push.
227
+
228
+ 4. From the clean `main` checkout, create or repoint local `development` at
229
+ `main_commit` and set it to track `origin/development`. Do not overwrite a
230
+ branch checked out with uncommitted work in another worktree. Keep the
231
+ checkout on `main` unless the user specified a different final branch.
232
+ 5. Fetch and query the final remote refs. Verify commit equality for local
233
+ `main`, remote `main`, and both `development` refs where applicable, together
234
+ with merged-source absence, except when the source was `development` and
235
+ has been recreated at the new main commit. Tree equality alone is
236
+ insufficient for these synchronized refs. If remote `main` advanced, synchronize to its new commit
237
+ and recheck; report an unstable or blocked state instead of claiming parity.
238
+
239
+ ## Reporting
240
+
241
+ Report the repository, working branch, fetched main commit, whether rebasing
242
+ was needed, validation results, push result, PR URL and state, administrator
243
+ merge use, source cleanup, final checkout, and main/development commit parity.
244
+ Distinguish merged, unchanged, not applicable, and blocked repositories. Give
245
+ the exact failing command and reason for an incomplete step. Do not amend
246
+ commits unless explicitly requested; use additive commits for follow-up work.
238
247
 
239
248
  ## TDD And Validation
240
249
 
package/.agents/skills/pkg-auth-util-auth-crypto-library/SKILL.md CHANGED
@@ -242,41 +242,51 @@ and remaining risk.
242
242
 
243
243
  ## Remote Git Operations Guardrail
244
244
 
245
- 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.
245
+ Fetches needed to establish a fresh `origin/main` at task start and before a
246
+ source-branch push are authorized without a separate approval question. Commits,
247
+ pushes, PR mutations, and branch cleanup require an authorized task; a request
248
+ for local work alone does not authorize publication. An authorized squash merge
249
+ into `main` includes the merged-source cleanup, local `main` update, and
250
+ `development` synchronization below unless the user explicitly says otherwise.
251
+ Never delete local or remote `main`, or force-push to remote `main`, including
252
+ with `--force-with-lease`.
246
253
 
247
254
  ## Agent Guidance Git Workflow
248
255
 
249
- When this skill or any repository-owned `.agents` guidance changes, use the
250
- repository's agents-only Git workflow:
251
-
252
- 1. Work from the affected repository root and confirm only intended `.agents`
253
- files changed.
254
- 2. Use `development` as the base branch when `origin/development` exists;
255
- otherwise use the repository's default base branch, usually `main`.
256
- 3. Create or update `feature/codex` from the updated remote base branch and
257
- commit all the changed `.agents` guidance files there.
258
- 4. Push `feature/codex`, create or reuse a pull request into the base branch,
259
- and mark the pull request ready for review with `gh pr ready <number>`.
260
- 5. Squash-merge with administrator privileges and delete the remote branch:
261
-
262
- ```sh
263
- gh pr merge <number> --squash --admin --delete-branch
264
- ```
265
-
266
- 6. After merge, update the local base branch and remove the local feature
267
- branch:
268
-
269
- ```sh
270
- git fetch origin <base> --prune
271
- git switch <base>
272
- git pull --ff-only origin <base>
273
- git branch -d feature/codex
274
- git ls-remote --heads origin feature/codex
275
- ```
276
-
277
- Do not commit or push `.agents` guidance changes directly from `development`
278
- or `main`. Do not stage unrelated files, generated output, dependency folders,
279
- build artifacts, logs, or `.DS_Store`.
256
+ Reuse the current working branch for every follow-up request, even when the
257
+ subject changes or the working tree is clean. Create a branch only when no
258
+ working branch exists or the checkout is on `main` or `development`. Otherwise,
259
+ fetch remote `main` HEAD and rebase the same working branch onto that fetched
260
+ commit, preserving its commits and uncommitted work.
261
+
262
+ Work from the owning repository root and stage only intended guidance changes.
263
+ Fetch fresh `origin/main` at task start. Create `<agent-name>/<branch-name>`
264
+ from it only when no working branch exists or the current branch is `main` or
265
+ `development`. Otherwise keep
266
+ and rebase the current branch onto it, preserving existing commits and
267
+ uncommitted changes. Build subsequent task commits on that same branch, even
268
+ for a different task or a clean working tree. Honor explicit user
269
+ working-branch instructions.
270
+
271
+ Fetch again before every source-branch push and rebase only when the branch
272
+ does not already contain the latest `origin/main`. Required fetches need no
273
+ separate approval; commits, pushes, PR mutations, and cleanup require an
274
+ authorized task. A local guidance edit does not authorize publishing it.
275
+
276
+ For an authorized merge, create or reuse the PR into `main`, run applicable
277
+ validation, and squash-merge; administrator privileges may be used without
278
+ GitHub reviews. Verify the merge and delete its source branch remotely and
279
+ locally after checking for newer unmerged work. Then fast-forward local `main`
280
+ and replace local and remote branches named exactly `development` with the
281
+ latest remote `main` commit, using an explicit observed-commit
282
+ `--force-with-lease` remotely. Create a missing development counterpart when
283
+ either existed; leave repositories with neither unchanged. If development was
284
+ the merged source, recreate it from the new main. Verify commit parity and
285
+ cleanup; preserve dirty worktrees and report conflicts or rejected leases.
286
+
287
+ Never delete local or remote `main` or force-push to remote `main`, including
288
+ with `--force-with-lease`. Guard exact destination refs before deleting or
289
+ forcing any branch. Do not amend commits or stage unrelated files.
280
290
 
281
291
  ## Fail-Closed Test Lifecycle Audit
282
292
 
package/.agents/skills/pkg-auth-util-coding-standards-and-best-practices/SKILL.md CHANGED
@@ -1,10 +1,32 @@
1
1
  ---
2
2
  name: pkg-auth-util-coding-standards-and-best-practices
3
- description: 'Mandatory for every pkg-auth-util task, including analysis, clarification, planning, implementation, review, debugging, documentation, public API work, skill maintenance, and validation. Use before every narrower skill.'
3
+ description: 'Use after carecard-must-do. Mandatory for every pkg-auth-util task, including analysis, clarification, planning, implementation, review, debugging, documentation, public API work, skill maintenance, and validation. Use before every narrower skill.'
4
4
  ---
5
5
 
6
6
  # Pkg Auth Util Coding Standards And Best Practices
7
7
 
8
+ ## Release 1.1.1 and production data
9
+
10
+ CareCard Release 1.1.1 is the production baseline. Seeding with
11
+ `--seed-release-data` is complete. Production cluster data, database rows,
12
+ and stored user files will be preserved going forward. There will be no
13
+ complete user-data wipeout and re-creation.
14
+
15
+ Future production changes must use data-preserving migrations. Do not replay
16
+ the completed initialization or run reset, rollback, or seed workflows as part
17
+ of ordinary production deployment.
18
+
19
+ ## Commit and merge documentation and skills with the task
20
+
21
+ In each owning repository, include all task-related documentation, plans, and
22
+ skill changes in the same commit as the related task changes. Merge them
23
+ together into remote `main`. Do not leave changed documentation or skills
24
+ uncommitted or unmerged, and do not declare the task complete until their
25
+ inclusion in the merged commit is verified. Preserve unrelated work.
26
+
27
+ First read [carecard-must-do](../carecard-must-do/SKILL.md); it is mandatory for every agent and task.
28
+ Then apply this engineering standard before selecting narrower skills.
29
+
8
30
  ## JavaScript And TypeScript Style Contract
9
31
 
10
32
  - 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.
40
62
 
41
63
  ## Mandatory Use And Authorities
42
64
 
43
- Load this skill before doing any work in `pkg-auth-util`, including read-only
65
+ After `carecard-must-do`, load this skill before doing any work in `pkg-auth-util`, including read-only
44
66
  and documentation-only work. Then load every narrower skill that owns the
45
67
  affected package contract.
46
68
 
@@ -166,6 +188,12 @@ them unused and replaced.
166
188
 
167
189
  ## Completion
168
190
 
191
+ Reuse the current working branch for every follow-up request, even when the
192
+ subject changes or the working tree is clean. Create a branch only when no
193
+ working branch exists or the checkout is on `main` or `development`. Otherwise,
194
+ fetch remote `main` HEAD and rebase the same working branch onto that fetched
195
+ commit, preserving its commits and uncommitted work.
196
+
169
197
  1. Review each changed repository's diff and status independently.
170
198
  2. Run focused runtime and type tests, then all broader checks required by
171
199
  local skills.
@@ -175,7 +203,15 @@ them unused and replaced.
175
203
  none exists, run the strongest repository-native focused validation.
176
204
  5. Fix every in-scope failure at its root cause and rerun the exact command.
177
205
  6. Report exact commands, results, limitations, and remaining risk.
178
- 7. Do not perform remote Git or GitHub operations unless explicitly requested.
206
+ 7. Fetch the latest `origin/main` at task start and before every source-branch
207
+ push; these required fetches need no separate approval. Create
208
+ `<agent-name>/<branch-name>` from it only when no working branch exists or the
209
+ current branch is `main` or `development`. Otherwise rebase the current branch
210
+ onto it, preserving
211
+ existing commits and uncommitted changes, and build subsequent task commits
212
+ on that same branch. Commits, pushes, PR mutations, and branch cleanup still
213
+ require an authorized task. Never delete local or remote `main` or
214
+ force-push to remote `main`.
179
215
 
180
216
  ## TDD And Validation
181
217