@veda-hq/niyam 0.6.16 → 0.6.18

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.
package/README.md CHANGED
@@ -329,8 +329,7 @@ Claude cloud sessions below).
329
329
  ◇ This Mac
330
330
  │ pre-push hook new
331
331
  │
332
- ◇ Claude cloud — by hand, once
333
- │ Setup script niyam cloud-setup, first
332
+ ◇ Claude cloud — by hand, once per claude.ai account
334
333
  │ claude.ai's GitHub as AGENT
335
334
  │
336
335
  ◇ Check
@@ -347,7 +346,16 @@ Claude cloud sessions below).
347
346
  run asks you to name the owner. Without a terminal, `onboard` refuses
348
347
  unless given `--yes` or `--dry-run`. After the yes it shows one line per step, a
349
348
  spinner while it works, and ends with the pull request and a short "By
350
- hand:" list of what GitHub's API cannot do.
349
+ hand:" list of what GitHub's and Claude's APIs cannot do. Each line there
350
+ is one sentence on standard output saying the whole step: how often (now,
351
+ once for the repository, once per claude.ai account), what to do, and its
352
+ link. A first onboarding with the review routine ends:
353
+
354
+ ```
355
+ By hand:
356
+ Once for owner/repo: in Claude Code, run /schedule and create a weekly routine on it, with claude.ai's GitHub connected as AGENT and the prompt below the line in https://github.com/veda-hq/niyam/blob/v0.6.15/routines/review.md.
357
+ Once per claude.ai account: sign in at https://claude.ai/code and connect GitHub as AGENT (or change it at https://claude.ai/customize/connectors); skip it if done.
358
+ ```
351
359
 
352
360
  It writes `.github/niyam.json`, adds to `.claude/settings.json`
353
361
  the lock in `env`, a SessionStart hook running `niyam session-start`, a
@@ -366,14 +374,16 @@ Claude cloud sessions below).
366
374
  `niyam / Work rules`. With identity alone `onboard` writes no workflow. It writes
367
375
  `.github/niyam/cloud-setup.sh`, which installs the CLI in Claude
368
376
  cloud sessions at the version the workflow pins, and writes it again on
369
- every run (see Claude cloud sessions below); the first time, the plan
370
- lists the one paste into the cloud environment's Setup script. Where the
377
+ every run (see Claude cloud sessions below); a cloud session with no
378
+ niyam runs it from the SessionStart hook, so there is nothing to paste,
379
+ and the first time, the plan lists the one connection of claude.ai's
380
+ GitHub as the agent, once per claude.ai account. Where the
371
381
  repo still has `.github/process-rules/cloud-setup.sh`, which releases up
372
382
  to 0.6.10 wrote beside it, the pull request deletes it, but only where it
373
383
  leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
374
384
  when GitHub names no sha256 for the release, keeps the old file too), and
375
- the description says to paste the new snippet once if the Setup script
376
- was pasted before 0.6.10. It checks the agent can
385
+ the description says to delete niyam's part of a Setup script pasted
386
+ before 0.6.10. It checks the agent can
377
387
  push. With no access, or read access only (a public repo, or an
378
388
  organisation's base permission), the plan gives it write access as you
379
389
  and accepts the invitation as the agent; and `onboard` names
@@ -686,6 +696,153 @@ request does not change is dropped, as another branch's. A file whose
686
696
  one. A bot's thread and the local finding at the same file and line are one
687
697
  signal: the same review, posted twice.
688
698
 
699
+ **The hand-off gate.** A session working on one thing that trips over
700
+ another, not its fault, fixes the other thing worse than a session with no
701
+ stake would: it wants its own work unblocked. No program can see that
702
+ moment, so the gate prices two of its footprints. A push whose branch edits
703
+ the repository's shared plumbing, or whose push history shows one stage
704
+ failing three times across two working trees or more, needs a declaration
705
+ first:
706
+
707
+ ```sh
708
+ niyam handoff --detect # what fires, as JSON
709
+ niyam handoff --record --disposition own-work --reason "the workflow change is this slice"
710
+ niyam handoff --record --disposition handed-off --reason "..." --open-brief .tmp/brief.md
711
+ ```
712
+
713
+ `own-work` is one sentence. `handed-off` names a Brief issue (`--brief #N`,
714
+ or `--open-brief <draft.md>`, which lints the draft and opens it as one, on
715
+ the board `.github/niyam.json`'s `project` names). `carrying` also owes
716
+ `## What I verified` and `## Why I did not hand off`, and may blame a file
717
+ the branch changed. `dismissed` cites where the owner decided (`#123`, a
718
+ link, an id such as `ABC-123`, or a commit). `niyam pre-push` runs the gate
719
+ for an agent session, right after the identity check; `niyam handoff
720
+ --assert-fresh` runs it alone, for a hook of the client's own. It passes
721
+ when nothing fires, and otherwise only when the session's newest
722
+ declaration (`--call-site push-skill`, the default) covers this head, this
723
+ base and every trigger that fired. A blocking
724
+ brief handed off holds the push until a merged pull request saying
725
+ `Fixes #N` closes it and this branch has its merge commit, or it is closed as
726
+ not planned. Declarations and the gate's verdicts are JSON lines in
727
+ `.tmp/push/handoff-log.jsonl`. `niyam brief [--lint] <draft.md>` opens a
728
+ draft, or only checks it.
729
+
730
+ A brief draft has YAML frontmatter (`slug`, `title`, `discovered-on`: this
731
+ branch, `blocking: yes|no`, `status: open`, `blamed-paths`: a list of files,
732
+ none in the branch's own diff) and five sections: `## What happened`, with
733
+ the command and its output in a fence, `## Why this is not caused by the
734
+ originating branch`, `## Hypothesis (UNVERIFIED)`, `## What the receiving
735
+ session must verify first` and `## Sequencing`. The gate is on where the
736
+ repository names its plumbing; a folder ends in `/`, anything else is one
737
+ file by its whole path. The copy of the settings on the remote's default
738
+ branch (or the `--base` asked for) decides when it names one, the settings
739
+ file always counts as plumbing, and the base must be a remote-tracking
740
+ branch, so a branch cannot turn the gate off in the push the gate judges:
741
+
742
+ ```json
743
+ {
744
+ "handoff": {
745
+ "plumbing": [".github/workflows/", ".husky/", "package.json"],
746
+ "history": ".tmp/performance/history.jsonl",
747
+ "ignoreStages": ["checking-incidental-handoff-declarations"],
748
+ "template": "docs/templates/brief.md",
749
+ "base": "origin/main"
750
+ }
751
+ }
752
+ ```
753
+
754
+ `history` is the push history, one JSON line per hook run with its `kind`,
755
+ `exitCode`, `branch`, tree `fingerprint` and `stages` (`name`, `status`);
756
+ without one, only the plumbing trigger fires. A line that is not a whole run
757
+ is skipped, never counted.
758
+
759
+ **Dismissing a Cubic finding.** A wrong finding is the agent's call; a true
760
+ one left unfixed is the owner's. `niyam cubic-dismiss --evidence <proof>
761
+ --title <exact title> --reason <why>` records one the agent proves wrong:
762
+ the proof is a path at HEAD (a `#section` or `:line` may follow), a commit
763
+ HEAD contains by its full 40-hex id, or a title already dismissed, and one
764
+ that does not resolve is refused. `--decision <where the owner chose>`
765
+ records the owner's call; a reason, evidence or context that says
766
+ "pre-existing", "out of scope", "later" or "follow-up" is refused on
767
+ evidence. `--title`/`--reason` pair up in order and repeat, and `--from
768
+ <file.json>`, a file in the repository holding `[{"title", "reason"}]`,
769
+ carries titles a shell cannot. It appends a dated comment and the title to
770
+ the dismiss file, refuses one that already differs from HEAD, and commits
771
+ that file alone (`git commit --only`, every hook run) with a
772
+ `Dismissal-Basis: evidence` trailer, or the owner's word, so
773
+ `git log --grep "Dismissal-Basis: evidence" -p -- .cubic-dismiss` lists every
774
+ call the agent made alone. A failed commit restores the file. The settings:
775
+
776
+ ```json
777
+ { "cubicDismiss": { "file": ".cubic-dismiss", "subject": "chore(review): dismiss {count} Cubic finding{s}", "ownerBasis": "owner" } }
778
+ ```
779
+
780
+ **A pushed branch gets its pull request.** git has no post-push hook, so
781
+ `niyam pr-autocreate` takes a push from three sides. `claude-hook`, Claude
782
+ Code's PostToolUse(Bash) and Stop hook, catches a session's foreground push
783
+ once the tracking ref moved (a background one at Stop), opens the pull
784
+ request, and tells the session once to switch Autofix on: in context after
785
+ the push, or by holding Stop (exit 2); a cloud session, which has no
786
+ Autofix, gets a `systemMessage` instead. `spawn-watchers --root <repo>
787
+ --remote <name>`, run by the pre-push hook with git's ref lines on stdin,
788
+ starts one detached `watch` per pushed branch, which waits for the remote to
789
+ hold the pushed commit, then opens the pull request, retrying GitHub for ten
790
+ minutes. Nothing opens for a protected or merge-queue branch, another remote,
791
+ a branch with no commits ahead of the base, one with a merged pull request
792
+ (it is retired) or a closed one (reopening is a person's call), or in CI.
793
+ `NIYAM_PR_AUTOCREATE=0` on a push opens none for the commit it sent: the
794
+ choice is recorded before git sends the refs, and a push whose choice cannot
795
+ be recorded is refused (exit 3). Every answer is kept in
796
+ `.tmp/pr-autocreate/` (one JSON record per branch, its opt-outs, the watch
797
+ log), so GitHub is asked once per pushed commit. A session's hook reaches
798
+ GitHub as the session's agent, with every check `as-agent` makes, and the
799
+ watcher with the push's own token. Its own errors never fail a push or hold
800
+ a session.
801
+
802
+ `refuse-retired --root <repo> --remote <name>`, which the pre-push hook runs
803
+ before its expensive checks with the same ref lines, refuses (exit 3) a push to
804
+ a branch whose pull request merged while none is open. Such a push recreates a
805
+ branch the merge retired, and the commits after the merge land in no pull
806
+ request. The refusal names the way out. A branch GitHub cannot answer for, or
807
+ one with a full page of pull requests (which may hide the open one), only
808
+ warns. Exit 4 means it could not check at all; a hook reports that as not
809
+ checked. The settings:
810
+
811
+ ```json
812
+ { "prAutocreate": { "base": "main", "draft": false, "protected": ["main", "master", "develop", "prod", "production"], "skip": ["mergify/", "gh-readonly-queue/"], "optOut": [], "describe": "`gh pr edit --body-file`" } }
813
+ ```
814
+
815
+ `optOut` names older opt-out variables read beside `NIYAM_PR_AUTOCREATE`;
816
+ `describe` says how the pushing session writes the real description;
817
+ `retired`, a link, explains why a merged pull request retires its branch;
818
+ `retire`, a command with `{number}` for the merged pull request, is the way out
819
+ `refuse-retired` names; `footer` ends the placeholder body.
820
+
821
+ **Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
822
+ sends a session back while its branch has commits the base lacks and its
823
+ pull request has not merged at this commit, saying what is left (push, open
824
+ the pull request, mark it ready, carry it to merge) and the count ("1 of
825
+ 5"). It lets the session stop for a subagent; on the base, another trunk or
826
+ a detached HEAD; when another remote branch carries the commits; while a
827
+ background task, `git commit` or `git push` runs (its exit wakes the
828
+ session), except in print mode (`NIYAM_PRINT_MODE=1`), where the task dies
829
+ with the turn; for a desktop session with every commit on a ready pull
830
+ request, which Autofix wakes; when GitHub cannot say; and at a stop note for
831
+ this commit, which `niyam keep-going --stop "<why>"` writes when only the
832
+ owner can unblock the work or it is proven unneeded, and whose reason it
833
+ shows once. At the sixth stop at one commit it writes that note itself. A new
834
+ commit resets the count and voids the note. The pull request is read over
835
+ REST, as the session's agent; a cloud session is held the same way. Its
836
+ records are in `.tmp/keep-going/`. The settings:
837
+
838
+ ```json
839
+ { "keepGoing": { "trunks": [], "printMode": [], "owner": "the owner", "tag": "niyam keep-going" } }
840
+ ```
841
+
842
+ `base`, when set, names the branch work merges into; otherwise it is
843
+ origin's default branch. `printMode` names older print-mode variables read beside `NIYAM_PRINT_MODE`;
844
+ `owner` is who the messages tell a session to tell; `tag` ends each message.
845
+
689
846
  **Design frames** is the `figma` feature, an optional extension for clients
690
847
  that design in Figma: with it on and two Actions secrets, `FIGMA_LIBRARY`
691
848
  (the design library's file key) and `FIGMA_TOKEN`, each State of the slice
@@ -1015,30 +1172,42 @@ read only its REST API, here and everywhere else. The one exception is who
1015
1172
  edited an owner's edited `Decision:` comment, which only GraphQL names; here
1016
1173
  such a comment does not count.
1017
1174
 
1018
- The cloud environment's Setup script, which runs as root once the repo is
1019
- cloned and before Claude Code starts, installs the CLI. Claude Code has no
1020
- API or CLI for that field, so you paste it once, by hand, and it names no
1021
- version: `niyam cloud-setup` prints a short snippet that finds the
1022
- clone and runs its `.github/niyam/cloud-setup.sh`, with `NIYAM_SETUP` set.
1023
- `onboard` writes that file in its pull request at the version
1024
- `.github/workflows/niyam.yml` pins, and writes it again on every
1025
- run, so the pin bump that upgrades the checks upgrades cloud sessions too,
1026
- with no new paste. A snippet pasted before 0.6.10 runs
1027
- `.github/process-rules/cloud-setup.sh` alone, which `onboard` deletes since
1028
- P-57: paste the new snippet over it, once. The Setup script runs from the folder that holds the
1029
- clone (the VM's home, the clone one folder down), so the snippet looks there
1030
- and in each home. The file unpacks Node and the CLI under
1031
- `/opt/niyam`, each once it matches the sha256 the file pins (Node's
1032
- from this release, the CLI's from GitHub's record of the release archive),
1033
- and puts `niyam` on `PATH`, leaving the image's own Node alone. The
1034
- environment needs the network to reach nodejs.org and GitHub's release
1035
- downloads.
1036
-
1037
- The Setup field holds one script, so the snippet runs in a shell of its
1038
- own (`bash <<'NIYAM' … NIYAM`): a failed download, or a
1039
- clone with no such file, says so on standard error and the commands after
1040
- it still run. If the repo has its own Setup script, put this first, then
1041
- the repo's own: a repo's script may end with `exit`, and nothing after that
1175
+ **Installing niyam there.** Claude Code has no API, CLI or repo file for a
1176
+ cloud environment's Setup script, but a repo's SessionStart hooks run in its
1177
+ cloud sessions. So when `CLAUDE_CODE_REMOTE=true` and the hook finds no
1178
+ niyam CLI, it runs the clone's `.github/niyam/cloud-setup.sh` (from
1179
+ `CLAUDE_PROJECT_DIR`, else the working folder), then `session-start` as
1180
+ usual, and says in one line that it installed niyam. `onboard` writes that
1181
+ file in its pull request at the version `.github/workflows/niyam.yml` pins,
1182
+ and writes it again on every run, so the pin bump that upgrades the checks
1183
+ upgrades cloud sessions too. The file unpacks Node and the CLI under
1184
+ `/opt/niyam`, each once it matches the sha256 the file pins (Node's from
1185
+ this release, the CLI's from GitHub's record of the release archive), and
1186
+ puts `niyam` in `/usr/local/bin`, leaving the image's own Node alone, so it
1187
+ needs root; the environment needs the network to reach nodejs.org and
1188
+ GitHub's release downloads, which the default Limited access allows. The
1189
+ install's own output is dropped. When it fails, the hook's line names its
1190
+ last error line and the user it ran as, and the STOP follows; a clone with
1191
+ no such file says to run `onboard`. On a Mac, or where a CLI is found, the
1192
+ hook does as before.
1193
+
1194
+ What a hook installs is not cached, so each such session downloads about
1195
+ 50 MB first. Claude keeps a snapshot of what a Setup script installs, so
1196
+ `niyam cloud-setup` prints an optional snippet that makes sessions start
1197
+ faster: pasted at the top of the environment's Setup script, it finds the
1198
+ clone and runs the same file, with `NIYAM_SETUP` set. It names no version,
1199
+ so a new release needs no new paste. Its instructions are comment lines at
1200
+ the top of the snippet, on standard output with it, so `niyam cloud-setup
1201
+ | pbcopy` copies them too and nothing is left on standard error. A snippet
1202
+ pasted before 0.6.10 runs `.github/process-rules/cloud-setup.sh` alone,
1203
+ which `onboard` deletes since P-57: delete it, or paste the new snippet
1204
+ over it. The Setup script runs as root from the folder that holds the clone
1205
+ (the VM's home, the clone one folder down), so the snippet looks there and
1206
+ in each home. The Setup field holds one script, so the snippet runs in a
1207
+ shell of its own (`bash <<'NIYAM' … NIYAM`): a failed download, or a clone
1208
+ with no such file, says so on standard error and the commands after it
1209
+ still run. If the repo has its own Setup script, put this first, then the
1210
+ repo's own: a repo's script may end with `exit`, and nothing after that
1042
1211
  runs.
1043
1212
 
1044
1213
  Claude keeps a snapshot of the environment once its Setup script has run,
@@ -1049,8 +1218,9 @@ says so in one line; the session goes on with the new CLI, and the snapshot
1049
1218
  catches up on its next build. When the repo has no `cloud-setup.sh` while
1050
1219
  the workflow pins another release, or the file is not at the workflow's
1051
1220
  pin, the line says to run `onboard` again. When the Setup script still
1052
- installs a release of its own (an older paste), the line also says to paste
1053
- the snippet over it, once. It only warns: the session works on.
1221
+ installs a release of its own (an older paste), the line also says to
1222
+ delete niyam's part of it or paste the snippet over it. It only warns: the
1223
+ session works on.
1054
1224
 
1055
1225
  claude.ai has one GitHub connection per account, so it is the agent's for
1056
1226
  every cloud session that account starts.
@@ -1064,13 +1234,13 @@ reads, in the same layout and with the same exit codes as on a Mac:
1064
1234
  ◇ This cloud session
1065
1235
  ✗ .github/niyam/cloud-setup.sh installs 0.5.24, but .github/workflows/niyam.yml pins v0.5.25 → niyam onboard again
1066
1236
  ✓ niyam 0.5.24 runs here
1067
- ▲ /opt/niyam/from-setup missing, so the cloud environment's Setup script does not run .github/niyam/cloud-setup.sh → paste what niyam cloud-setup prints into the cloud environment's Setup script, once
1237
+ ✓ the SessionStart hook installs niyam from .github/niyam/cloud-setup.sh when a session has none; the Setup script does not run it, which only makes sessions start slower
1068
1238
  │
1069
1239
  ◇ GitHub — as AGENT
1070
1240
  ✓ the proxy acts as AGENT, an agent the repo's settings name
1071
1241
  ✓ session-start gave this session AGENT's identity
1072
1242
  │
1073
- └ 2 to fix
1243
+ └ 1 to fix
1074
1244
  ```
1075
1245
 
1076
1246
  This cloud session checks that `cloud-setup.sh` opens with the comment
@@ -1078,8 +1248,9 @@ This cloud session checks that `cloud-setup.sh` opens with the comment
1078
1248
  the workflow's pin (`✗`, fixed by running `onboard` again; a workflow that pins no one version is `▲`), that the CLI running is that
1079
1249
  release (`▲`: `session-start` installs it, or `bash
1080
1250
  .github/niyam/cloud-setup.sh` does), and that the Setup script
1081
- runs the repo's file (`▲` without `/opt/niyam/from-setup`),
1082
- naming the file it ran: the mark holds its path. GitHub
1251
+ runs the repo's file, naming the file it ran (the mark
1252
+ `/opt/niyam/from-setup` holds its path), or that the SessionStart hook
1253
+ installs it, since the Setup script does not: both are `✓`. GitHub
1083
1254
  checks that the account the proxy acts as is one of the settings' agents,
1084
1255
  and that `session-start` gave the session that identity (`✗` otherwise:
1085
1256
  `gh` and git stay locked out). This repo lists hooks that reach GitHub
@@ -1158,15 +1329,21 @@ is a slice the owner approves.
1158
1329
 
1159
1330
  ### Releases and upgrading
1160
1331
 
1161
- Each release is a tag `vX.Y.Z` on `main`, matching `package.json`; the
1162
- Release workflow checks both, runs `pnpm check` and publishes the GitHub
1163
- release, attaching the CLI package it built and tested. From 0.6.16 the same
1332
+ A release is the merge of its version bump: a push to `main` whose
1333
+ `package.json` version has no tag `vX.Y.Z` yet (P-61). The Release workflow
1334
+ then runs `pnpm check`, makes that annotated tag (`niyam X.Y.Z`) on the
1335
+ merged commit itself, and publishes the GitHub release, attaching the CLI
1336
+ package it built and tested. Agents push no release tags. From 0.6.16 the same
1164
1337
  package is on npm as `@veda-hq/niyam`, with provenance, for a repository that
1165
- pins it as an exact version. Install the attached package on each machine with
1166
- pnpm, once; nothing is built on install:
1338
+ pins it as an exact version; it publishes from the `npm` environment, which
1339
+ only `main` may deploy to. A tag on any other commit is not a release:
1340
+ `niyam upgrade` and `niyam onboard` ask GitHub's compare API, with no token,
1341
+ whether the tag's commit is on `main`, and refuse one that is not, naming the
1342
+ tag and the commit. Install the attached package on each machine with pnpm,
1343
+ once; nothing is built on install:
1167
1344
 
1168
1345
  ```bash
1169
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.16/veda-hq-niyam-0.6.16.tgz
1346
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.18/veda-hq-niyam-0.6.18.tgz
1170
1347
  ```
1171
1348
 
1172
1349
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
@@ -1182,11 +1359,11 @@ niyam upgrade
1182
1359
  ```
1183
1360
 
1184
1361
  `upgrade` asks GitHub's public releases API for the newest release, with no
1185
- token and no sign-in, and when it is newer than the CLI running, installs it
1186
- with the same `pnpm add -g`, printing old → new and the version the shell then
1362
+ token and no sign-in, and when it is newer than the CLI running and its tag's
1363
+ commit is on `main`, installs it with the same `pnpm add -g`, printing old → new and the version the shell then
1187
1364
  runs. On the newest release it says so and installs nothing; it never moves
1188
1365
  back to an older one. When GitHub cannot be reached, or a newer release has no
1189
- package attached yet, or pnpm fails, it says which and exits 1, checking
1366
+ package attached yet, or its tag is not on `main`, or pnpm fails, it says which and exits 1, checking
1190
1367
  nothing more. After an install, or when there was nothing to install, it walks
1191
1368
  `PATH`, as `type -a niyam` does, reading an empty or relative entry
1192
1369
  against the current folder as the shell does. It exits 0 when exactly one
@@ -1201,7 +1378,10 @@ newest release with the line above. `onboard`, when the repo pins a newer releas
1201
1378
  CLI running, refuses and says to run `niyam upgrade` first.
1202
1379
 
1203
1380
  `onboard` pins the client's workflow to one version, the release of the CLI
1204
- that ran it. Each job writes the pin twice, `checks.yml@vX.Y.Z` and, two lines
1381
+ that ran it, and writes `.github/niyam/cloud-setup.sh` at the same one. First
1382
+ it asks GitHub's compare API, with no token, whether that release's tag is on
1383
+ `main`; when it is not, or GitHub cannot say, it refuses and changes nothing.
1384
+ Each job writes the pin twice, `checks.yml@vX.Y.Z` and, two lines
1205
1385
  below it under `with:`, `niyam-ref: vX.Y.Z`, the one input `checks.yml`
1206
1386
  declares; GitHub refuses a caller that passes an input the called workflow
1207
1387
  does not declare, `process-rules-ref` too since P-57. Every job of
@@ -1237,6 +1417,39 @@ functions, 90% branches), builds `dist/` and runs it. `pnpm scan:secrets` runs
1237
1417
  Gitleaks and TruffleHog over the working tree; CI runs both over the whole
1238
1418
  history.
1239
1419
 
1420
+ ### Guard
1421
+
1422
+ The `guard` workflow (`.github/workflows/guard.yml`) runs on
1423
+ `pull_request_target`, so GitHub runs it from `main`'s copy, never the pull
1424
+ request's. Its job, `Guard`, checks out `main` alone, reads the pull
1425
+ request's changed files from GitHub's API as data, and runs
1426
+ `scripts/guard.mjs` (tested in `scripts/guard.test.mjs`). A change to a guard
1427
+ file passes only when the pull request's slice names it in a `**Guards:**`
1428
+ section, one already in the slice when the owner put `approved` on its Work
1429
+ item (for a slice added later, when the owner's `Decision:` settled it):
1430
+
1431
+ ```markdown
1432
+ **Guards:** `.github/workflows/ci.yml`, `scripts/*.mjs`, `.githooks/`
1433
+ ```
1434
+
1435
+ A name is a path, a folder ending in `/`, or a pattern where `*` matches
1436
+ within one folder and `**` across them. The guard files are everything under
1437
+ `.github/`, `.githooks/`, `.dvara.json`, `.dvara/records-baseline.json`,
1438
+ `.gitleaks.toml`, `.trufflehog-exclude`, the `scripts` of `package.json`,
1439
+ and `scripts/*.mjs`. A test file needs naming too when a pull request
1440
+ deletes it, leaves it fewer `test(`/`it(` calls than the merge base, or adds
1441
+ `.skip`, `.only` or `todo`.
1442
+
1443
+ Two changes pass unnamed: an onboard pull request
1444
+ (`chore(niyam): onboard at vX.Y.Z`) whose every changed line only moves the
1445
+ niyam version, and a sha256 with it, to that release, tagged on `main`; and a
1446
+ Dependabot pull request whose every changed line only moves a `uses:` to
1447
+ another full commit sha with its version comment. Whatever the slice says,
1448
+ Guard refuses a pull request that adds a job reporting a check the `main`
1449
+ ruleset requires, or `Guard`. It fails closed: a truncated file list, or any
1450
+ read GitHub does not answer, refuses. Each refusal names the file and how to
1451
+ pass. A slice edit does not run Guard again: edit or push the pull request.
1452
+
1240
1453
  ## License
1241
1454
 
1242
1455
  MIT
@@ -1264,7 +1477,7 @@ What P-57 removed for good, by hand where it is on a machine:
1264
1477
  `doctor` marks either one still there ▲.
1265
1478
  - `niyam onboard` deletes `.github/process-rules/cloud-setup.sh` wherever it
1266
1479
  leaves `.github/niyam/cloud-setup.sh`, and writes and runs none under that
1267
- name; a Setup snippet pasted before 0.6.10 needs the new one pasted once.
1480
+ name; a Setup snippet pasted before 0.6.10 needs the new one pasted once, or, since P-60, deleting.
1268
1481
  - `niyam owner-step required-checks` takes each `process-rules / …` check out of
1269
1482
  a ruleset: no workflow reports one since P-53, so it would hold every pull
1270
1483
  request. The `niyam / …` check of the same job takes its place where the
package/dist/agent.js CHANGED
@@ -21,6 +21,10 @@ export const API = GITHUB_API;
21
21
  const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
22
22
  /** The GitHub remotes `repoAt` accepts: HTTPS, scp-like SSH, or SSH URLs, on GitHub's host only. */
23
23
  const GITHUB_REMOTE = new RegExp(`^(?:https://(?:[^@/\\s]+@)?${GITHUB_HOST_RE}/|git@${GITHUB_HOST_RE}:|ssh://git@(?:ssh\\.)?${GITHUB_HOST_RE}(?::\\d+)?/)([^/\\s]+/[^/\\s]+?)(?:\\.git)?/?$`);
24
+ /** The owner/name a GitHub remote's url names; undefined for any other url. */
25
+ export function githubSlug(url) {
26
+ return GITHUB_REMOTE.exec(url.trim())?.[1];
27
+ }
24
28
  /** The classic-token scopes an agent account needs (docs/decisions.md). */
25
29
  export const TOKEN_SCOPES = ['repo', 'workflow', 'read:org', 'project', 'write:ssh_signing_key'];
26
30
  /** Broader scopes that include a needed one. */
package/dist/as-agent.js CHANGED
@@ -37,32 +37,40 @@ export function asAgentArgs(args) {
37
37
  * a fallback.
38
38
  */
39
39
  export function asAgent(sys, io, parsed) {
40
- const locked = (reason) => {
41
- io.err(refusal(reason));
40
+ const env = agentEnv(sys, parsed.sessionId);
41
+ if ('problem' in env) {
42
+ io.err(refusal(env.problem));
42
43
  return LOCKED;
43
- };
44
- if (!sessionRecord(sys.home, parsed.sessionId))
45
- return locked(`"${parsed.sessionId}" is not a Claude Code session id`);
46
- const recorded = recordedAgent(sys, parsed.sessionId);
44
+ }
45
+ const result = sys.exec(parsed.command, parsed.args, { env: env.env, interactive: true });
46
+ // With standard error passed through, what is left is why the command could not start.
47
+ if (result.stderr)
48
+ io.err(`niyam as-agent: ${parsed.command}: ${result.stderr.trim()}`);
49
+ return result.code;
50
+ }
51
+ /**
52
+ * The environment `as-agent` gives its command for the session, with every
53
+ * check it makes: session-start recorded one of the repo settings' agents
54
+ * for this session, and the agent's token is in the store (or, in a cloud
55
+ * session, the proxy's). A hook that reaches GitHub itself, such as
56
+ * pr-autocreate's, takes its token from here.
57
+ */
58
+ export function agentEnv(sys, sessionId, root) {
59
+ if (!sessionRecord(sys.home, sessionId))
60
+ return { problem: `"${sessionId}" is not a Claude Code session id` };
61
+ const recorded = recordedAgent(sys, sessionId);
47
62
  if ('problem' in recorded)
48
- return locked(recorded.problem);
63
+ return recorded;
49
64
  let agents;
50
65
  try {
51
- agents = loadSettings(sys, repoRoot(sys)).agents;
66
+ agents = loadSettings(sys, root ?? repoRoot(sys)).agents;
52
67
  }
53
68
  catch (error) {
54
- return locked(message(error));
69
+ return { problem: message(error) };
55
70
  }
56
71
  if (!anyLogin(agents, recorded.agent))
57
- return locked(`session-start recorded ${recorded.agent}, and the repo's settings name the agents ${either(agents)}`);
58
- const env = sys.env.CLAUDE_CODE_REMOTE === 'true' ? cloudEnv(sys, recorded.agent) : macEnv(sys, recorded.agent);
59
- if ('problem' in env)
60
- return locked(env.problem);
61
- const result = sys.exec(parsed.command, parsed.args, { env: env.env, interactive: true });
62
- // With standard error passed through, what is left is why the command could not start.
63
- if (result.stderr)
64
- io.err(`niyam as-agent: ${parsed.command}: ${result.stderr.trim()}`);
65
- return result.code;
72
+ return { problem: `session-start recorded ${recorded.agent}, and the repo's settings name the agents ${either(agents)}` };
73
+ return sys.env.CLAUDE_CODE_REMOTE === 'true' ? cloudEnv(sys, recorded.agent) : macEnv(sys, recorded.agent);
66
74
  }
67
75
  /**
68
76
  * The agent's variable before P-55, which an older release's shell may still
package/dist/board.js CHANGED
@@ -238,19 +238,19 @@ approved) {
238
238
  if (!done.grouped) {
239
239
  for (const line of viewsChecklist(project.url))
240
240
  io.out(line);
241
- byHand.push(`Type on Needs you, group 2 views, auto-archive → ${project.url}`);
241
+ byHand.push(`Once for the board: at ${project.url}, add the Type column to Needs you, group Work items by Step and Decisions by Decision, and set the Auto-archive items workflow to ${ARCHIVE_FILTER}, which GitHub's API cannot.`);
242
242
  }
243
243
  else {
244
244
  if (reset.includes('Needs you')) {
245
245
  // The column list sent could not name Type, so a Type the owner showed may be gone.
246
246
  io.out(`Needs you's columns were set through GitHub's API, which cannot see a Type column, so one shown there may be gone; in ${project.url}: ${TYPE_STEP}`);
247
- byHand.push(`Type on Needs you again → ${project.url}`);
247
+ byHand.push(`Once for the board: at ${project.url}, add the Type column to Needs you again, which GitHub's API cannot.`);
248
248
  }
249
249
  io.out(`- Board shows slices and briefs; Done keeps one until the Auto-archive items workflow archives it, with the template's filter ${ARCHIVE_FILTER}, which GitHub's API can neither read nor set`);
250
250
  }
251
251
  if (done.off.length > 0) {
252
252
  io.out(`Turn on the workflows ${done.off.join(', ')} in ${project.url} → Workflows (GitHub's API cannot)`);
253
- byHand.push(`turn on ${done.off.length} project workflow${done.off.length === 1 ? '' : 's'} → ${project.url}/workflows`);
253
+ byHand.push(`Once for the board: turn on the workflow${done.off.length === 1 ? '' : 's'} ${done.off.join(', ')} at ${project.url}/workflows, which GitHub's API cannot.`);
254
254
  }
255
255
  return { url: project.url, byHand: [...typesByHand, ...byHand] };
256
256
  }