@orkestrel/scaffold 0.0.108 → 0.0.110

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.
Files changed (162) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +326 -91
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +110 -14
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +280 -0
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +188 -26
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +142 -43
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +240 -62
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +323 -0
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +169 -32
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +290 -69
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +560 -0
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +1052 -205
  12. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +361 -0
  13. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +455 -80
  14. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +327 -0
  15. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +298 -51
  16. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +170 -13
  17. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +956 -191
  18. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +707 -112
  19. package/dist/agents/skills/orkestrel-publish/scripts/window.js +235 -41
  20. package/dist/agents/skills/orkestrel-scout/scripts/map.js +341 -54
  21. package/dist/agents/templates/brief.md +6 -2
  22. package/dist/bin/main.js +51 -46
  23. package/dist/bin/main.js.map +1 -1
  24. package/dist/host/AGENTS.md +23 -21
  25. package/dist/host/agents/orchestration.md +85 -54
  26. package/dist/host/agents/platforms/windows.md +8 -3
  27. package/dist/host/agents/skills/orkestrel-align/SKILL.md +10 -13
  28. package/dist/host/agents/skills/orkestrel-align/references/fleet.md +4 -10
  29. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  30. package/dist/host/agents/skills/orkestrel-build/SKILL.md +16 -48
  31. package/dist/host/agents/skills/orkestrel-build/agents/openai.yaml +1 -1
  32. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +19 -16
  33. package/dist/host/agents/skills/orkestrel-debrief/agents/openai.yaml +1 -1
  34. package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +15 -28
  35. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +5 -6
  36. package/dist/host/agents/skills/orkestrel-debrief/references/retention.md +4 -6
  37. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +36 -25
  38. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +4 -5
  39. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +366 -75
  40. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +126 -16
  41. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +323 -0
  42. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +220 -31
  43. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +176 -33
  44. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +294 -59
  45. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +401 -0
  46. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +199 -34
  47. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +330 -69
  48. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +14 -12
  49. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -5
  50. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -1
  51. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +701 -0
  52. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +31 -24
  53. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +23 -81
  54. package/dist/host/agents/skills/orkestrel-harden/references/centralization.md +4 -5
  55. package/dist/host/agents/skills/orkestrel-harden/references/contract.md +2 -0
  56. package/dist/host/agents/skills/orkestrel-harden/references/document.md +33 -0
  57. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +6 -3
  58. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +34 -18
  59. package/dist/host/agents/skills/orkestrel-harden/references/research.md +2 -0
  60. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +1272 -279
  61. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +425 -0
  62. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +603 -98
  63. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +79 -98
  64. package/dist/host/agents/skills/orkestrel-journey/references/captures.md +54 -17
  65. package/dist/host/agents/skills/orkestrel-journey/references/decide.md +1 -20
  66. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +21 -31
  67. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +1 -1
  68. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +33 -29
  69. package/dist/host/agents/skills/orkestrel-parallel/references/claude.md +15 -13
  70. package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
  71. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  72. package/dist/host/agents/skills/orkestrel-parallel/references/cursor.md +13 -13
  73. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
  74. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +389 -0
  75. package/dist/host/agents/skills/orkestrel-polish/SKILL.md +16 -20
  76. package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +16 -26
  77. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -26
  78. package/dist/host/agents/skills/orkestrel-publish/agents/openai.yaml +2 -2
  79. package/dist/host/agents/skills/orkestrel-publish/references/adopt.md +23 -0
  80. package/dist/host/agents/skills/orkestrel-publish/references/release.md +4 -4
  81. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +13 -10
  82. package/dist/host/agents/skills/orkestrel-publish/references/window.md +21 -26
  83. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +348 -59
  84. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +202 -22
  85. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +1061 -191
  86. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +812 -140
  87. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +280 -38
  88. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  89. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +428 -70
  90. package/dist/host/agents/templates/brief.md +6 -2
  91. package/dist/host/agents/transports/claude-cli.md +3 -3
  92. package/dist/host/agents/transports/codex.md +3 -8
  93. package/dist/host/agents/transports/cursor.md +2 -3
  94. package/dist/host/claude/AGENTS.md +2 -3
  95. package/dist/host/claude/agents/analyst.md +3 -3
  96. package/dist/host/claude/agents/astra.md +4 -4
  97. package/dist/host/claude/agents/builder.md +4 -3
  98. package/dist/host/claude/agents/checker.md +1 -1
  99. package/dist/host/claude/agents/distiller.md +1 -1
  100. package/dist/host/claude/agents/grok.md +1 -1
  101. package/dist/host/claude/agents/opus.md +3 -3
  102. package/dist/host/claude/agents/orkestrel.md +57 -90
  103. package/dist/host/claude/agents/researcher.md +1 -1
  104. package/dist/host/claude/agents/reviewer.md +6 -2
  105. package/dist/host/claude/agents/scout.md +1 -1
  106. package/dist/host/claude/agents/verifier.md +2 -2
  107. package/dist/host/claude/rules/application.md +14 -21
  108. package/dist/host/claude/rules/architecture.md +34 -44
  109. package/dist/host/claude/rules/browser.md +3 -4
  110. package/dist/host/claude/rules/campaign.md +3 -2
  111. package/dist/host/claude/rules/documentation.md +25 -12
  112. package/dist/host/claude/rules/names.md +9 -4
  113. package/dist/host/claude/rules/patterns.md +6 -7
  114. package/dist/host/claude/rules/portability.md +1 -1
  115. package/dist/host/claude/rules/quality.md +7 -6
  116. package/dist/host/claude/rules/styles.md +2 -2
  117. package/dist/host/claude/rules/tests.md +68 -115
  118. package/dist/host/claude/rules/typescript.md +7 -9
  119. package/dist/host/claude/rules/workspace.md +27 -26
  120. package/dist/host/claude/rules/writing.md +2 -5
  121. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  122. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  123. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -1
  124. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  125. package/dist/host/codex/agents/analyst.toml +9 -3
  126. package/dist/host/codex/agents/astra.toml +10 -7
  127. package/dist/host/codex/agents/builder.toml +4 -4
  128. package/dist/host/codex/agents/opus.toml +6 -6
  129. package/dist/host/codex/agents/orkestrel.toml +1 -1
  130. package/dist/host/codex/agents/researcher.toml +2 -2
  131. package/dist/host/codex/agents/reviewer.toml +2 -2
  132. package/dist/host/codex/agents/verifier.toml +4 -4
  133. package/dist/host/codex/config.toml +1 -1
  134. package/dist/host/configs/helpers.ts +21 -1
  135. package/dist/host/configs/policy.ts +299 -15
  136. package/dist/host/cursor/rules/orchestration.mdc +1 -1
  137. package/dist/host/dotfiles/oxlintrc.json +137 -3
  138. package/dist/host/guides/agent.md +111 -134
  139. package/dist/host/guides/capture.md +801 -0
  140. package/dist/host/guides/probe.md +27 -8
  141. package/dist/host/guides/scaffold.md +97 -19
  142. package/dist/host/guides/study.md +534 -440
  143. package/dist/host/guides/test.md +111 -44
  144. package/dist/host/manifest.json +170 -244
  145. package/dist/host/tests/config.test.ts +977 -187
  146. package/dist/host/tests/policy.test.ts +165 -1
  147. package/dist/host/tests/setupPolicy.ts +1246 -33
  148. package/dist/src/core/index.cjs +222 -90
  149. package/dist/src/core/index.cjs.map +1 -1
  150. package/dist/src/core/index.d.cts +126 -40
  151. package/dist/src/core/index.d.ts +126 -40
  152. package/dist/src/core/index.js +217 -89
  153. package/dist/src/core/index.js.map +1 -1
  154. package/dist/src/server/index.cjs +20 -27
  155. package/dist/src/server/index.cjs.map +1 -1
  156. package/dist/src/server/index.js +21 -28
  157. package/dist/src/server/index.js.map +1 -1
  158. package/package.json +11 -11
  159. package/dist/agents/skills/orkestrel-dispatch/scripts/helpers.js +0 -283
  160. package/dist/host/agents/skills/orkestrel-dispatch/references/bench.md +0 -25
  161. package/dist/host/agents/skills/orkestrel-dispatch/scripts/helpers.ts +0 -333
  162. package/dist/host/guides/supervisor.md +0 -4890
@@ -1,19 +1,19 @@
1
1
  name = "builder"
2
- description = "Sol executor for one bounded unit with a closed shape in src, app, tests, or configs; writes only owned files as the sole writer in its checkout and validates scoped to them."
2
+ description = "Sol executor for a fully specified unit with a closed shape in src, app, tests, or configs; writes only owned files as the sole writer in its checkout and validates scoped to them."
3
3
  model = "gpt-6.1-sol"
4
4
  model_reasoning_effort = "low"
5
5
  sandbox_mode = "workspace-write"
6
6
  developer_instructions = """
7
- Implement one bounded unit with a closed shape. The dispatch is the plan; do not re-plan.
7
+ Implement a fully specified unit with a closed shape. The dispatch is the plan; do not re-plan.
8
8
 
9
9
  Read the brief, the .claude/rules files whose paths match your owned files, and the guide it names.
10
10
  Write only the owned files; return an exact patch for a shared file. Follow AGENTS.md § Work loop
11
11
  at the size the brief names: edit, prove or test the claim, run the touched test file, then the
12
12
  touched project when the brief names it. Validate read-only and scoped: a non-fix lint on your paths, the
13
- scoped check: script, the touched tests; never run format, lint --fix, build, or the whole suite. Delete any probe you wrote before returning.
13
+ scoped check: script, the touched tests; never run format, lint --fix, build, or the whole suite. Leave no probe behind, per .claude/rules/tests.md § Probes.
14
14
 
15
15
  A unit that leaves naming, API shape, or architecture open, or that spans packages, belongs to
16
- astra or opus: stop and say so. Never install, commit, push, read a secret, or run a destructive command. Stop and report
16
+ astra or opus: stop and say so. A unit whose mechanism is open: a protocol, a lock, a retry class, or a termination path; report it as belonging to astra or opus. Never install, commit, push, read a secret, or run a destructive command. Stop and report
17
17
  per .agents/orchestration.md § Deviation protocol on any conflict with the brief.
18
18
 
19
19
  Return changed files with one line each, the scoped commands run and their results, shared-file
@@ -7,20 +7,20 @@ developer_instructions = """
7
7
  Implement one dispatched subjective unit on GPT-6 Astra and spawn nothing.
8
8
 
9
9
  Read the brief, AGENTS.md, the rules whose paths match the owned files, the named skill, and the
10
- guide. Follow AGENTS.md § Work loop: types first, prove the claim with the prove tool, implement,
11
- test, consolidate, document. For a defect, record the failing command and count before the fix
12
- and the same command green after.
10
+ guide. Follow AGENTS.md § Work loop: types first, prove the claim, implement, test, consolidate,
11
+ document. Select the instrument per AGENTS.md § Work loop and .claude/rules/quality.md § Instruments
12
+ and return the evidence that instrument produced.
13
13
 
14
14
  Write only the owned files; return an exact patch for a shared file. Validate read-only and
15
15
  scoped: the touched project's check: script, the touched test file, then the touched project.
16
- Never run format, lint --fix, build, or the whole suite. Delete every probe before returning;
17
- promote a probe that settled a claim into a test. Finish the whole unit. Stop only per
16
+ Never run format, lint --fix, build, or the whole suite. Leave no probe behind, per
17
+ .claude/rules/tests.md § Probes. Finish the whole unit. Stop only per
18
18
  .agents/orchestration.md § Deviation protocol.
19
19
 
20
20
  Never add a dependency, suppress a diagnostic, mock project-owned behavior, leave a TODO in
21
21
  scope, commit, push, install, read a secret, or run a destructive command.
22
22
 
23
23
  Return touched files with one line each, diffstat, scoped validation commands and results, the
24
- prove closing line per claim, failing-first test names, shared-file patches, deviation state.
24
+ instrument's closing evidence per claim, failing-first test names, shared-file patches, deviation state.
25
25
  No process diary.
26
26
  """
@@ -1,7 +1,7 @@
1
1
  name = "orkestrel"
2
2
  description = "Read-only Orkestrel ecosystem reconciler: turns the evidence the dispatch supplies — manifests, lockfiles, installed declarations, guides, and registry readings — into package maps, dependency sequencing, blast radius, and drift findings. Collects no live state itself, and never treats the embedded catalog as live state."
3
3
  model = "gpt-6.1-sol"
4
- model_reasoning_effort = "medium"
4
+ model_reasoning_effort = "low"
5
5
  sandbox_mode = "read-only"
6
6
  developer_instructions = """
7
7
  Read .agents/orchestration.md first. It owns the role set, the routing, and the
@@ -11,6 +11,6 @@ installed declaration under node_modules. Read each source; never answer from me
11
11
  fact with its URL or file:line and the shortest supporting quote that carries the fact, never a
12
12
  passage. Put anything a primary source did not settle under Unknowns.
13
13
 
14
- Return only: Question, Facts (claim, source, date, quote), Matrix when asked (each row ending
15
- implement, repair, retain, or exclude with evidence), Unknowns. Never spawn another agent.
14
+ Return only: Question, Facts (claim, source, date, quote), Matrix when asked (capability or
15
+ defect rows, each with the evidence for and against it; the Orchestrator rules on each row), Unknowns. Never spawn another agent.
16
16
  """
@@ -9,7 +9,7 @@ commands. Never edit, run a mutating command, or spawn. Use a clean context; nev
9
9
 
10
10
  Read the claims file, the actual diff and git status --porcelain the dispatch supplies,
11
11
  AGENTS.md, the rules whose paths match the changed files, the guide, and enough surrounding
12
- source to judge. Return a deviation if the diff is missing.
12
+ source to judge. The diff and git status are required only for a code subject; return a deviation if that diff is missing.
13
13
 
14
14
  Hold the lane the dispatch names and say which. Subjective: requested shape and voice, coherent
15
15
  names and boundaries, the right layer, each concept's purpose, guide parity. Objective:
@@ -25,5 +25,5 @@ as a proposal to test against the code, never as authority.
25
25
 
26
26
  Return the orkestrel-falsify verdict shape: numbered verdicts with evidence, findings outside the
27
27
  claims, tested-and-held, one terminal line. Each required change carries file:line, what is
28
- wrong, and what right looks like. Nothing else. Your final message is the verdict.
28
+ wrong, and what right looks like. For a remedy that adds a mechanism per `.agents/orchestration.md` § Size gate, return the failing case and the violated property, never the mechanism. A dispatch-named skill that fixes another shape wins. Nothing else. Your final message is the verdict.
29
29
  """
@@ -1,7 +1,7 @@
1
1
  name = "verifier"
2
2
  description = "Independent gate runner that runs the exact commands the dispatch names, scoped first, and reports exit-code truth with exact failure excerpts without fixing anything."
3
3
  model = "gpt-6-luna"
4
- model_reasoning_effort = "medium"
4
+ model_reasoning_effort = "low"
5
5
  sandbox_mode = "workspace-write"
6
6
  developer_instructions = """
7
7
  Run the requested gates and report their results. Write only the evidence artifacts and the declared
@@ -13,9 +13,9 @@ Run exactly the commands the dispatch names, in order. Default scoped sweep: the
13
13
  scripts of each named project. Default tree-wide sweep, only when the dispatch says tree-wide:
14
14
  npm run format:check; npm run lint:check; npm run check; npm run build; npm test. Read each gate
15
15
  bare, never through tail or grep. Record each outcome by exit code; a gate that mostly passes
16
- failed. On failure capture the exact excerpt and the file:line it points to. On a timing failure, request one coordinated isolated rerun and preserve both results. When that
17
- rerun fails, stop and report; run again only after a changed condition or an explicit investigation
18
- request.
16
+ failed. On failure capture the exact excerpt and the file:line it points to. Report a failure that
17
+ passes alone per orkestrel-dispatch § Write the brief, and rerun nothing to reclassify it; run again
18
+ only after a changed condition or an explicit investigation request.
19
19
 
20
20
  Never run a source-mutating gate (lint, format, or any --fix), or a build without the declarations
21
21
  and holds .agents/orchestration.md § Permission floor requires. Never run git checkout, restore,
@@ -21,7 +21,7 @@ before relying on a capability those pages name. .agents/platforms/ owns the hos
21
21
 
22
22
  Hooks: .codex/hooks.json runs the orkestrel-dispatch sweep script (node
23
23
  .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report) on SessionStart and git diff --check
24
- on Stop. Every script an agent writes is TypeScript run by node, per AGENTS.md.
24
+ on Stop.
25
25
  """
26
26
 
27
27
  [agents]
@@ -756,6 +756,26 @@ export function readCompilerOutput(compiler: string, args: readonly string[]): s
756
756
  return result.stdout ?? ''
757
757
  }
758
758
 
759
+ /**
760
+ * Resolves the TypeScript command from its exported package manifest.
761
+ * @param path - The module or manifest path whose installation supplies TypeScript.
762
+ * @returns The absolute compiler command path on TypeScript 6 and 7.
763
+ * @throws An error when the package declares no `bin.tsc` command.
764
+ */
765
+ export function resolveCompiler(path: string): string {
766
+ const load = createRequire(path)
767
+ const manifest = load.resolve('typescript/package.json')
768
+ const declared: unknown = load(manifest)
769
+ if (typeof declared !== 'object' || declared === null || !('bin' in declared)) {
770
+ throw new Error('The TypeScript package declares no bin.tsc command')
771
+ }
772
+ const bin = declared.bin
773
+ if (typeof bin !== 'object' || bin === null || !('tsc' in bin) || typeof bin.tsc !== 'string') {
774
+ throw new Error('The TypeScript package declares no bin.tsc command')
775
+ }
776
+ return resolvePath(dirname(manifest), bin.tsc)
777
+ }
778
+
759
779
  /**
760
780
  * Parses a `tsc --showConfig` reading into the compiler scope a face's roll-up requires.
761
781
  *
@@ -886,7 +906,7 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
886
906
  )
887
907
  }
888
908
  const load = createRequire(import.meta.url)
889
- const compiler = load.resolve('typescript/bin/tsc')
909
+ const compiler = resolveCompiler(import.meta.url)
890
910
  const scope = parseProjectScope(
891
911
  readCompilerOutput(compiler, ['--showConfig', '-p', options.project]),
892
912
  options.project,
@@ -12,8 +12,20 @@ export interface PolicyExpression extends PolicyNode {
12
12
  readonly key?: PolicyExpression
13
13
  readonly id?: PolicyExpression | null
14
14
  readonly method?: boolean
15
- readonly kind?: 'const' | 'get' | 'init' | 'let' | 'set' | 'var'
15
+ readonly kind?:
16
+ | 'const'
17
+ | 'get'
18
+ | 'global'
19
+ | 'init'
20
+ | 'let'
21
+ | 'module'
22
+ | 'namespace'
23
+ | 'set'
24
+ | 'var'
16
25
  readonly expression?: boolean
26
+ readonly readonly?: boolean
27
+ readonly test?: PolicyExpression
28
+ readonly alternate?: PolicyExpression | null
17
29
  readonly object?: PolicyExpression
18
30
  readonly property?: PolicyExpression
19
31
  readonly computed?: boolean
@@ -25,6 +37,7 @@ export interface PolicyExpression extends PolicyNode {
25
37
  readonly quasis?: readonly PolicyExpression[]
26
38
  readonly expressions?: readonly PolicyExpression[]
27
39
  readonly accessibility?: 'private' | 'protected' | 'public' | null
40
+ readonly declare?: boolean
28
41
  readonly declaration?: PolicyExpression
29
42
  readonly declarations?: readonly PolicyExpression[]
30
43
  readonly init?: PolicyExpression | null
@@ -52,12 +65,30 @@ export interface PolicyComment extends PolicyNode {
52
65
  readonly value: string
53
66
  }
54
67
 
68
+ /** Describes one reference the scope manager records to a declared variable. */
69
+ export interface PolicyReference {
70
+ readonly identifier: PolicyNode
71
+ readonly init?: boolean
72
+ isWrite(): boolean
73
+ }
74
+
75
+ /** Describes one variable the scope manager records for a declaration. */
76
+ export interface PolicyVariable {
77
+ readonly identifiers: readonly PolicyNode[]
78
+ readonly references: readonly PolicyReference[]
79
+ }
80
+
55
81
  /** Lists the Oxlint source-text operations the comment rules read. */
56
82
  export interface PolicySourceCode {
57
83
  readonly text: string
58
84
  getAllComments(): readonly PolicyComment[]
59
85
  }
60
86
 
87
+ /** Adds the Oxlint scope operation the binding rule reads. */
88
+ export interface PolicyScopeCode extends PolicySourceCode {
89
+ getDeclaredVariables(node: PolicyNode): readonly PolicyVariable[]
90
+ }
91
+
61
92
  /** Pairs one doc block with the declared name its first sentence must not repeat. */
62
93
  export interface PolicyDoc {
63
94
  readonly comment: PolicyComment
@@ -89,7 +120,7 @@ export interface PolicyContext {
89
120
  readonly filename: string
90
121
  /** Names the directory Oxlint resolves `filename` against. */
91
122
  readonly cwd: string
92
- readonly sourceCode: PolicySourceCode
123
+ readonly sourceCode: PolicyScopeCode
93
124
  report(diagnostic: PolicyDiagnostic): void
94
125
  }
95
126
 
@@ -130,6 +161,7 @@ export interface PolicyVisitor {
130
161
  readonly TSEnumDeclaration?: (node: PolicyNode) => void
131
162
  readonly TSInterfaceDeclaration?: (node: PolicyNode) => void
132
163
  readonly TSModuleDeclaration?: (node: PolicyNode) => void
164
+ readonly TSPropertySignature?: (node: PolicyNode) => void
133
165
  readonly TSTypeAliasDeclaration?: (node: PolicyNode) => void
134
166
  readonly VariableDeclaration?: (node: PolicyNode) => void
135
167
  }
@@ -266,6 +298,68 @@ export const POLICY_ENDING_GLOBS: readonly string[] = Object.freeze([
266
298
  'src/**/*.ts',
267
299
  ])
268
300
 
301
+ /** Lists every source extension the nested-function rule reads. */
302
+ export const POLICY_CODE_EXTENSIONS: readonly string[] = Object.freeze([
303
+ 'cjs',
304
+ 'cts',
305
+ 'js',
306
+ 'jsx',
307
+ 'mjs',
308
+ 'mts',
309
+ 'ts',
310
+ 'tsx',
311
+ 'vue',
312
+ ])
313
+
314
+ /**
315
+ * Matches the lint population the nested-function rule runs over, as the Oxlint configuration
316
+ * declares it.
317
+ */
318
+ export const POLICY_NESTED_GLOBS: readonly string[] = Object.freeze(
319
+ ['src', 'app', 'tests', 'configs'].map(
320
+ (root) => `${root}/**/*.{${POLICY_CODE_EXTENSIONS.join(',')}}`,
321
+ ),
322
+ )
323
+
324
+ /**
325
+ * Matches the lint population the skill-script rules run over, as the Oxlint configuration declares
326
+ * it.
327
+ */
328
+ export const POLICY_SCRIPT_GLOBS: readonly string[] = Object.freeze([
329
+ '.agents/skills/*/scripts/*.ts',
330
+ ])
331
+
332
+ /** Matches the workspace-relative path of a skill script, the file shape the script rule reads. */
333
+ export const POLICY_SCRIPT_PATTERN = /^\.agents\/skills\/[^/]+\/scripts\/[^/]+\.ts$/u
334
+
335
+ /** Holds the one entry guard a skill script runs `main` under, as its source text reads. */
336
+ export const POLICY_ENTRY_GUARD =
337
+ 'process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename'
338
+
339
+ /** Lists every statement type that declares a name at module scope. */
340
+ export const POLICY_DECLARATION_TYPES: readonly string[] = Object.freeze([
341
+ 'ClassDeclaration',
342
+ 'FunctionDeclaration',
343
+ 'TSDeclareFunction',
344
+ 'TSEnumDeclaration',
345
+ 'TSInterfaceDeclaration',
346
+ 'TSModuleDeclaration',
347
+ 'TSTypeAliasDeclaration',
348
+ 'VariableDeclaration',
349
+ ])
350
+
351
+ /**
352
+ * Lists the type nodes a property signature's search for its owning declaration never crosses,
353
+ * because a parameter, call, or construct signature beyond one is an inline type.
354
+ */
355
+ export const POLICY_INLINE_TYPES: readonly string[] = Object.freeze([
356
+ 'TSCallSignatureDeclaration',
357
+ 'TSConstructSignatureDeclaration',
358
+ 'TSConstructorType',
359
+ 'TSFunctionType',
360
+ 'TSMethodSignature',
361
+ ])
362
+
269
363
  /**
270
364
  * Matches the file name shape an implementation file takes, holding the class that matches its
271
365
  * stem.
@@ -870,12 +964,37 @@ export function isPolicyVoiced(word: string): boolean {
870
964
  }
871
965
 
872
966
  /**
873
- * Pairs every exported top-level statement with the doc block written directly above it.
967
+ * Reads the doc block written directly above one top-level statement.
874
968
  *
875
969
  * @remarks
876
970
  * A statement takes the last comment that closes before it, and takes it only where that comment is
877
971
  * a doc block and nothing but whitespace separates the two. A blank line between them is still
878
- * whitespace, so the pairing survives one.
972
+ * whitespace, so the pairing survives one. Every comment is read where a `findLast` would stop at
973
+ * the nearest one.
974
+ *
975
+ * @param statement - The top-level statement to pair.
976
+ * @param comments - Every comment of the linted file, in source order.
977
+ * @param sourceCode - The source-text reader supplying the text between a comment and the statement.
978
+ * @returns The paired doc block, or `undefined` where the statement has none.
979
+ */
980
+ export function statementToPolicyDoc(
981
+ statement: PolicyExpression,
982
+ comments: readonly PolicyComment[],
983
+ sourceCode: PolicySourceCode,
984
+ ): PolicyComment | undefined {
985
+ const start = statement.range[0]
986
+ const previous = Iterator.from(comments)
987
+ .flatMap((comment) => (comment.range[1] <= start ? [comment] : []))
988
+ .toArray()
989
+ .at(-1)
990
+ if (previous === undefined || previous.type !== 'Block') return undefined
991
+ if (!previous.value.startsWith('*')) return undefined
992
+ if (sourceCode.text.slice(previous.range[1], start).trim() !== '') return undefined
993
+ return previous
994
+ }
995
+
996
+ /**
997
+ * Pairs every exported top-level statement with the doc block written directly above it.
879
998
  *
880
999
  * @param node - The program node whose top-level statements are read.
881
1000
  * @param sourceCode - The source-text reader supplying the comments and the text between them.
@@ -886,24 +1005,18 @@ export function programToPolicyDocs(
886
1005
  sourceCode: PolicySourceCode,
887
1006
  ): readonly PolicyDoc[] {
888
1007
  // The iterator consumes one entry at a time and reads a hole as an `undefined` entry, as a
889
- // `for…of` over the list would. The comments are read only for an export statement, once per
890
- // statement, and every comment is read where a `findLast` would stop at the nearest one.
1008
+ // `for…of` over the list would. The comments are read once, and a statement pairs with one only
1009
+ // where it is an export.
891
1010
  const comments = sourceCode.getAllComments()
892
1011
  return Iterator.from(programToPolicyStatements(node))
893
1012
  .flatMap((statement) => {
894
1013
  if (!statement.type.startsWith('Export')) return []
895
- const start = statement.range[0]
896
- const previous = Iterator.from(comments)
897
- .flatMap((comment) => (comment.range[1] <= start ? [comment] : []))
898
- .toArray()
899
- .at(-1)
900
- if (previous === undefined || previous.type !== 'Block') return []
901
- if (!previous.value.startsWith('*')) return []
902
- if (sourceCode.text.slice(previous.range[1], start).trim() !== '') return []
1014
+ const comment = statementToPolicyDoc(statement, comments, sourceCode)
1015
+ if (comment === undefined) return []
903
1016
  const declaration = statement.declaration
904
1017
  return [
905
1018
  {
906
- comment: previous,
1019
+ comment,
907
1020
  name:
908
1021
  identifierToPolicyName(declaration?.id) ??
909
1022
  identifierToPolicyName(declaration?.declarations?.[0]?.id),
@@ -1023,6 +1136,54 @@ export function reportPrivacy(context: PolicyContext, node: PolicyExpression): v
1023
1136
  }
1024
1137
  }
1025
1138
 
1139
+ /** Checks whether code writes a declared variable anywhere but in its own declaration. */
1140
+ export function isPolicyReassigned(variable: PolicyVariable): boolean {
1141
+ return variable.references.some(
1142
+ (reference) =>
1143
+ reference.isWrite() &&
1144
+ reference.init !== true &&
1145
+ !variable.identifiers.includes(reference.identifier),
1146
+ )
1147
+ }
1148
+
1149
+ /**
1150
+ * Checks whether a node sits inside a `declare` module, namespace, or global augmentation.
1151
+ *
1152
+ * @remarks
1153
+ * A declaration inside such a block carries no `declare` flag of its own and no value, because the
1154
+ * block is the ambient context. A `global` block is ambient wherever it stands.
1155
+ */
1156
+ export function isPolicyInDeclaredModule(node: PolicyExpression): boolean {
1157
+ const parent = node.parent
1158
+ if (parent === undefined || parent === null) return false
1159
+ return (
1160
+ (parent.type === 'TSModuleDeclaration' &&
1161
+ (parent.declare === true || parent.kind === 'global')) ||
1162
+ isPolicyInDeclaredModule(parent)
1163
+ )
1164
+ }
1165
+
1166
+ /** Reports a let declaration that prefer-const leaves: one reassigned or declared without a value. */
1167
+ export function reportLet(context: PolicyContext, node: PolicyExpression): void {
1168
+ if (
1169
+ node.kind !== 'let' ||
1170
+ node.declare === true ||
1171
+ isPolicyAmbient(context.filename) ||
1172
+ isPolicyInDeclaredModule(node)
1173
+ ) {
1174
+ return
1175
+ }
1176
+ const head = node.parent?.type === 'ForInStatement' || node.parent?.type === 'ForOfStatement'
1177
+ const bare =
1178
+ !head &&
1179
+ (node.declarations ?? []).some(
1180
+ (declarator) => declarator.init === undefined || declarator.init === null,
1181
+ )
1182
+ if (bare || context.sourceCode.getDeclaredVariables(node).some(isPolicyReassigned)) {
1183
+ context.report({ node, messageId: 'let' })
1184
+ }
1185
+ }
1186
+
1026
1187
  /** Reports a centralized declaration that carries no export. */
1027
1188
  export function reportHidden(context: PolicyContext, node: PolicyExpression): void {
1028
1189
  if (isPolicyAmbient(context.filename)) return
@@ -1193,6 +1354,64 @@ export function reportEndingImport(context: PolicyContext, node: PolicyExpressio
1193
1354
  if (importsPolicyTerminator(node)) context.report({ node, messageId: 'terminator' })
1194
1355
  }
1195
1356
 
1357
+ /** Reports whether a path is a skill script, the one file shape the script rule reads. */
1358
+ export function isPolicyScript(filename: string, cwd: string): boolean {
1359
+ return POLICY_SCRIPT_PATTERN.test(pathToPolicyRelative(filename, cwd))
1360
+ }
1361
+
1362
+ /** Reports whether a statement is the one entry guard a skill script runs its main under. */
1363
+ export function isPolicyGuard(statement: PolicyExpression, sourceCode: PolicySourceCode): boolean {
1364
+ const test = statement.test
1365
+ if (statement.type !== 'IfStatement' || test === undefined) return false
1366
+ if (statement.alternate !== undefined && statement.alternate !== null) return false
1367
+ const text = sourceCode.text.slice(test.range[0], test.range[1]).replace(/\s+/gu, ' ')
1368
+ return text === POLICY_ENTRY_GUARD
1369
+ }
1370
+
1371
+ /** Reports a skill script's top-level statement that is hidden, undocumented, or runs at import. */
1372
+ export function reportScript(context: PolicyContext, node: PolicyExpression): void {
1373
+ if (isPolicyAmbient(context.filename) || !isPolicyScript(context.filename, context.cwd)) return
1374
+ const sourceCode = context.sourceCode
1375
+ const comments = sourceCode.getAllComments()
1376
+ const statements = programToPolicyStatements(node)
1377
+ const guard = statements.findIndex((statement) => isPolicyGuard(statement, sourceCode))
1378
+ for (const [index, statement] of statements.entries()) {
1379
+ if (statement.type === 'ImportDeclaration' || index === guard) continue
1380
+ const declaration = statement.declaration
1381
+ if (
1382
+ statement.type === 'ExportNamedDeclaration' &&
1383
+ declaration !== undefined &&
1384
+ declaration !== null
1385
+ ) {
1386
+ if (statementToPolicyDoc(statement, comments, sourceCode) === undefined) {
1387
+ context.report({ node: statement, messageId: 'doc' })
1388
+ }
1389
+ continue
1390
+ }
1391
+ context.report({
1392
+ node: statement,
1393
+ messageId: POLICY_DECLARATION_TYPES.includes(statement.type) ? 'hidden' : 'entry',
1394
+ })
1395
+ }
1396
+ }
1397
+
1398
+ /** Reports whether a property signature sits in an interface or in a type alias's object type. */
1399
+ export function isPolicyOwned(node: PolicyExpression): boolean {
1400
+ const parent = node.parent
1401
+ if (parent === undefined || parent === null) return false
1402
+ if (parent.type === 'TSInterfaceDeclaration' || parent.type === 'TSTypeAliasDeclaration') {
1403
+ return true
1404
+ }
1405
+ if (POLICY_INLINE_TYPES.includes(parent.type)) return false
1406
+ return isPolicyOwned(parent)
1407
+ }
1408
+
1409
+ /** Reports a property signature of an interface or type alias that is not readonly. */
1410
+ export function reportMutable(context: PolicyContext, node: PolicyExpression): void {
1411
+ if (isPolicyAmbient(context.filename) || node.readonly === true) return
1412
+ if (isPolicyOwned(node)) context.report({ node, messageId: 'mutable' })
1413
+ }
1414
+
1196
1415
  /** Bans function declarations and assignments inside another function body. */
1197
1416
  export const NESTED_RULE: PolicyRuleInterface = {
1198
1417
  meta: {
@@ -1262,6 +1481,25 @@ export const PRIVACY_RULE: PolicyRuleInterface = {
1262
1481
  },
1263
1482
  }
1264
1483
 
1484
+ /** Bans a let declaration that prefer-const does not already report. */
1485
+ export const LET_RULE: PolicyRuleInterface = {
1486
+ meta: {
1487
+ type: 'problem',
1488
+ docs: {
1489
+ description:
1490
+ 'Disallow a let declaration that is reassigned or declared without a value; prefer-const reports the rest.',
1491
+ },
1492
+ messages: {
1493
+ let: 'Declare this binding with const and derive its value: an expression, a helper that returns it, or a for…of over entries() in place of a counter.',
1494
+ },
1495
+ },
1496
+ create(context) {
1497
+ return {
1498
+ VariableDeclaration: (node) => reportLet(context, node),
1499
+ }
1500
+ },
1501
+ }
1502
+
1265
1503
  /** Bans a centralized declaration that no export reaches. */
1266
1504
  export const HIDDEN_RULE: PolicyRuleInterface = {
1267
1505
  meta: {
@@ -1546,6 +1784,49 @@ export const VOICE_RULE: PolicyRuleInterface = {
1546
1784
  },
1547
1785
  }
1548
1786
 
1787
+ /** Bans a skill script top-level statement that is hidden, undocumented, or runs at import. */
1788
+ export const SCRIPT_RULE: PolicyRuleInterface = {
1789
+ meta: {
1790
+ type: 'problem',
1791
+ docs: {
1792
+ description:
1793
+ 'Disallow an unexported declaration, an undocumented export, and a statement beyond the one guarded entry in a skill script.',
1794
+ },
1795
+ messages: {
1796
+ hidden:
1797
+ 'Export this declaration; a skill script exports every declaration so its proof can test each one.',
1798
+ doc: 'Write a one-sentence TSDoc summary directly above this export.',
1799
+ entry:
1800
+ 'Move this statement into a function; a skill script holds imports, exported declarations, and the one process.argv[1] guard that runs main, and an import runs nothing.',
1801
+ },
1802
+ },
1803
+ create(context) {
1804
+ return {
1805
+ Program: (node) => reportScript(context, node),
1806
+ }
1807
+ },
1808
+ }
1809
+
1810
+ /** Bans a property signature in an interface or type alias that is not readonly. */
1811
+ export const MUTABLE_RULE: PolicyRuleInterface = {
1812
+ meta: {
1813
+ type: 'problem',
1814
+ docs: {
1815
+ description:
1816
+ 'Disallow a property signature without readonly in an interface or in the object type of a type alias.',
1817
+ },
1818
+ messages: {
1819
+ mutable:
1820
+ 'Declare this property readonly; a contract exposes its members and no holder rewrites them.',
1821
+ },
1822
+ },
1823
+ create(context) {
1824
+ return {
1825
+ TSPropertySignature: (node) => reportMutable(context, node),
1826
+ }
1827
+ },
1828
+ }
1829
+
1549
1830
  /** Bans a comment carrying a term the substitution table bans unconditionally. */
1550
1831
  export const TERM_RULE: PolicyRuleInterface = {
1551
1832
  meta: {
@@ -1571,6 +1852,7 @@ export default {
1571
1852
  rules: {
1572
1853
  'no-mocking': MOCKING_RULE,
1573
1854
  'no-keyword-privacy': PRIVACY_RULE,
1855
+ 'no-let': LET_RULE,
1574
1856
  'no-nested-functions': NESTED_RULE,
1575
1857
  'no-hidden-declaration': HIDDEN_RULE,
1576
1858
  'no-misplaced-type': TYPE_RULE,
@@ -1586,5 +1868,7 @@ export default {
1586
1868
  'no-host-line-endings': ENDING_RULE,
1587
1869
  'no-malformed-summary': VOICE_RULE,
1588
1870
  'no-banned-term': TERM_RULE,
1871
+ 'no-malformed-script': SCRIPT_RULE,
1872
+ 'no-mutable-property': MUTABLE_RULE,
1589
1873
  },
1590
1874
  }
@@ -9,7 +9,7 @@ alwaysApply: true
9
9
 
10
10
  ## Posture
11
11
 
12
- - Invoked through the `grok` bridge (`agent -p --mode=ask`): act as a read-only executor. Return distilled evidence with `file:line` pointers. Never edit, decide, or accept.
12
+ - Invoked through the `grok` bridge (`agent -p --mode=ask`): act as the `grok` role per `.agents/orchestration.md` § Roles and § Engines. Return distilled evidence with `file:line` pointers.
13
13
  - Driven by the user: act as the Orchestrator per `.agents/orchestration.md`, on Grok.
14
14
  - `.agents/skills/orkestrel-parallel/references/cursor.md` owns Cursor's lane mechanics and quirks; `.agents/platforms/` owns the host shell.
15
15