@jjanczur/tyran 0.1.4 → 0.1.5

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.4",
14
+ "version": "0.1.5",
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.4",
3
+ "version": "0.1.5",
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",
@@ -9,7 +9,6 @@
9
9
  "homepage": "https://github.com/jjanczur/tyran#readme",
10
10
  "repository": "https://github.com/jjanczur/tyran",
11
11
  "license": "Apache-2.0",
12
- "hooks": "./hooks/hooks.json",
13
12
  "keywords": [
14
13
  "orchestration",
15
14
  "multi-agent",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,54 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.5 — 2026-08-03
4
+
5
+ ### The plugin loads again (0.1.4 did not)
6
+
7
+ On Claude Code 2.1.197 the plugin failed to load outright — `Duplicate hooks
8
+ file detected: ./hooks/hooks.json` — because the manifest declared
9
+ `"hooks": "./hooks/hooks.json"` while the harness now auto-loads that standard
10
+ path, and the duplicate is fatal. With the hooks unloaded there was no gate at
11
+ all: an out-of-repo write the gate exists to refuse went straight through.
12
+ Every other plugin ships `hooks/hooks.json` with no manifest reference — the
13
+ key is removed. The standard location is auto-discovered on every recent
14
+ version, so this is also cross-version safe.
15
+
16
+ ### The main thread may write its own working files
17
+
18
+ The gate refuses writes outside the repository as KERNEL — correct for a
19
+ fanned-out subagent, wrong for Claude Code's own bookkeeping. Adopting Tyran
20
+ made the harness unable to write to its memory store or plan files: "outside
21
+ this repository". (0.1.4 shipped the memory half of this fix but never loaded,
22
+ so users meet it here first.)
23
+
24
+ The **main thread** — never a subagent — may now write three built-in
25
+ out-of-repo locations: the memory store (`<config>/projects/<slug>/memory/`),
26
+ the plans directory (`<config>/plans/`), and the per-session scratchpad
27
+ (`<tmp>/claude-*/`). For anything else, `.tyran/config.yaml` gains an optional
28
+ **`main_writable_paths`** list (globs, `~` expanded) the operator opts into.
29
+ Both are actor-scoped: a subagent still falls through to KERNEL, so a parallel
30
+ run stays contained. Everything else outside the repo is still refused.
31
+
32
+ ### Retrospectives applied
33
+
34
+ Four field reports across two initiatives, folded into the conductor and its
35
+ tools:
36
+
37
+ - **`scan-repo`** now recognises `format:check` as a validation command — the
38
+ CHECK name only, because a bare `format` rewrites the working tree. A repo
39
+ that ran it in CI but was missing it from this list shipped two unformatted
40
+ files to main.
41
+ - **`run` rule 7** — worktrees must live OUTSIDE the directories Tyran governs
42
+ (`.claude/`, `.tyran/`). One placed inside has every file, `src/**` included,
43
+ fall through to `default: GATED`, and a subagent cannot edit anything.
44
+ - **`run` rule 2 (evidence contract)** — measure a fix in the EXECUTION MODE
45
+ the defect appeared in (a `next dev` pass was inert under `next start`), and a
46
+ guard or regression test is proven only by a run in which it FAILS without the
47
+ change: one that matches nothing passes exactly like one that works.
48
+ - **`deslop`** — "started with" is the state immediately before THIS pass, not
49
+ the branch point; make the count recomputable by committing the story's work
50
+ and the pass separately.
51
+
3
52
  ## 0.1.4 — 2026-08-01
4
53
 
5
54
  ### The gate stopped refusing Claude Code's own memory
@@ -533,6 +533,45 @@ export async function loadDeployClass(root) {
533
533
  return value;
534
534
  }
535
535
 
536
+ /**
537
+ * A leading `~` expanded to the home directory; everything else untouched so
538
+ * the `*`/`**` in a glob survive (`resolve` would collapse a trailing `**`).
539
+ */
540
+ function expandHome(p) {
541
+ if (p === '~') return homedir();
542
+ if (p.startsWith('~/')) return join(homedir(), p.slice(2));
543
+ return p;
544
+ }
545
+
546
+ /**
547
+ * The out-of-repo paths config.yaml lets the MAIN thread write, home-expanded.
548
+ * Optional: absence is [], never a refusal. A config too broken to parse yields
549
+ * [] rather than throwing, so the write stays refused — fail closed. This only
550
+ * lists paths; the actor split (main-thread only) is enforced at the call site,
551
+ * so it can never widen what a subagent may do.
552
+ */
553
+ export async function loadMainWritablePaths(root) {
554
+ let text = null;
555
+ for (const candidate of [root, mainWorktreeOf(root)].filter((r) => r !== null)) {
556
+ text = await readBounded(join(candidate, CONFIG_PATH), 'the Tyran config');
557
+ if (text !== null) break;
558
+ }
559
+ if (text === null) return [];
560
+ let doc;
561
+ try {
562
+ doc = parse(text);
563
+ } catch {
564
+ return [];
565
+ }
566
+ const raw = doc !== null && typeof doc === 'object' ? doc.main_writable_paths : undefined;
567
+ if (!Array.isArray(raw)) return [];
568
+ const out = [];
569
+ for (const entry of raw) {
570
+ if (typeof entry === 'string' && entry.trim() !== '') out.push(expandHome(entry.trim()));
571
+ }
572
+ return out;
573
+ }
574
+
536
575
  // ------------------------------------------------------ quoting the decision
537
576
 
538
577
  /**
@@ -739,9 +778,13 @@ export function harnessWritable(rawPath, env = process.env) {
739
778
  ? env.CLAUDE_CONFIG_DIR
740
779
  : join(homedir(), '.claude');
741
780
  const underConfig = segmentsUnder(canon, configDir);
742
- // The memory store's exact shape: <config>/projects/<slug>/memory/**.
743
- if (underConfig !== null && underConfig[0] === 'projects' && underConfig[2] === 'memory') {
744
- return true;
781
+ if (underConfig !== null) {
782
+ // The memory store's exact shape: <config>/projects/<slug>/memory/**.
783
+ if (underConfig[0] === 'projects' && underConfig[2] === 'memory') return true;
784
+ // The plans directory: <config>/plans/** — where the main thread writes the
785
+ // plan files a user reads between sessions. A popular out-of-repo path, so
786
+ // it is exempt by default rather than requiring per-repo config.
787
+ if (underConfig[0] === 'plans') return true;
745
788
  }
746
789
  // The scratchpad: <tmp>/claude-*/**, under whichever temp root the platform
747
790
  // used. `/tmp` is included explicitly because `os.tmpdir()` is `/var/...` on
@@ -1062,6 +1105,11 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
1062
1105
  return PASS;
1063
1106
  }
1064
1107
 
1108
+ // Config-declared out-of-repo allowances for the main thread
1109
+ // (`.tyran/config.yaml` `main_writable_paths`), loaded lazily and once: only
1110
+ // an out-of-repo main-thread write ever consults them.
1111
+ let mainWritable;
1112
+
1065
1113
  for (const target of targets) {
1066
1114
  // Normalized HERE, with the root this call is about, and only then handed
1067
1115
  // to the resolver. `classifyPath` normalizes internally too, but against
@@ -1071,13 +1119,20 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
1071
1119
  // and the two would agree in every test that happened to run in the repo
1072
1120
  // root. Normalization is idempotent, so the resolver's own call is a no-op.
1073
1121
  const normalized = repoRelative(target, root);
1074
- // Claude Code's own memory store and per-session scratchpad are outside
1075
- // every repository, so `normalized` is null and the matrix below answers
1076
- // KERNEL — which made adopting Tyran refuse the harness's own memory
1077
- // writes. `harnessWritable` exempts exactly those two locations, and only
1078
- // for the main thread; a subagent still falls through to KERNEL. See its
1079
- // definition for the full argument.
1080
- if (normalized === null && actor === 'main' && harnessWritable(target, env)) continue;
1122
+ // Claude Code's own memory store, plans dir and scratchpad are outside every
1123
+ // repository, so `normalized` is null and the matrix below answers KERNEL —
1124
+ // which made adopting Tyran refuse the harness's own writes. `harnessWritable`
1125
+ // exempts those built-in locations; `main_writable_paths` in config.yaml adds
1126
+ // operator-chosen ones. Both are MAIN-thread only: a subagent still falls
1127
+ // through to KERNEL.
1128
+ if (normalized === null && actor === 'main') {
1129
+ if (harnessWritable(target, env)) continue;
1130
+ if (mainWritable === undefined) mainWritable = await loadMainWritablePaths(root);
1131
+ if (mainWritable.length > 0) {
1132
+ const canon = canonicalDeepest(target);
1133
+ if (mainWritable.some((glob) => globMatches(glob, canon) || globMatches(glob, target))) continue;
1134
+ }
1135
+ }
1081
1136
  // The one branch this cannot delegate: a path outside the repository makes
1082
1137
  // `normalizePath` return null, which `classifyPath` answers with KERNEL.
1083
1138
  // Restated in one line rather than reached by passing a null through, and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
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": {
@@ -325,6 +325,7 @@ export const HOOK_SEVERITY_BY_CODE = Object.freeze(
325
325
  'hooks-manifest-missing': 'error',
326
326
  'hooks-manifest-unreadable': 'error',
327
327
  'hooks-manifest-no-hooks': 'error',
328
+ 'hooks-manifest-duplicates-standard': 'error',
328
329
  'hooks-file-missing': 'error',
329
330
  'hooks-file-unreadable': 'error',
330
331
  'hooks-file-invalid': 'error',
@@ -1043,23 +1044,53 @@ export function checkHooks({ root = DEFAULT_PLUGIN_ROOT, env = process.env } = {
1043
1044
  );
1044
1045
  return summarize(pluginRoot, findings, checked);
1045
1046
  }
1047
+ // Claude Code auto-loads the standard hooks/hooks.json at the plugin root, so
1048
+ // manifest.hooks is for ADDITIONAL hook files only. Declaring the standard
1049
+ // path there too is a duplicate the harness rejects — measured on 2.1.197,
1050
+ // "Duplicate hooks file detected" — and the plugin then fails to load and
1051
+ // gates NOTHING. This inverts the old check: a missing field is healthy when
1052
+ // the standard file exists, and a field naming the standard file is the error.
1053
+ const standardHooksPath = resolve(pluginRoot, 'hooks', 'hooks.json');
1046
1054
  const declaredHooks = typeof manifest?.hooks === 'string' ? manifest.hooks : null;
1047
- if (declaredHooks === null) {
1055
+ const declaredIsStandard = declaredHooks !== null && resolve(pluginRoot, declaredHooks) === standardHooksPath;
1056
+
1057
+ if (declaredIsStandard) {
1058
+ findings.push(
1059
+ finding(
1060
+ 'hooks-manifest-duplicates-standard',
1061
+ q(manifestPath),
1062
+ `the manifest declares "hooks": ${q(declaredHooks)}, but Claude Code auto-loads the standard ` +
1063
+ 'hooks/hooks.json at the plugin root. Declaring it again is a duplicate the harness rejects, so ' +
1064
+ 'the plugin fails to load and gates NOTHING. manifest.hooks is for ADDITIONAL hook files only.',
1065
+ `remove the "hooks" key from ${q(manifestPath)} — the standard file is auto-loaded`,
1066
+ ),
1067
+ );
1068
+ return summarize(pluginRoot, findings, checked);
1069
+ }
1070
+
1071
+ if (declaredHooks === null && !existsSync(standardHooksPath)) {
1048
1072
  findings.push(
1049
1073
  finding(
1050
1074
  'hooks-manifest-no-hooks',
1051
1075
  q(manifestPath),
1052
- 'the manifest declares no "hooks" file. Every gate in this repository is registered through it, ' +
1053
- 'so without the field the plugin installs cleanly and gates nothing.',
1054
- `add "hooks": "./hooks/hooks.json" to ${q(manifestPath)}`,
1076
+ 'no hooks file: the manifest declares none and there is no hooks/hooks.json at the plugin root, ' +
1077
+ 'so nothing registers a gate at all.',
1078
+ `create ${q(standardHooksPath)} — it is auto-loaded — or point "hooks" at an additional file`,
1055
1079
  ),
1056
1080
  );
1057
1081
  return summarize(pluginRoot, findings, checked);
1058
1082
  }
1059
- checked.push(`manifest: name "${readPluginName(pluginRoot) ?? '(unnamed)'}", hooks -> ${declaredHooks}`);
1083
+
1084
+ // The file the platform loads: the additional file if the manifest names one,
1085
+ // otherwise the auto-loaded standard file.
1086
+ const hooksRel = declaredHooks ?? './hooks/hooks.json';
1087
+ checked.push(
1088
+ `manifest: name "${readPluginName(pluginRoot) ?? '(unnamed)'}", hooks -> ${hooksRel}` +
1089
+ (declaredHooks === null ? ' (auto-loaded)' : ''),
1090
+ );
1060
1091
 
1061
1092
  // ---- the hooks file ----------------------------------------------------
1062
- const hooksPath = resolve(pluginRoot, declaredHooks);
1093
+ const hooksPath = resolve(pluginRoot, hooksRel);
1063
1094
  let doc;
1064
1095
  try {
1065
1096
  doc = JSON.parse(readFileSync(hooksPath, 'utf8'));
@@ -69,11 +69,18 @@ export const LANGUAGES = Object.freeze({
69
69
  });
70
70
 
71
71
  /**
72
- * Script names worth running before calling something done, most valuable
73
- * first. `build` is deliberately absent: it is slow, and on most repos the
74
- * type check already covers what a build would catch.
72
+ * Script names worth running before calling something done. `build` is
73
+ * deliberately absent: it is slow, and on most repos the type check already
74
+ * covers what a build would catch.
75
+ *
76
+ * `format:check` leads because it is the cheapest and fails fastest, and it is
77
+ * here at all because omitting it ships a red main. Measured: a repo declared
78
+ * `format:check` in package.json AND ran it in CI, this list did not include
79
+ * it, so no handoff required it — two unformatted files reached main and
80
+ * needed a repair commit. Only the CHECKING name is listed: a bare `format`
81
+ * REWRITES the working tree, which is not a validation command.
75
82
  */
76
- export const VALIDATION_SCRIPTS = Object.freeze(['lint', 'typecheck', 'types', 'test']);
83
+ export const VALIDATION_SCRIPTS = Object.freeze(['format:check', 'lint', 'typecheck', 'types', 'test']);
77
84
 
78
85
  const RUN_PREFIX = Object.freeze({ npm: 'npm run', pnpm: 'pnpm', yarn: 'yarn', bun: 'bun run' });
79
86
 
@@ -68,7 +68,7 @@ export function validateConfig(doc) {
68
68
  const errors = [];
69
69
  if (!isPlainObject(doc)) return ['config must be a mapping'];
70
70
 
71
- const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget'];
71
+ const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths'];
72
72
  for (const key of Object.keys(doc)) {
73
73
  if (!known.includes(key)) errors.push(`${key}: unknown top-level key`);
74
74
  }
@@ -131,6 +131,20 @@ export function validateConfig(doc) {
131
131
  }
132
132
  }
133
133
 
134
+ // Out-of-repo paths the MAIN thread may write, on top of the built-in memory
135
+ // store, plans dir and scratchpad. A `~` is expanded to the home directory;
136
+ // globs are the same `*`/`**` the policy uses. Never widens what a SUBAGENT
137
+ // may do — the gate enforces the actor split, this only lists paths.
138
+ if ('main_writable_paths' in doc) {
139
+ if (!Array.isArray(doc.main_writable_paths)) {
140
+ errors.push('main_writable_paths: must be a list of path globs');
141
+ } else {
142
+ doc.main_writable_paths.forEach((p, i) => {
143
+ if (!isNonEmptyString(p)) errors.push(`main_writable_paths[${i}]: must be a non-empty path glob`);
144
+ });
145
+ }
146
+ }
147
+
134
148
  return errors;
135
149
  }
136
150
 
@@ -9,8 +9,15 @@ description: The optimization pass, defined - delete before you add, one smell c
9
9
 
10
10
  **The default action is deletion.** A pass that ends with more lines than it
11
11
  started with was a refactor, and a refactor is a different piece of work with a
12
- different risk profile. If you cannot delete anything, say so and stop — that is
13
- a complete and respectable outcome.
12
+ different risk profile. **"Started with" means the state immediately before
13
+ THIS pass, not the branch point** — a story that adds a feature adds lines, and
14
+ judging the pass by the whole branch diff condemns it in advance. That number
15
+ is then invisible to everyone but you, so make it recomputable: commit the
16
+ story's work, then commit the pass separately. Measured: an author counting
17
+ honestly from its own uncommitted draft and a reviewer counting from the branch
18
+ point produced a blocking CHANGES-REQUESTED and an arbitration, with neither
19
+ agent wrong on its own terms. If you cannot delete anything, say so and stop —
20
+ that is a complete and respectable outcome.
14
21
 
15
22
  ## The order, and why it is an order
16
23
 
@@ -92,6 +99,7 @@ For a README, a report, an error message or a commit body:
92
99
  ## The report
93
100
 
94
101
  Files touched, what class of slop came out of each, the test output from before
95
- and after, and one line on what you deliberately left. The last part matters: a
102
+ and after, the two line counts with the commit range a reviewer can recompute
103
+ them from, and one line on what you deliberately left. The last part matters: a
96
104
  cleanup that silently declined to touch the worst file in the area looks
97
105
  identical to one that found nothing there.
@@ -163,7 +163,13 @@ open one.
163
163
  rather than asserting it — take that baseline after a `git fetch` run
164
164
  immediately beforehand, because a stale `origin/main` once turned a
165
165
  methodologically correct proof into a false accusation of someone else's
166
- regression; (6) "verify the premises of this handoff in the code — and
166
+ regression. And measure the fix in the EXECUTION MODE the defect was
167
+ observed in — a dev server is not a production build: a 404 fix green under
168
+ `next dev` was inert under `next start`, caught by the reviewer's production
169
+ builds one merge short of shipping. A guard or regression test is proven
170
+ only by a run in which it FAILS without the change — one that matches nothing
171
+ passes exactly like one that works (measured twice); (6) "verify the
172
+ premises of this handoff in the code — and
167
173
  premises about DATA by measuring the real thing read-only: a field being in
168
174
  the schema is not the same as the field being in the data. Correct a wrong
169
175
  premise and report the correction EXPLICITLY"; (7) when to escalate.
@@ -258,6 +264,15 @@ open one.
258
264
  create** and, if `.tyran/` is missing, get it committed on the main
259
265
  checkout first rather than copying it in — a copy makes four divergent
260
266
  configs, which is the same defect one layer down.
267
+ **And place them OUTSIDE the directories Tyran governs.** A worktree under
268
+ `.claude/` or `.tyran/` fails the opposite way: every file in it, `src/**`
269
+ included, repo-relativizes into Tyran's own artefact namespace, matches no
270
+ rule written for product code, and falls through to the policy's
271
+ `default: GATED` — which denies a subagent unconditionally. The implementer
272
+ cannot edit anything and has no legitimate route through. Measured: two
273
+ implementers restarted and one fix delivered as a hand-applied diff.
274
+ Siblings of the checkout (`../<repo>-<slug>`) sidestep it, whatever
275
+ convention the repo already had.
261
276
  - **Leases are files.** Every worktree and every heavy slot has
262
277
  `.tyran/initiatives/<slug>/locks/<resource>.lease` holding holder,
263
278
  purpose, story and expiry. A handoff BEGINS by taking the lease — an