@veda-hq/niyam 0.6.22 → 0.6.24

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
@@ -421,7 +421,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
421
421
  every run (see Claude cloud sessions below); a cloud session with no
422
422
  niyam runs it from the SessionStart hook, so there is nothing to paste,
423
423
  and the first time, the plan lists the one connection of claude.ai's
424
- GitHub as the agent, once per claude.ai account. Where the
424
+ GitHub as the agent, once per claude.ai account. When the agent has no
425
+ signing key on GitHub titled `niyam cloud signing`, the plan's Claude
426
+ cloud group also lists one, "signing key for AGENT, on the clipboard":
427
+ as its last step, after the pull request opens, `onboard` makes it as
428
+ `niyam cloud-key` does (below), and "By hand:" starts with the paste
429
+ into each cloud environment's variables. The key is the agent's, not the
430
+ repository's, so onboarding a second repository finds it and says nothing
431
+ about it. A key that fails only warns, leaving the pull request and every
432
+ step before it in place, and "By hand:" names `niyam cloud-key <agent>`
433
+ instead; so does a run where `cloud-key` would refuse, in a Claude Code
434
+ or cloud session. A dry run plans no key. Where the
425
435
  repo still has `.github/process-rules/cloud-setup.sh`, which releases up
426
436
  to 0.6.10 wrote beside it, the pull request deletes it, but only where it
427
437
  leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
@@ -444,11 +454,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
444
454
  you (`label:needs-owner is:open`), Board (`type:Slice,Brief`, by Status,
445
455
  showing linked pull requests), Work items (`type:"Work item"`, grouped by Step), Decisions
446
456
  (`type:Decision`, grouped by Decision) and Reviews due (`"Review
447
- date":<=@today`), with its workflows; so the board needs nothing done by
448
- hand. What the board lacks is known only once you have signed in, so the
457
+ date":<=@today`), with its workflows. A copy lacks one workflow: Auto-add
458
+ to project, which names a repository, and which GitHub's API can neither
459
+ create nor set. Without it, a Work item or Slice an agent opens is on no
460
+ board, so "By hand:" names it, and Auto-add sub-issues to project when a
461
+ Project lacks that too, with the repository and the filter
462
+ `is:issue is:open` to give it. What the board lacks is known only once you have signed in, so the
449
463
  plan says "set up or check"; issue types are an organisation-wide
450
464
  setting, so the plan says "org-wide" and lists what it would change. If
451
- a copy's workflows arrive off, "By hand:" links where to turn them on. A
465
+ a copy's workflows arrive off, "By hand:" links where to turn them on.
466
+ Auto-add adds an issue only as it opens or changes, never one already
467
+ open: `niyam board-audit` (below) lists those. A
452
468
  Project of that title made before the template is left as it is: the plan's
453
469
  yes does not replace it. When GitHub refuses the copy, or for such an
454
470
  older Project, `onboard` adds the fields and makes or updates the views
@@ -601,10 +617,23 @@ hold their issues, so this reads no issue on its own. A Project whose Step
601
617
  has no Done, made before it, gets one line saying so, and `onboard` adds the
602
618
  option, keeping every item's Step. A workflow's `GITHUB_TOKEN` cannot write to a Project, so the
603
619
  agent's push does this, with the agent token's `project` scope, with `board`
604
- on. It uses GitHub's REST API for Projects alone, so it works through a
605
- Claude cloud session's GitHub proxy, which refuses GraphQL.
620
+ on, through GitHub's REST API for Projects alone.
606
621
  A board it cannot read, or a move GitHub refuses, is said and does not stop
607
- the push; a push for a closed slice, such as a fix, moves nothing. When a pull request naming a slice merges into the default branch,
622
+ the push; a push for a closed slice, such as a fix, moves nothing. A Claude
623
+ cloud session's GitHub proxy lets through only `repos/{owner}/{repo}/…`, so
624
+ its push never reaches an organization's Projects and says only that the
625
+ workflow moves the slice. When a pull request from the repository opens or
626
+ reopens, the shared workflow's Slice started job makes the same moves, under
627
+ the same conditions, with a token from the board GitHub App. The client's
628
+ workflow passes it the app's client id and private key as the
629
+ `NIYAM_BOARD_APP_ID` and `NIYAM_BOARD_APP_KEY` secrets. With `board` on,
630
+ onboard writes them under the `niyam` job's secrets, the pull request job
631
+ alone. Where the repository lacks either, its own or its organization's,
632
+ onboard's by-hand list and its pull request say how to set up the app once
633
+ per organization: organization Projects read and write and repository Issues
634
+ read, installed on the repository. `niyam doctor` marks a missing one ▲.
635
+ Without them, the job says so in one line and passes, as it does when the
636
+ board refuses: the board never fails a pull request. When a pull request naming a slice merges into the default branch,
608
637
  the shared workflow comments on the slice, linking the pull request, and
609
638
  closes it, and the Project's Item closed workflow moves it to Done: a
610
639
  `Slice: #N` line is not one of GitHub's closing keywords, so GitHub does not
@@ -617,6 +646,22 @@ beside it, still gets the comment; one that has it gets no second one. That job
617
646
  pull requests from the repository itself: a fork's run gets a read-only token, so
618
647
  a slice a fork's pull request builds is closed by hand.
619
648
 
649
+ **Checking the board.** `niyam board-audit [owner/repo] [--project <title>]`
650
+ compares a repository with its Project and changes nothing: the open issues
651
+ not on it, the unarchived items whose Status disagrees with their issue
652
+ (open but Done, or closed but not Done), and whether Auto-add to project
653
+ and Auto-add sub-issues to project are on. Open issues archived on the
654
+ Project are listed in one line but not counted, since the audit cannot tell
655
+ an archive made on purpose from one made before the issue reopened. The
656
+ repository is the clone's here when none is named, and the Project is the
657
+ one `.github/niyam.json`'s `"project"` names, else "<repo> work". GitHub's
658
+ API shows a workflow's name and whether it is on, not the repository or
659
+ filter it adds from, so the audit says so. It runs with `GH_TOKEN`, which
660
+ needs read access to the Project, and exits 0 when the board matches, 3 when
661
+ something is to fix, and 1 when it could not check. A Claude cloud
662
+ session's GitHub proxy refuses GraphQL and an organisation's Projects
663
+ (veda-hq/niyam#399), so there it says it cannot run and checks nothing.
664
+
620
665
  **What needs the owner.** A request the owner made on the work item is its
621
666
  own approval, linked as above. A fix needs none: it restores what the owner
622
667
  approved and changes nothing they would see beyond it, so it is filed as a
@@ -888,6 +933,21 @@ checked. The settings:
888
933
  `retire`, a command with `{number}` for the merged pull request, is the way out
889
934
  `refuse-retired` names; `footer` ends the placeholder body.
890
935
 
936
+ **On sarathi's Auto-fix list.** Outside a cloud session, `claude-hook` puts
937
+ the open pull request it opened or found on the session's sarathi Auto-fix
938
+ list (sarathi 0.6.15's `autofix-watch.sh`): an `opened` row
939
+ `{ "at", "pr": "owner/repo#N", "url", "event": "opened", "source": "niyam pr-autocreate" }`
940
+ in `<dir>/<session id>.jsonl`, where `<dir>` is `SARATHI_AUTOFIX_DIR`, else
941
+ `$XDG_STATE_HOME/sarathi/autofix`, else `~/.local/state/sarathi/autofix`. A
942
+ pull request the list names already gets no second row. With
943
+ `"autofixList": true`, for a repository whose sessions run that sarathi hook,
944
+ the instruction leaves out its `set_monitor` step, because sarathi's warning
945
+ repeats that call at every `wrap_up` until the app confirms Auto-fix. The
946
+ ToolSearch step, the `<pr-created>` tag and `bind_pr` stay: without them the
947
+ app refuses `set_monitor` for a pull request a hook opened. When the row
948
+ cannot be written, or the session id cannot name a list, the whole
949
+ instruction goes out.
950
+
891
951
  **Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
892
952
  sends a session back while its branch has commits the base lacks and its
893
953
  pull request has not merged at this commit, saying what is left (push, open
@@ -1266,11 +1326,68 @@ session's shell, so run by hand there it always says STOP, which says
1266
1326
  nothing about the session.
1267
1327
  The hook's own line at session start is what counts.
1268
1328
 
1269
- A cloud session's git commits are authored and committed as Claude's own
1270
- account, `Claude <noreply@anthropic.com>`, and signed by it (Verified),
1271
- while the push is the agent's. PR identity checks only commits that claim
1272
- an agent, so these pass, and GitHub records the agent as having pushed
1273
- them.
1329
+ By default, the platform authors and commits a cloud session's git commits as
1330
+ `Claude <noreply@anthropic.com>` and signs them with Anthropic's key
1331
+ (Verified), while the agent makes the push. PR identity checks only commits
1332
+ that claim an agent, so these pass, and GitHub records the agent as having
1333
+ pushed them.
1334
+
1335
+ **The agent's commits, signed.** A cloud environment whose variables hold
1336
+ the agent's cloud signing key, `NIYAM_SIGNING_KEY`, makes its commits the
1337
+ agent's, as on a Mac: authored and committed with the agent's no-reply
1338
+ address and signed with that key.
1339
+
1340
+ Once `session-start` confirms the login as the agent, it does four things:
1341
+
1342
+ - reads the account's id from the same GitHub answer;
1343
+ - writes the key to the agent's key file (`~/.ssh/<agent>_signing`, mode 0600) and checks GitHub lists its public half as one of the agent's signing keys;
1344
+ - makes a probe commit object, on no branch, with exactly the settings the session will get;
1345
+ - checks that its signature verifies as that key's.
1346
+
1347
+ Only then does it add the agent's author and committer variables and SSH
1348
+ signing, with `gpg.ssh.program` set back from the platform's own program to
1349
+ `ssh-keygen`, all together to `CLAUDE_ENV_FILE`. It also unsets the key's
1350
+ variable there, so commands do not carry it in their environment.
1351
+
1352
+ When any step fails, nothing is set and the commits stay Claude's, which PR
1353
+ identity passes. Steps that can fail: no key, one that is not an OpenSSH
1354
+ private key, a key GitHub does not list, a lookup the proxy refuses, or a
1355
+ probe that does not verify. The session's line says why and the session
1356
+ works on as the agent. A commit claiming the agent without the agent's
1357
+ signature would fail PR identity, so it is all or nothing.
1358
+
1359
+ `niyam onboard` makes the key the first time it runs for an agent that has
1360
+ none (see Adopting above), so all that is left is the paste. To make one
1361
+ yourself, as when the line was lost, run `niyam cloud-key [agent]` in your own
1362
+ terminal on the Mac `niyam machine` set up for the agent (`--yes` skips its
1363
+ one question). One line serves every cloud environment the agent works in.
1364
+ `onboard` and `cloud-key` make the key alike, in four steps:
1365
+
1366
+ - makes a new ed25519 key in a private temporary folder, for the agent's cloud sessions alone, apart from the Mac's signing key, so it can be revoked on its own;
1367
+ - registers it as the agent's signing key, titled `niyam cloud signing`, with the token `machine` stored, and checks GitHub lists it;
1368
+ - puts `NIYAM_SIGNING_KEY=<the private key, base64>` on the clipboard, never on the screen;
1369
+ - deletes the files, at a Ctrl-C too.
1370
+
1371
+ Paste the line into the cloud environment's variables (https://claude.ai/code →
1372
+ the environment's settings). Claude Code has no API for them, so this step stays
1373
+ yours. A key GitHub does not list, or one the clipboard does not take, is deleted
1374
+ from GitHub again, since no one holds it, and so is one a Ctrl-C stops after it
1375
+ was registered.
1376
+
1377
+ `cloud-key` also names the agent's other cloud signing keys, by date and id. Delete
1378
+ one at https://github.com/settings/keys, signed in as the agent, once no environment
1379
+ uses it; `cloud-key` deletes none itself. It refuses in an agent session or a cloud
1380
+ session, and without a working agent token (`niyam machine` first). In a cloud
1381
+ session, `doctor` says whether the session's commits are the agent's, and names
1382
+ `niyam cloud-key` when the environment has no key.
1383
+
1384
+ Anyone who uses the environment can read its variables, and so can any
1385
+ command its sessions run. Claude's settings warn against keeping secrets
1386
+ there. Whoever holds the key can sign commits that GitHub shows as Verified
1387
+ for the agent, though pushing still needs the agent's GitHub connection,
1388
+ which PR identity checks. To revoke the key, delete it from the agent's
1389
+ signing keys. The platform's own git hooks may still add a `Co-authored-by`
1390
+ trailer for Claude.
1274
1391
 
1275
1392
  The proxy refuses GitHub's GraphQL API, so the work rules and `reviews-due`
1276
1393
  read only its REST API, here and everywhere else. The one exception is who
@@ -1455,7 +1572,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
1455
1572
  once; nothing is built on install:
1456
1573
 
1457
1574
  ```bash
1458
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.22/veda-hq-niyam-0.6.22.tgz
1575
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.24/veda-hq-niyam-0.6.24.tgz
1459
1576
  ```
1460
1577
 
1461
1578
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
package/dist/agent.js CHANGED
@@ -187,7 +187,8 @@ const LOCKED_CONFIG = [
187
187
  [`url.${GITHUB_WEB}/.insteadOf`, `ssh://${GITHUB_SSH}:22/`],
188
188
  [`url.${GITHUB_WEB}/.insteadOf`, `ssh://${GITHUB_SSH_443}:443/`],
189
189
  ];
190
- function configVars(config) {
190
+ /** Git config, as the GIT_CONFIG_COUNT variables that carry it over every config file. */
191
+ export function configVars(config) {
191
192
  return [
192
193
  ['GIT_CONFIG_COUNT', String(config.length)],
193
194
  ...config.flatMap(([key, value], i) => [
@@ -203,26 +204,46 @@ function configVars(config) {
203
204
  * release since sets or reads that name (P-57).
204
205
  */
205
206
  const AGENT_VARS_0610 = [AGENT_VAR, 'PROCESS_RULES_AGENT'];
207
+ /**
208
+ * The variables that make the agent the author and committer of a session's
209
+ * commits, over any `user.name` and `user.email` git config: the same in a
210
+ * local session's file and a cloud session's env file.
211
+ */
212
+ export function authorVars(agent, id) {
213
+ const email = noreplyEmail(id, agent);
214
+ return [
215
+ ['GIT_AUTHOR_NAME', agent],
216
+ ['GIT_COMMITTER_NAME', agent],
217
+ ['GIT_AUTHOR_EMAIL', email],
218
+ ['GIT_COMMITTER_EMAIL', email],
219
+ ];
220
+ }
221
+ /** Git config that signs commits and tags with the SSH key whose public half is at `pub`. */
222
+ export function signingConfig(pub) {
223
+ return [
224
+ ['gpg.format', 'ssh'],
225
+ ['user.signingkey', pub],
226
+ ['commit.gpgsign', 'true'],
227
+ ['tag.gpgsign', 'true'],
228
+ ];
229
+ }
230
+ /** `vars` as shell lines exporting each, quoted. */
231
+ export function exportLines(vars) {
232
+ return vars.map(([name, value]) => `export ${name}=${quote(value)}`);
233
+ }
206
234
  /** The variables an agent session gets, except GH_TOKEN. */
207
235
  function identityVars(agent, id, paths, agentVars = [AGENT_VAR]) {
208
- const email = noreplyEmail(id, agent);
209
236
  const helper = `!f() { test "$1" = get && printf 'username=%s\\npassword=%s\\n' ${agent} "$GH_TOKEN"; }; f`;
210
237
  const [reset, askpass, ...https] = LOCKED_CONFIG;
211
238
  return [
212
239
  ...agentVars.map((name) => [name, agent]),
213
240
  ['GH_CONFIG_DIR', paths.gh],
214
- ['GIT_AUTHOR_NAME', agent],
215
- ['GIT_COMMITTER_NAME', agent],
216
- ['GIT_AUTHOR_EMAIL', email],
217
- ['GIT_COMMITTER_EMAIL', email],
241
+ ...authorVars(agent, id),
218
242
  ['GIT_TERMINAL_PROMPT', '0'],
219
243
  // Any SSH remote left (a host alias in ~/.ssh/config) fails instead of using the owner's key.
220
244
  ['GIT_SSH_COMMAND', NO_SSH],
221
245
  ...configVars([
222
- ['gpg.format', 'ssh'],
223
- ['user.signingkey', `${paths.key}.pub`],
224
- ['commit.gpgsign', 'true'],
225
- ['tag.gpgsign', 'true'],
246
+ ...signingConfig(`${paths.key}.pub`),
226
247
  // After the reset, the agent's token goes to GitHub's host only.
227
248
  reset,
228
249
  [`credential.${GITHUB_WEB}.helper`, helper],
@@ -292,7 +313,7 @@ function sessionText(agent, id, paths, read, agentVars = [AGENT_VAR]) {
292
313
  `[ -n "$GH_TOKEN" ] || export GH_TOKEN=${NO_TOKEN}`,
293
314
  // Inherited `git -c` and config-file injection could bring back a helper; askpass could prompt.
294
315
  `unset ${UNSET.join(' ')}`,
295
- ...identityVars(agent, id, paths, agentVars).map(([name, value]) => `export ${name}=${quote(value)}`),
316
+ ...exportLines(identityVars(agent, id, paths, agentVars)),
296
317
  '',
297
318
  ].join('\n');
298
319
  }
@@ -336,7 +357,7 @@ export function lockScript(home) {
336
357
  `# Written by ${CLI} session-start. GitHub is locked out unless an agent identity below replaces this.`,
337
358
  `export GH_TOKEN=${NO_TOKEN}`,
338
359
  `unset ${UNSET.join(' ')}`,
339
- ...vars.map(([name, value]) => `export ${name}=${quote(value)}`),
360
+ ...exportLines(vars),
340
361
  '',
341
362
  ].join('\n');
342
363
  }
@@ -0,0 +1,177 @@
1
+ import { API, SETTINGS_PATH, repoAt } from './agent.js';
2
+ import { AUTO_ADD, AUTO_ADD_FILTER, graphql } from './board.js';
3
+ /** board-audit's options: the repository, and the Project's title. */
4
+ export function auditArgs(args) {
5
+ const parsed = {};
6
+ for (let at = 0; at < args.length; at++) {
7
+ const arg = args[at];
8
+ if (arg === '--project') {
9
+ const value = args[++at];
10
+ if (!value || value.startsWith('-'))
11
+ throw new Error("board-audit --project needs the Project's title");
12
+ parsed.project = value;
13
+ }
14
+ else if (parsed.slug === undefined && /^[\w.-]+\/[\w.-]+$/.test(arg)) {
15
+ parsed.slug = arg;
16
+ }
17
+ else {
18
+ throw new Error(`board-audit takes [owner/repo] [--project <title>], not "${arg}"`);
19
+ }
20
+ }
21
+ return parsed;
22
+ }
23
+ /** The `project` the repository's settings name, from the clone here when it is that repository, else from GitHub; undefined when they name none. */
24
+ async function settingsTitle(sys, token, slug) {
25
+ let text;
26
+ try {
27
+ const here = repoAt(sys);
28
+ const path = `${here.root}/${SETTINGS_PATH}`;
29
+ if (here.slug.toLowerCase() === slug.toLowerCase() && sys.exists(path))
30
+ text = sys.read(path);
31
+ }
32
+ catch {
33
+ // fail-open: not in a clone, so the settings come from GitHub, read next.
34
+ }
35
+ if (text === undefined) {
36
+ const { status, json } = await sys.http(`${API}/repos/${slug}/contents/${SETTINGS_PATH}`, { token });
37
+ const content = json?.content;
38
+ if (status === 404)
39
+ return undefined;
40
+ if (status !== 200 || typeof content !== 'string')
41
+ throw new Error(`cannot read ${slug}'s ${SETTINGS_PATH} (HTTP ${status})`);
42
+ text = Buffer.from(content, 'base64').toString('utf8');
43
+ }
44
+ const raw = JSON.parse(text);
45
+ const project = raw !== null && typeof raw === 'object' && 'project' in raw ? raw.project : undefined;
46
+ return typeof project === 'string' && project.trim() ? project.trim() : undefined;
47
+ }
48
+ /**
49
+ * Compares `slug`'s issues with its open Project titled `title`, reading only:
50
+ * the open issues not on it, the items whose Status disagrees with their
51
+ * issue, and whether the auto-add workflows are on. GitHub's API shows a
52
+ * workflow's name and whether it is on, not the repository or filter it adds
53
+ * from.
54
+ */
55
+ export async function auditBoard(sys, token, slug, title) {
56
+ const [owner, name] = slug.split('/');
57
+ let project;
58
+ for (let after = null;;) {
59
+ const read = (await graphql(sys, token, 'query BoardAuditProject($login: String!, $title: String!, $after: String) { repositoryOwner(login: $login) { ... on ProjectV2Owner { projectsV2(first: 100, query: $title, after: $after) { nodes { id title url closed } pageInfo { hasNextPage endCursor } } } } }', { login: owner, title, after }));
60
+ const projects = read.repositoryOwner?.projectsV2;
61
+ if (!projects)
62
+ throw new Error(`GitHub shows no owner ${owner} with Projects`);
63
+ project = projects.nodes.find((node) => node.title === title && !node.closed);
64
+ if (project || !projects.pageInfo.hasNextPage)
65
+ break;
66
+ after = projects.pageInfo.endCursor;
67
+ }
68
+ if (!project)
69
+ throw new Error(`${owner} has no open Project titled "${title}"; name it with --project`);
70
+ const missing = [];
71
+ const archived = [];
72
+ for (let after = null;;) {
73
+ const read = (await graphql(sys, token, 'query BoardAuditIssues($owner: String!, $name: String!, $after: String) { repository(owner: $owner, name: $name) { issues(states: OPEN, first: 100, after: $after) { nodes { number title projectItems(first: 50, includeArchived: true) { nodes { isArchived project { id } } } } pageInfo { hasNextPage endCursor } } } }', { owner, name, after }));
74
+ if (!read.repository)
75
+ throw new Error(`GitHub shows no repository ${slug}`);
76
+ for (const issue of read.repository.issues.nodes) {
77
+ const items = issue.projectItems.nodes.filter((item) => item.project.id === project.id);
78
+ if (items.some((item) => !item.isArchived))
79
+ continue;
80
+ (items.length > 0 ? archived : missing).push({ number: issue.number, title: issue.title });
81
+ }
82
+ if (!read.repository.issues.pageInfo.hasNextPage)
83
+ break;
84
+ after = read.repository.issues.pageInfo.endCursor;
85
+ }
86
+ const disagree = [];
87
+ let workflows = [];
88
+ for (let after = null;;) {
89
+ const read = (await graphql(sys, token, 'query BoardAuditItems($id: ID!, $after: String) { node(id: $id) { ... on ProjectV2 { workflows(first: 50) { nodes { name enabled } } items(first: 100, after: $after) { nodes { isArchived status: fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { __typename ... on Issue { number title state repository { nameWithOwner } } } } pageInfo { hasNextPage endCursor } } } } }', { id: project.id, after }));
90
+ workflows = read.node.workflows.nodes;
91
+ for (const item of read.node.items.nodes) {
92
+ const issue = item.content;
93
+ if (item.isArchived || issue?.__typename !== 'Issue' || issue.number === undefined || issue.repository?.nameWithOwner.toLowerCase() !== slug.toLowerCase())
94
+ continue;
95
+ const status = item.status?.name;
96
+ const done = status?.toLowerCase() === 'done';
97
+ const open = issue.state === 'OPEN';
98
+ if (open === done)
99
+ disagree.push({ number: issue.number, title: issue.title ?? '', state: open ? 'open' : 'closed', status });
100
+ }
101
+ if (!read.node.items.pageInfo.hasNextPage)
102
+ break;
103
+ after = read.node.items.pageInfo.endCursor;
104
+ }
105
+ return {
106
+ project: { title: project.title, url: project.url },
107
+ missing: missing.sort((a, b) => a.number - b.number),
108
+ archived: archived.sort((a, b) => a.number - b.number),
109
+ disagree: disagree.sort((a, b) => a.number - b.number),
110
+ workflows: AUTO_ADD.map((name) => ({ name, on: workflows.find((workflow) => workflow.name === name)?.enabled })),
111
+ };
112
+ }
113
+ /** The audit as lines, ✓ or ✗ each, with what to do; and how many things are wrong. */
114
+ export function auditLines(audit, slug) {
115
+ const { url } = audit.project;
116
+ const lines = [`board-audit: ${slug} on "${audit.project.title}" (${url})`];
117
+ let wrong = 0;
118
+ for (const { name, on } of audit.workflows) {
119
+ if (on) {
120
+ lines.push(`✓ workflow ${name} is on`);
121
+ continue;
122
+ }
123
+ wrong++;
124
+ const what = name === 'Auto-add to project' ? `, for the repository ${slug} with the filter ${AUTO_ADD_FILTER}` : '';
125
+ lines.push(on === false ? `✗ workflow ${name} is off: turn it on at ${url}/workflows${what}` : `✗ workflow ${name} is missing: add it at ${url}/workflows${what} (GitHub's API cannot)`);
126
+ }
127
+ lines.push(` GitHub's API shows whether a workflow is on, not the repository or filter it adds from; Auto-add adds an issue only as it opens or changes, never one already open`);
128
+ if (audit.missing.length === 0)
129
+ lines.push('✓ every open issue is on the board');
130
+ else {
131
+ wrong += audit.missing.length;
132
+ const one = audit.missing.length === 1;
133
+ lines.push(`✗ ${audit.missing.length} open issue${one ? ' is' : 's are'} not on the board: add ${one ? 'it' : 'them'} at ${url} (+ Add item, then #N), or gh project item-add`);
134
+ for (const issue of audit.missing)
135
+ lines.push(` #${issue.number} ${issue.title}`);
136
+ }
137
+ if (audit.archived.length > 0) {
138
+ // Archived by someone, or by the auto-archive workflow before a reopen: the audit cannot tell, so it says them without counting them.
139
+ const plural = audit.archived.length === 1 ? ' is' : 's are';
140
+ lines.push(`- ${audit.archived.length} open issue${plural} archived on the board, so hidden there; restore any that belong on it: ${audit.archived.map((issue) => `#${issue.number}`).join(', ')}`);
141
+ }
142
+ if (audit.disagree.length === 0)
143
+ lines.push("✓ every item's Status agrees with its issue");
144
+ else {
145
+ wrong += audit.disagree.length;
146
+ lines.push(`✗ ${audit.disagree.length} item${audit.disagree.length === 1 ? "'s Status disagrees" : "s' Status disagree"} with the issue: set it at ${url}`);
147
+ for (const issue of audit.disagree)
148
+ lines.push(` #${issue.number} is ${issue.state}, Status ${issue.status ?? 'empty'}: ${issue.title}`);
149
+ }
150
+ lines.push(wrong > 0 ? `board-audit: ${wrong} to fix` : audit.archived.length > 0 ? 'board-audit: nothing to fix but the archived issues above' : 'board-audit: the board matches the repository');
151
+ return { lines, wrong };
152
+ }
153
+ /**
154
+ * `niyam board-audit [owner/repo] [--project <title>]`: lists where the
155
+ * repository and its work board disagree, changing nothing. The repository
156
+ * is the clone's here when none is named; the Project is the one the
157
+ * settings' `project` names, or `<repo> work`. Exit 0 when they agree, 3
158
+ * when something is to fix, 1 when it could not run. A Claude cloud
159
+ * session's GitHub proxy refuses GraphQL and every path outside
160
+ * `repos/{owner}/{repo}/…` (veda-hq/niyam#399), so the audit cannot run there.
161
+ */
162
+ export async function boardAudit(sys, io, args) {
163
+ if (sys.env.CLAUDE_CODE_REMOTE === 'true') {
164
+ io.err("board-audit: cannot run in a Claude cloud session: its GitHub proxy refuses GraphQL and an organisation's Projects (veda-hq/niyam#399), so nothing was checked; run it on a Mac");
165
+ return 1;
166
+ }
167
+ const parsed = auditArgs(args);
168
+ const token = sys.env.GH_TOKEN;
169
+ if (!token)
170
+ throw new Error('board-audit needs GH_TOKEN, with read access to the Project: run it in an agent session, or GH_TOKEN="$(gh auth token)" niyam board-audit');
171
+ const slug = parsed.slug ?? repoAt(sys).slug;
172
+ const title = parsed.project ?? (await settingsTitle(sys, token, slug)) ?? `${slug.split('/')[1]} work`;
173
+ const { lines, wrong } = auditLines(await auditBoard(sys, token, slug, title), slug);
174
+ for (const line of lines)
175
+ io.out(line);
176
+ return wrong === 0 ? 0 : 3;
177
+ }
package/dist/board.js CHANGED
@@ -49,6 +49,20 @@ const GROUPING = [
49
49
  * workflow takes closed items off after it.
50
50
  */
51
51
  const ARCHIVE_FILTER = 'is:closed updated:<@today-7d';
52
+ /**
53
+ * The Project workflows that put a repository's issues on the board, by
54
+ * GitHub's names. GitHub's API can neither create nor set one, and lists
55
+ * one only once it is set up; a copy of the template has no Auto-add to
56
+ * project, since that one names a repository. Without them an issue an
57
+ * agent opens directly, such as a Work item or a Slice, is on no board.
58
+ */
59
+ export const AUTO_ADD = ['Auto-add to project', 'Auto-add sub-issues to project'];
60
+ /** The filter Auto-add to project takes: every open issue of the repository. */
61
+ export const AUTO_ADD_FILTER = 'is:issue is:open';
62
+ /** What the owner sets up for an auto-add workflow that is missing, at the repository `slug`. */
63
+ function autoAddStep(name, slug) {
64
+ return name === 'Auto-add to project' ? `${name}, for the repository ${slug} with the filter ${AUTO_ADD_FILTER}` : `${name}, turned on`;
65
+ }
52
66
  /**
53
67
  * How the owner shows Type on Needs you. GitHub's API can neither read nor
54
68
  * set the issue-type column: GraphQL lists no such field, REST cannot update
@@ -66,7 +80,7 @@ export function viewsChecklist(url) {
66
80
  ` [ ] Workflows → Auto-archive items: ${ARCHIVE_FILTER}`,
67
81
  ];
68
82
  }
69
- async function graphql(sys, token, query, variables) {
83
+ export async function graphql(sys, token, query, variables) {
70
84
  const { status, json } = await sys.http(`${API}/graphql`, { method: 'POST', token, body: { query, variables } });
71
85
  const reply = json;
72
86
  if (status !== 200 || reply?.errors?.length || !reply?.data) {
@@ -248,6 +262,12 @@ approved) {
248
262
  }
249
263
  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
264
  }
265
+ if (done.missing.length > 0) {
266
+ const steps = done.missing.map((name) => autoAddStep(name, slug)).join('; ');
267
+ const plural = done.missing.length === 1 ? '' : 's';
268
+ io.out(`Add the workflow${plural} ${steps} in ${project.url} → Workflows (GitHub's API cannot); it adds issues as they open or change, not those already open, which niyam board-audit lists`);
269
+ byHand.push(`Once for the board: at ${project.url}/workflows, add the workflow${plural} ${steps}, which GitHub's API cannot; then niyam board-audit lists the open issues still not on the board.`);
270
+ }
251
271
  if (done.off.length > 0) {
252
272
  io.out(`Turn on the workflows ${done.off.join(', ')} in ${project.url} → Workflows (GitHub's API cannot)`);
253
273
  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.`);
@@ -297,7 +317,8 @@ async function copyTemplate(sys, io, token, ownerId, title, instead) {
297
317
  /**
298
318
  * What a copy of the template has that GitHub's API cannot set: whether the
299
319
  * views are grouped as the template's are, which marks a Project copied from
300
- * it, and the names of its workflows that are off.
320
+ * it, the names of its workflows that are off, and the auto-add workflows it
321
+ * lacks.
301
322
  */
302
323
  async function finished(sys, token, projectId) {
303
324
  const read = (await graphql(sys, token, 'query($id: ID!) { node(id: $id) { ... on ProjectV2 { views(first: 50) { nodes { name groupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } } } workflows(first: 50) { nodes { name enabled } } } } }', { id: projectId }));
@@ -305,6 +326,7 @@ async function finished(sys, token, projectId) {
305
326
  return {
306
327
  grouped: GROUPING.every(({ view, field }) => views.some((had) => had.name === view && had.groupByFields.nodes.some((by) => by.name === field))),
307
328
  off: read.node.workflows.nodes.filter((workflow) => !workflow.enabled).map((workflow) => workflow.name),
329
+ missing: AUTO_ADD.filter((name) => !read.node.workflows.nodes.some((workflow) => workflow.name === name)),
308
330
  };
309
331
  }
310
332
  /** The field kinds whose values move with an item; the others belong to the issue or are GitHub's own. */
@@ -588,8 +610,12 @@ export async function boardSwept(sys, token, slug) {
588
610
  * Work item's Step to Build, as its first slice has started; and every
589
611
  * other Work item to the Step `stepDue` gives it, so a closed one is Done
590
612
  * and a new one is at Frame. A workflow's GITHUB_TOKEN cannot write a
591
- * Project, so the agent's push does this, through GitHub's REST API alone,
592
- * as a cloud session's proxy refuses GraphQL. Returns what moved, as lines.
613
+ * Project, so this runs with the agent's token on its push from the desktop,
614
+ * and with the board GitHub App's token in the shared workflow's Slice
615
+ * started job when the pull request opens. A Claude cloud session's proxy
616
+ * refuses GraphQL and every path outside `repos/{owner}/{repo}/…`, so it
617
+ * never reaches an org's Projects; there only the workflow moves the board.
618
+ * It uses GitHub's REST API alone. Returns what moved, as lines.
593
619
  */
594
620
  export async function boardStarted(sys, token, slug, slice) {
595
621
  const issue = (await rest(sys, token, `${API}/repos/${slug}/issues/${slice}`)).json;