@installagent/sdk 0.10.0 → 0.11.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.
@@ -1,5 +1,5 @@
1
- import { existsSync } from "node:fs";
2
- import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { copyFile, mkdir, readdir, readFile, rm } from "node:fs/promises";
3
3
  import { dirname, join, resolve } from "node:path";
4
4
  import { readGcpManifestFromRepo } from "./client-manifest.js";
5
5
  /**
@@ -41,10 +41,6 @@ export const TEMPLATE_SYNCED_FILES = [
41
41
  // repo-lint imports log-progress (rule 9), so the two always travel together.
42
42
  "ci/log-progress.mjs",
43
43
  "ci/log-progress.test.mjs",
44
- // repo-lint also imports roadmap (rule 10): the Roadmap tab + client roadmap
45
- // are generated from docs/06-roadmap.md.
46
- "ci/roadmap.mjs",
47
- "ci/roadmap.test.mjs",
48
44
  // repo-lint also imports builds-manifest (rule 11): the `## Builds` block
49
45
  // of CLIENT.md, the source of `ia portal sync-builds`.
50
46
  "ci/builds-manifest.mjs",
@@ -53,8 +49,13 @@ export const TEMPLATE_SYNCED_FILES = [
53
49
  // and Builds-card blocks of onboarding.html (client drift program, step 3).
54
50
  "ci/onboarding.mjs",
55
51
  "ci/onboarding.test.mjs",
56
- // The one write command for every generated view (roadmap, progress list,
57
- // onboarding blocks): rules 9, 10 and 18 name it, CADENCE.md points at it.
52
+ // repo-lint also imports access (rule 21, 2026-11-08): docs/04 §1 is the one
53
+ // source of access status; the client's block in docs/03 is generated.
54
+ "ci/access.mjs",
55
+ "ci/access.test.mjs",
56
+ // The one write command for every generated view (progress list,
57
+ // onboarding blocks, the access block): rules 9, 18 and 21 name it,
58
+ // CADENCE.md points at it.
58
59
  "ci/sync.mjs",
59
60
  "ci/sync.test.mjs",
60
61
  "lefthook.yml",
@@ -66,19 +67,75 @@ export const TEMPLATE_SYNCED_FILES = [
66
67
  "docs/kickoff-presentation.html",
67
68
  ];
68
69
  /**
69
- * Client repos that left the template on purpose, with the reason. They are
70
- * listed (so the report shows they were seen) but never compared and never
71
- * written, not even by `--apply`. A shared rule change reaches them only by a
72
- * hand copy, recorded in that repo's own commit.
70
+ * Files the template used to sync and has since retired. A client repo that
71
+ * still has one is not in sync: the dry run lists it as `retired`, and
72
+ * `--apply` deletes it (`deleted`). Nothing else is ever deleted.
73
73
  *
74
- * best-materials (2026-10-19): the repo moved to the client's GitHub org
75
- * and dropped Linear. Its CADENCE.md (backlog, not Linear),
76
- * lefthook.yml (runs every ci/*.test.mjs) and repo-lint CI are its own, and it
77
- * has no PR → Slack workflow (the Install Agent org secrets are not there).
74
+ * ci/roadmap.mjs + its test (2026-11-08): docs/06-roadmap.md is retired —
75
+ * Linear owns the order of work and the portal reads Now / Next / Later from
76
+ * it. The per-client docs/06-roadmap.md itself is history: `ia roadmap-retire`
77
+ * moves it to docs/archive/, never this operation.
78
78
  */
79
- export const TEMPLATE_SYNC_EXCLUDED = {
80
- "best-materials": "diverged from the template on 2026-10-19 (client's GitHub org, no Linear): its CADENCE.md, lefthook.yml and CI are its own — copy a shared ci/ change by hand",
81
- };
79
+ export const TEMPLATE_RETIRED_FILES = ["ci/roadmap.mjs", "ci/roadmap.test.mjs"];
80
+ const AD_HOC = "ad hoc repo: CLIENT.md says `linear_project: none`, so it is not an official Install Agent project — no template-sync, no Linear-based rule; it keeps its own docs/06-roadmap.md and rules";
81
+ const AD_HOC_BACKLOG = "ad hoc repo: CLIENT.md has `backlog:` in place of a Linear project — its CADENCE.md, lefthook.yml and CI are its own; copy a shared ci/ change by hand";
82
+ /**
83
+ * Why a client repo is ad hoc (not an official Install Agent project), or null.
84
+ * The repo says so itself, in its CLIENT.md: `linear_project: none`, or a
85
+ * `backlog:` key in place of a Linear project. A new repo still holds the
86
+ * template placeholder and is official. The names are read at run time and
87
+ * never listed in this package: @installagent/sdk is public on npm.
88
+ *
89
+ * Ad hoc repos are listed (so a report shows they were seen) but never compared
90
+ * and never written by `template-sync` (not even `--apply`), and `client-drift
91
+ * --all`, `roadmap-migrate --all` and `roadmap-retire --all` skip them and say
92
+ * so. A shared rule change reaches them only by a hand copy, recorded in that
93
+ * repo's own commit. The portal falls back to their hand today / next.
94
+ */
95
+ export function adhocReason(repoDir) {
96
+ const path = join(repoDir, "CLIENT.md");
97
+ if (!existsSync(path))
98
+ return null;
99
+ const text = readFileSync(path, "utf8");
100
+ if (/^backlog\s*:/m.test(text))
101
+ return AD_HOC_BACKLOG;
102
+ const linear = /^linear_project\s*:\s*(\S*)/m.exec(text)?.[1] ?? "";
103
+ return linear.toLowerCase() === "none" ? AD_HOC : null;
104
+ }
105
+ const CLIENT_SLUG = /^[a-z0-9][a-z0-9-]*$/;
106
+ /**
107
+ * The client slugs an operation runs on: one named slug (its checkout must
108
+ * exist; an ad hoc repo is kept, so the caller can say why it skips it), or
109
+ * every clients/client-*\/ checkout except client-template with `all`, where
110
+ * the ad hoc repos are left out and returned in `adhoc` so the report can say so.
111
+ */
112
+ export function selectClientSlugs(workspaceDir, options, op) {
113
+ if (Boolean(options.slug) === Boolean(options.all)) {
114
+ throw new Error(`${op} needs a slug or --all (one of them, not both)`);
115
+ }
116
+ const clientsDir = join(workspaceDir, "clients");
117
+ if (options.all) {
118
+ const all = existsSync(clientsDir)
119
+ ? readdirSync(clientsDir, { withFileTypes: true })
120
+ .filter((e) => e.isDirectory() && e.name.startsWith("client-") && e.name !== "client-template")
121
+ .map((e) => e.name.slice("client-".length))
122
+ .sort()
123
+ : [];
124
+ const isAdhoc = (slug) => adhocReason(join(clientsDir, `client-${slug}`)) !== null;
125
+ return {
126
+ slugs: all.filter((slug) => !isAdhoc(slug)),
127
+ adhoc: all.filter(isAdhoc),
128
+ };
129
+ }
130
+ const slug = String(options.slug).replace(/^client-/, "");
131
+ if (!CLIENT_SLUG.test(slug)) {
132
+ throw new Error(`"${options.slug}" is not a client slug (kebab-case, e.g. acme-hvac)`);
133
+ }
134
+ if (!existsSync(join(clientsDir, `client-${slug}`))) {
135
+ throw new Error(`no checkout at clients/client-${slug} under ${workspaceDir}`);
136
+ }
137
+ return { slugs: [slug], adhoc: [] };
138
+ }
82
139
  /**
83
140
  * Compare (and optionally fix) the shared infra files every client-<slug>
84
141
  * build repo copies verbatim from client-template at creation time. Never
@@ -102,7 +159,7 @@ export async function templateSync(options) {
102
159
  const repos = [];
103
160
  for (const slug of slugs) {
104
161
  const dir = join(clientsDir, `client-${slug}`);
105
- const excluded = TEMPLATE_SYNC_EXCLUDED[slug];
162
+ const excluded = adhocReason(dir);
106
163
  if (excluded) {
107
164
  repos.push({ slug, dir, files: [], inSync: true, excluded, manifestGaps: [] });
108
165
  continue;
@@ -128,12 +185,22 @@ export async function templateSync(options) {
128
185
  }
129
186
  fileResults.push({ file: rel, status });
130
187
  }
188
+ if (!options.files) {
189
+ for (const rel of TEMPLATE_RETIRED_FILES) {
190
+ const repoFile = join(dir, rel);
191
+ if (!existsSync(repoFile))
192
+ continue;
193
+ if (apply)
194
+ await rm(repoFile);
195
+ fileResults.push({ file: rel, status: apply ? "deleted" : "retired" });
196
+ }
197
+ }
131
198
  const manifest = readGcpManifestFromRepo(dir);
132
199
  repos.push({
133
200
  slug,
134
201
  dir,
135
202
  files: fileResults,
136
- inSync: fileResults.every((f) => f.status === "in-sync" || f.status === "fixed"),
203
+ inSync: fileResults.every((f) => ["in-sync", "fixed", "deleted"].includes(f.status)),
137
204
  manifestGaps: manifest
138
205
  ? [...manifest.missing, ...manifest.unfilled, ...manifest.invalid]
139
206
  : [],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -92,7 +92,7 @@ two (step 4):
92
92
  | `check` | What it compares |
93
93
  |---|---|
94
94
  | `linear` | Linear vs the delivery log: an issue Done with no entry, or an entry that says shipped while the issue is open |
95
- | `lint` | the repo's drift rules 12–19: an `AS OF` date behind the log (12), a dead evidence link or an evidence file no entry names (13), a Builds `workflow_id` no doc names (14), a `CLIENT.md` placeholder (15), stale status words on an active build (16), a dead pointer (17), a generated block behind its source (18), a doc with no `Type:` line (19) |
95
+ | `lint` | the repo's drift rules 12–19, 21 and 22: an `AS OF` date behind the log (12), a dead evidence link or an evidence file no entry names (13), a Builds `workflow_id` no doc names (14), a `CLIENT.md` placeholder (15), stale status words on an active build (16), a dead pointer (17), a generated block behind its source (18), a doc with no `Type:` line (19), the client's access block in `03` not matching `04` §1, or the retired Access tab still in the page (21), work state in a spec (a `Status:` line, an open question with no INS id) or a hand-kept "Next" list in the page (22) |
96
96
  | `git`, `open-pr` | uncommitted, untracked or unpushed work, no upstream; open PRs |
97
97
  | `active-flag`, `missing-workflow`, `name` | `CLIENT.md` `## Builds` vs n8n: inactive or archived while the repo says live, an id the instance does not have, `SHADOW`/`TEST` still in a live name |
98
98
  | `missing-export`, `stale-export`, `orphan-export` | `workflows/` exports vs the instance |
@@ -40,7 +40,7 @@ you keep that same build folder's `onboarding.html` in sync:
40
40
  | `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
41
41
  | `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
42
42
  | `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
43
- | `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING. This is the **tracker**, kept current as access lands. Mirror §1 only into `onboarding.html`'s Access tab. |
43
+ | `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING/N/A. This is the **tracker** and the **one source** of access status: §1's Item, System and Why are client words, and the client's table in `03` is generated from them (`node ci/sync.mjs --write`, repo-lint rule 21). |
44
44
  | `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
45
45
 
46
46
  **Every doc carries a Type line** on the line under its title, so a reader
@@ -107,7 +107,9 @@ This skill runs **twice** per engagement, against two different calls in
107
107
  - For content already filled, update only what the tech call firms up,
108
108
  corrects, or adds (a confirmed trigger, a newly-scoped item, a
109
109
  resolved open question) — don't regenerate prose that's already
110
- accurate just because you're touching the file.
110
+ accurate just because you're touching the file. A resolved open
111
+ question: write the answer into the spec, close its Linear issue, and
112
+ drop its INS id from § Open questions.
111
113
  - Leave anything a human has clearly hand-edited since the first pass
112
114
  alone unless the tech call directly contradicts it.
113
115
  - Move resolved items out of `02-tech-spec.md`'s open-questions list
@@ -161,7 +163,12 @@ the Kingdom tech-spec sections that apply:
161
163
  defensive parser fallback.
162
164
  - **Security** — where credentials live, what gets scrubbed from logs.
163
165
  - **Open questions for the build** — the things the call left unresolved. This
164
- section is the most valuable; it prevents building on an assumption.
166
+ section is the most valuable; it prevents building on an assumption. **Each
167
+ one is a Linear issue** in the client's project (the `linear` skill; ask
168
+ before you create issues — Linear is shared): the spec lists only the INS
169
+ ids (`- INS-123 — short title`), never the open work itself. A spec holds no
170
+ work state — no `Status:` line under the title either (build status lives in
171
+ `CLIENT.md` `## Builds`); repo-lint rule 22 warns on both.
165
172
  - **Build sequence** — the order you'll actually implement in.
166
173
 
167
174
  ### 4. Draft `03-client-onboarding.md` (what we need from them)
@@ -185,22 +192,34 @@ overwhelmed:
185
192
  or a shared doc — every credential goes through the portal or 1Password,
186
193
  never pasted in a message — and no access beyond the named systems.
187
194
  - **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
195
+ - **`## Where things stand`** — the last section: only the two marker lines
196
+ `<!-- ACCESS_STATUS_TABLE:START -->` and `<!-- ACCESS_STATUS_TABLE:END -->`.
197
+ Never write the table by hand: after step 5, `node ci/sync.mjs --write`
198
+ builds it from `04` §1, and the client sees it on the portal Access tab.
188
199
 
189
200
  ### 5. Draft `04-access-checklist.md` (internal tracker)
190
201
 
191
202
  Two tables, never one. **§1 Credentials & grants** — one row per *system* we
192
203
  need a credential or an access grant for (a login, an OAuth scope, a share, an
193
- API key): **System | Access we need (minimum role/scope) | Used by | Status |
194
- Notes**. Every software the client named on the sales call gets a row, even
195
- when the ask is still MISSING or it is UNKNOWN whether a credential is needed.
204
+ API key): **Item | System | Why we need it | Status | Notes**. §1 is the one
205
+ source of access status, and the client reads part of it: **Item, System and
206
+ Why we need it are client words** (plain, no tool jargon, no ticket numbers,
207
+ no dollar amounts) — `node ci/sync.mjs --write` builds the client's table in
208
+ `03` from them. **Notes** stays internal: the minimum role/scope, which build
209
+ uses it, chase detail, INS ids. You may add internal columns (`Access we need`,
210
+ `Used by`); they are never shown. A row that is ours only (our vault, our
211
+ Airtable base) gets `—` in Item: it stays internal. Every software the client
212
+ named on the sales call gets a row, even when the ask is still MISSING; a row
213
+ where it is UNKNOWN whether a credential is needed stays internal (`—` in Item)
214
+ until you know — a client row is HAVE, REQUESTED, MISSING or N/A.
196
215
  **§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
197
216
  intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
198
217
  list, a person or a decision is never a §1 row; that mixing is what turns the
199
218
  tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
200
219
  UNKNOWN / N/A — set from what the call notes and registry profile actually say
201
- was granted or promised, never assumed. This is the doc (and the matching
202
- `onboarding.html` Access tab) a teammate opens to answer "what are we still
203
- waiting on from this client?" without re-reading the call transcript. Update
220
+ was granted or promised, never assumed. This is the doc a teammate opens to
221
+ answer "what are we still waiting on from this client?" without re-reading
222
+ the call transcript. Update
204
223
  it in the same commit whenever access lands — it decays fast otherwise.
205
224
 
206
225
  - **Capture status, don't invent it.** If a call didn't confirm an item was
@@ -216,10 +235,14 @@ it in the same commit whenever access lands — it decays fast otherwise.
216
235
  thing the client must say, not grant.
217
236
  - **No credential values or IDs** — status and the 1Password vault *name*
218
237
  only (from `CLIENT.md`), same rule as everywhere else in the repo.
219
- - Mirror **§1 only** into `onboarding.html`'s Access tab (its own sidebar
220
- entry, `#access`) so a developer sees it in one screen without opening
221
- `docs/`. §2 stays in the doc; the Client tab's status snapshot carries the
222
- open decisions.
238
+ - **Put the line `<!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->` above the §1 table** once you have read Item,
239
+ System and Why as the client would: it tells sync that §1 may be shown.
240
+ Without it nothing is generated.
241
+ - **Then run `node ci/sync.mjs --write`** in the repo: it builds the client's
242
+ table (the `ACCESS_STATUS_TABLE` block in `03`) from §1. Never hand-edit
243
+ that block; repo-lint rule 21 warns when it says something else. There is
244
+ no Access tab in `onboarding.html` any more (retired 2026-11-08):
245
+ technicians read `04`. §2 stays in the doc.
223
246
 
224
247
  ### 6. Populate `onboarding.html`
225
248
 
@@ -237,10 +260,9 @@ In short:
237
260
  tokens, `TRIGGER`, `THRESHOLD`, `IDEMPOTENCY`, `INSTANCE`,
238
261
  `STACK_NOTES`) — pulled straight from `02-tech-spec.md`'s architecture
239
262
  summary and idempotency section. Repeating list tokens
240
- (`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`, `DONE_ITEM`, `NEXT_ITEM`) — one
241
- `<li>` per item, duplicate the template's stub `<li>` as needed. The
242
- access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
243
- `04-access-checklist.md` mirror already required in step 5.
263
+ (`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`) — one `<li>` per item, duplicate
264
+ the template's stub `<li>` as needed. The page has no access table and no
265
+ hand-kept "Next" list: access lives in `04` §1, open work in Linear.
244
266
  - **Builds tab** — one *systems-level* block per build in scope, duplicating
245
267
  the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
246
268
  `SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
@@ -263,7 +285,8 @@ In short:
263
285
  - **Public tab** — the client-safe rewrite: tech-agnostic
264
286
  `PUBLIC_SUMMARY`/`TODAY`/`AFTER`/`METRIC`, `PLAIN_STEP`+`PLAIN_DETAIL`
265
287
  pairs (same pipeline as the Client tab's architecture nodes, no tool
266
- names), `PUBLIC_DONE_ITEM`/`PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
288
+ names), `PUBLIC_DONE_ITEM`, `CLIENT_ASK` (no "Up next" list: the portal
289
+ reads Now / Next / Later from Linear).
267
290
 
268
291
  If a list section has more real items than the template's stub `<li>`s,
269
292
  duplicate the stub; if fewer, delete the extras — don't leave unfilled
@@ -297,12 +320,15 @@ tokens or empty bullets.
297
320
  - [ ] `01-overview.md`: problem → build (plain) → expectations (measurable,
298
321
  hedged); no bare tool names without a gloss.
299
322
  - [ ] `02-tech-spec.md`: schema, node-by-node, idempotency (both halves),
300
- error table, AI specifics, **open questions**, build sequence.
323
+ error table, AI specifics, **open questions** (each a Linear issue; the
324
+ spec lists INS ids only), build sequence; no `Status:` line.
301
325
  - [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
302
326
  / quick-fill; minimum roles; "creds in your vault, never a password".
303
327
  - [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
304
- sales-call software has a row) + §2 decisions/information; Status set from
305
- what's actually confirmed (not assumed); §1 mirrored into the Access tab.
328
+ sales-call software has a row; Item / System / Why in client words,
329
+ `—` in Item for an internal row) + §2 decisions/information; Status set
330
+ from what's actually confirmed (not assumed); `node ci/sync.mjs --write`
331
+ run, so the `03` block matches §1 (repo-lint rule 21 clean).
306
332
  - [ ] Each of `01`–`04` has its Type line under the title:
307
333
  `<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
308
334
  - [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
@@ -14,7 +14,6 @@ the `client-kingdom/docs/` exemplars.
14
14
 
15
15
  **Prepared for:** <Client legal/dba name>
16
16
  **Prepared by:** Install Agent
17
- **Status:** Proposal, post-discovery
18
17
 
19
18
  ---
20
19
 
@@ -60,7 +59,6 @@ daily review queue that shrinks as the system learns."><br/>
60
59
  Type: spec
61
60
 
62
61
  **Audience:** Install Agent engineering. Internal.
63
- **Status:** Pre-implementation, ready for build kickoff.
64
62
  **Source diagram:** docs/<name>-diagram.html
65
63
 
66
64
  ---
@@ -103,7 +101,9 @@ parser fallback, retry policy, rough per-call cost at expected volume.>
103
101
  <Audit log of record; daily/weekly digest; native dashboards.>
104
102
 
105
103
  ## 10. Open questions for the build
106
- <Everything the discovery call left unresolved. Resolve before coding.>
104
+ Each open item is a Linear issue in this client's project (`linear_project` in
105
+ `CLIENT.md`), never a line here: list its INS id below, one per line.
106
+ - INS-<id> — <short title of one thing the call left unresolved>
107
107
 
108
108
  ## 11. Build sequence
109
109
  <The order you'll implement: infra → fixtures → core nodes → rules → AI shadow →
@@ -149,8 +149,17 @@ no access beyond the named systems.>
149
149
  - [ ] <decision made>
150
150
  - [ ] <contact + handle>
151
151
  - [ ] <person available for live linking>
152
+
153
+ ## Where things stand
154
+
155
+ <!-- ACCESS_STATUS_TABLE:START -->
156
+ <!-- ACCESS_STATUS_TABLE:END -->
152
157
  ```
153
158
 
159
+ The two marker lines stay empty here: `node ci/sync.mjs --write` fills them
160
+ from `04` §1 (the client's table on the portal Access tab). Never write the
161
+ table by hand.
162
+
154
163
  ---
155
164
 
156
165
  ## `04-access-checklist.md` (internal — status tracker)
@@ -159,12 +168,14 @@ no access beyond the named systems.>
159
168
  # Access & Credentials Checklist — <slug>
160
169
  Type: spec
161
170
 
162
- Internal tracker: same items as `03-client-onboarding.md`'s §1 Access and §2
163
- Decisions, plus what we actually have. `03` is the **ask** we send the
164
- client; this file is the **tracker** — update it the moment access lands or a
165
- decision gets made, so anyone can answer "what are we still waiting on?"
166
- without re-reading the call notes. Mirror this table into `onboarding.html`'s
167
- Client tab in the same commit.
171
+ Internal tracker, and the one source of access status. `03` is the **ask**
172
+ we send the client; this file is the **tracker** — update it the moment
173
+ access lands or a decision gets made, so anyone can answer "what are we still
174
+ waiting on?" without re-reading the call notes. In §1, **Item, System and Why
175
+ we need it are client words**: the client reads them on the portal Access tab
176
+ (no ticket numbers, no dollar amounts). **Notes** stays internal. `—` in Item
177
+ keeps a row internal. After any change, run `node ci/sync.mjs --write`: it
178
+ rebuilds the client's table in `03` (repo-lint rule 21).
168
179
 
169
180
  No real credential values or IDs here — status and the 1Password vault
170
181
  *name* only (see `CLIENT.md`).
@@ -172,12 +183,22 @@ No real credential values or IDs here — status and the 1Password vault
172
183
  Status legend: **HAVE** · **REQUESTED** (asked, not yet received) ·
173
184
  **MISSING** (not yet asked, or blocking) · **N/A**
174
185
 
186
+ ## §1 — Credentials & grants
187
+
188
+ <!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->
189
+
175
190
  | Item | System | Why we need it | Status | Notes |
176
191
  |---|---|---|---|---|
177
- | <e.g. Portal login> | <e.g. Catalyte> | <what it unblocks> | MISSING | <who's chasing it, by when> |
178
- | <e.g. EHR admin user> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
179
- | <e.g. Notification space> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
180
- | <e.g. Data-handling agreement> | <BAA / DPA> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
192
+ | <e.g. A login for your portal> | <e.g. Catalyte> | <what it lets us do for them, in their words> | MISSING | <minimum role; which build; who's chasing it, by when> |
193
+ | <e.g. An admin user for your records system> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
194
+ | <e.g. A space for alerts> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
195
+ | — | <e.g. 1Password vault `client-<slug>`> | — | HAVE | <ours: never shown to the client> |
196
+
197
+ ## §2 — Decisions & information owed
198
+
199
+ | Item | Who owes it | Why | Status | Notes |
200
+ |---|---|---|---|---|
201
+ | <e.g. Data-handling agreement (BAA / DPA)> | <client> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
181
202
 
182
203
  _Last updated: <date> — update in the same commit as any access change._
183
204
  ```
@@ -202,9 +223,10 @@ once (even if the same value is reused verbatim in more than one spot, e.g.
202
223
  `IDEMPOTENCY`, `INSTANCE`, `STACK_NOTES`, `CLIENT_SPECIFIC_RULE`, `DATE`
203
224
  (status-snapshot "as of").
204
225
  - **(repeat)** `SCOPE_ITEM` (Phase 1 scope), `PARKED_ITEM`, `STEP` (build
205
- order, numbered), `DONE_ITEM`, `NEXT_ITEM`.
206
- - **(repeat, one row)** access table: `ITEM`, `SYSTEM`, `REASON`, `NOTE` —
207
- the `04-access-checklist.md` mirror; Status is a badge class, not a token.
226
+ order, numbered). No "Next" list: open work lives in Linear (repo-lint
227
+ rule 22 warns on a hand-kept one).
228
+ - No access table: the Access tab is retired (2026-11-08). Access lives in
229
+ `04-access-checklist.md` §1; the client's table in `03` is generated from it.
208
230
 
209
231
  **Workflows tab** — one whole diagram block duplicated per automation in
210
232
  scope:
@@ -223,7 +245,8 @@ scope:
223
245
  `METRIC`, `DATE` (reused, progress "as of").
224
246
  - **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
225
247
  Client tab's architecture nodes, described without tool names.
226
- - **(repeat)** `PUBLIC_DONE_ITEM`, `PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
248
+ - **(repeat)** `PUBLIC_DONE_ITEM`, `CLIENT_ASK`. No "Up next" list: the
249
+ portal reads Now / Next / Later from Linear.
227
250
  - **`portal-overview` JSON block** (the client portal's Onboarding tab):
228
251
  not tokens you replace one by one — fill the whole JSON (`asOf`,
229
252
  `summary` — one plain paragraph ≤ 280 chars that opens the page —,
@@ -41,6 +41,7 @@ secrets).
41
41
  | What's in client X's build repo docs? | `ia client-build <slug> [query]` |
42
42
  | Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
43
43
  | Open Linear issues for a client | `ia client-linear <slug> [query]` |
44
+ | Move a client's old `docs/06-roadmap.md` into Linear / retire the roadmap file | `ia roadmap-migrate <slug> \| --all` (dry run: labels and `Client line:` to add, state mismatches, rows with no INS id), then `ia roadmap-retire <slug> \| --all` (dry run: the `git mv` and the `onboarding.html` removals). The account owner runs each `--apply`; ad hoc repos are skipped |
44
45
  | Did anything drift? / does client X's repo still agree with n8n, Linear and git? | `ia client-drift <slug> [--json]` (`--all` for every client repo) — read-only: Builds vs n8n (active flag, missing workflow, SHADOW/TEST names), exports vs the instance, silent schedules and failed last runs (status only), git and open PRs, Linear vs the delivery log, the repo's drift lint (rules 12–19). Exit 1 on drift or when a source could not be read. The `client-latest` skill runs it for you |
45
46
  | Open issues in an internal Linear project | `ia linear-project <project> [query]` |
46
47
  | Start a new client engagement | `ia client-intake <slug> --name <name>` (or bare `ia new-client <slug>`) |
@@ -62,6 +62,38 @@ Statuses on this team: `Backlog` → `Todo` → `In Progress` → `In Review`
62
62
  updates and write-ups to the end of a session — that's how issues sit in
63
63
  "In Progress" days after the work actually finished.
64
64
 
65
+ ## Order of work and the client's plan (Linear owns it)
66
+
67
+ Linear owns work state; the client repo owns context. Since 2026-11-08 there
68
+ is no `docs/06-roadmap.md` (old ones sit in `docs/archive/`), and the client
69
+ portal reads **Now / Next / Later** from the client's project at request time.
70
+
71
+ | Fact | In Linear | On the client portal |
72
+ |---|---|---|
73
+ | Being worked this week | state In Progress / In Review (type *started*) | **Now** |
74
+ | Up next | state Todo (type *unstarted*) | **Next** |
75
+ | Later | state Backlog (type *backlog*) | **Later** |
76
+ | Parked | label `parked` (any state) | never shown |
77
+ | Done | Done; the delivery-log entry names the INS id | the progress list (from the log) |
78
+ | Rank | priority, then the project's manual sort order. The account owner moves ranks; a technician moves states | the order inside each list |
79
+ | Who it serves | label `value` (moves the number we committed to), `client-ask` (the client asked); both labels = both | — |
80
+ | Why this rank | the issue description | — |
81
+ | The client-safe line | one line in the description: `Client line: <one sentence, 140 characters at most>` | the only text the client sees |
82
+
83
+ **Client line rules:** plain words, no tool names, no ticket numbers, **no
84
+ dollar amounts** (Linear is shared by all staff). An issue with no `Client
85
+ line:` is internal: the client never sees it. The portal never shows an issue
86
+ title or any other part of the description, and drops a line with `$` or a
87
+ ticket id.
88
+
89
+ **A new client ask** is a new issue in the client's project: its `Client
90
+ line:`, the `client-ask` label, and a priority. The account owner places it.
91
+
92
+ **Follow-ups are issues.** Work still owed after something ships is a Linear
93
+ issue. The delivery-log entry's `- **Follow-ups:**` holds only its INS ids, or
94
+ `none` (repo-lint rule 20, entries dated 2026-11-08 or later). `ia
95
+ client-drift` flags a follow-up id that is not in the client's project.
96
+
65
97
  ## Creating issues
66
98
 
67
99
  - Set `project` to the client's Linear project (from `CLIENT.md`), not just
@@ -70,7 +70,7 @@ its agenda carries forward intact.
70
70
  In order: registry `PROFILE.md` (including Internal notes — that's where
71
71
  name mis-transcriptions and discrepancies live), every file in registry
72
72
  `calls/`, then the build repo's `CLIENT.md`, `docs/00`–`04`, and
73
- `onboarding.html` (Proposals tab + access table). For a monthly scoping
73
+ `onboarding.html` (Proposals tab). For a monthly scoping
74
74
  call, add `docs/00-delivery-log.md` and `evidence/`.
75
75
 
76
76
  **Check for the auto-drafted agenda.** The portal's Lead Close Kickoff
@@ -151,7 +151,7 @@ access I need. At the end we book the follow-ups."
151
151
  - <which process to walk, who should drive, what artifact to ask them to share>
152
152
 
153
153
  ## Questions to ask <!-- ONLY unanswered ones; use the script's question FORMS -->
154
- - <question> → fills <02-tech-spec §X / trigger / volume / boundary / …>
154
+ - <question> → fills <02-tech-spec §X / trigger / volume / boundary / …> (INS-<id> when it is an open Linear issue)
155
155
 
156
156
  ## The month-one pitch
157
157
  - Lead: <primary candidate> — because <their stated cost>.
@@ -202,7 +202,11 @@ convention.
202
202
  - **Questions come from gaps, not templates.** A question already
203
203
  answered in a call note never appears on the agenda — re-known facts go
204
204
  in the read-back as statements to confirm, not questions to re-ask.
205
- Every question names the doc section its answer fills.
205
+ Every question names the doc section its answer fills. The spec's open
206
+ questions are Linear issues (its § Open questions lists their INS ids;
207
+ `ia client-linear <slug>` shows them): ask the open ones and name the INS
208
+ id. After the call, the answer goes into the spec and the issue closes —
209
+ the agenda and the spec never keep their own list of open work.
206
210
  - **Facts get verified, not copied.** Transcripts mangle names; the
207
211
  registry's Internal notes section is authoritative for known
208
212
  discrepancies. Never propagate a mis-transcription onto an agenda the