@jjanczur/tyran 0.1.35 → 0.1.36

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.35",
14
+ "version": "0.1.36",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.35",
3
+ "version": "0.1.36",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,119 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.36 — 2026-08-17
4
+
5
+ Four fixes, three of them found by installing Tyran into a clean repo and
6
+ walking through what a new user actually gets, rather than by reading the code.
7
+
8
+ ### The first sentence a new install reads was wrong
9
+
10
+ A brand-new user's opening message ended *"Run `/tyran` to resume, or read
11
+ `.tyran/state/<init>/STATE.md` in full."* There is nothing to resume, and
12
+ `.tyran/state/<init>/` is not a directory — at that point `.tyran/state/` holds
13
+ only `board-server.json`.
14
+
15
+ A regression from 0.1.34. `renderContext` returned `''` when there was no
16
+ initiative and no pause, so that line was unreachable from an empty repo;
17
+ autostart added `board` to the guard, `board` is non-null in every adopted
18
+ repo, and the whole scaffold began rendering for repos with no state at all.
19
+ Checked: a repo that never adopted Tyran still injects `{}`.
20
+
21
+ The closing line now branches, and names the initiative when there is exactly
22
+ one instead of sending the reader to look up `<init>`. The README's dashboard
23
+ section was stale the same way — it opened with `--serve`, a command setup made
24
+ unnecessary, and taught `--write` as an opt-in flag that setup now writes by
25
+ default.
26
+
27
+ ### A board that failed to start deleted the record of the one running
28
+
29
+ With a board already up, a second `--serve` loses the bind, prints *"port 4173
30
+ is already in use"*, and exits — running the `clear` handler `board.mjs`
31
+ registers on `process.exit` unconditionally. That deleted the RUNNING board's
32
+ record. Measured after: `curl` still answering on 4173, `.tyran/state/` empty,
33
+ `--stop` reporting *"no board server is recorded"*. A server serving with
34
+ nothing naming it — invisible to `--status`, unreachable by `--stop`, killable
35
+ only with `lsof`.
36
+
37
+ `removeServerRecord` now refuses to unlink a record naming another pid. The
38
+ guard is in the module, not at the call site: ownership enforced by whoever
39
+ remembers to check is caller discipline, which `journal.mjs` and `doctor.mjs`
40
+ both reject by name. `stopServer` passes `owner: null` and has earned it.
41
+
42
+ Same session, same cause: `--detach --write --transcripts <dir>` against a
43
+ running board printed *"already serving"*, exit 0, and applied nothing.
44
+ `--transcripts` is the remedy the Spend tab itself prints, so the product
45
+ recommended a command that reported success and fixed nothing. The inert flags
46
+ are now named, with how to apply them. A plain re-run stays silent — autostart
47
+ runs it every session.
48
+
49
+ ### The chip printed spawn time under the words "last signal"
50
+
51
+ `NOTES-REQUESTS` §11 recorded that four shipped features rest on a `progress`
52
+ event that fires once in 388 journals, and that the measurement to decide what
53
+ to do had not been made. It has now. Folding **420 real journals**: 72 running
54
+ agents on boards, `last_signal === since` for **72 of 72**, never once an actual
55
+ signal, with `detail`, `next` and `state: "blocked"` at zero.
56
+
57
+ `last_signal` fell back to the spawn time, so this was not an empty field — it
58
+ was spawn time published under a label saying *"when it last spoke"*, in the
59
+ chip, the `BOARD.md` column and the cross-repo line. A blank reads as an
60
+ absence; a number reads as a measurement.
61
+
62
+ The age was worth keeping, so this is a relabelling: the chip measures from
63
+ `since` and says *"since it started"*, `BOARD.md` gains a **Started** column,
64
+ and a real signal gets its own line when there is one. The golden fixture
65
+ missed it because its one agent does signal — the case that is universal in the
66
+ wild was the one no fixture covered.
67
+
68
+ `agents/implementer.md` now asks for **one** `progress` emission, at the first
69
+ blockage, instead of four. Three of the four were reconstructable from events
70
+ another party writes; a blockage is the exception, because nothing else says an
71
+ agent is stuck or why. Deleting `progress` outright was rejected for that
72
+ reason — `spawn-blocked` and the `blocked` lane stay.
73
+
74
+ ### Four commands silently ignored a flag they did not understand
75
+
76
+ Swept every command `bin/tyran.mjs` dispatches, against a repo where setup had
77
+ just run:
78
+
79
+ | | |
80
+ |---|---:|
81
+ | `--help` answered as help | **0 of 14** |
82
+ | silently ignored an unknown flag | **4** |
83
+
84
+ `tiers`, `scan-repo`, `stop-check` and `desc-budget` parse by looking up the
85
+ flags they know, so a flag they do not know is never rejected — it is never
86
+ seen. `tiers --rol reviewer` exited **0** and printed the entire routing table:
87
+ a different answer to a different question, given without a word about the
88
+ typo. One character later, `tiers --role revieweer` was refused by name with
89
+ the list of valid roles — the value was checked and the flag was not. Worse,
90
+ `scan-repo --wrte .tyran/config.yaml` scanned, printed JSON and exited 0, a
91
+ swallowed typo in the one flag that decides whether the command writes.
92
+
93
+ `scripts/cli-args.mjs` is now the single implementation of both rules, and it
94
+ is not a new convention: `board`, `doctor`, `answer`, `cost` and `migrate`
95
+ already refused unknown flags, so this is the majority one made importable so
96
+ the count of spellings stops rising (ADR-21).
97
+
98
+ **`--help` is now answered, on stdout, exit 0, by all nine flag-taking
99
+ commands.** `cost` needed a second fix on the way: its `main` is handed an
100
+ already-sliced argv, so an added `argv.slice(2)` dropped the first two
101
+ arguments and `--help` fell through to the parser. The four subcommand-style
102
+ commands (`journal`, `schema`, `knowledge`, `mistakes`) still print usage with
103
+ exit 2; recorded in `NOTES-REQUESTS.md` rather than fixed here.
104
+
105
+ ### Exercise cloud access, and never ask for a secret's value
106
+
107
+ Both from `NOTES-REQUESTS` §12.4. STEP 0 already spawns a throwaway teammate
108
+ rather than infer that Agent Teams work; cloud access had no such rule, and a
109
+ missing permission surfaces at deploy — after the work. It is now exercised
110
+ with a read-only call per service the plan names.
111
+
112
+ And a gate must never ask for a credential's VALUE: `journal.mjs ask` writes
113
+ the question into the journal and `answer.mjs apply` folds the reply back as a
114
+ `decision`, both into a committed file. Ask where it lives — the SSM parameter
115
+ name, the secrets-manager key, the vault path.
116
+
3
117
  ## 0.1.35 — 2026-08-17
4
118
 
5
119
  ### Three surfaces promised a consolidation step that nobody implements
package/README.md CHANGED
@@ -229,20 +229,29 @@ echo "wrong branch — hold everything" > .tyran/STOP
229
229
 
230
230
  ## The dashboard
231
231
 
232
+ **It is already running.** `/tyran:setup` writes `board: autostart: true`, so
233
+ every session after it starts the dashboard if it is not up and prints the URL —
234
+ **open that.** The board is bound to loopback, re-rendered on every request, and
235
+ it reloads itself every 30 seconds.
236
+
237
+ The **Settings** tab is an editor for `.tyran/config.yaml` and the autonomy
238
+ policy — every knob with a sentence explaining it, your comments kept, and
239
+ loosening a boundary behind a second deliberate press. Setup turns it on;
240
+ `board: write: false` makes the board read-only, `autostart: false` stops it
241
+ starting at all.
242
+
243
+ From a plain shell — outside Claude Code, or in a script:
244
+
232
245
  ```bash
233
- npx @jjanczur/tyran board --dir .tyran --serve
246
+ npx @jjanczur/tyran board --dir .tyran --detach # starts it, prints the URL, returns
247
+ npx @jjanczur/tyran board --dir .tyran --status # where is it, if anywhere
248
+ npx @jjanczur/tyran board --dir .tyran --stop # ends it
234
249
  ```
235
250
 
236
- It prints `board: serving http://127.0.0.1:4173/` — **open that URL.** The
237
- board is bound to loopback, re-rendered on every request, and it reloads itself
238
- every 30 seconds; `--port <n>` if 4173 is taken, `Ctrl-C` to stop. That command
239
- is the one place a Node version matters, because `npx` runs the scripts outside
240
- Claude Code and they need **Node ≥ 22**.
241
-
242
- Add `--write` and the **Settings** tab becomes an editor for `.tyran/config.yaml`
243
- and the autonomy policy — every knob with a sentence explaining it, your
244
- comments kept, and loosening a boundary behind a second deliberate press. It is
245
- read-only without that flag.
251
+ `--serve` instead of `--detach` holds the terminal until `Ctrl-C`, which is what
252
+ you want only if you are a person at a prompt. `--port <n>` if 4173 is taken.
253
+ These are the one place a Node version matters, because `npx` runs the scripts
254
+ outside Claude Code and they need **Node ≥ 22**.
246
255
 
247
256
  No terminal, no server: the same page is written to **`.tyran/state/board.html`**
248
257
  after every agent, so you can just open the file —
@@ -309,7 +318,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
309
318
  fires and who invokes it, is in
310
319
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
311
320
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
312
- it: 1571 unit tests, run with `node --test "tests/**/*.test.mjs"`.
321
+ it: 1586 unit tests, run with `node --test "tests/**/*.test.mjs"`.
313
322
 
314
323
  ## Documentation
315
324
 
@@ -15,16 +15,25 @@ commits and anything written to disk are in English.**
15
15
  lease file as the handoff describes. Another agent's unexpired lease
16
16
  means you do NOT start — you report back. Release it when you finish,
17
17
  including when you finish by failing.
18
- - **Signal at four points, no more** — `progress` events appended to the
19
- MAIN checkout's journal (the handoff carries its absolute path):
20
- `started` right after the lease (it is also the proof the lease protocol
21
- was honoured) · `blocked` at the FIRST blockage, BEFORE attempting any
22
- workaround · `unblocked` when it clears · `working` before the final
23
- full validation run, the longest silent stretch you have. Shape:
18
+ - **Signal ONCE: at the first blockage, before any workaround.** A
19
+ `progress` event appended to the MAIN checkout's journal (the handoff
20
+ carries its absolute path):
24
21
  `node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <abs-journal>
25
22
  progress <init> --actor <you> --data
26
- '{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'`.
27
- Four emissions per story; this is a closed list, not a diary.
23
+ '{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'`,
24
+ and `state: "unblocked"` when it clears.
25
+
26
+ This asked for four emissions until 2026-08-17 — `started`, `blocked`,
27
+ `unblocked`, `working` — and measurement ended the argument: **one**
28
+ `progress` event across 388 real journals, against roughly six thousand
29
+ the instruction predicted. The lease bullet immediately above produced
30
+ 434 in the same set, so this is not an agent that ignores the journal or
31
+ ignores this file. Three of the four asks were also reconstructable from
32
+ events someone else writes — your lease IS `started`, your report IS the
33
+ end of `working` — and a signal only you can contradict is worth less
34
+ than one another party produces. A blockage is the exception: nothing
35
+ else in the journal says you are stuck, or why. So the list is one item
36
+ long, and it is the item that carries information nothing else can.
28
37
  - **Grep before you build.** Search for an existing implementation of the
29
38
  thing you are about to write; if it exists, report it as a corrected
30
39
  premise instead of duplicating it. Durable discoveries worth another
@@ -256,10 +256,34 @@ export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso,
256
256
  lines.push('- run `node scripts/doctor.mjs --state --now "$(date -u +%FT%TZ)"` by hand');
257
257
  }
258
258
  lines.push('');
259
- lines.push('Run `/tyran` to resume, or read `.tyran/state/<init>/STATE.md` in full.');
259
+ lines.push(closingLine(initiatives));
260
260
  return lines.join('\n');
261
261
  }
262
262
 
263
+ /**
264
+ * The last line — which, on a fresh install, is the FIRST sentence Tyran says.
265
+ *
266
+ * Until the board began starting itself this line was unreachable from an
267
+ * empty repo: the guard above returned '' when there was no initiative and no
268
+ * pause, so only someone with state to resume ever read it. Autostart made
269
+ * `board` non-null in every adopted repo, the guard stopped tripping, and a
270
+ * first-time user's opening message became an instruction to *resume* work
271
+ * that does not exist and to open a `STATE.md` under a literal `<init>`
272
+ * directory that is not on disk. A wrong first sentence, not a missing one.
273
+ *
274
+ * Naming the initiative when there is exactly one is the same defect a size
275
+ * down: `<init>` is a placeholder standing in a sentence whose writer already
276
+ * knows the answer. The name is a directory read off disk, so it is journal-
277
+ * adjacent input and goes through `inlinePlain` like everything else here.
278
+ */
279
+ export function closingLine(initiatives) {
280
+ if (initiatives.length === 0) {
281
+ return 'No initiative here yet — run `/tyran` and describe what you want done.';
282
+ }
283
+ const where = initiatives.length === 1 ? inlinePlain(initiatives[0].name) : '<init>';
284
+ return `Run \`/tyran\` to resume, or read \`.tyran/state/${where}/STATE.md\` in full.`;
285
+ }
286
+
263
287
  /**
264
288
  * The plugin's own gates, checked at session start — the ONE thing this probe
265
289
  * says even in a repository that has no Tyran state at all.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.35",
3
+ "version": "0.1.36",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -54,6 +54,7 @@ import { append, ASK_KIND_RE, CAPPED_DATA_KEYS, readJournal } from './journal.mj
54
54
  import { formatCodePoint, invisibleProblem } from './invisible.mjs';
55
55
  import { resumeArgv, SESSION_ID_RE } from './overnight.mjs';
56
56
  import { inlinePlain, naturalCompare, projectFile, WAITING_RE, writeAllAtomic, writeAtomic } from './project.mjs';
57
+ import { wantsHelp } from './cli-args.mjs';
57
58
 
58
59
  /** The sheet, and the session record `apply --resume` reads. Both under
59
60
  * `state/`, which is already the AUTO policy class on every install. */
@@ -871,6 +872,10 @@ function doApply(tyranDir, sheetPath, flags) {
871
872
  }
872
873
 
873
874
  function main() {
875
+ if (wantsHelp(process.argv.slice(2))) {
876
+ console.log(USAGE);
877
+ return;
878
+ }
874
879
  let parsed;
875
880
  try {
876
881
  parsed = parseArgs(process.argv.slice(2));
@@ -112,8 +112,34 @@ export function writeServerRecord(dir, record) {
112
112
  }
113
113
  }
114
114
 
115
- export function removeServerRecord(dir) {
115
+ /**
116
+ * Remove the record — but only if it is THIS process's to remove.
117
+ *
118
+ * `owner` is the pid the caller claims. It defaults to this process because
119
+ * the ordinary caller is a server tidying up after itself, and the defect this
120
+ * guards is precisely a caller tidying up after somebody else: `board.mjs`
121
+ * registers its `clear` handler on `process.exit` unconditionally, so a
122
+ * `--serve` that lost the port to EADDRINUSE still ran it on the way out and
123
+ * deleted the record belonging to the healthy board that HELD the port. That
124
+ * board went on serving with no record naming it — invisible to `--status`,
125
+ * unreachable by `--stop`, and stoppable only with `lsof` and a kill. A leaked
126
+ * server is the exact failure this module was written to end, so it may not be
127
+ * reintroduced by the cleanup path.
128
+ *
129
+ * The guard lives here rather than at the call site on purpose. Ownership
130
+ * enforced by whoever remembers to check is caller discipline, which this
131
+ * repository rejects by name in `journal.mjs` and `doctor.mjs`.
132
+ *
133
+ * `owner: null` means "any", and `stopServer` is the one caller that has
134
+ * earned it: it health-probes the port and confirms the board answering there
135
+ * belongs to this directory before it signals or unlinks anything.
136
+ */
137
+ export function removeServerRecord(dir, { owner = process.pid } = {}) {
116
138
  try {
139
+ if (owner !== null) {
140
+ const record = readServerRecord(dir);
141
+ if (record !== null && record.pid !== owner) return false;
142
+ }
117
143
  rmSync(serverRecordPath(dir), { force: true });
118
144
  return true;
119
145
  } catch {
@@ -290,7 +316,20 @@ export async function startDetached(
290
316
  ) {
291
317
  const existing = await findLiveServer(dir, port, { probe });
292
318
  if (existing !== null) {
293
- return { started: false, reused: true, port: existing.port, url: urlFor(existing.port), pid: existing.health.pid ?? null };
319
+ // `write` comes back with the reuse so the caller can tell the operator
320
+ // when the flags on THIS command line did not apply. Start-time flags are
321
+ // silently inert against a server that is already up, and autostart has
322
+ // made "already up" the ordinary case rather than the unlucky one — so the
323
+ // remedy printed on the Spend tab (`--transcripts <dir>`) reported success
324
+ // and changed nothing for anyone whose board was already running.
325
+ return {
326
+ started: false,
327
+ reused: true,
328
+ port: existing.port,
329
+ url: urlFor(existing.port),
330
+ pid: existing.health.pid ?? null,
331
+ write: existing.health.write === true,
332
+ };
294
333
  }
295
334
  const chosen = await pickPort(dir, port, { probe });
296
335
  if (chosen === null) {
@@ -381,7 +420,10 @@ export async function stopServer(dir, { probe = probeHealth, kill = process.kill
381
420
  if (record === null) return { stopped: false, reason: 'no board server is recorded for this directory' };
382
421
  const health = await probe(record.port);
383
422
  if (health === null || !sameDir(health.dir, dir)) {
384
- removeServerRecord(dir);
423
+ // `owner: null` — see removeServerRecord. Clearing a record that names
424
+ // another pid is this function's JOB, and it has proved the right to it:
425
+ // either nothing answers, or what answers is not this directory's board.
426
+ removeServerRecord(dir, { owner: null });
385
427
  return { stopped: false, reason: `nothing is answering on port ${record.port} — cleared the stale record` };
386
428
  }
387
429
  const pid = health.pid ?? record.pid;
@@ -391,7 +433,7 @@ export async function stopServer(dir, { probe = probeHealth, kill = process.kill
391
433
  } catch (err) {
392
434
  return { stopped: false, reason: `could not signal pid ${pid}: ${String(err?.message ?? err)}` };
393
435
  }
394
- removeServerRecord(dir);
436
+ removeServerRecord(dir, { owner: null });
395
437
  return { stopped: true, pid, port: record.port };
396
438
  }
397
439
 
@@ -501,11 +501,21 @@ if (data.schema !== 1) {
501
501
  // Four buckets, not three. The old top bucket was "30 minutes or six
502
502
  // hours", which are not the same event: one is a long test run, the
503
503
  // other is an agent that is not coming back.
504
- var ageMs = ageMsOf(a.last_signal);
505
- var ageText = ageMs === null ? 'no signal recorded'
506
- : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
507
- : Math.round(ageMs / 60000) + ' min since last signal';
504
+ // Measured from SPAWN, and it says so. This line read "N min since last
505
+ // signal" off a field that held spawn time for 72 of 72 agents across
506
+ // 420 journals — a real number under a label describing a different
507
+ // event. The number was worth keeping; the label was not.
508
+ var ageMs = ageMsOf(a.since);
509
+ var ageText = ageMs === null ? 'start time unknown'
510
+ : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since it started — likely dead'
511
+ : Math.round(ageMs / 60000) + ' min since it started';
508
512
  chip.appendChild(el('div', ageClass(ageMs), ageText));
513
+ // Shown only when there IS one. An agent that has signalled is rare
514
+ // enough that it deserves its own line rather than a slot that reads the
515
+ // same whether it spoke or not.
516
+ if (a.last_signal) {
517
+ chip.appendChild(el('div', ageClass(ageMsOf(a.last_signal)), 'said so ' + ago(a.last_signal)));
518
+ }
509
519
  // Signal is what the agent SAID; evidence is what it SHOWED. An agent
510
520
  // emitting progress every few minutes while achieving nothing is the
511
521
  // healthiest-looking chip on the board, and the strip is sorted by the
@@ -1004,7 +1014,7 @@ if (data.schema !== 1) {
1004
1014
  var sp = panels.spend;
1005
1015
  var spBody = el('div');
1006
1016
  sp.appendChild(spBody);
1007
- spBody.appendChild(el('div', 'hint', 'Spend is read from the transcripts Claude Code already writes, and it is served rather than embedded — open this board with "board.mjs --serve" to see it. Over file:// there is no server, so this tab stays empty.'));
1017
+ spBody.appendChild(el('div', 'hint', 'Spend is read from the transcripts Claude Code already writes, and it is served rather than embedded. You are reading the file on disk, so this tab stays empty. Setup starts a dashboard with every session — open the URL it printed, or run "board.mjs --dir .tyran --detach" to start one and print it.'));
1008
1018
 
1009
1019
  // Mirrors compositionLabel in cost.mjs. Restated rather than imported
1010
1020
  // because this file is a browser bundle with no module graph — the two are
@@ -1073,8 +1083,9 @@ if (data.schema !== 1) {
1073
1083
  if (payload && payload.transcripts_found === false) {
1074
1084
  hints.push(
1075
1085
  'No transcripts found for this repo. If the conductor ran from another working directory, ' +
1076
- 'point the board at that session: board.mjs --serve --transcripts <dir> or set ' +
1077
- 'spend.transcript_dirs in .tyran/config.yaml.'
1086
+ 'set spend.transcript_dirs in .tyran/config.yaml \\u2014 that survives a restart and is read ' +
1087
+ 'on the next request. The --transcripts <dir> flag does the same, but only as a server STARTS: ' +
1088
+ 'against a board that is already up it has no effect, so stop that one first.'
1078
1089
  );
1079
1090
  }
1080
1091
  return hints;
@@ -1242,8 +1253,9 @@ if (data.schema !== 1) {
1242
1253
  if ((cov.agent_transcripts || 0) === 0 && agents.length > 0) {
1243
1254
  into.appendChild(el('div', 'hint',
1244
1255
  'No agent transcripts found where this repo\\u2019s transcripts are expected. If the conductor ' +
1245
- 'ran from another working directory, point the board at that session: board.mjs --serve ' +
1246
- '--transcripts <dir> or set spend.transcript_dirs in .tyran/config.yaml.'));
1256
+ 'ran from another working directory, set spend.transcript_dirs in .tyran/config.yaml. The ' +
1257
+ '--transcripts <dir> flag does the same, but only as a server STARTS: against a board that is ' +
1258
+ 'already up it has no effect, so stop that one first.'));
1247
1259
  }
1248
1260
  // cost.transcripts_found is true whenever this function runs at all, so
1249
1261
  // spendResolutionHints only ever contributes the missing-dirs line here
@@ -1351,7 +1363,7 @@ if (data.schema !== 1) {
1351
1363
  var st = panels.settings;
1352
1364
  var stBody = el('div');
1353
1365
  st.appendChild(stBody);
1354
- stBody.appendChild(el('div', 'setnote', 'Settings are read from .tyran/config.yaml and .tyran/policies/autonomy.yaml, and they are served rather than embedded — open this board with "board.mjs --serve" to see them.'));
1366
+ stBody.appendChild(el('div', 'setnote', 'Settings are read from .tyran/config.yaml and .tyran/policies/autonomy.yaml, and they are served rather than embedded. You are reading the file on disk. Setup starts a dashboard with every session — open the URL it printed, or run "board.mjs --dir .tyran --detach" to start one and print it.'));
1355
1367
 
1356
1368
  // Auto-refresh, and the reason it is a timer rather than a meta tag.
1357
1369
  //
package/scripts/board.mjs CHANGED
@@ -55,6 +55,7 @@ import { SettingsError, applyPolicyClass, applySetting, readSettings } from './s
55
55
  import { checkStopAt } from './stop-check.mjs';
56
56
  import { runState } from './overnight.mjs';
57
57
  import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender, sortAsks } from './answer.mjs';
58
+ import { wantsHelp } from './cli-args.mjs';
58
59
  import {
59
60
  HEALTH_ROUTE,
60
61
  PORT_SEARCH_SPAN,
@@ -453,7 +454,8 @@ export function renderCrossMd(payload) {
453
454
  parts.push(
454
455
  `- \`${inline(a.agent)}\` (${inline(a.role)}) — ${inline(a.init)}` +
455
456
  `${a.ticket != null ? ` · \`${inline(a.ticket)}\`` : ''} · ${inline(a.state)}` +
456
- `${a.detail != null ? ` — ${inline(a.detail)}` : ''} · last signal ${inline(a.last_signal)}` +
457
+ `${a.detail != null ? ` — ${inline(a.detail)}` : ''} · started ${inline(a.since)}` +
458
+ `${a.last_signal != null ? ` · last signal ${inline(a.last_signal)}` : ''}` +
457
459
  `${a.next != null ? ` · next: ${inline(a.next)}` : ''}\n`,
458
460
  );
459
461
  }
@@ -697,18 +699,25 @@ function parseArgs(argv) {
697
699
  return flags;
698
700
  }
699
701
 
702
+ export const BOARD_USAGE =
703
+ 'usage: board.mjs [--dir <.tyran>] [--check]\n' +
704
+ ' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
705
+ ' [--status] [--stop]';
706
+
700
707
  function main() {
708
+ // Answered before parsing, because the parser's job is to refuse what it
709
+ // does not know and `--help` is exactly that to every parser here.
710
+ if (wantsHelp(process.argv.slice(2))) {
711
+ console.log(BOARD_USAGE);
712
+ return;
713
+ }
701
714
  let flags;
702
715
  try {
703
716
  flags = parseArgs(process.argv.slice(2));
704
717
  } catch (err) {
705
718
  if (!(err instanceof UsageError)) throw err;
706
719
  console.error(`board: ${err.message}`);
707
- console.error(
708
- 'usage: board.mjs [--dir <.tyran>] [--check]\n' +
709
- ' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
710
- ' [--status] [--stop]'
711
- );
720
+ console.error(BOARD_USAGE);
712
721
  process.exit(2);
713
722
  }
714
723
  // `--detach` is `--serve` that returns. Every flag describing HOW to serve
@@ -805,12 +814,27 @@ function main() {
805
814
  // "Already running" is a SUCCESS, and saying which one it is matters:
806
815
  // this command is meant to be safe to run on every session start, so
807
816
  // its ordinary outcome is that there was nothing to do.
817
+ if (result.reused) {
818
+ console.log(`board: already serving ${result.url} (pid ${result.pid ?? '?'})`);
819
+ // Start-time flags do not reach a server that is already up. Saying
820
+ // so is the whole fix: the command reported success, the operator
821
+ // reloaded the tab, and nothing had changed — with `--transcripts`
822
+ // that is the remedy the Spend tab itself recommends.
823
+ const inert = [];
824
+ if (flags.transcripts.length > 0) inert.push('--transcripts');
825
+ if (flags.write && !result.write) inert.push('--write');
826
+ if (inert.length > 0) {
827
+ console.log(
828
+ `board: ${inert.join(' and ')} had NO effect — that server was started separately. ` +
829
+ `To change how it runs: node scripts/board.mjs --dir ${dir} --stop, then start it again.`,
830
+ );
831
+ }
832
+ return;
833
+ }
808
834
  console.log(
809
- result.reused
810
- ? `board: already serving ${result.url} (pid ${result.pid ?? '?'})`
811
- : `board: serving ${result.url} (pid ${result.pid ?? '?'}; ` +
812
- `${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
813
- `stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
835
+ `board: serving ${result.url} (pid ${result.pid ?? '?'}; ` +
836
+ `${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
837
+ `stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
814
838
  );
815
839
  });
816
840
  return;
@@ -0,0 +1,82 @@
1
+ /**
2
+ * cli-args — the two things every command-line entry point owes its caller:
3
+ * answer `--help`, and refuse a flag it does not understand.
4
+ *
5
+ * Measured across the 14 commands `bin/tyran.mjs` dispatches, on a repo where
6
+ * setup had just run:
7
+ *
8
+ * --help answered as help ............ 0 of 14
9
+ * silently IGNORED an unknown flag ... 4 (tiers, scan-repo, stop-check,
10
+ * desc-budget)
11
+ *
12
+ * The second is the defect; the first is the symptom that found it. Those four
13
+ * parse by scanning for the flags they know (`args.indexOf('--role')`), so a
14
+ * flag they do not know is not rejected — it is never looked at. `tiers --rol
15
+ * reviewer` therefore exits 0 and prints the whole routing table, which is a
16
+ * different answer to a different question, given without a word about the
17
+ * typo. The same line one character later, `tiers --role revieweer`, is
18
+ * refused with the list of valid roles: the VALUE was validated and the flag
19
+ * NAME was not.
20
+ *
21
+ * board.mjs, doctor.mjs, answer.mjs, cost.mjs and migrate.mjs already refuse
22
+ * unknown flags. This module is not a new convention — it is the one already
23
+ * in the majority, made importable so the count of spellings stops going up
24
+ * (ADR-21).
25
+ */
26
+
27
+ /** What a caller types when they want to be told, rather than obeyed. */
28
+ export const HELP_FLAGS = Object.freeze(['--help', '-h', 'help']);
29
+
30
+ export function wantsHelp(args) {
31
+ return args.some((arg) => HELP_FLAGS.includes(arg));
32
+ }
33
+
34
+ /**
35
+ * Every `--flag` in `args` that is not in `known`.
36
+ *
37
+ * Returns the offending tokens rather than throwing, so each caller keeps its
38
+ * own exit code and its own `name: message` prefix — the scripts disagree
39
+ * about those on purpose and this module has no business unifying them.
40
+ *
41
+ * A bare `--` ends flag parsing by convention and is not a flag; anything
42
+ * after it is a positional and is not inspected. Negative numbers (`-3`) are
43
+ * not flags either, which is why only `--` prefixes are considered.
44
+ */
45
+ export function unknownFlags(args, known) {
46
+ const allow = new Set(known.map((k) => (k.startsWith('--') ? k : `--${k}`)));
47
+ const found = [];
48
+ for (const arg of args) {
49
+ if (arg === '--') break;
50
+ if (!arg.startsWith('--')) continue;
51
+ // `--flag=value` is the same flag as `--flag`.
52
+ const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
53
+ if (!allow.has(name)) found.push(name);
54
+ }
55
+ return found;
56
+ }
57
+
58
+ /**
59
+ * The whole contract in one call, for a script whose usage is a plain string.
60
+ *
61
+ * `print`/`fail` are injected so a test can drive this without a process, and
62
+ * `exit` is called rather than returned so a caller cannot forget to stop.
63
+ */
64
+ export function handleArgs(
65
+ args,
66
+ { name, usage, known },
67
+ { print = console.log, fail = console.error, exit = process.exit } = {},
68
+ ) {
69
+ if (wantsHelp(args)) {
70
+ print(usage);
71
+ exit(0);
72
+ return false;
73
+ }
74
+ const bad = unknownFlags(args, known);
75
+ if (bad.length > 0) {
76
+ fail(`${name}: unknown flag ${bad.join(', ')}`);
77
+ fail(usage);
78
+ exit(2);
79
+ return false;
80
+ }
81
+ return true;
82
+ }
package/scripts/cost.mjs CHANGED
@@ -47,6 +47,7 @@ import { parse } from './yaml-lite.mjs';
47
47
  import { pricingOf, PRICING_RATE_KEYS } from './schema.mjs';
48
48
  import { defaultRateCard, RATE_CARD_ID, planOfTier, PLAN_LABELS, SUBSCRIPTION_USD, periodStart } from './pricing.mjs';
49
49
  import { jsonEscapeInvisible } from './invisible.mjs';
50
+ import { wantsHelp } from './cli-args.mjs';
50
51
 
51
52
  export const COST_FILE = 'cost.json';
52
53
 
@@ -1265,16 +1266,26 @@ function parseArgs(argv) {
1265
1266
  return flags;
1266
1267
  }
1267
1268
 
1269
+ export const COST_USAGE =
1270
+ 'usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] ' +
1271
+ '[--transcripts <dir>]... [--window 30d|period|all] [--json]';
1272
+
1268
1273
  function main(argv) {
1274
+ // `argv` reaches here ALREADY sliced — `main(process.argv.slice(2))` at the
1275
+ // bottom of this file — unlike migrate.mjs next door, which is handed the
1276
+ // whole of process.argv. Slicing again here silently dropped the first two
1277
+ // arguments, so `cost --help` fell through to the parser and was reported as
1278
+ // an unknown argument.
1279
+ if (wantsHelp(argv)) {
1280
+ console.log(COST_USAGE);
1281
+ return 0;
1282
+ }
1269
1283
  let flags;
1270
1284
  try {
1271
1285
  flags = parseArgs(argv);
1272
1286
  } catch (err) {
1273
1287
  console.error(String(err.message ?? err));
1274
- console.error(
1275
- 'usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] ' +
1276
- '[--transcripts <dir>]... [--window 30d|period|all] [--json]'
1277
- );
1288
+ console.error(COST_USAGE);
1278
1289
  return 2;
1279
1290
  }
1280
1291
  const tyranDir = resolve(flags.dir);
@@ -14,6 +14,7 @@ import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'n
14
14
  import { escapeInvisible } from './invisible.mjs';
15
15
  import { join, dirname, resolve } from 'node:path';
16
16
  import { fileURLToPath } from 'node:url';
17
+ import { handleArgs } from './cli-args.mjs';
17
18
 
18
19
  /**
19
20
  * The ceiling, and the ONLY place it is written.
@@ -68,8 +69,13 @@ export function collectSkillDescriptions(pluginRoot) {
68
69
  return out.sort((a, b) => b.length - a.length);
69
70
  }
70
71
 
72
+ export const DESC_BUDGET_USAGE =
73
+ 'usage: desc-budget.mjs [--budget <chars>] [pluginRoot]\n' +
74
+ 'Exit: 0 within budget · 1 over budget · 2 usage/IO error';
75
+
71
76
  function main() {
72
77
  const args = process.argv.slice(2);
78
+ if (!handleArgs(args, { name: 'desc-budget', usage: DESC_BUDGET_USAGE, known: ['budget'] })) return;
73
79
  let budget = DEFAULT_BUDGET;
74
80
  const bi = args.indexOf('--budget');
75
81
  if (bi !== -1) {
@@ -67,6 +67,7 @@ import { readPlatformUsage } from './usage-source.mjs';
67
67
  import { gitRunner } from './scan-repo.mjs';
68
68
  import { SERVER_RECORD_FILE } from './board-daemon.mjs';
69
69
  import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
70
+ import { wantsHelp } from './cli-args.mjs';
70
71
 
71
72
  /** Severity order is also the report order. `info` never fails the check. */
72
73
  export const SEVERITIES = Object.freeze(['error', 'warning', 'info']);
@@ -2099,7 +2100,21 @@ export function parseArgs(argv) {
2099
2100
  };
2100
2101
  }
2101
2102
 
2103
+ export const DOCTOR_USAGE =
2104
+ 'usage: doctor.mjs --state [--dir <.tyran>] [--json] [--now <iso>] [--stale-hours <n>]\n' +
2105
+ ' doctor.mjs --hooks [--plugin-root <dir>] [--json]\n' +
2106
+ '\n' +
2107
+ ' A mode is REQUIRED: `--state` asks whether the record of the work is\n' +
2108
+ ' consistent, `--hooks` whether the gates can fire at all. They answer\n' +
2109
+ ' different questions, and a bare invocation would have to pick one\n' +
2110
+ ' silently. This text said `--state is the only mode today` long after\n' +
2111
+ ' `--hooks` shipped, which sent readers looking for a flag they had.';
2112
+
2102
2113
  function main() {
2114
+ if (wantsHelp(process.argv.slice(2))) {
2115
+ console.log(DOCTOR_USAGE);
2116
+ return;
2117
+ }
2103
2118
  try {
2104
2119
  const args = parseArgs(process.argv.slice(2));
2105
2120
  const { dir, json, now, staleHours, dirGiven } = args;
@@ -2126,16 +2141,7 @@ function main() {
2126
2141
  if (!allOk) process.exit(1);
2127
2142
  } catch (err) {
2128
2143
  if (err instanceof UsageError) {
2129
- console.error(
2130
- 'usage: doctor.mjs --state [--dir <.tyran>] [--json] [--now <iso>] [--stale-hours <n>]\n' +
2131
- ' doctor.mjs --hooks [--plugin-root <dir>] [--json]\n' +
2132
- '\n' +
2133
- ' A mode is REQUIRED: `--state` asks whether the record of the work is\n' +
2134
- ' consistent, `--hooks` whether the gates can fire at all. They answer\n' +
2135
- ' different questions, and a bare invocation would have to pick one\n' +
2136
- ' silently. This text said `--state is the only mode today` long after\n' +
2137
- ' `--hooks` shipped, which sent readers looking for a flag they had.',
2138
- );
2144
+ console.error(DOCTOR_USAGE);
2139
2145
  process.exit(2);
2140
2146
  }
2141
2147
  console.error(`doctor: ${err.message}`);
@@ -41,6 +41,7 @@ import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } f
41
41
  import { join, resolve } from 'node:path';
42
42
 
43
43
  import { escapeInvisible } from './invisible.mjs';
44
+ import { wantsHelp } from './cli-args.mjs';
44
45
 
45
46
  /** The pre-0.1.9 home of the initiative directories. */
46
47
  export const LEGACY_DIR = 'initiatives';
@@ -154,6 +155,10 @@ function usage(message) {
154
155
 
155
156
  function main(argv) {
156
157
  const args = argv.slice(2);
158
+ if (wantsHelp(args)) {
159
+ console.log('usage: node scripts/migrate.mjs [--dir <.tyran>] [--apply]');
160
+ return;
161
+ }
157
162
  for (const arg of args) {
158
163
  if (!['--dir', '--apply'].includes(arg) && arg.startsWith('--')) usage(`unknown flag ${arg}`);
159
164
  }
@@ -978,7 +978,22 @@ export function boardOf(state, { staleHours = DEFAULT_STALE_HOURS } = {}) {
978
978
  open_hours: ageHours === null ? null : Math.round(ageHours * 10) / 10,
979
979
  detail: signal?.detail ?? null,
980
980
  next: signal?.next ?? null,
981
- last_signal: signal?.ts ?? a.spawnTs,
981
+ // NULL when the agent has never signalled, and it almost never has.
982
+ //
983
+ // This used to fall back to `a.spawnTs`, which made every consumer
984
+ // print spawn time under a label that says "when it last spoke".
985
+ // Measured over 420 real journals: 72 running agents on boards, and
986
+ // `last_signal === since` for 72 of 72. Not once a signal. `detail`,
987
+ // `next` and `state: 'blocked'` were zero across the same set, because
988
+ // all four come from a `progress` event that fires once in 388
989
+ // journals against an instruction asking for four per story.
990
+ //
991
+ // The fallback made that invisible: the board looked like it was
992
+ // reporting agent chatter and was reporting process ages. A wrong
993
+ // number reads as a measurement, which is worse than a blank — so the
994
+ // blank is the honest value, and `since` (right below) is where spawn
995
+ // time has always actually lived.
996
+ last_signal: signal?.ts ?? null,
982
997
  // What it has SHOWN. Null until it shows something, which is the
983
998
  // ordinary state of an agent that has just started — the strip says
984
999
  // "nothing yet" rather than implying silence.
@@ -1029,13 +1044,17 @@ export function renderBoard(state, board = boardOf(state)) {
1029
1044
  parts.push('\n## Agents\n\n');
1030
1045
  parts.push(
1031
1046
  table(
1032
- ['Agent', 'Role', 'Ticket', 'State', 'Detail', 'Last signal'],
1047
+ // "Started" is the column that always has a value; "Last signal" is the
1048
+ // one that almost never does, and printing spawn time in it made the
1049
+ // table look fuller than the journal was.
1050
+ ['Agent', 'Role', 'Ticket', 'State', 'Detail', 'Started', 'Last signal'],
1033
1051
  sortByKey(board.agents, (a) => a.agent).map((a) => [
1034
1052
  inline(a.agent),
1035
1053
  inline(a.role),
1036
1054
  inline(a.ticket),
1037
1055
  inline(a.state),
1038
1056
  inline(a.detail),
1057
+ inline(a.since),
1039
1058
  inline(a.last_signal),
1040
1059
  ]),
1041
1060
  ),
@@ -35,6 +35,7 @@ import { fileURLToPath } from 'node:url';
35
35
  import { parse, stringify } from './yaml-lite.mjs';
36
36
  import { validatePolicy } from './schema.mjs';
37
37
  import { escapeInvisible } from './invisible.mjs';
38
+ import { handleArgs } from './cli-args.mjs';
38
39
 
39
40
  /** Lockfile -> package manager. Order matters only for reporting stability. */
40
41
  export const LOCKFILES = Object.freeze({
@@ -820,8 +821,18 @@ export function ensureStateGitignore(repoRoot) {
820
821
  return { path, status: 'created' };
821
822
  }
822
823
 
824
+ export const SCAN_REPO_USAGE =
825
+ 'usage: scan-repo.mjs [--dir <repo-root>] [--write <.tyran/config.yaml>]\n' +
826
+ ' [--ensure-policy]\n' +
827
+ 'With no --write, prints the scan as JSON and changes nothing.\n' +
828
+ '--write also installs .tyran/policies/autonomy.yaml first, create-only.\n' +
829
+ '--ensure-policy is the repair path: seed the policy and do nothing else.';
830
+
823
831
  function main() {
824
832
  const args = process.argv.slice(2);
833
+ // `--wrte .tyran/config.yaml` used to scan, print JSON and exit 0 — a typo
834
+ // in the one flag that decides whether this command WRITES, swallowed.
835
+ if (!handleArgs(args, { name: 'scan-repo', usage: SCAN_REPO_USAGE, known: ['dir', 'write', 'ensure-policy'] })) return;
825
836
  const flag = (name, fallback) => {
826
837
  const i = args.indexOf(`--${name}`);
827
838
  return i === -1 ? fallback : args[i + 1];
@@ -26,6 +26,7 @@ import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
26
26
  import { join, resolve } from 'node:path';
27
27
  import { fileURLToPath } from 'node:url';
28
28
  import { escapeInvisible } from './invisible.mjs';
29
+ import { handleArgs } from './cli-args.mjs';
29
30
 
30
31
  export const STOP_PATH = join('.tyran', 'STOP');
31
32
 
@@ -66,8 +67,13 @@ export function checkStopAt(path) {
66
67
  }
67
68
  }
68
69
 
70
+ export const STOP_CHECK_USAGE =
71
+ 'usage: stop-check.mjs [--dir <repo-root>]\n' +
72
+ 'Exit: 0 clear · 1 stopped by .tyran/STOP · 2 usage';
73
+
69
74
  function main() {
70
75
  const args = process.argv.slice(2);
76
+ if (!handleArgs(args, { name: 'stop-check', usage: STOP_CHECK_USAGE, known: ['dir'] })) return;
71
77
  const di = args.indexOf('--dir');
72
78
  const dir = resolve(di === -1 ? process.cwd() : (args[di + 1] ?? process.cwd()));
73
79
 
package/scripts/tiers.mjs CHANGED
@@ -38,6 +38,7 @@ import { validateConfig, PROFILES, TIER_KEYS } from './schema.mjs';
38
38
  import { escapeInvisible } from './invisible.mjs';
39
39
  import { APPROVING_RE } from './project.mjs';
40
40
  import { readJournal } from './journal.mjs';
41
+ import { handleArgs } from './cli-args.mjs';
41
42
 
42
43
  /** Capability tiers, cheapest first. Index order is the escalation ladder. */
43
44
  export const TIER_ORDER = TIER_KEYS;
@@ -412,8 +413,28 @@ export function readProfile(doc) {
412
413
  return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.value : raw;
413
414
  }
414
415
 
416
+ /**
417
+ * Every flag `main` reads. It is a LIST rather than a comment because the
418
+ * parser below cannot derive it: `flag()` looks up the names it wants, so a
419
+ * name it does not want is not rejected, it is unseen. `--rol reviewer` used
420
+ * to print the entire routing table and exit 0 — a different answer to a
421
+ * different question, with nothing said about the typo — while `--role
422
+ * revieweer` one character later was refused by name. The value was checked
423
+ * and the flag was not.
424
+ */
425
+ export const TIERS_FLAGS = Object.freeze([
426
+ 'config', 'profile', 'risk', 'role', 'field', 'tier', 'effort', 'unavailable', 'journal', 'ticket',
427
+ ]);
428
+
429
+ export const TIERS_USAGE =
430
+ 'usage: tiers.mjs [--config <config.yaml>] [--profile <p>] [--risk <normal|high>]\n' +
431
+ ' [--role <role>] [--field <model|effort|tier>] [--tier <t>] [--effort <e>]\n' +
432
+ ' [--unavailable <model>]... [--journal <path> --ticket <T-n>]\n' +
433
+ 'With no --role, prints the whole resolved routing table as JSON.';
434
+
415
435
  function main() {
416
436
  const args = process.argv.slice(2);
437
+ if (!handleArgs(args, { name: 'tiers', usage: TIERS_USAGE, known: TIERS_FLAGS })) return;
417
438
  const flag = (name, fallback) => {
418
439
  const i = args.indexOf(`--${name}`);
419
440
  return i === -1 ? fallback : args[i + 1];
@@ -80,6 +80,16 @@ English regardless.
80
80
  - **dry-run every automaton** for one no-op iteration before you trust it
81
81
  with unattended work. Trust dialogs and missing dependencies surface
82
82
  then, not at 3am.
83
+ - **exercise cloud access, never infer it.** A profile in `~/.aws/config`, a
84
+ key in the environment and a role named in a template are three claims
85
+ that the call you actually need will succeed — none of them is the call.
86
+ Make one cheap read-only request per service the plan names, starting with
87
+ an identity check (`aws sts get-caller-identity` and its equivalents) and
88
+ then a `list`/`describe` on the one resource you will touch, and record
89
+ the account, region and profile as a `decision`. This is the teammate
90
+ probe two bullets up, one layer out: availability that was inferred rather
91
+ than exercised has already been wrong here, and the cloud version of that
92
+ mistake surfaces at deploy time — after the work, in front of the operator.
83
93
  5. **Project configuration — detect it yourself.**
84
94
  - If `.tyran/config.yaml` exists, read it and treat it as binding.
85
95
  - Otherwise send `tyran:scout` to establish: (a) the **stack** — languages,
@@ -295,6 +305,16 @@ open one.
295
305
  your scope without the domain owner's consent — proposals go to `NOTES.md`.
296
306
  Secrets never enter the repo. Production data only through the accounts the
297
307
  configuration names.
308
+ - **The gate below is a way in, so it has its own rule.** `journal.mjs ask`
309
+ writes the question into the journal, and `answer.mjs apply` folds the
310
+ operator's reply back as a `decision` — both in a file you commit. **Never
311
+ ask for a credential's VALUE. Ask where it lives**: the SSM parameter
312
+ NAME, the secrets-manager key, the vault path — something whose disclosure
313
+ costs nothing and which the machine doing the work can already resolve.
314
+ *"Which SSM parameter holds the staging database password?"* is a question
315
+ whose answer is safe in a committed file. *"What is the staging database
316
+ password?"* is a leak with a ticket number on it, and the operator who
317
+ pasted it now has a credential to rotate.
298
318
  6. **Gates are the only stops:** plan acceptance (L) or concept acceptance
299
319
  (XL); product, visual and irreversible decisions, put in plain language
300
320
  with your recommendation; anything hard to undo or visible outside the